@jossuealcala/madre 0.2.0

package/src/adapters/codex.mjs

@@ -0,0 +1,84 @@
+import { runReadonlyProcess } from './process.mjs';
+
+// With a lease, the working root is the lease directory (the only writable
+// place) and the sandbox allows workspace writes; the project stays readable.
+// A TOML value for `-c key=value`: strings quoted, arrays and tables inline.
+export function tomlValue(value) {
+  if (Array.isArray(value)) return `[${value.map(tomlValue).join(', ')}]`;
+  if (value && typeof value === 'object') return `{ ${Object.entries(value).map(([key, item]) => `${/^[A-Za-z0-9_-]+$/.test(key) ? key : JSON.stringify(key)} = ${tomlValue(item)}`).join(', ')} }`;
+  return JSON.stringify(String(value));
+}
+
+// The room's memory as an MCP server for this run only: Codex reads
+// mcp_servers.<name> from its config, and -c overrides it on the command line
+// without touching the user's config.toml.
+export function codexMcpOverrides(memoryServer) {
+  if (!memoryServer) return [];
+  const key = `mcp_servers.${memoryServer.name}`;
+  return [
+    '-c', `${key}.command=${tomlValue(memoryServer.command)}`,
+    '-c', `${key}.args=${tomlValue(memoryServer.args)}`,
+    '-c', `${key}.env=${tomlValue(memoryServer.env ?? {})}`,
+  ];
+}
+
+export function buildCodexArgs({ projectRoot, prompt, model = null, attachments = [], lease = null, scopes = null, memoryServer = null }) {
+  const images = attachments.filter((file) => /^image\//.test(file.contentType ?? ''));
+  return [
+    '--sandbox', lease ? 'workspace-write' : 'read-only',
+    '--ask-for-approval', 'never',
+    // Live web search is a global Codex flag; the human's web scope decides.
+    ...(scopes?.web ? ['--search'] : []),
+    '-C', lease ? lease.outDir : projectRoot,
+    ...codexMcpOverrides(memoryServer),
+    // Image generation is a Codex feature; the human's scope decides per turn.
+    ...(lease && (scopes?.imageGen === false || lease.scopes?.imageGen === false) ? ['-c', 'features.image_generation=false'] : []),
+    'exec',
+    ...(lease ? ['--skip-git-repo-check'] : []),
+    ...(model ? ['--model', model] : []),
+    ...images.flatMap((file) => ['--image', file.path]),
+    '--ephemeral',
+    '--color', 'never',
+    '--json',
+    prompt,
+  ];
+}
+
+export function parseCodexOutput(output) {
+  let text = '';
+  let usage = null;
+  for (const line of output.split('\n').filter(Boolean)) {
+    try {
+      const event = JSON.parse(line);
+      if (event.type === 'item.completed' && event.item?.type === 'agent_message') {
+        text += event.item.text ?? '';
+      }
+      if (event.type === 'turn.completed' && event.usage) {
+        usage = {
+          inputTokens: event.usage.input_tokens ?? 0,
+          cachedInputTokens: event.usage.cached_input_tokens ?? 0,
+          outputTokens: event.usage.output_tokens ?? 0,
+          reasoningTokens: event.usage.reasoning_output_tokens ?? 0,
+          totalTokens: (event.usage.input_tokens ?? 0) + (event.usage.output_tokens ?? 0),
+          source: 'codex-json',
+        };
+      }
+    } catch {
+      // Ignore CLI diagnostics that are not JSON events.
+    }
+  }
+  return { text: text.trim(), usage };
+}
+
+export function invokeCodex({ executable, projectRoot, prompt, timeoutMs = 120000, signal, model = null, attachments = [], lease = null, scopes = null, memoryServer = null }) {
+  return runReadonlyProcess({
+    executable,
+    args: buildCodexArgs({ projectRoot, prompt, model, attachments, lease, scopes, memoryServer }),
+    cwd: lease ? lease.outDir : projectRoot,
+    env: process.env,
+    timeoutMs,
+    signal,
+    label: 'Codex',
+    parse: parseCodexOutput,
+  });
+}

package/src/adapters/gemini.mjs

@@ -0,0 +1,335 @@
+import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runReadonlyProcess } from './process.mjs';
+
+export const geminiReadonlyPolicy = `[[rule]]
+toolName = "*"
+decision = "deny"
+priority = 998
+interactive = false
+denyMessage = "MADRE consultation mode only permits local project reads."
+
+[[rule]]
+toolName = ["read_file", "list_directory", "glob", "grep_search"]
+decision = "allow"
+priority = 999
+interactive = false
+`;
+
+// Only credentials are carried into the isolated home: OAuth tokens, the
+// account marker, the installation id and ~/.gemini/.env (where users may keep
+// GEMINI_API_KEY). Keys stored in the OS keychain need no copy. Hooks,
+// extensions, MCP servers, memory files and history stay behind.
+export const geminiCredentialFiles = ['oauth_creds.json', 'google_accounts.json', 'installation_id', '.env'];
+
+// The read-only policy plus, under a lease, allow rules for the write tools
+// whose file_path argument starts with the lease directory. Plan mode would
+// block every write regardless of policy, so a lease uses approval "default":
+// headless Gemini cannot prompt, so anything the policy does not allow fails.
+export function geminiLeasePolicy(outDir, { control = false } = {}) {
+  const escaped = outDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const forbidden = control ? `
+[[rule]]
+toolName = ["write_file", "replace", "edit", "run_shell_command"]
+argsPattern = '${escaped}/(\\.git|\\.pulse|\\.env)'
+decision = "deny"
+priority = 1100
+interactive = false
+` : '';
+  return `${geminiReadonlyPolicy}
+[[rule]]
+toolName = ["write_file", "replace", "edit"]
+argsPattern = '"file_path"\\s*:\\s*"${escaped}/'
+decision = "allow"
+priority = 1000
+interactive = false
+${forbidden}`;
+}
+
+export const geminiWebPolicy = `
+[[rule]]
+toolName = ["google_web_search", "web_fetch"]
+decision = "allow"
+priority = 999
+interactive = false
+`;
+
+export function geminiPolicy({ lease = null, scopes = null, imageStudio = null, memoryServer = null } = {}) {
+  return `${lease ? geminiLeasePolicy(lease.outDir, { control: Boolean(lease.control) }) : geminiReadonlyPolicy}${scopes?.web ? geminiWebPolicy : ''}${imageStudio && lease ? geminiImagePolicy(imageStudio) : ''}${memoryServer ? geminiMemoryPolicy(memoryServer) : ''}`;
+}
+
+export function geminiMemoryPolicy(memoryServer) {
+  const names = memoryServer.tools.flatMap((tool) => [tool, `${memoryServer.name}__${tool}`]);
+  return `
+[[rule]]
+toolName = [${names.map((name) => `"${name}"`).join(', ')}]
+decision = "allow"
+priority = 1000
+interactive = false
+`;
+}
+
+// Gemini CLI reads "@something" in a prompt as a file to include, even in
+// headless mode, and fuzzily resolves "@claude" to CLAUDE.md. Its parser skips
+// an @ preceded by a backslash, so every handle goes in as \@name; the model
+// is told what that means and its reply is unescaped on the way out.
+export const GEMINI_MENTION_NOTE = 'Note: in this prompt every @handle is written as \\@handle (your CLI would otherwise read @name as a file to include). Read \\@name as @name and write handles plainly as @name in your reply.';
+export function escapeGeminiMentions(text) {
+  return String(text ?? '').replace(/(^|[^\\])@(?=[\w./~-])/g, '$1\\@');
+}
+export const unescapeGeminiMentions = (text) => String(text ?? '').replace(/\\@/g, '@');
+
+export function buildGeminiArgs({ projectRoot, prompt, policyPath, model = null, attachmentsDir = null, lease = null }) {
+  const includes = [projectRoot, attachmentsDir, lease?.outDir].filter(Boolean).join(',');
+  const escaped = escapeGeminiMentions(prompt);
+  const safePrompt = escaped !== prompt ? `${GEMINI_MENTION_NOTE}\n\n${escaped}` : prompt;
+  return [
+    ...(model && model !== 'auto' ? ['--model', model] : []),
+    '--approval-mode', lease ? 'default' : 'plan',
+    // stream-json emits init / tool_use / message deltas / result as JSONL, so
+    // MADRE can tell a thinking Gemini from a hung one.
+    '--output-format', 'stream-json',
+    '--skip-trust',
+    '--include-directories', includes,
+    '--policy', policyPath,
+    '--prompt', safePrompt,
+  ];
+}
+
+export function buildGeminiEnvironment({ runtimeRoot, environment = process.env }) {
+  return {
+    ...environment,
+    // Storage resolves ~/.gemini from this root, so settings, hooks and
+    // extensions are read from the temporary home instead of the real one.
+    GEMINI_CLI_HOME: runtimeRoot,
+    // The launcher otherwise re-spawns itself in a second process that owns
+    // the request; a SIGTERM to the launcher would not stop the model call.
+    GEMINI_CLI_NO_RELAUNCH: 'true',
+  };
+}
+
+export function isolateGeminiSettings(settings, { imageStudio = null, memoryServer = null } = {}) {
+  const auth = settings?.security?.auth;
+  const isolated = auth ? { security: { auth } } : {};
+  for (const server of [memoryServer, imageStudio]) {
+    if (!server) continue;
+    isolated.mcpServers ??= {};
+    isolated.mcpServers[server.name] = { command: server.command, args: server.args, env: server.env, trust: true };
+  }
+  return isolated;
+}
+
+export function geminiImagePolicy(imageStudio) {
+  return `
+[[rule]]
+toolName = ["${imageStudio.tool}", "${imageStudio.name}__${imageStudio.tool}"]
+decision = "allow"
+priority = 1000
+interactive = false
+`;
+}
+
+export async function prepareGeminiHome({ runtimeRoot, sourceHome = join(homedir(), '.gemini'), imageStudio = null, memoryServer = null }) {
+  const geminiDir = join(runtimeRoot, '.gemini');
+  await mkdir(geminiDir, { recursive: true, mode: 0o700 });
+  for (const name of geminiCredentialFiles) {
+    await copyFile(join(sourceHome, name), join(geminiDir, name)).catch((error) => {
+      if (error.code !== 'ENOENT') throw error;
+    });
+  }
+  let settings = {};
+  try {
+    settings = JSON.parse(await readFile(join(sourceHome, 'settings.json'), 'utf8'));
+  } catch (error) {
+    if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
+  }
+  await writeFile(join(geminiDir, 'settings.json'), JSON.stringify(isolateGeminiSettings(settings, { imageStudio, memoryServer })), { mode: 0o600 });
+  return geminiDir;
+}
+
+function usageFromStats(stats) {
+  const models = Object.values(stats?.models ?? {});
+  if (!models.length) return null;
+  const totals = models.reduce((usage, model) => {
+    // Two shapes exist: the older { tokens: { prompt, candidates, total, cached, thoughts } }
+    // and stream-json's flat { input_tokens, output_tokens, total_tokens, cached }.
+    const tokens = model?.tokens ?? model ?? {};
+    const input = tokens.prompt ?? tokens.input_tokens ?? tokens.input ?? 0;
+    const output = tokens.candidates ?? tokens.output_tokens ?? 0;
+    usage.inputTokens += input;
+    usage.cachedInputTokens += tokens.cached ?? 0;
+    usage.outputTokens += output;
+    usage.reasoningTokens += tokens.thoughts ?? 0;
+    usage.totalTokens += tokens.total ?? tokens.total_tokens ?? (input + output);
+    return usage;
+  }, { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, reasoningTokens: 0, totalTokens: 0, source: 'gemini-json' });
+  return totals;
+}
+
+// Accepts stream-json (JSONL events) and, for compatibility, the single-object
+// output of `--output-format json`.
+export function parseGeminiOutput(output) {
+  const trimmed = String(output ?? '').trim();
+  if (!trimmed) return { text: '', usage: null };
+  const lines = trimmed.split('\n').map((line) => line.trim()).filter(Boolean);
+  const events = [];
+  for (const line of lines) {
+    try { events.push(JSON.parse(line)); } catch { /* diagnostics between events */ }
+  }
+  if (events.length === 1 && !events[0].type && (events[0].response !== undefined || events[0].error || events[0].stats)) {
+    const result = events[0];
+    if (result.error) return { text: '', usage: null, error: result.error.message ?? 'Gemini returned an error.' };
+    return { text: typeof result.response === 'string' ? unescapeGeminiMentions(result.response.trim()) : '', usage: usageFromStats(result.stats) };
+  }
+  let text = '';
+  let usage = null;
+  let error = null;
+  let toolCalls = 0;
+  for (const event of events) {
+    if (event.type === 'message' && event.role === 'assistant' && typeof event.content === 'string') text += event.content;
+    if (event.type === 'tool_use') toolCalls += 1;
+    if (event.type === 'error' || (event.type === 'result' && event.status && event.status !== 'success')) {
+      error = event.error?.message ?? event.message ?? `Gemini finished with status ${event.status ?? 'error'}.`;
+    }
+    if (event.type === 'result') usage = usageFromStats(event.stats);
+  }
+  return { text: unescapeGeminiMentions(text.trim()), usage, toolCalls, ...(error ? { error } : {}) };
+}
+
+// Best-effort removal of the temporary home. A killed Gemini may still be
+// flushing files for a moment, which makes a single recursive rm fail with
+// ENOTEMPTY; cleanup must never replace the real outcome of the turn.
+export async function cleanupRuntimeRoot(runtimeRoot, { attempts = 6, delayMs = 250 } = {}) {
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      await rm(runtimeRoot, { recursive: true, force: true });
+      return true;
+    } catch (error) {
+      if (attempt === attempts) {
+        console.error(`MADRE could not remove Gemini's temporary home ${runtimeRoot}: ${error.message}`);
+        return false;
+      }
+      await new Promise((resolve) => setTimeout(resolve, delayMs * attempt));
+    }
+  }
+  return false;
+}
+
+// Gemini CLI retries HTTP 429 (quota / rate limit) with exponential backoff
+// and prints only stack traces to stderr while it waits. From the room that
+// looked like a hang; naming it lets the human act on it.
+export function diagnoseGeminiStderr(stderr) {
+  const text = String(stderr ?? '');
+  if (/prepayment credits are depleted/i.test(text)) {
+    return { code: 'CREDITS_DEPLETED', message: 'Google says the AI Studio project behind this Gemini key has no prepaid credits left; every request is refused (HTTP 429) until it is topped up.', hint: 'Add credits at https://ai.studio/projects, or switch the Gemini CLI to another key.' };
+  }
+  if (/status:\s*429|\b429\b|RESOURCE_EXHAUSTED|rate ?limit|quota exceeded/i.test(text)) {
+    const router = /ClassifierStrategy|\.route\b/.test(text);
+    return {
+      code: 'RATE_LIMITED',
+      message: `Google is rate-limiting this Gemini key (HTTP 429)${router ? ' while its "auto" router picked a model' : ''}; the CLI kept retrying with backoff.`,
+      hint: 'Wait a minute, or pick an explicit model such as gemini-3-flash-preview to skip the router; check the key\'s quota at aistudio.google.com.',
+    };
+  }
+  if (/status:?\s*503|UNAVAILABLE|high demand/i.test(text)) {
+    return { code: 'UNAVAILABLE', message: 'Google reported the model as unavailable (HTTP 503) and the CLI kept retrying.', hint: 'Try again shortly or choose another model.' };
+  }
+  if (/status:\s*40[13]|PERMISSION_DENIED|API key not valid|IneligibleTierError/i.test(text)) {
+    return { code: 'AUTH', message: 'Google rejected the Gemini credentials.', hint: 'Run `gemini` and use /auth, or check GEMINI_API_KEY.' };
+  }
+  return null;
+}
+
+// Gemini is bimodal in practice: it answers in 10–60 s or never at all,
+// printing nothing after startup. With stream-json every tool call and text
+// delta is activity, so a long silence means a hang; one retry usually lands.
+export async function invokeGemini({
+  executable,
+  projectRoot,
+  prompt,
+  timeoutMs = 120000,
+  signal,
+  model = null,
+  attachments = [],
+  lease = null,
+  scopes = null,
+  imageStudio = null,
+  memoryServer = null,
+  idleTimeoutMs = Number(process.env.PULSE_GEMINI_IDLE_MS ?? 90000),
+  retries = Number(process.env.PULSE_GEMINI_RETRIES ?? 1),
+  fallbackModel = process.env.PULSE_GEMINI_FALLBACK_MODEL ?? 'gemini-2.5-flash',
+  failFastMs = 15000,
+  run = runReadonlyProcess,
+}) {
+  const runtimeRoot = await mkdtemp(join(tmpdir(), 'pulse-gemini-'));
+  const policyPath = join(runtimeRoot, 'readonly.toml');
+  try {
+    await writeFile(policyPath, geminiPolicy({ lease, scopes, imageStudio: lease ? imageStudio : null, memoryServer }), { mode: 0o600 });
+    await prepareGeminiHome({ runtimeRoot, imageStudio: lease ? imageStudio : null, memoryServer });
+    let attempt = 0;
+    let currentModel = model;
+    let switched = false;
+    for (;;) {
+      attempt += 1;
+      // The CLI retries a 503 or 429 with backoff for minutes while stderr
+      // fills with stack traces. Read stderr as it comes and stop as soon as
+      // the condition is clear: credits/auth at once, capacity after a grace.
+      let firstSeenAt = null;
+      const watchStderr = (stderr) => {
+        const diagnosis = diagnoseGeminiStderr(stderr);
+        if (!diagnosis) return null;
+        firstSeenAt ??= Date.now();
+        const terminal = diagnosis.code === 'CREDITS_DEPLETED' || diagnosis.code === 'AUTH';
+        if (!terminal && Date.now() - firstSeenAt < failFastMs) return null;
+        return Object.assign(new Error(`${diagnosis.message} ${diagnosis.hint}`), { code: diagnosis.code, diagnosis });
+      };
+      try {
+        return await run({
+          executable,
+          args: buildGeminiArgs({ projectRoot, prompt, policyPath, model: currentModel, attachmentsDir: attachments[0]?.dir ?? null, lease }),
+          cwd: runtimeRoot,
+          env: buildGeminiEnvironment({ runtimeRoot }),
+          timeoutMs,
+          idleTimeoutMs,
+          watchStderr,
+          signal,
+          label: 'Gemini',
+          parse: parseGeminiOutput,
+        });
+      } catch (error) {
+        const produced = parseGeminiOutput(error.partialOutput ?? '').text;
+        const diagnosis = error.diagnosis ?? diagnoseGeminiStderr(error.partialStderr ?? error.stderr ?? '');
+        if (diagnosis?.code === 'AUTH' || diagnosis?.code === 'CREDITS_DEPLETED') {
+          error.message = `${diagnosis.message} ${diagnosis.hint}`;
+          error.code = diagnosis.code;
+          throw error;
+        }
+        // Capacity trouble (503) or a rate limit on the chosen model: one more
+        // try on a lighter, explicit model before giving up.
+        if ((diagnosis?.code === 'UNAVAILABLE' || diagnosis?.code === 'RATE_LIMITED') && !produced && !signal?.aborted && fallbackModel && !switched && currentModel !== fallbackModel) {
+          switched = true;
+          currentModel = fallbackModel;
+          continue;
+        }
+        if (diagnosis?.code === 'UNAVAILABLE' || diagnosis?.code === 'RATE_LIMITED') {
+          error.message = `${diagnosis.message} ${diagnosis.hint}${switched ? ` (also tried ${fallbackModel})` : ''}`;
+          error.code = diagnosis.code;
+          throw error;
+        }
+        if (error.code === 'IDLE' && !produced && attempt <= retries && !signal?.aborted) {
+          continue;
+        }
+        if (diagnosis) error.message = `${error.message} ${diagnosis.message} ${diagnosis.hint}`;
+        else if ((error.code === 'TIMEOUT' || error.code === 'IDLE') && error.partialStderr?.trim()) {
+          const lastStderr = error.partialStderr.trim().split('\n').filter(Boolean).at(-1);
+          if (lastStderr) error.message = `${error.message} stderr: ${lastStderr.slice(0, 200)}`;
+        }
+        if (attempt > 1) error.message = `${error.message} (retried ${attempt - 1}×)`;
+        throw error;
+      }
+    }
+  } finally {
+    void cleanupRuntimeRoot(runtimeRoot);
+  }
+}

package/src/adapters/opencode.mjs

@@ -0,0 +1,148 @@
+import { runReadonlyProcess } from './process.mjs';
+
+const readonlyConfig = {
+  share: 'disabled',
+  agent: {
+    'pulse-readonly': {
+      description: 'MADRE project consultation without mutations',
+      mode: 'primary',
+      prompt: 'Answer the user directly. Inspect project files only when necessary. Never modify files, run commands, browse the web, or launch subagents.',
+      permission: {
+        '*': 'deny',
+        read: 'allow',
+        glob: 'allow',
+        grep: 'allow',
+        list: 'allow',
+      },
+    },
+  },
+};
+
+// Optional provider/model override (e.g. "openai/gpt-5.6-sol"). Without it,
+// OpenCode picks its own default provider, which may not be the one the user
+// actually signed in to.
+export function buildOpenCodeArgs({ projectRoot, prompt, model = process.env.PULSE_OPENCODE_MODEL, attachments = [] }) {
+  return [
+    '--pure',
+    'run',
+    '--format', 'json',
+    '--agent', 'pulse-readonly',
+    ...(model ? ['--model', model] : []),
+    ...attachments.flatMap((file) => ['--file', file.path]),
+    '--dir', projectRoot,
+    prompt,
+  ];
+}
+
+export function leaseConfig(outDir, { control = false } = {}) {
+  const forbidden = control ? Object.fromEntries(['.git/**', '.pulse/**', '.env', '.env.*', '**/.env', '**/.env.*'].map((glob) => [`${outDir}/${glob}`, 'deny'])) : {};
+  return {
+    ...readonlyConfig,
+    agent: {
+      'pulse-readonly': {
+        ...readonlyConfig.agent['pulse-readonly'],
+        prompt: control
+          ? 'Answer the user directly. You are in CONTROL of this project: create and edit files anywhere inside it except .git, .pulse and .env files. Do not run commands, browse the web, or launch subagents.'
+          : 'Answer the user directly. Inspect project files when necessary. You may create or edit files only inside the creation lease directory named in the request; never elsewhere. Do not run commands, browse the web, or launch subagents.',
+        permission: {
+          ...readonlyConfig.agent['pulse-readonly'].permission,
+          edit: { '*': 'deny', [`${outDir}/**`]: 'allow', ...forbidden },
+        },
+      },
+    },
+  };
+}
+
+export function openCodeConfig({ lease = null, scopes = null, imageStudio = null, memoryServer = null } = {}) {
+  let config = lease ? leaseConfig(lease.outDir, { control: Boolean(lease.control) }) : readonlyConfig;
+  if (scopes?.web) {
+    config = {
+      ...config,
+      agent: {
+        'pulse-readonly': {
+          ...config.agent['pulse-readonly'],
+          prompt: config.agent['pulse-readonly'].prompt.replace('browse the web, ', ''),
+          permission: { ...config.agent['pulse-readonly'].permission, webfetch: 'allow', websearch: 'allow' },
+        },
+      },
+    };
+  }
+  if (imageStudio && lease) {
+    config = {
+      ...config,
+      mcp: { ...(config.mcp ?? {}), [imageStudio.name]: { type: 'local', command: [imageStudio.command, ...imageStudio.args], environment: imageStudio.env, enabled: true } },
+    };
+  }
+  if (memoryServer) {
+    config = {
+      ...config,
+      mcp: { ...(config.mcp ?? {}), [memoryServer.name]: { type: 'local', command: [memoryServer.command, ...memoryServer.args], environment: memoryServer.env, enabled: true } },
+      agent: {
+        'pulse-readonly': {
+          ...config.agent['pulse-readonly'],
+          permission: {
+            ...config.agent['pulse-readonly'].permission,
+            [`${memoryServer.name}*`]: 'allow',
+            ...Object.fromEntries(memoryServer.tools.map((tool) => [`${memoryServer.name}_${tool}`, 'allow'])),
+          },
+        },
+      },
+    };
+  }
+  return config;
+}
+
+export function openCodeEnvironment(environment = process.env, { lease = null, scopes = null, imageStudio = null, memoryServer = null } = {}) {
+  return {
+    ...environment,
+    OPENCODE_AUTO_SHARE: 'false',
+    OPENCODE_CONFIG_CONTENT: JSON.stringify(openCodeConfig({ lease, scopes, imageStudio, memoryServer })),
+    OPENCODE_DISABLE_AUTOUPDATE: 'true',
+  };
+}
+
+export function parseOpenCodeOutput(output) {
+  const text = [];
+  let usage = null;
+  let error = null;
+  for (const line of output.split('\n').filter(Boolean)) {
+    try {
+      const event = JSON.parse(line);
+      if (event.type === 'error' && event.error) {
+        const detail = event.error.data?.message ?? event.error.message ?? '';
+        error = [event.error.name, detail].filter(Boolean).join(': ') || 'OpenCode returned an error.';
+      }
+      if (event.type === 'text' && typeof event.part?.text === 'string') {
+        text.push(event.part.text);
+      }
+      if (event.type === 'step_finish' && event.part?.tokens) {
+        const tokens = event.part.tokens;
+        usage = {
+          inputTokens: tokens.input ?? 0,
+          cachedInputTokens: tokens.cache?.read ?? 0,
+          outputTokens: tokens.output ?? 0,
+          reasoningTokens: tokens.reasoning ?? 0,
+          totalTokens: tokens.total ?? ((tokens.input ?? 0) + (tokens.output ?? 0)),
+          costUsd: event.part.cost ?? null,
+          source: 'opencode-json',
+        };
+      }
+    } catch {
+      // Ignore non-event diagnostic lines; stderr is reported when the process fails.
+    }
+  }
+  return { text: text.join('').trim(), usage, ...(error ? { error } : {}) };
+}
+
+export function invokeOpenCode({ executable, projectRoot, prompt, timeoutMs = 120000, signal, model = null, attachments = [], lease = null, scopes = null, imageStudio = null, memoryServer = null }) {
+  return runReadonlyProcess({
+    executable,
+    args: buildOpenCodeArgs({ projectRoot, prompt, attachments, ...(model ? { model } : {}) }),
+    cwd: projectRoot,
+    env: openCodeEnvironment(process.env, { lease, scopes, imageStudio, memoryServer }),
+    timeoutMs,
+    signal,
+    label: 'OpenCode',
+    parse: parseOpenCodeOutput,
+  });
+}