zengate 1.0.4 → 1.1.0

package/src/openai/responses-store.js

@@ -3,21 +3,37 @@ const MAX_ENTRY_CHARS = 4 * 1024 * 1024;
 
 /**
  * In-memory store behind previous_response_id and GET/DELETE
- * /v1/responses/{id}. Bounded (LRU + 1h TTL) and never persisted: a gateway
- * restart forgets stored responses, which clients see as "not found".
- * @param {{ maxEntries: number }} options
+ * /v1/responses/{id}. Bounded by entry count, by an approximate memory budget
+ * (JSON size of each entry's full history, so chained turns that share
+ * messages are counted conservatively) and by a 1h TTL, evicting least
+ * recently used entries first. Never persisted: a gateway restart forgets
+ * stored responses, which clients see as "not found".
+ * @param {{ maxEntries: number, maxChars?: number }} options
  */
-export function createResponsesStore({ maxEntries }) {
+export function createResponsesStore({ maxEntries, maxChars = Infinity }) {
     const entries = new Map();
     const items = new Map();
+    // Chained turns reuse the same message objects, so each is sized once.
+    const messageSizes = new WeakMap();
+    let chars = 0;
 
     const expired = (entry) => Date.now() - entry.at > TTL_MS;
 
+    const messageSize = (message) => {
+        let size = messageSizes.get(message);
+        if (size === undefined) {
+            size = JSON.stringify(message).length;
+            messageSizes.set(message, size);
+        }
+        return size;
+    };
+
     function evict(id) {
         const entry = entries.get(id);
         if (!entry) return;
         for (const itemId of entry.itemIds) items.delete(itemId);
         entries.delete(id);
+        chars -= entry.size;
     }
 
     function get(id) {
@@ -50,11 +66,14 @@ export function createResponsesStore({ maxEntries }) {
              */
             save(response, history) {
                 if (maxEntries <= 0) return;
-                if (JSON.stringify(history).length > MAX_ENTRY_CHARS) return;
+                const size = history.reduce((sum, message) => sum + messageSize(message), JSON.stringify(response).length);
+                if (size > Math.min(MAX_ENTRY_CHARS, maxChars)) return;
+                evict(response.id);
                 const itemIds = response.output.map((item) => item.id);
                 for (const item of response.output) items.set(item.id, { item, responseId: response.id });
-                entries.set(response.id, { response, history, itemIds, owner, at: Date.now() });
-                while (entries.size > maxEntries) evict(entries.keys().next().value);
+                entries.set(response.id, { response, history, itemIds, owner, at: Date.now(), size });
+                chars += size;
+                while (entries.size > maxEntries || chars > maxChars) evict(entries.keys().next().value);
             },
             response: (id) => owned(id, owner)?.response ?? null,
             history: (id) => owned(id, owner)?.history ?? null,
@@ -74,5 +93,6 @@ export function createResponsesStore({ maxEntries }) {
         enabled: maxEntries > 0,
         scope,
         size: () => entries.size,
+        chars: () => chars,
     });
 }

package/src/openai/responses.js

@@ -1,6 +1,8 @@
 import { ApiError } from '../server/errors.js';
 import { generate } from './generate.js';
+import { setIgnoredParams } from './ignored-params.js';
 import { buildPrompt } from './prompt.js';
+import { inlineRemoteAttachments } from './remote-media.js';
 import { createResponseBuilder } from './response-builder.js';
 import { parseResponsesRequest } from './responses-request.js';
 import { openSse } from './sse-writer.js';
@@ -21,9 +23,10 @@ export function responsesHandlers({ runner, catalog, store, limits }) {
         const model = await catalog.resolve(request.model);
         const prompt = buildPrompt(request, model);
         await assertPublicUrls(prompt.parts);
-        if (request.ignored.length) res.set('x-gateway-ignored-params', request.ignored.join(','));
+        setIgnoredParams(res, request.ignored);
 
         await req.withSlot(async (signal) => {
+            const ready = await inlineRemoteAttachments(prompt, { ...limits, signal });
             const sse = request.stream ? openSse(res) : null;
             const builder = createResponseBuilder({
                 model: model.id,
@@ -33,7 +36,7 @@ export function responsesHandlers({ runner, catalog, store, limits }) {
             builder.start();
             try {
                 const result = await generate({
-                    runner, prompt, request, signal,
+                    runner, prompt: ready, request, signal, onFirstToken: req.markFirstToken,
                     onText: (text) => builder.textDelta(text),
                     onReasoning: (text) => builder.reasoningDelta(text),
                 });

package/src/openai/stop.js

@@ -5,10 +5,38 @@
  */
 export function createStopFilter(stops) {
     const sequences = stops.filter(Boolean);
-    const hold = sequences.reduce((max, s) => Math.max(max, s.length - 1), 0);
     let pending = '';
     let stopped = false;
 
+    /** Index of the earliest complete stop sequence in `pending`, or -1. */
+    function firstMatch() {
+        let cut = -1;
+        for (const sequence of sequences) {
+            const index = pending.indexOf(sequence);
+            if (index >= 0 && (cut < 0 || index < cut)) cut = index;
+        }
+        return cut;
+    }
+
+    /**
+     * Index of the earliest position where `pending` ends with the start of a
+     * stop sequence that more text could complete, or `pending.length`.
+     */
+    function firstPartial() {
+        for (let i = 0; i < pending.length; i++) {
+            const tail = pending.slice(i);
+            if (sequences.some((s) => s.length > tail.length && s.startsWith(tail))) return i;
+        }
+        return pending.length;
+    }
+
+    function stopAt(cut) {
+        stopped = true;
+        const out = pending.slice(0, cut);
+        pending = '';
+        return out;
+    }
+
     return {
         get stopped() { return stopped; },
         /** @returns {string} text that can be emitted now */
@@ -16,24 +44,20 @@ export function createStopFilter(stops) {
             if (stopped || !text) return '';
             if (!sequences.length) return text;
             pending += text;
-            let cut = -1;
-            for (const sequence of sequences) {
-                const index = pending.indexOf(sequence);
-                if (index >= 0 && (cut < 0 || index < cut)) cut = index;
-            }
-            if (cut >= 0) {
-                stopped = true;
-                const out = pending.slice(0, cut);
-                pending = '';
-                return out;
-            }
-            const safe = Math.max(0, pending.length - hold);
+            const cut = firstMatch();
+            // A longer sequence that starts earlier may still complete, so a
+            // match is final only when no partial one begins before it.
+            const partial = firstPartial();
+            if (cut >= 0 && cut <= partial) return stopAt(cut);
+            const safe = cut >= 0 ? Math.min(cut, partial) : partial;
             const out = pending.slice(0, safe);
             pending = pending.slice(safe);
             return out;
         },
         flush() {
-            const out = stopped ? '' : pending;
+            if (stopped) return '';
+            const cut = firstMatch();
+            const out = cut >= 0 ? pending.slice(0, cut) : pending;
             pending = '';
             return out;
         },

package/src/openai/tool-calls.js

@@ -1,4 +1,5 @@
 import crypto from 'node:crypto';
+import { escapeFrames } from './markup.js';
 
 /**
  * OpenAI function calling, emulated over a plain-text protocol.
@@ -49,11 +50,14 @@ export function toolInstructions(tools, choice, parallel) {
     return lines.join('\n');
 }
 
-/** Render a past call in the same syntax, so history teaches the protocol. */
+/**
+ * Render a past call in the same syntax, so history teaches the protocol.
+ * Its name and arguments come from the client, so frame tags are escaped.
+ */
 export function renderToolCall(call) {
     let args = call.arguments;
     try { args = JSON.parse(call.arguments); } catch { /* keep raw string */ }
-    return `${OPEN}${JSON.stringify({ name: call.name, arguments: args })}${CLOSE}`;
+    return `${OPEN}${escapeFrames(JSON.stringify({ name: call.name, arguments: args }))}${CLOSE}`;
 }
 
 /** Length of a trailing fragment that could still grow into an opening tag. */
@@ -162,6 +166,8 @@ export function createToolCallParser(tools) {
     let capturing = false;
 
     return {
+        /** True while a call block is open and its text is held back. */
+        get capturing() { return capturing; },
         push(text) {
             pending += text;
             if (capturing) return '';

package/src/openai/url-guard.js

@@ -3,59 +3,127 @@ import net from 'node:net';
 import { invalidRequest } from '../server/errors.js';
 
 /**
- * Attachment URLs are fetched by OpenCode on this host, so a client could
- * otherwise point them at internal services (SSRF). Only public addresses
- * are allowed; this blocks loopback, private, link-local, CGNAT, multicast
- * and other special-purpose ranges.
+ * Attachment URLs are fetched by the gateway, so a client could otherwise
+ * point them at internal services (SSRF). Only public addresses are allowed;
+ * this blocks loopback, private, link-local, CGNAT, multicast and other
+ * special-purpose ranges, including IPv6 forms that embed an IPv4 address.
  */
-const BLOCKED = new net.BlockList();
+const BLOCKED_V4 = new net.BlockList();
 [
     ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16],
-    ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24], ['192.168.0.0', 16], ['198.18.0.0', 15],
-    ['198.51.100.0', 24], ['203.0.113.0', 24], ['224.0.0.0', 4], ['240.0.0.0', 4],
-].forEach(([address, prefix]) => BLOCKED.addSubnet(address, prefix, 'ipv4'));
+    ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24], ['192.88.99.0', 24], ['192.168.0.0', 16],
+    ['198.18.0.0', 15], ['198.51.100.0', 24], ['203.0.113.0', 24], ['224.0.0.0', 4], ['240.0.0.0', 4],
+].forEach(([address, prefix]) => BLOCKED_V4.addSubnet(address, prefix, 'ipv4'));
+
+const BLOCKED_V6 = new net.BlockList();
 [
-    ['::', 128], ['::1', 128], ['64:ff9b::', 96], ['100::', 64], ['2001:db8::', 32], ['fc00::', 7], ['fe80::', 10], ['ff00::', 8],
-].forEach(([address, prefix]) => BLOCKED.addSubnet(address, prefix, 'ipv6'));
+    // ::/96 also covers the deprecated IPv4-compatible form (::a.b.c.d).
+    ['::', 96], ['64:ff9b:1::', 48], ['100::', 64], ['2001::', 23], ['2001:db8::', 32],
+    ['2002::', 16], ['3fff::', 20], ['5f00::', 16], ['fc00::', 7], ['fe80::', 10], ['fec0::', 10], ['ff00::', 8],
+].forEach(([address, prefix]) => BLOCKED_V6.addSubnet(address, prefix, 'ipv6'));
 
 const LOOKUP_TIMEOUT_MS = 5000;
+/** Most attachments one request may send as URLs. */
+export const MAX_REMOTE_PARTS = 16;
+
+/** The eight 16-bit groups of a valid IPv6 address (which may end in dotted IPv4). */
+function ipv6Groups(address) {
+    let text = address.toLowerCase();
+    const dotted = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+    if (dotted) {
+        const [a, b, c, d] = dotted[1].split('.').map(Number);
+        text = `${text.slice(0, dotted.index)}${((a << 8) | b).toString(16)}:${((c << 8) | d).toString(16)}`;
+    }
+    const [head, tail] = text.split('::');
+    const left = head ? head.split(':') : [];
+    const right = tail ? tail.split(':') : [];
+    const fill = text.includes('::') ? 8 - left.length - right.length : 0;
+    return [...left, ...Array(fill).fill('0'), ...right].map((group) => parseInt(group, 16));
+}
+
+/**
+ * The IPv4 address inside an IPv4-mapped (::ffff:0:0/96), IPv4-translated
+ * (::ffff:0:0:0/96) or NAT64 well-known-prefix (64:ff9b::/96) address.
+ */
+function embeddedIpv4(groups) {
+    const mapped = groups.slice(0, 5).every((g) => g === 0) && groups[5] === 0xffff;
+    const translated = groups.slice(0, 4).every((g) => g === 0) && groups[4] === 0xffff && groups[5] === 0;
+    const nat64 = groups[0] === 0x64 && groups[1] === 0xff9b && groups.slice(2, 6).every((g) => g === 0);
+    if (!mapped && !translated && !nat64) return null;
+    return [groups[6] >> 8, groups[6] & 0xff, groups[7] >> 8, groups[7] & 0xff].join('.');
+}
 
 export function isBlockedAddress(address) {
-    const family = net.isIP(address);
-    if (family === 0) return true;
-    const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address);
-    if (mapped) return BLOCKED.check(mapped[1], 'ipv4');
-    return BLOCKED.check(address, family === 4 ? 'ipv4' : 'ipv6');
+    const plain = String(address).replace(/%.*$/, '');
+    const family = net.isIP(plain);
+    if (family === 4) return BLOCKED_V4.check(plain, 'ipv4');
+    if (family !== 6) return true;
+    const v4 = embeddedIpv4(ipv6Groups(plain));
+    return v4 ? BLOCKED_V4.check(v4, 'ipv4') : BLOCKED_V6.check(plain, 'ipv6');
 }
 
 async function resolve(hostname) {
     const literal = hostname.replace(/^\[|\]$/g, '');
-    if (net.isIP(literal)) return [literal];
-    const lookup = dns.lookup(literal, { all: true, verbatim: true });
-    const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error('DNS lookup timed out')), LOOKUP_TIMEOUT_MS).unref());
-    const records = await Promise.race([lookup, timeout]);
-    return records.map((record) => record.address);
+    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);
+    }
+}
+
+/**
+ * Every address `hostname` resolves to, provided all of them are public.
+ * @param {string} hostname
+ * @param {(address: string) => boolean} [isBlocked]
+ * @returns {Promise<{ address: string, family: number }[]>}
+ */
+export async function resolvePublic(hostname, isBlocked = isBlockedAddress) {
+    // One message for both failures, so clients cannot probe which internal names exist.
+    const records = await resolve(hostname).catch(() => []);
+    if (!records.length || records.some((record) => isBlocked(record.address))) {
+        throw invalidRequest(`Attachment host '${hostname}' is not a public address.`, null, 'invalid_attachment_url');
+    }
+    return records;
+}
+
+/**
+ * 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]
+ */
+export function publicLookup(isBlocked = isBlockedAddress) {
+    return (hostname, options, callback) => {
+        resolvePublic(hostname, isBlocked).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' }));
+            } else if (options?.all) {
+                callback(null, wanted);
+            } else {
+                callback(null, wanted[0].address, wanted[0].family);
+            }
+        }, callback);
+    };
 }
 
 /**
- * Reject prompt parts whose https URL resolves to a non-public address.
+ * 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.
  * @param {{ url?: string }[]} parts OpenCode prompt parts
  */
 export async function assertPublicUrls(parts) {
-    const hosts = new Set();
-    for (const part of parts) {
-        if (typeof part.url !== 'string' || !part.url.startsWith('https:')) continue;
-        hosts.add(new URL(part.url).hostname);
+    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');
     }
-    await Promise.all([...hosts].map(async (hostname) => {
-        let addresses;
-        try {
-            addresses = await resolve(hostname);
-        } catch {
-            throw invalidRequest(`Could not resolve attachment host '${hostname}'.`, null, 'invalid_attachment_url');
-        }
-        if (!addresses.length || addresses.some(isBlockedAddress)) {
-            throw invalidRequest(`Attachment host '${hostname}' is not a public address.`, null, 'invalid_attachment_url');
-        }
-    }));
+    const hosts = new Set(remote.map((part) => new URL(part.url).hostname));
+    await Promise.all([...hosts].map((hostname) => resolvePublic(hostname)));
 }

package/src/openai/usage-estimate.js

@@ -0,0 +1,42 @@
+import { CHARS_PER_TOKEN } from './length-limit.js';
+
+export const NO_USAGE = Object.freeze({ input: 0, output: 0, reasoning: 0, cacheRead: 0 });
+
+export const estimateTokens = (text) => Math.ceil(text.length / CHARS_PER_TOKEN);
+
+/**
+ * Input tokens OpenCode adds on top of the prompt text (its system prompt and
+ * tool list), as last measured for each model. Model ids come from the
+ * catalog, so the map stays small.
+ */
+const overheadByModel = new Map();
+let lastOverhead = 0;
+
+const modelKey = (prompt) => `${prompt.model?.providerID}/${prompt.model?.modelID}`;
+
+function promptTokens(prompt) {
+    const texts = [prompt.system || '', ...prompt.parts.filter((part) => part.type === 'text').map((part) => part.text)];
+    return texts.reduce((sum, text) => sum + estimateTokens(text), 0);
+}
+
+/** Remember how far a finished turn's real input count was above the prompt text alone. */
+export function learnPromptOverhead(prompt, usage) {
+    const measured = usage.input + usage.cacheRead;
+    if (!(measured > 0)) return;
+    lastOverhead = Math.max(0, measured - promptTokens(prompt));
+    overheadByModel.set(modelKey(prompt), lastOverhead);
+}
+
+/**
+ * Usage for a turn cut off before OpenCode reported any: the output side
+ * from the text that was produced, the input side from the prompt plus the
+ * overhead last measured for this model (or any model, before the first).
+ */
+export function estimateUsage(prompt, content, reasoning) {
+    return {
+        ...NO_USAGE,
+        input: promptTokens(prompt) + (overheadByModel.get(modelKey(prompt)) ?? lastOverhead),
+        output: estimateTokens(content),
+        reasoning: estimateTokens(reasoning),
+    };
+}

package/src/opencode/backend.js

@@ -1,22 +1,45 @@
 import { execFile, spawn } from 'node:child_process';
-import net from 'node:net';
 import { createOpencodeClient } from './client.js';
 import { resolveOpencodeBinary, spawnCommand } from './binary.js';
-import { backendEnv, createIsolatedRoot, randomPassword, removeIsolatedRoot, sweepStaleRoots } from './isolation.js';
+import {
+    backendEnv, createIsolatedRoot, HEARTBEAT_MS, randomPassword, recordBackendPid, removeIsolatedRoot, sweepStaleRoots, touchIsolatedRoot,
+} from './isolation.js';
 
 const START_TIMEOUT_MS = 60000;
+// Sweeping now and then (not only at start) also clears trees that were
+// still too fresh to judge when this gateway started.
+const SWEEP_EVERY_BEATS = 10;
 const MAX_RESTART_DELAY_MS = 30000;
 const ANSI = /\x1b\[[0-9;]*m/g;
 
-function freePort() {
+const LISTENING = /listening on http:\/\/127\.0\.0\.1:(\d{1,5})\b/;
+
+/**
+ * The port OpenCode reports once it has bound it. OpenCode picks the port
+ * itself (--port 0), so no other process can take it between being chosen
+ * and being bound and then pose as the backend.
+ */
+function boundPort(proc, timeoutMs) {
     return new Promise((resolve, reject) => {
-        const server = net.createServer();
-        server.unref();
-        server.once('error', reject);
-        server.listen(0, '127.0.0.1', () => {
-            const { port } = server.address();
-            server.close(() => resolve(port));
-        });
+        let seen = '';
+        const onData = (chunk) => {
+            seen = `${seen}${chunk}`.slice(-4096);
+            const port = Number(LISTENING.exec(seen.replace(ANSI, ''))?.[1]);
+            if (port > 0 && port < 65536) finish(null, port);
+        };
+        const onExit = () => finish(new Error('OpenCode exited during startup'));
+        const timer = setTimeout(() => finish(new Error(`OpenCode did not start listening in ${timeoutMs / 1000}s`)), timeoutMs);
+        function finish(error, port) {
+            clearTimeout(timer);
+            proc.stdout.off('data', onData);
+            proc.off('exit', onExit);
+            proc.off('error', onExit);
+            if (error) reject(error);
+            else resolve(port);
+        }
+        proc.stdout.on('data', onData);
+        proc.once('exit', onExit);
+        proc.once('error', onExit);
     });
 }
 
@@ -63,7 +86,7 @@ function pipeLogs(stream, logger) {
 
 /**
  * Starts and supervises a private `opencode serve` bound to 127.0.0.1 on a
- * free port with a random password. It restarts with backoff if it crashes.
+ * port it picks itself, with a random password. It restarts with backoff if it crashes.
  */
 export function createManagedBackend({ opencodePath, logger }) {
     let client = null;
@@ -73,15 +96,16 @@ export function createManagedBackend({ opencodePath, logger }) {
     let stopping = false;
     let restartDelay = 1000;
     let ready = false;
-    let everReady = false;
+    let heartbeat = null;
 
     async function launch() {
         const binary = resolveOpencodeBinary(opencodePath);
         dirs = createIsolatedRoot();
-        const port = await freePort();
+        const { root } = dirs;
+        const deadline = Date.now() + START_TIMEOUT_MS;
         const password = randomPassword();
-        const { command, args, windowsVerbatimArguments } = spawnCommand(binary.path, ['serve', '--hostname', '127.0.0.1', '--port', String(port)]);
-        logger.debug('Starting OpenCode backend', { binary: binary.path, source: binary.source, port });
+        const { command, args, windowsVerbatimArguments } = spawnCommand(binary.path, ['serve', '--hostname', '127.0.0.1', '--port', '0']);
+        logger.debug('Starting OpenCode backend', { binary: binary.path, source: binary.source });
         const proc = spawn(command, args, {
             cwd: dirs.workspace,
             env: backendEnv(dirs, password),
@@ -91,54 +115,94 @@ export function createManagedBackend({ opencodePath, logger }) {
             windowsVerbatimArguments,
         });
         child = proc;
+        if (proc.pid) recordBackendPid(root, proc.pid);
         pipeLogs(proc.stdout, logger);
         pipeLogs(proc.stderr, logger);
         let dead = false;
+        let served = false;
         proc.once('error', (error) => { dead = true; logger.error('Could not start OpenCode', { error: error.message }); });
         proc.once('exit', (code, signal) => {
             dead = true;
-            ready = false;
-            if (!stopping && everReady) onCrash(code, signal, dirs.root);
+            if (child === proc) ready = false;
+            // A backend that dies while starting is handled by whoever is
+            // waiting for launch(); only a crash after it served is restarted here.
+            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, Date.now() + START_TIMEOUT_MS, () => dead);
+        const health = await waitHealthy(candidate, deadline, () => dead);
         client = candidate;
         version = health.version || null;
         ready = true;
-        everReady = true;
+        served = true;
         restartDelay = 1000;
         logger.info(`OpenCode ${version || ''} backend ready (managed, isolated, tools disabled)`.replace('  ', ' '));
     }
 
-    function onCrash(code, signal, root) {
+    /** Kill the current backend, if any, and wait (briefly) until it is gone. */
+    async function terminate() {
+        const proc = child;
+        if (!proc?.pid || proc.exitCode !== null || proc.signalCode !== null) return;
+        const exited = new Promise((resolve) => proc.once('exit', resolve));
+        killTree(proc);
+        await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 5000).unref())]);
+    }
+
+    /** Relaunch with exponential backoff until a backend is up or the gateway stops. */
+    async function restart(reason) {
+        let why = reason;
+        while (!stopping) {
+            const delay = restartDelay;
+            restartDelay = Math.min(MAX_RESTART_DELAY_MS, restartDelay * 2);
+            await new Promise((resolve) => setTimeout(resolve, delay).unref());
+            if (stopping) return;
+            logger.warn(`OpenCode backend ${why}; restarting after ${delay / 1000}s`);
+            try {
+                await launch();
+                return;
+            } catch (error) {
+                if (stopping) {
+                    removeIsolatedRoot(dirs?.root);
+                    return;
+                }
+                logger.error('OpenCode restart failed', { error: error.message });
+                await terminate();
+                removeIsolatedRoot(dirs?.root);
+                why = 'failed to restart';
+            }
+        }
+    }
+
+    function onCrash(reason, root) {
         // Ctrl+C and service managers signal the whole process group, so OpenCode
         // can exit just before the gateway starts stopping. Only warn if the
         // restart actually goes ahead.
-        const reason = signal || code;
         logger.debug(`OpenCode backend exited (${reason})`);
         removeIsolatedRoot(root);
-        const delay = restartDelay;
-        restartDelay = Math.min(MAX_RESTART_DELAY_MS, restartDelay * 2);
-        setTimeout(() => {
-            if (stopping) return;
-            logger.warn(`OpenCode backend exited (${reason}); restarting after ${delay / 1000}s`);
-            launch().catch((error) => {
-                logger.error('OpenCode restart failed', { error: error.message });
-                killTree(child);
-            });
-        }, delay).unref();
+        void restart(`exited (${reason})`);
     }
 
     return Object.freeze({
         mode: 'managed',
         async start() {
-            const swept = sweepStaleRoots();
-            if (swept) logger.debug(`Removed ${swept} stale backend directories`);
+            const sweep = async () => {
+                const swept = await sweepStaleRoots();
+                if (swept) logger.debug(`Removed ${swept} stale backend directories`);
+            };
+            await sweep();
+            let beats = 0;
+            heartbeat = setInterval(() => {
+                if (dirs) touchIsolatedRoot(dirs.root);
+                beats += 1;
+                if (beats % SWEEP_EVERY_BEATS === 0) void sweep();
+            }, HEARTBEAT_MS);
+            heartbeat.unref();
             try {
                 await launch();
             } catch (error) {
                 stopping = true;
-                killTree(child);
+                clearInterval(heartbeat);
+                await terminate();
                 removeIsolatedRoot(dirs?.root);
                 throw error;
             }
@@ -153,11 +217,8 @@ export function createManagedBackend({ opencodePath, logger }) {
         async stop() {
             stopping = true;
             ready = false;
-            if (child && child.exitCode === null) {
-                const exited = new Promise((resolve) => child.once('exit', resolve));
-                killTree(child);
-                await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 5000).unref())]);
-            }
+            clearInterval(heartbeat);
+            await terminate();
             removeIsolatedRoot(dirs?.root);
         },
     });

package/src/opencode/client.js

@@ -65,6 +65,7 @@ export function createOpencodeClient({ baseUrl, username, password, fetchImpl =
         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),
         /** Blocks until the assistant turn finishes; returns { info, parts }. */
         prompt: (sessionId, body, options) => request('POST', `/session/${id(sessionId)}/message`, { body, timeoutMs: 0, ...options }),
         replyPermission: (requestId, reply, message) =>