Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* opencode runner — invokes the real `opencode` binary (SST terminal agent,
* opencode.ai) in a tempdir with a BRIEF.md prompt. Live mode only.
*
* Invocation pattern (verified against a pinned hermetic install, v1.18.18 —
* see docs/mcp/OPENCODE-CLI-PIN.md):
* opencode run "<brief>" --format default
*
* `run` is opencode's headless one-shot: prompt in, final answer text ALONE
* on stdout (banner/UI on stderr), exit 0. `--format default` is passed
* explicitly so an upstream default flip cannot silently change the
* transcript shape. NO `--auto`: MCP tool calls fire in run mode without any
* permission flag (verified — the keyless SMOKE recalled a nonce through
* gbrain_recall with the flag absent). NO `-m`: live mode runs the
* OPERATOR's configured opencode, whose model pin (or the anonymous free
* tier) is the point of the measurement.
*
* Naming: opencode (SST, opencode.ai, npm `opencode-ai`) is not OpenClaw
* (the platform with its own runner) and not the original `opencode` CLI
* that became Crush — the version preamble below makes a mis-bound claimant
* diagnosable (the SST CLI answers `--version` with a BARE semver).
*
* Hermeticity posture (deliberate): live mode runs the OPERATOR's configured
* opencode — the real XDG config/data dirs are inherited unless
* XDG_CONFIG_HOME/XDG_DATA_HOME point elsewhere — against a hermetic BRAIN.
* opencode-specific contamination channel (observed): the user-global
* opencode config is read for EVERY run, and a project opencode.json in the
* cwd spawns its local MCP servers with NO trust gate. Live-mode workspaces
* are harness-created tempdirs (no project config in reach), but a global
* mcp.gbrain entry would bind the operator's REAL brain while the oracle
* probes the hermetic one — `invoke()` logs a loud warning for that case.
* The fully hermetic lane is the door e2e
* (install-real-opencode.serial.test.ts): fresh HOME + XDG dirs.
* OPENCODE_CONFIG_CONTENT (inline whole-config env) is deliberately NOT
* forwarded — it is a config-shadowing channel, and it was observed inert in
* 1.18.18 anyway (OPENCODE-CLI-PIN.md §Path seams).
*
* Binary resolution: $OPENCODE_BIN > `which opencode` > unavailable.
*/
import { execFileSync } from '../../spawn.ts';
import { existsSync, readFileSync } from 'fs';
import { join } from 'path';
import {
BASE_ENV_ALLOWLIST,
detectBinary,
filterAllowlistEnv,
type AgentRunner,
type DetectResult,
type InvokeOpts,
type InvokeResult,
} from '../agent-runner.ts';
import { spawnWithCapture } from '../transcript-capture.ts';
/**
* Allow-list for env propagation when spawning opencode. The base list
* carries ONLY Anthropic + OpenAI provider keys — opencode's headline
* feature is multi-provider, so the delta NAMES the additional provider
* keys a live-lane operator may be running on (xAI, Google, OpenRouter);
* anything not named here silently strips and reads as a misleading
* agent-auth failure. Plus the opencode seams: XDG dirs (config/auth
* relocation for hermetic callers), OPENCODE_CONFIG(_DIR) (observed inert
* in 1.18.18 but forwarded so a future release that activates them behaves
* the way the caller intended), and OPENCODE_DISABLE_AUTOUPDATE (the env
* half of the double autoupdate kill).
*/
const ENV_ALLOWLIST = [
...BASE_ENV_ALLOWLIST,
'XAI_API_KEY',
'GOOGLE_GENERATIVE_AI_API_KEY',
'GEMINI_API_KEY',
'OPENROUTER_API_KEY',
'XDG_CONFIG_HOME',
'XDG_DATA_HOME',
'OPENCODE_CONFIG',
'OPENCODE_CONFIG_DIR',
'OPENCODE_DISABLE_AUTOUPDATE',
];
export class OpencodeRunner implements AgentRunner {
readonly name = 'opencode';
async detect(): Promise<DetectResult> {
return detectBinary('OPENCODE_BIN', 'opencode');
}
async invoke(opts: InvokeOpts): Promise<InvokeResult> {
const detected = await this.detect();
if (!detected.available || !detected.binPath) {
throw new Error(`opencode runner unavailable: ${detected.reason ?? 'unknown'}`);
}
const args = ['run', opts.brief, '--format', 'default'];
const env = filterAllowlistEnv(ENV_ALLOWLIST, opts.env);
this.warnOnGlobalGbrainEntry(env);
// Version preamble: recorded as a plain stdout transcript event. The SST
// CLI answers with a BARE semver (`1.18.18` — no name, no build hash);
// any other shape means a colliding `opencode` claimant is bound.
// execFileSync (no shell) with the SAME filtered env as the turn itself.
try {
const version = execFileSync(detected.binPath, ['--version'], {
encoding: 'utf-8',
stdio: ['ignore', 'pipe', 'ignore'],
timeout: 15_000,
env: env as NodeJS.ProcessEnv,
cwd: opts.cwd,
}).trim();
opts.transcriptSink.write({
ts: Date.now(),
channel: 'stdout',
bytes: Buffer.from(`[opencode-runner preamble] version: ${version}\n`, 'utf-8'),
});
} catch {
// Preamble is diagnostic only — never fail the run for it.
}
const result = await spawnWithCapture(detected.binPath, args, {
cwd: opts.cwd,
env,
timeoutMs: opts.timeoutMs,
transcriptSink: opts.transcriptSink,
});
return { exitCode: result.exitCode, durationMs: result.durationMs };
}
/**
* Loud tripwire for the global-config contamination channel: when the
* config dir opencode will resolve carries an mcp.gbrain entry, a live
* turn routes gbrain tool calls at the operator's REAL brain while the
* oracle probes the hermetic one. Warning only (live mode deliberately
* runs the operator's agent); the hermetic lane is the door e2e. Checks
* BOTH filenames — opencode merges opencode.json AND opencode.jsonc.
*/
private warnOnGlobalGbrainEntry(env: Record<string, string>): void {
try {
const xdg = env.XDG_CONFIG_HOME ?? process.env.XDG_CONFIG_HOME;
const home = env.HOME ?? process.env.HOME;
const cfgDir = xdg ? join(xdg, 'opencode') : home ? join(home, '.config', 'opencode') : null;
if (!cfgDir) return;
for (const file of ['opencode.jsonc', 'opencode.json']) {
const p = join(cfgDir, file);
if (!existsSync(p)) continue;
// Loose containment probe, not a parse: the global config is JSONC
// (comments legal), and a substring hit is enough for a warning.
const text = readFileSync(p, 'utf-8');
if (/"gbrain"\s*:/.test(text) && /"mcp"\s*:/.test(text)) {
console.warn(
`[opencode-runner] WARNING: ${p} carries an mcp.gbrain entry. opencode reads the ` +
"user-global config on every run, so this live turn may bind the OPERATOR'S REAL " +
'brain instead of the hermetic one. Use a scratch HOME/XDG_CONFIG_HOME for clean ' +
'measurements (docs/mcp/OPENCODE-CLI-PIN.md).',
);
return;
}
}
} catch {
// Best-effort tripwire — unreadable/invalid config is not an error here.
}
}
}