@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/code/runtime.ts

@@ -0,0 +1,757 @@
+import { spawn, spawnSync, type ChildProcess } from "node:child_process"
+import { existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+import { createOpencodeClient, type OpencodeClient } from "@opencode-ai/sdk/v2"
+
+import { entraGateway } from "../entra.ts"
+import { missingKey, type LlmProfile } from "../llm.ts"
+import type { CodeEvent, Usage } from "../types.ts"
+import { envRefs, withoutNames } from "../childEnv.ts"
+import { addUsage, recordUsage, type Role } from "../usage.ts"
+import { linkSkills, type Skill, type SkillAgent } from "../skills/registry.ts"
+import { EXE, githubDigest, installTool, isMusl, toolPath, type Log } from "../tools.ts"
+import { RESULT_SCHEMA, testAgentPrompt, type AgentReport } from "./prompt.ts"
+import { protectPatterns } from "./worktree.ts"
+
+export const AGENT_NAME = "forgeqe-test"
+
+/** Matches the agent runtime SDK version in package.json. */
+export const OPENCODE_VERSION = "1.18.33"
+const OPENCODE_BIN = `opencode${EXE}`
+
+function managedOpencode(): string {
+  return toolPath("opencode", OPENCODE_VERSION, OPENCODE_BIN)
+}
+
+/** The agent runtime binary: configured path or name, then PATH, then the installer's bin directory, then one ForgeQE downloaded. */
+export function findOpencode(configured?: string): string | null {
+  if (configured) {
+    if (/[\\/]/.test(configured)) return existsSync(configured) ? configured : null
+    return Bun.which(configured)
+  }
+  const onPath = Bun.which("opencode")
+  if (onPath) return onPath
+  for (const c of [path.join(os.homedir(), ".opencode", "bin", OPENCODE_BIN), managedOpencode()]) if (existsSync(c)) return c
+  return null
+}
+
+/** Agent runtime release asset for this machine. x64 uses the baseline build so CPUs without AVX2 work too. */
+export function opencodeAsset(platform: string = process.platform, arch: string = process.arch, musl = isMusl()): string | null {
+  const cpu = ({ x64: "x64-baseline", arm64: "arm64" } as Record<string, string>)[arch]
+  if (!cpu) return null
+  if (platform === "darwin") return `opencode-darwin-${cpu}.zip`
+  if (platform === "linux") return `opencode-linux-${cpu}${musl ? "-musl" : ""}.tar.gz`
+  if (platform === "win32") return `opencode-windows-${cpu}.zip`
+  return null
+}
+
+/** findOpencode, else download the pinned agent runtime into ~/.forgeqe/tools. Null when code.runtime points elsewhere or the download fails. */
+export async function ensureOpencode(configured: string | undefined, log: Log): Promise<string | null> {
+  const found = findOpencode(configured)
+  if (found || configured) return found
+  const asset = opencodeAsset()
+  if (!asset) return null
+  const repo = "anomalyco/opencode"
+  const tag = `v${OPENCODE_VERSION}`
+  try {
+    const sha256 = await githubDigest(repo, tag, asset)
+    const url = `https://github.com/${repo}/releases/download/${tag}/${asset}`
+    return await installTool({ name: "opencode", version: OPENCODE_VERSION, asset, url, binary: OPENCODE_BIN, sha256, log, label: `the agent runtime ${OPENCODE_VERSION}` })
+  } catch (err) {
+    log(`Could not download the agent runtime (${err instanceof Error ? err.message : String(err)}).`)
+    return null
+  }
+}
+
+export const INSTALL_HINT = "The agent runtime could not be downloaded; run forgeqe setup once the network is reachable, or set code.runtime to its binary."
+
+type ModelRef = { providerID: string; modelID: string }
+
+const env = (name: string | undefined) => (name ? `{env:${name}}` : undefined)
+
+function trimSlash(url: string): string {
+  return url.replace(/\/+$/, "")
+}
+
+/**
+ * Agent runtime provider config for a ForgeQE llms.json profile. Keys are referenced as {env:NAME}, which the agent runtime
+ * substitutes itself, so key values never leave the environment.
+ */
+export function providerFor(profile: LlmProfile): { provider: Record<string, unknown>; model: ModelRef } {
+  if (profile.auth === "entra") throw new Error("An auth: entra profile reaches the coding agent through entraGateway, which gives it a profile of its own.")
+  const key = profile.apiKeyEnv ? env(profile.apiKeyEnv) : profile.apiKey
+  const model = { tool_call: true, temperature: false, limit: { context: 200_000, output: 32_000 } }
+  switch (profile.provider) {
+    case "azure": {
+      if (!profile.endpoint) throw new Error("The azure profile needs an endpoint for the coding agent.")
+      const deployment = profile.deployment || profile.model
+      const origin = trimSlash(profile.endpoint).replace(/\/openai(\/v1)?$/, "")
+      return {
+        provider: {
+          azure: {
+            options: { baseURL: `${origin}/openai/v1`, ...(key ? { apiKey: key } : {}) },
+            models: { [deployment]: { id: deployment, name: profile.model, ...model } },
+          },
+        },
+        model: { providerID: "azure", modelID: deployment },
+      }
+    }
+    case "openai":
+      return {
+        provider: {
+          openai: {
+            options: { ...(key ? { apiKey: key } : {}), ...(profile.endpoint ? { baseURL: trimSlash(profile.endpoint) } : {}) },
+          },
+        },
+        model: { providerID: "openai", modelID: profile.model },
+      }
+    case "openai_compatible":
+    case "ollama":
+      if (!profile.endpoint) throw new Error(`The ${profile.provider} profile needs an endpoint for the coding agent.`)
+      return {
+        provider: {
+          forgeqe: {
+            npm: "@ai-sdk/openai-compatible",
+            name: "ForgeQE profile",
+            options: { baseURL: trimSlash(profile.endpoint), ...(key ? { apiKey: key } : {}) },
+            models: { [profile.model]: { name: profile.model, ...model } },
+          },
+        },
+        model: { providerID: "forgeqe", modelID: profile.model },
+      }
+    default:
+      throw new Error(`The coding agent needs a live LLM profile; "${profile.provider}" has no model. Pick one with --profile or set code.model.`)
+  }
+}
+
+function parseModel(ref: string): ModelRef {
+  const i = ref.indexOf("/")
+  if (i <= 0) throw new Error(`code.model must be provider/model, got "${ref}".`)
+  return { providerID: ref.slice(0, i), modelID: ref.slice(i + 1) }
+}
+
+/**
+ * `permission` entries replace the defaults (edit, run anything but push, fetch) key by key. `skills` names whose
+ * registry skills the agent may load; without it every skill is denied.
+ */
+export type AgentSpec = {
+  name: string
+  description: string
+  prompt: string
+  permission?: Record<string, unknown>
+  skills?: SkillAgent
+  /** Most tool-calling steps in one turn; at the limit the agent must answer with what it has. */
+  steps?: number
+}
+
+export const TEST_AGENT: AgentSpec = {
+  name: AGENT_NAME,
+  description: "Turns a verified ForgeQE browser run into a passing test in this repository",
+  get prompt() {
+    return testAgentPrompt()
+  },
+  skills: "scribe",
+}
+
+/** Scribe before the flow arrives: the same instructions, reading only (no file changes, no live browser). */
+export const READ_AGENT: AgentSpec = {
+  name: "forgeqe-read",
+  description: "Learns the repository's test setup before ForgeQE hands over a verified flow",
+  get prompt() {
+    return testAgentPrompt()
+  },
+  permission: { edit: "deny", "live_*": "deny" },
+  skills: "scribe",
+}
+
+/**
+ * The agent runtime's own skill discovery (~/.claude/skills, ~/.agents/skills, and the project's) stays off: skills
+ * come only from ForgeQE's registry, through `skills.paths`. The runtime accepts only 1/0 style values here.
+ */
+const SKILL_ENV: Record<string, string> = { OPENCODE_DISABLE_EXTERNAL_SKILLS: "1", OPENCODE_DISABLE_CLAUDE_CODE_SKILLS: "1" }
+
+/**
+ * The agent runtime server's environment: this terminal's, without the secrets in `hide` that its config does not
+ * reference, plus `secrets` (values ForgeQE derived for {env:} references) and the runtime's own folder on PATH.
+ * Nothing here is written into process.env, so other children and later sessions never see it.
+ */
+export function serverEnv(opts: { bin: string; config: Record<string, unknown>; hide?: string[]; secrets?: Record<string, string> }): Record<string, string> {
+  const needed = new Set(envRefs(opts.config))
+  const env = withoutNames(process.env, (opts.hide || []).filter((n) => !needed.has(n)))
+  const binDir = path.dirname(opts.bin)
+  const pathKey = Object.keys(env).find((k) => k.toUpperCase() === "PATH") || "PATH"
+  const parts = (env[pathKey] || "").split(path.delimiter).filter(Boolean)
+  if (!parts.includes(binDir)) env[pathKey] = [binDir, ...parts].join(path.delimiter)
+  return { ...env, ...SKILL_ENV, ...opts.secrets, OPENCODE_CONFIG_CONTENT: JSON.stringify(opts.config) }
+}
+
+/**
+ * A runtime plugin that blanks `names` in the environment of every shell command the agents run, so a prompt injected
+ * by a page under test cannot read the model key or tracker tokens the runtime itself needs. Returns the plugin's URL.
+ */
+export function hideEnvPlugin(dir: string, names: string[]): string {
+  const file = path.join(dir, "forgeqe-hide-env.js")
+  writeFileSync(
+    file,
+    `const NAMES = ${JSON.stringify([...new Set(names)].sort())}\n` +
+      `export const ForgeQEHideEnv = async () => ({\n` +
+      `  "shell.env": async (_input, output) => {\n` +
+      `    for (const name of NAMES) output.env[name] = ""\n` +
+      `  },\n` +
+      `})\n`,
+  )
+  return `file://${file.split(path.sep).join("/").replace(/^([A-Za-z]):/, "/$1:")}`
+}
+
+function stopProcess(proc: ChildProcess): void {
+  if (proc.exitCode !== null || proc.signalCode !== null) return
+  if (process.platform === "win32" && proc.pid) {
+    const out = spawnSync("taskkill", ["/pid", String(proc.pid), "/T", "/F"], { windowsHide: true })
+    if (!out.error && out.status === 0) return
+  }
+  proc.kill()
+}
+
+/** `opencode serve` on 127.0.0.1 with an explicit environment (the SDK's launcher copies process.env). */
+export async function startServer(bin: string, env: Record<string, string>, timeoutMs: number): Promise<{ url: string; close(): void }> {
+  const proc = spawn(bin, ["serve", "--hostname=127.0.0.1", "--port=0"], { env, stdio: ["ignore", "pipe", "pipe"], windowsHide: true })
+  const url = await new Promise<string>((resolve, reject) => {
+    let output = ""
+    const fail = (err: Error) => {
+      clearTimeout(timer)
+      stopProcess(proc)
+      reject(err)
+    }
+    const timer = setTimeout(() => fail(new Error(`Timeout waiting for the agent runtime to start after ${timeoutMs}ms`)), timeoutMs)
+    proc.stdout!.on("data", (chunk) => {
+      output += String(chunk)
+      const line = output.split("\n").find((l) => l.startsWith("opencode server listening"))
+      if (!line) return
+      const match = line.match(/on\s+(https?:\/\/\S+)/)
+      clearTimeout(timer)
+      if (match) resolve(match[1]!)
+      else fail(new Error(`Could not read the agent runtime's address from: ${line}`))
+    })
+    proc.stderr!.on("data", (chunk) => {
+      output += String(chunk)
+    })
+    proc.on("exit", (code) => fail(new Error(`The agent runtime exited with code ${code}${output.trim() ? `\n${output.trim()}` : ""}`)))
+    proc.on("error", fail)
+  })
+  return { url, close: () => stopProcess(proc) }
+}
+
+/** `skill` permission for one agent: only the registry's skills for its audience; everything else, built-ins included, denied. */
+export function skillPermission(skills: Skill[] | undefined, audience: SkillAgent | undefined): string | Record<string, string> {
+  const names = audience ? (skills || []).filter((s) => s.agents.includes(audience)).map((s) => s.name) : []
+  if (!names.length) return "deny"
+  return { "*": "deny", ...Object.fromEntries(names.map((n) => [n, "allow"])) }
+}
+
+/** Shell commands the agents may not run; pushing goes through ForgeQE's guarded push_branch tool. */
+/**
+ * The runtime matches each command of a pipeline or `&&` chain on its own, so `cd x && git push` is caught by the plain
+ * rules; the `*`-prefixed ones catch a push wrapped in another command (`env git push`, `sh -c 'git push'`). These are
+ * guard rails, not a sandbox: worktree.ts puts back what the agent may not change.
+ */
+export const BASH_PERMISSION = {
+  "*": "allow",
+  "git push*": "deny",
+  "git * push*": "deny",
+  "*git push*": "deny",
+  "*git -C * push*": "deny",
+  "*git -c * push*": "deny",
+  "gh repo delete*": "deny",
+  "*gh repo delete*": "deny",
+}
+
+/** Commands that throw away the user's uncommitted work, also when wrapped in another command. */
+const DISCARD_WORK = ["git clean*", "git reset --hard*", "git stash*", "git restore*", "git checkout -- *", "git checkout .*"].flatMap((c) => [c, `*${c}`])
+
+/** Paths the agent may not change: `edit` relative to the git worktree root as the agent runtime matches them, `bash` as they appear in commands. */
+export type Protect = { edit: string[]; bash: string[] }
+
+export function protectedPermission(protect: Protect, discardWork = true): { edit: Record<string, string>; bash: Record<string, string> } {
+  const edit: Record<string, string> = { "*": "allow" }
+  const bash: Record<string, string> = { ...BASH_PERMISSION }
+  for (const p of protect.edit) {
+    edit[p] = "deny"
+    edit[`${p}/*`] = "deny"
+  }
+  for (const p of protect.bash) bash[`*${p}*`] = "deny"
+  if (discardWork) for (const c of DISCARD_WORK) bash[c] = "deny"
+  return { edit, bash }
+}
+
+/** Inline agent runtime config: the model, the agent, MCP servers, and permissions for an unattended run. */
+export function opencodeConfig(opts: {
+  profile: LlmProfile
+  model?: string
+  readDirs: string[]
+  agent?: AgentSpec
+  /** More agents in the same config, e.g. READ_AGENT; a prompt picks one by name. */
+  agents?: AgentSpec[]
+  mcp?: Record<string, unknown>
+  /** Paths the agent may read but never change: ForgeQE's files and run folders. */
+  protect?: Protect
+  /** Without `protect`: paths the agent still may not change (the skill folders). */
+  readOnly?: Protect
+  /** Registry skills for this session and the folder of links the runtime reads them from. */
+  skills?: Skill[]
+  skillsDir?: string
+}): {
+  config: Record<string, unknown>
+  model: ModelRef
+} {
+  const fromProfile = opts.model ? null : providerFor(opts.profile)
+  const model = opts.model ? parseModel(opts.model) : fromProfile!.model
+  const ref = `${model.providerID}/${model.modelID}`
+  const agent = opts.agent || TEST_AGENT
+  const external: Record<string, string> = { "*": "ask" }
+  for (const dir of opts.readDirs) external[`${dir}/**`] = "allow"
+  const entry = (spec: AgentSpec) => ({
+    description: spec.description,
+    mode: "primary",
+    prompt: spec.prompt,
+    ...(spec.steps ? { steps: spec.steps } : {}),
+    permission: {
+      ...(opts.protect ? protectedPermission(opts.protect) : opts.readOnly ? protectedPermission(opts.readOnly, false) : { edit: "allow", bash: BASH_PERMISSION }),
+      webfetch: "allow",
+      question: "deny",
+      doom_loop: "ask",
+      external_directory: external,
+      skill: skillPermission(opts.skills, spec.skills),
+      ...(opts.mcp ? Object.fromEntries(Object.keys(opts.mcp).map((k) => [`${k}_*`, "allow"])) : {}),
+      ...spec.permission,
+    },
+  })
+  return {
+    model,
+    config: {
+      $schema: "https://opencode.ai/config.json",
+      model: ref,
+      small_model: ref,
+      share: "disabled",
+      autoupdate: false,
+      experimental: { openTelemetry: false },
+      ...(fromProfile ? { provider: fromProfile.provider } : {}),
+      ...(opts.mcp ? { mcp: opts.mcp } : {}),
+      ...(opts.skillsDir ? { skills: { paths: [opts.skillsDir] } } : {}),
+      agent: Object.fromEntries([agent, ...(opts.agents || [])].map((spec) => [spec.name, entry(spec)])),
+    },
+  }
+}
+
+function realpathOr(dir: string): string {
+  try {
+    return realpathSync(dir)
+  } catch {
+    return path.resolve(dir)
+  }
+}
+
+function rel(repo: string, p: unknown): string {
+  const s = String(p || "")
+  if (!s) return ""
+  const r = path.relative(repo, s)
+  return r && !r.startsWith("..") ? r : s
+}
+
+const clip = (s: string, n: number) => {
+  const one = s.replace(/\s+/g, " ").trim()
+  return one.length <= n ? one : `${one.slice(0, n - 1)}…`
+}
+
+/** A tool error without the `<<nonce>> [UNTRUSTED … CONTENT …] <<nonce>> … <</nonce>>` wrapper some MCP servers put around results. */
+export function toolError(s: string): string {
+  return s
+    .replace(/<<[0-9a-f]{16,}>>\s*\[UNTRUSTED[^\]]*\]\s*<<[0-9a-f]{16,}>>/gi, "")
+    .replace(/<<\/?[0-9a-f]{16,}>>/gi, "")
+    .trim()
+}
+
+const QUIET_TOOLS = new Set(["StructuredOutput", "todowrite", "todoread"])
+
+const FILE_VERBS: Record<string, string> = { read: "Reading", write: "Writing", edit: "Editing", patch: "Editing", multiedit: "Editing" }
+
+/** One line for a finished tool call, e.g. `Editing tests/search.spec.ts` or `Running npx playwright test …`. */
+export function toolLine(repo: string, tool: string, input: Record<string, unknown>, title?: string): string {
+  switch (tool) {
+    case "read":
+    case "edit":
+    case "write":
+    case "patch":
+    case "multiedit":
+      return `${FILE_VERBS[tool]} ${rel(repo, input.filePath || input.path) || title || ""}`.trim()
+    case "bash":
+      return `Running ${clip(String(input.command || title || ""), 100)}`
+    case "glob":
+      return `Finding files ${clip(String(input.pattern || ""), 60)}${input.path ? ` in ${rel(repo, input.path)}` : ""}`
+    case "grep":
+      return `Searching for ${clip(String(input.pattern || ""), 60)}${input.path ? ` in ${rel(repo, input.path)}` : ""}`
+    case "list":
+      return `Listing ${rel(repo, input.path) || "."}`
+    case "webfetch":
+      return `Fetching ${input.url || ""}`
+    case "task":
+      return `Delegating: ${clip(String(input.description || title || ""), 80)}`
+    case "skill":
+      return `Using skill ${input.name || title || ""}`.trim()
+    case "live_browser_navigate":
+      return `Live browser: open ${input.url || ""}`
+    default: {
+      if (tool.startsWith("live_browser_")) return `Live browser: ${tool.slice(13).replace(/_/g, " ")}${title ? ` ${clip(title, 80)}` : ""}`
+      const server = MCP_SERVERS.find(([prefix]) => tool.startsWith(prefix))
+      if (server) return `${server[1]} · ${tool.slice(server[0].length).replace(/_/g, " ")}${mcpArgs(input)}`
+      return `${tool}${title ? ` ${clip(title, 80)}` : ""}`
+    }
+  }
+}
+
+/** MCP servers ForgeQE's agent gets (external.ts), by tool-name prefix, as the transcript names them. */
+const MCP_SERVERS: [string, string][] = [
+  ["azure_devops_", "Azure DevOps"],
+  ["atlassian_", "Atlassian"],
+  ["confluence_", "Confluence"],
+]
+
+/** The short values an MCP call was made with (ids, keys, project), so the line says what was fetched. */
+export function mcpArgs(input: Record<string, unknown>): string {
+  const parts = Object.entries(input || {})
+    .filter(([k, v]) => !/token|secret|password|^auth|api_?key/i.test(k) && (["string", "number", "boolean"].includes(typeof v) || (Array.isArray(v) && v.length > 0 && v.length <= 10 && v.every((x) => typeof x === "number" || typeof x === "string"))))
+    .map(([k, v]) => `${k.replace(/_/g, " ")} ${clip(Array.isArray(v) ? v.join(", ") : String(v).replace(/\s+/g, " "), 40)}`)
+    .slice(0, 4)
+  return parts.length ? ` (${parts.join(", ")})` : ""
+}
+
+type AnyEvent = { type: string; properties: Record<string, any> }
+
+/** Why a permission request outside the config was declined, in words the agent can act on. */
+export function declineMessage(permission: string): string {
+  if (permission === "doom_loop") return "You are repeating the same call. Try a different approach."
+  if (permission === "external_directory") return "Stay inside the repository."
+  return `ForgeQE runs unattended and does not grant ${permission || "this"} permission. Do the task without it.`
+}
+
+/** A shell command that kept failing: the turn was stopped after its `count`th failure. */
+export type Stall = { command: string; count: number; output: string }
+
+export type PromptOutcome<R = AgentReport> = { report: R | null; text: string; error?: string; stalled?: Stall }
+
+/** Failures of each exact shell command since the last reset; `add` returns the stall once a command reaches `limit`. */
+export class FailedCommands {
+  private counts = new Map<string, number>()
+  constructor(private limit: number) {}
+  add(command: string, exit: unknown, output: string): Stall | null {
+    if (typeof exit !== "number" || exit === 0 || !command.trim()) return null
+    const count = (this.counts.get(command) || 0) + 1
+    this.counts.set(command, count)
+    return count >= this.limit ? { command, count, output: output.split("\n").slice(-40).join("\n").trim() } : null
+  }
+  reset(): void {
+    this.counts.clear()
+  }
+}
+
+/**
+ * Per prompt: tools switched on or off by name (`*` patterns allowed; the setting stays for later prompts, and `true`
+ * overrides the agent's path rules for that tool, so never pass it for file tools), whether the turn must end with the
+ * structured answer, and which of the session's agents answers.
+ */
+export type PromptOptions = { tools?: Record<string, boolean>; structured?: boolean; agent?: string }
+
+export type OpencodeSession<R = AgentReport> = {
+  sessionId: string
+  /** The session asked for with `resume` was reopened, with its earlier messages. */
+  resumed?: boolean
+  model: string
+  prompt(text: string, options?: PromptOptions): Promise<PromptOutcome<R>>
+  abort(): Promise<void>
+  close(): Promise<void>
+  usage: Usage
+  /** Forget the failed commands counted so far (ForgeQE ran the test, so the agent starts a fresh round). */
+  resetStall?(): void
+  /** Each MCP server's state: connected, failed (with error), needs_auth, … */
+  mcpStatus?(): Promise<Record<string, { status: string; error?: string }>>
+  /** Skills the agent loaded so far, in order. */
+  skillsUsed?: string[]
+}
+
+/**
+ * Start the agent runtime server with ForgeQE's inline config, open a session in the repo, and relay its events.
+ * Every permission request is outside the config (paths outside the repo, repeated identical tool calls, the runtime's
+ * own "ask" defaults such as reading .env files), so each is declined and an unattended run never waits for a human.
+ */
+/** The agent with the product's domain added to its instructions (once, when its prompt does not carry it already). */
+export function withDomain(agent: AgentSpec, domain: string | null): AgentSpec {
+  const prompt = agent.prompt
+  return domain && !prompt.includes(domain) ? { ...agent, prompt: `${prompt}\n\n${domain}` } : agent
+}
+
+export async function openSession<R = AgentReport>(opts: {
+  repo: string
+  profile: LlmProfile
+  model?: string
+  bin?: string
+  readDirs: string[]
+  signal?: AbortSignal
+  onEvent?: (e: CodeEvent) => void
+  /** Default: the test-writing agent. */
+  agent?: AgentSpec
+  agents?: AgentSpec[]
+  /** JSON schema of the answer each prompt must end with. Default: the test result. */
+  schema?: Record<string, unknown>
+  mcp?: Record<string, unknown>
+  /** Tool calls not to show as ⚙ lines (the caller shows them itself). */
+  hideTool?: (tool: string) => boolean
+  title?: string
+  protect?: Protect
+  /** Stop the turn when one shell command has failed this many times since the last resetStall. */
+  stallAfter?: number
+  /** Reopen this earlier session (the agent runtime keeps sessions on disk); a new one is created when it is gone. */
+  resume?: string
+  /** Registry skills; each agent may load the ones for its audience (AgentSpec.skills). */
+  skills?: Skill[]
+  /**
+   * ForgeQE's own secrets (privateEnvNames): left out of the runtime unless its config references them, and blanked
+   * in every shell command the agents run either way.
+   */
+  hide?: string[]
+  /**
+   * The product's domain (domainNotes: its industry and regulations, or how to work them out), added to every agent's
+   * instructions so each one applies it. Required, so no new kind of session can leave it out; null only where it must
+   * not apply (a judge that is given the domain as data).
+   */
+  domain: string | null
+  /** Values for {env:} references in `mcp` that are not in this terminal (e.g. base64 of email:token). */
+  secrets?: Record<string, string>
+  /** Who this session is in the usage meter. Default Scribe. */
+  role?: Role
+}): Promise<OpencodeSession<R>> {
+  const missing = opts.model ? null : missingKey(opts.profile)
+  if (missing) throw new Error(missing)
+  const bin = findOpencode(opts.bin)
+  if (!bin) throw new Error(`The agent runtime was not found. ${INSTALL_HINT}`)
+
+  const agent = opts.agent || TEST_AGENT
+  const role: Role = opts.role || "Scribe"
+  // With code.model the runtime picks the model and its price is unknown; otherwise the profile's price applies.
+  const price = opts.model ? undefined : opts.profile.price
+  const audiences = new Set([agent, ...(opts.agents || [])].map((a) => a.skills).filter(Boolean))
+  const skills = (opts.skills || []).filter((s) => s.agents.some((a) => audiences.has(a)))
+  const links = linkSkills(skills)
+  const skillDirs = links ? [links.dir, ...skills.map((s) => s.dir)] : []
+  const readDirs = [...new Set([...opts.readDirs, ...skillDirs.flatMap((d) => [d, realpathOr(d)])])]
+  let protect = opts.protect
+  // ForgeQE's agent may change the user's and the project's skills when asked; built-in and global ones stay read-only.
+  const lockedDirs = audiences.has("forgeqe") ? [...(links ? [links.dir] : []), ...skills.filter((s) => s.source === "prebuilt" || s.source === "external").map((s) => s.dir)] : skillDirs
+  const skillPaths = lockedDirs.length ? protectPatterns(opts.repo, [], lockedDirs) : undefined
+  if (protect && skillPaths) protect = { edit: [...protect.edit, ...skillPaths.edit], bash: [...protect.bash, ...skillPaths.bash] }
+  // With auth: entra the runtime gets a local gateway that adds an Entra ID token to each request; it holds no key.
+  const gateway = !opts.model && opts.profile.auth === "entra" ? entraGateway(opts.profile) : null
+  const secrets = { ...opts.secrets, ...gateway?.secrets }
+  let built: ReturnType<typeof opencodeConfig>
+  try {
+    built = opencodeConfig({
+      profile: gateway?.profile || opts.profile,
+      model: opts.model,
+      readDirs,
+      agent: withDomain(agent, opts.domain),
+      agents: opts.agents?.map((a) => withDomain(a, opts.domain)),
+      mcp: opts.mcp,
+      protect,
+      readOnly: skillPaths,
+      skills,
+      skillsDir: links?.dir,
+    })
+  } catch (err) {
+    gateway?.close()
+    throw err
+  }
+  const { config, model } = built
+  const pluginDir = mkdtempSync(path.join(os.tmpdir(), "forgeqe-runtime-"))
+  const shellHidden = [...(opts.hide || []), ...Object.keys(secrets), ...envRefs(config), "OPENCODE_CONFIG_CONTENT"]
+  config.plugin = [...((config.plugin as string[] | undefined) || []), hideEnvPlugin(pluginDir, shellHidden)]
+  const cleanup = () => {
+    links?.remove()
+    gateway?.close()
+    rmSync(pluginDir, { recursive: true, force: true })
+  }
+  let server: { url: string; close(): void }
+  try {
+    server = await startServer(bin, serverEnv({ bin, config, hide: opts.hide, secrets }), 60_000)
+  } catch (err) {
+    cleanup()
+    throw err
+  }
+  const client: OpencodeClient = createOpencodeClient({ baseUrl: server.url, directory: opts.repo })
+  const emit = opts.onEvent || (() => {})
+  const usage: Usage = { input: 0, output: 0 }
+
+  let session: { id: string }
+  let resumed = false
+  try {
+    const earlier = opts.resume ? await client.session.get({ sessionID: opts.resume }).catch(() => null) : null
+    if (earlier?.data?.id) {
+      session = earlier.data
+      resumed = true
+    } else {
+      const created = await client.session.create({ title: opts.title || "ForgeQE test" })
+      if (!created.data) throw new Error(`The agent runtime could not create a session: ${JSON.stringify(created.error)}`)
+      session = created.data
+    }
+  } catch (err) {
+    server.close()
+    cleanup()
+    throw err
+  }
+
+  const skillsUsed: string[] = []
+  const assistant = new Set<string>()
+  const said = new Set<string>()
+  let idle: (() => void) | null = null
+  let sessionError = ""
+  // The turn's result comes from events: in agent runtime 1.18 listing a session's messages fails once a prompt used `format`.
+  let turn: { structured: R | null; error: string; text: string[]; stalled?: Stall } = { structured: null, error: "", text: [] }
+  const failed = opts.stallAfter ? new FailedCommands(opts.stallAfter) : null
+
+  const handle = async (e: AnyEvent) => {
+    const p = e.properties || {}
+    const sid = p.sessionID ?? p.part?.sessionID ?? p.info?.sessionID
+    if (sid && sid !== session.id) return
+    switch (e.type) {
+      case "message.updated":
+        if (p.info?.role === "assistant") {
+          assistant.add(p.info.id)
+          if (p.info.structured && typeof p.info.structured === "object") turn.structured = p.info.structured
+          if (p.info.error) turn.error = `${p.info.error.name}: ${p.info.error.data?.message || ""}`.trim()
+        }
+        break
+      case "message.part.updated": {
+        const part = p.part
+        if (part?.type === "tool" && (part.state?.status === "completed" || part.state?.status === "error")) {
+          if (part.tool === "StructuredOutput" && part.state.status === "completed" && !turn.structured) {
+            turn.structured = part.state.input || null
+          }
+          if (part.tool === "bash" && failed && !turn.stalled) {
+            const stall = failed.add(String(part.state.input?.command || ""), part.state.metadata?.exit, String(part.state.metadata?.output || part.state.output || ""))
+            if (stall) {
+              turn.stalled = stall
+              emit({ type: "code", kind: "info", text: `Stopped the turn: ${clip(stall.command, 80)} failed ${stall.count} times` })
+              void client.session.abort({ sessionID: session.id }).catch(() => {})
+            }
+          }
+          if (part.tool === "skill" && part.state.status === "completed") {
+            const name = String(part.state.input?.name || "")
+            if (name && !skillsUsed.includes(name)) skillsUsed.push(name)
+          }
+          if (QUIET_TOOLS.has(part.tool) || opts.hideTool?.(part.tool)) break
+          const line = toolLine(opts.repo, part.tool, part.state.input || {}, part.state.title)
+          const ok = part.state.status === "completed"
+          emit({ type: "code", kind: "tool", ok, text: ok ? line : `${line}: ${clip(toolError(String(part.state.error || "")) || "failed", 120)}` })
+        } else if (part?.type === "text" && part.time?.end && assistant.has(part.messageID) && !said.has(part.id)) {
+          said.add(part.id)
+          const text = String(part.text || "").trim()
+          if (text) {
+            turn.text.push(text)
+            emit({ type: "code", kind: "say", text: clip(text, 400) })
+          }
+        } else if (part?.type === "step-finish" && part.tokens) {
+          const t = part.tokens
+          const step: Usage = {
+            input: (t.input || 0) + (t.cache?.read || 0) + (t.cache?.write || 0),
+            output: (t.output || 0) + (t.reasoning || 0),
+            ...(t.cache?.read ? { cached: t.cache.read } : {}),
+            ...(t.cache?.write ? { cacheWrite: t.cache.write } : {}),
+          }
+          Object.assign(usage, addUsage(usage, step))
+          recordUsage(role, step, price)
+          emit({ type: "code", kind: "usage", usage: { ...usage } })
+        }
+        break
+      }
+      case "session.status":
+        if (p.status?.type === "retry") emit({ type: "code", kind: "info", text: `Agent runtime retrying: ${clip(String(p.status.message || ""), 160)}` })
+        if (p.status?.type === "idle") idle?.()
+        break
+      case "session.idle":
+        idle?.()
+        break
+      case "session.error": {
+        const err = p.error
+        sessionError = String(err?.data?.message || err?.message || err?.name || "agent runtime error")
+        break
+      }
+      case "permission.asked": {
+        // The config allows or denies everything an agent needs, so a request that still asks is outside it: decline it.
+        await client.permission.reply({ requestID: p.id, reply: "reject", message: declineMessage(String(p.permission || "")) })
+        emit({ type: "code", kind: "info", text: `declined ${p.permission} ${(p.patterns || []).join(", ")}` })
+        break
+      }
+      case "question.asked":
+        await client.question.reject({ requestID: p.id })
+        break
+    }
+  }
+
+  const sub = await client.event.subscribe({}, { sseMaxRetryAttempts: 1, onSseError: () => {} })
+  ;(async () => {
+    try {
+      for await (const e of sub.stream as AsyncIterable<AnyEvent>) await handle(e).catch(() => {})
+    } catch {
+      // stream closed
+    }
+  })()
+
+  const abort = async () => {
+    await client.session.abort({ sessionID: session.id }).catch(() => {})
+  }
+  opts.signal?.addEventListener("abort", () => void abort(), { once: true })
+
+  return {
+    sessionId: session.id,
+    resumed,
+    model: `${model.providerID}/${model.modelID}`,
+    usage,
+    abort,
+    async prompt(text: string, options: PromptOptions = {}): Promise<PromptOutcome<R>> {
+      sessionError = ""
+      turn = { structured: null, error: "", text: [] }
+      const done = new Promise<void>((resolve) => {
+        idle = resolve
+      })
+      const sent = await client.session.promptAsync({
+        sessionID: session.id,
+        agent: options.agent || agent.name,
+        model,
+        ...(options.structured === false ? {} : { format: { type: "json_schema" as const, schema: (opts.schema || RESULT_SCHEMA) as never } }),
+        ...(options.tools ? { tools: options.tools } : {}),
+        parts: [{ type: "text", text }],
+      })
+      if (sent.error) return { report: null, text: "", error: `The agent runtime rejected the prompt: ${JSON.stringify(sent.error)}` }
+      const onAbort = () => idle?.()
+      opts.signal?.addEventListener("abort", onAbort, { once: true })
+      await done
+      opts.signal?.removeEventListener("abort", onAbort)
+      idle = null
+      if (opts.signal?.aborted) return { report: null, text: "", error: "stopped" }
+      await Bun.sleep(100)
+      if (turn.stalled) return { report: null, text: turn.text.join("\n"), stalled: turn.stalled }
+      return { report: turn.structured, text: turn.text.join("\n"), error: turn.error || sessionError || undefined }
+    },
+    resetStall() {
+      failed?.reset()
+    },
+    skillsUsed,
+    async close() {
+      server.close()
+      cleanup()
+    },
+    async mcpStatus() {
+      const res = await client.mcp.status()
+      return (res.data || {}) as Record<string, { status: string; error?: string }>
+    },
+  }
+}