Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

test(opencode door): surface free-tier quota refusals instead of a silent 8-minute hang (#6049)

garrytan69624ac8b43d
diff --git a/test/e2e/install-real-opencode.serial.test.ts b/test/e2e/install-real-opencode.serial.test.ts
index f9e0b4e59c..f401e2dcdc 100644
--- a/test/e2e/install-real-opencode.serial.test.ts
+++ b/test/e2e/install-real-opencode.serial.test.ts
@@ -452,13 +452,16 @@ describe.skipIf(!CAN_RUN_KEYLESS)('install real-opencode door — keyless tier (
const parsed = parseOpencodeJsonl(turn.finalText.split('\n'));
finalText = parsed.finalText;
toolCalls = parsed.toolCalls;
- errors = parsed.errors;
+ errors = [...parsed.errors, ...turn.streamErrors];
try { writeFileSync(join(home, 'door-turn.jsonl'), turn.finalText); } catch { /* evidence */ }
if (turn.exitCode === 0 && finalText.includes(nonce)) break;
+ // A quota refusal is not transient: a second turn only spends more of the same quota.
+ if (turn.providerRefusal) break;
if (attempt === 1) await new Promise((r) => setTimeout(r, 3_000));
}
- // #6049: a turn the provider refused (e.g. FreeTierError 403) fails with its own message, not `Received: ""`.
+ // #6049: a turn the provider refused (a FreeTierError 403, or the free tier's "Free usage limit
+ // reached" quota that opencode retries silently for hours) fails with its own message, not `Received: ""`.
if (!finalText.includes(nonce) && errors.length) throw new Error(`opencode turn ended with provider error(s): ${errors.join('; ')}`);
expect(finalText).toContain(nonce);
expect(finalText).not.toContain('NO-GBRAIN-TOOL');
diff --git a/test/helpers/agent-harness.ts b/test/helpers/agent-harness.ts
index 8cd2fa7137..3a77f207fa 100644
--- a/test/helpers/agent-harness.ts
+++ b/test/helpers/agent-harness.ts
@@ -724,6 +724,8 @@ export interface OneShotSpawnResult {
exitCode: number | null;
timedOut: boolean;
stderrText: string;
+ /** The value abortWhen returned when it ended the run early. */
+ abortReason?: string;
}
/**
@@ -738,6 +740,9 @@ export async function runOneShotSpawn(opts: {
cwd: string;
env: NodeJS.ProcessEnv;
timeoutMs: number;
+ /** Polled every second; a returned string kills the child like a timeout
+ * and comes back as abortReason. */
+ abortWhen?: () => string | undefined;
}): Promise<OneShotSpawnResult> {
const proc = Bun.spawn(opts.argv, {
cwd: opts.cwd,
@@ -748,11 +753,21 @@ export async function runOneShotSpawn(opts: {
});
let timedOut = false;
- const timer = setTimeout(() => {
- timedOut = true;
+ let abortReason: string | undefined;
+ const kill = () => {
try { proc.kill(); } catch { /* already dead */ }
setTimeout(() => { try { proc.kill(9); } catch { /* already dead */ } }, 5_000);
+ };
+ const timer = setTimeout(() => {
+ timedOut = true;
+ kill();
}, opts.timeoutMs);
+ const abortPoll = opts.abortWhen && setInterval(() => {
+ abortReason = opts.abortWhen!();
+ if (abortReason === undefined) return;
+ clearInterval(abortPoll);
+ kill();
+ }, 1_000);
const drainCap = opts.timeoutMs + 30_000;
// The cap timer is CLEARED when the real promise wins — an uncancelled
@@ -771,12 +786,14 @@ export async function runOneShotSpawn(opts: {
]);
const exitCode = await bounded(proc.exited, 124);
clearTimeout(timer);
+ clearInterval(abortPoll);
return {
finalText: stdout.trim(),
exitCode: timedOut ? 124 : exitCode,
timedOut,
stderrText,
+ ...(abortReason !== undefined ? { abortReason } : {}),
};
}
@@ -1144,17 +1161,58 @@ export interface OpencodeTurnOpts {
paid?: boolean;
}
+export interface OpencodeTurnResult extends OneShotSpawnResult {
+ /** error.error of each main-turn `stream error` opencode logged during this turn. */
+ streamErrors: string[];
+ /** The quota/rate-limit refusal that ended the turn early, if any. */
+ providerRefusal?: string;
+}
+
+/** #6049: opencode answers a quota refusal (free tier: "Free usage limit
+ * reached", HTTP 429) by retrying after the server's retry-after, hours
+ * later, with nothing on stdout. Waiting can never produce an answer. */
+const OPENCODE_QUOTA_REFUSAL = /usage limit|rate limit|quota/i;
+
+/** Main-turn (`small=false`) `stream error` lines appended to opencode's
+ * file log (<XDG_DATA_HOME>/opencode/log) since `offsets` was taken. */
+function opencodeStreamErrorsSince(logDir: string, offsets: Map<string, number>): string[] {
+ let files: string[];
+ try { files = fs.readdirSync(logDir).sort(); } catch { return []; }
+ const errors: string[] = [];
+ for (const name of files) {
+ let text: string;
+ try { text = fs.readFileSync(path.join(logDir, name)).subarray(offsets.get(name) ?? 0).toString('utf-8'); } catch { continue; }
+ for (const line of text.split('\n')) {
+ if (!line.includes('message="stream error"') || !line.includes(' small=false ')) continue;
+ const m = line.match(/error\.error="((?:[^"\\]|\\.)*)"/);
+ errors.push(m ? m[1].replace(/\\(.)/g, '$1') : line);
+ }
+ }
+ return errors;
+}
+
+function opencodeLogOffsets(logDir: string): Map<string, number> {
+ const offsets = new Map<string, number>();
+ try {
+ for (const name of fs.readdirSync(logDir)) offsets.set(name, fs.statSync(path.join(logDir, name)).size);
+ } catch { /* no log yet */ }
+ return offsets;
+}
+
/**
* Drive one `opencode run` turn against a hermetic HOME + XDG dirs. Default
* format prints the final answer ALONE on stdout (banner/UI on stderr —
* observed); no permission flag is needed for MCP tool calls (observed:
* --auto not passed, deliberately). Shared spawn core: kill(9) escalation +
- * bounded drain.
+ * bounded drain. Provider stream errors come from opencode's own file log;
+ * a quota refusal ends the turn at once instead of at the timeout.
*/
-export async function opencodeOneShotTurn(opts: OpencodeTurnOpts): Promise<OneShotSpawnResult> {
+export async function opencodeOneShotTurn(opts: OpencodeTurnOpts): Promise<OpencodeTurnResult> {
const bin = resolveOpencodeBinary();
if (!bin) throw new Error('opencodeOneShotTurn: opencode binary not found');
- return runOneShotSpawn({
+ const logDir = path.join(opts.home, '.local', 'share', 'opencode', 'log');
+ const offsets = opencodeLogOffsets(logDir);
+ const res = await runOneShotSpawn({
argv: [
bin, 'run', opts.prompt, '--pure',
'--format', opts.format ?? 'default',
@@ -1163,7 +1221,14 @@ export async function opencodeOneShotTurn(opts: OpencodeTurnOpts): Promise<OneSh
cwd: opts.cwd,
env: opencodeChildEnv(opts.home, { binDir: opts.binDir, paid: opts.paid }),
timeoutMs: opts.timeoutMs ?? 240_000,
+ abortWhen: () => opencodeStreamErrorsSince(logDir, offsets).find((e) => OPENCODE_QUOTA_REFUSAL.test(e)),
});
+ const { abortReason, ...rest } = res;
+ return {
+ ...rest,
+ streamErrors: opencodeStreamErrorsSince(logDir, offsets),
+ ...(abortReason !== undefined ? { providerRefusal: abortReason } : {}),
+ };
}
// ────────────────────────────────────────────────────────────────────────────
diff --git a/test/helpers/agent-harness.unit.test.ts b/test/helpers/agent-harness.unit.test.ts
index 5bd4689394..9925e2bfba 100644
--- a/test/helpers/agent-harness.unit.test.ts
+++ b/test/helpers/agent-harness.unit.test.ts
@@ -13,7 +13,7 @@
* leaks into sibling tests.
*/
import { describe, test, expect } from 'bun:test';
-import { mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import {
@@ -35,6 +35,7 @@ import {
seedOpencodeConfig,
parseOpencodeJsonl,
runOneShotSpawn,
+ opencodeOneShotTurn,
} from './agent-harness.ts';
import { withEnv } from './with-env.ts';
@@ -688,3 +689,83 @@ describe('runOneShotSpawn — drain-cap timer hygiene', () => {
}
});
});
+
+describe('opencodeOneShotTurn — provider refusals logged by opencode surface instead of a silent hang (#6049)', () => {
+ // opencode 1.18.18 answers a free-tier quota refusal ("Free usage limit
+ // reached", HTTP 429) by retrying after the server's retry-after (hours),
+ // printing nothing on stdout; the only trace is the "stream error" line in
+ // <XDG_DATA_HOME>/opencode/log/opencode.log. These stubs replay that exact
+ // log shape so the turn's behavior is pinned without a network call.
+ const QUOTA_LINE =
+ 'timestamp=2026-11-01T16:05:31.565Z level=ERROR run=a6ecc561 message="stream error" providerID=opencode modelID=big-pickle ' +
+ 'session.id=ses_x small=false agent=build mode=primary error.error="AI_APICallError: Free usage limit reached. ' +
+ 'Free models work in OpenCode (https://opencode.ai); subscribe to OpenCode Go to keep going: https://opencode.ai/go"';
+ const TITLE_LINE =
+ 'timestamp=2026-11-01T16:05:37.341Z level=ERROR run=a6ecc561 message="stream error" providerID=opencode modelID=big-pickle ' +
+ 'session.id=ses_x small=true agent=title mode=primary error.error="AI_RetryError: Failed after 3 attempts. Last error: upstream 502"';
+ const TRANSIENT_LINE =
+ 'timestamp=2026-11-01T16:05:31.565Z level=ERROR run=b1 message="stream error" providerID=opencode modelID=big-pickle ' +
+ 'session.id=ses_y small=false agent=build mode=primary error.error="AI_APICallError: Bad Gateway"';
+
+ function stubOpencode(dir: string, body: string): string {
+ const bin = join(dir, 'opencode');
+ writeFileSync(bin, `#!/bin/sh\nlog="$XDG_DATA_HOME/opencode/log"\nmkdir -p "$log"\n${body}\n`, { mode: 0o755 });
+ return bin;
+ }
+
+ test('a quota refusal ends the turn within seconds with the provider message (was: timeout with empty stdout)', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'gb-oc-quota-'));
+ try {
+ const home = join(dir, 'home');
+ const bin = stubOpencode(dir, `printf '%s\\n%s\\n' '${TITLE_LINE}' '${QUOTA_LINE}' >> "$log/opencode.log"\nexec sleep 600`);
+ const t0 = Date.now();
+ const turn = await withEnv({ OPENCODE_BIN: bin }, () =>
+ opencodeOneShotTurn({ prompt: 'p', cwd: dir, home, timeoutMs: 30_000, format: 'json' }));
+ expect(Date.now() - t0).toBeLessThan(15_000);
+ expect(turn.timedOut).toBe(false);
+ expect(turn.finalText).toBe('');
+ expect(turn.providerRefusal).toBe(
+ 'AI_APICallError: Free usage limit reached. Free models work in OpenCode (https://opencode.ai); subscribe to OpenCode Go to keep going: https://opencode.ai/go',
+ );
+ expect(turn.streamErrors).toEqual([turn.providerRefusal!]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ }, 60_000);
+
+ test('a transient main-stream error is reported but never cuts short a turn opencode recovers from', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'gb-oc-transient-'));
+ try {
+ const home = join(dir, 'home');
+ const text = JSON.stringify({ type: 'text', part: { text: 'recovered' } });
+ const bin = stubOpencode(dir, `printf '%s\\n' '${TRANSIENT_LINE}' >> "$log/opencode.log"\nsleep 3\nprintf '%s\\n' '${text}'`);
+ const turn = await withEnv({ OPENCODE_BIN: bin }, () =>
+ opencodeOneShotTurn({ prompt: 'p', cwd: dir, home, timeoutMs: 30_000, format: 'json' }));
+ expect(turn.exitCode).toBe(0);
+ expect(turn.providerRefusal).toBeUndefined();
+ expect(parseOpencodeJsonl(turn.finalText.split('\n')).finalText).toBe('recovered');
+ expect(turn.streamErrors).toEqual(['AI_APICallError: Bad Gateway']);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ }, 60_000);
+
+ test('stream errors already in the log from an earlier turn in the same home are not attributed to this turn', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'gb-oc-offset-'));
+ try {
+ const home = join(dir, 'home');
+ const logDir = join(home, '.local', 'share', 'opencode', 'log');
+ mkdirSync(logDir, { recursive: true });
+ writeFileSync(join(logDir, 'opencode.log'), `${QUOTA_LINE}\n`);
+ const text = JSON.stringify({ type: 'text', part: { text: 'ok' } });
+ const bin = stubOpencode(dir, `printf '%s\\n' '${text}'`);
+ const turn = await withEnv({ OPENCODE_BIN: bin }, () =>
+ opencodeOneShotTurn({ prompt: 'p', cwd: dir, home, timeoutMs: 30_000, format: 'json' }));
+ expect(turn.exitCode).toBe(0);
+ expect(turn.providerRefusal).toBeUndefined();
+ expect(turn.streamErrors).toEqual([]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ }, 60_000);
+});