@vercel/agent-eval 1.1.1 → 1.3.0

package/dist/lib/agents/opencode/agent.js

@@ -0,0 +1,166 @@
+/**
+ * OpenCode agent — host-side definition + the thin Agent wrapper.
+ *
+ * The definition is pure data/auth/config; the actual CLI invocation + transcript
+ * capture live in ./run.mjs (shipped into the sandbox by the orchestrator). The
+ * wrapper keeps the public Agent interface identical so the registry / runner are
+ * untouched.
+ *
+ * OpenCode only supports the Vercel AI Gateway (no direct provider APIs), so there
+ * is a single variant: `vercel-ai-gateway/opencode`.
+ *
+ * `generateOpenCodeConfig` (the pure host-side config generator) STAYS in this file
+ * and is exported so the existing unit tests keep importing it. The transcript /
+ * observed-model parsing helpers (`extractObservedModelFromOpenCodeOutput`,
+ * `extractSessionIdFromTranscript`, `extractObservedModelFromSessionExport`) moved
+ * INTO ./run.mjs (so the tested logic is exactly what the sandbox runs) and the
+ * test now imports them from there — see the test import change in the migration
+ * notes.
+ */
+import { fileURLToPath } from 'node:url';
+import { AI_GATEWAY } from '../shared.js';
+import { runWithDefinition } from '../plugin/orchestrator.js';
+/**
+ * Generate OpenCode config file content.
+ * Configures the Vercel AI Gateway provider, plus any additional providers.
+ *
+ * STAYS host-side + exported (the unit test imports it). The content is written
+ * verbatim into `opencode.json` in the sandbox by the orchestrator. Behavior is
+ * identical to the old adapter, including writing the resolved apiKey into the
+ * config (falling back to the `{env:AI_GATEWAY_API_KEY}` placeholder).
+ */
+export function generateOpenCodeConfig(extraProviders, apiKey, timeoutMs, webResearch) {
+    const vercelBase = {
+        options: {
+            apiKey: apiKey || '{env:AI_GATEWAY_API_KEY}',
+            ...(timeoutMs ? { timeout: timeoutMs } : {}),
+        },
+    };
+    const { vercel: vercelExtra, ...otherProviders } = extraProviders || {};
+    const providers = {
+        vercel: {
+            ...vercelBase,
+            ...vercelExtra,
+            options: { ...vercelBase.options, ...vercelExtra?.options },
+        },
+        ...otherProviders,
+    };
+    return JSON.stringify({
+        $schema: 'https://opencode.ai/config.json',
+        provider: providers,
+        permission: {
+            write: 'allow',
+            edit: 'allow',
+            bash: 'allow',
+            // OpenCode has no native web search; Exa-backed search is enabled via
+            // OPENCODE_ENABLE_EXA=1 alongside these tool permissions.
+            ...(webResearch ? { webfetch: 'allow', websearch: 'allow' } : {}),
+        },
+    }, null, 2);
+}
+/**
+ * Build the OpenCode plugin definition.
+ *
+ * Auth is single-mode: the Vercel AI Gateway. authEnv() also carries the Exa
+ * websearch toggle (OPENCODE_ENABLE_EXA) when webResearch is on — it rides in
+ * process.env alongside the gateway key, exactly as the old adapter set it on the
+ * CLI's spawn env. The matching tool permissions are written into opencode.json by
+ * generateOpenCodeConfig.
+ */
+export function createOpenCodeDefinition() {
+    return {
+        name: 'vercel-ai-gateway/opencode',
+        displayName: 'OpenCode (Vercel AI Gateway)',
+        defaultModel: 'vercel/anthropic/claude-sonnet-4',
+        o11yAgentName: 'vercel-ai-gateway/opencode',
+        // Resolve run.mjs next to this file (works in src during dev and in dist after
+        // the build copies run.mjs alongside the compiled agent.js).
+        runnerPath: fileURLToPath(new URL('./run.mjs', import.meta.url)),
+        // OpenCode only supports the Vercel AI Gateway, never direct provider APIs.
+        getApiKeyEnvVar() {
+            return AI_GATEWAY.apiKeyEnvVar;
+        },
+        install(options) {
+            // Project deps (retried once, last-10-lines wording), then the OpenCode CLI.
+            // The CLI has two mutually-exclusive install paths preserved from the old
+            // adapter:
+            //   - binaryUrl set → curl a custom binary into $HOME/.local/bin (e.g. a
+            //     patched build for unreleased models). Error body is stdout+stderr.
+            //   - otherwise     → `npm install -g opencode-ai`. Error body is stderr.
+            const binaryUrl = options.agentOptions?.binaryUrl;
+            const steps = [
+                {
+                    kind: 'command',
+                    cmd: 'npm',
+                    args: ['install'],
+                    retryOnce: true,
+                    errorPrefix: 'npm install failed',
+                    errorBody: 'last10',
+                },
+            ];
+            if (binaryUrl) {
+                // Download a custom binary (e.g. a patched build for unreleased models).
+                // Invoked as the old adapter did: `bash -c "<line>"` via a 'command' step,
+                // so the curl line is byte-identical. On failure the orchestrator renders
+                // `OpenCode CLI install failed: <stderr>`; the old adapter rendered
+                // `OpenCode CLI install failed: <stdout> <stderr>` — for `curl -fsSL`
+                // stdout is empty on failure, so the only difference is a dropped leading
+                // space (see behaviorNotes / contractAdditions for the exact-parity option).
+                steps.push({
+                    kind: 'command',
+                    cmd: 'bash',
+                    args: [
+                        '-c',
+                        `mkdir -p $HOME/.local/bin && curl -fsSL "${binaryUrl}" -o $HOME/.local/bin/opencode && chmod +x $HOME/.local/bin/opencode`,
+                    ],
+                    errorPrefix: 'OpenCode CLI install failed',
+                    errorBody: 'stderr',
+                });
+            }
+            else {
+                steps.push({
+                    kind: 'command',
+                    cmd: 'npm',
+                    args: ['install', '-g', 'opencode-ai'],
+                    errorPrefix: 'OpenCode CLI install failed',
+                    errorBody: 'stderr',
+                });
+            }
+            return steps;
+        },
+        // OpenCode is configured via a project-local opencode.json (writeFiles target,
+        // relative to cwd — not a `~` path, so no viaShell heredoc needed).
+        configFiles(options) {
+            const extraProviders = options.agentOptions?.extraProviders;
+            const content = generateOpenCodeConfig(extraProviders, options.apiKey, options.timeout, options.webResearch);
+            return [{ path: 'opencode.json', content }];
+        },
+        authEnv(options) {
+            return {
+                [AI_GATEWAY.apiKeyEnvVar]: options.apiKey,
+                // Exa-backed websearch is gated behind this env var in the OpenCode CLI;
+                // the matching tool permissions are written into opencode.json by
+                // generateOpenCodeConfig.
+                ...(options.webResearch ? { OPENCODE_ENABLE_EXA: '1' } : {}),
+            };
+        },
+    };
+}
+/**
+ * Create the OpenCode Agent. Thin wrapper over the generic orchestrator so the
+ * Agent interface (and thus registry.ts / index.ts / runner.ts) is unchanged.
+ */
+export function createOpenCodeAgent() {
+    const definition = createOpenCodeDefinition();
+    return {
+        name: definition.name,
+        displayName: definition.displayName,
+        getApiKeyEnvVar: definition.getApiKeyEnvVar,
+        getDefaultModel() {
+            return definition.defaultModel;
+        },
+        run: (fixturePath, options) => runWithDefinition(definition, fixturePath, options),
+        definition,
+    };
+}
+//# sourceMappingURL=agent.js.map

package/dist/lib/agents/opencode/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../../src/lib/agents/opencode/agent.ts"],"names":[],"mappings":"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"}

package/dist/lib/agents/opencode/run.mjs

@@ -0,0 +1,308 @@
+/**
+ * OpenCode in-sandbox runner.
+ *
+ * This file is shipped INTO the sandbox by the orchestrator and executed there as
+ * `node __agent_eval__/run.mjs '<AgentRunInput JSON>'`. It is intentionally
+ * ZERO-DEPENDENCY (only `node:*` builtins) because the sandbox only has the
+ * fixture's own deps + the installed `opencode` CLI — it cannot import anything
+ * from the @vercel/agent-eval package.
+ *
+ * Dual mode:
+ *   - runnable: invoked directly → reads argv, runs the agent, writes the result
+ *     file + prints a status line, exits 0.
+ *   - importable: `import { runAgent } from './run.mjs'` → returns a RunnerResult
+ *     (no file write, no exit). This is what a future in-sandbox judge reuses.
+ *
+ * The pure helpers below are exported (not just `runAgent`) so they can be
+ * unit-tested directly — the same code the sandbox runs (see opencode.test.ts).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Build the OpenCode CLI argument list.
+ *
+ * Preserved verbatim from the old adapter:
+ *   - `run <prompt> --format json` is always emitted (`--format json` gives the
+ *     structured JSON event stream we parse for the transcript).
+ *   - `--model <model>` is appended when a model override is present.
+ *   - else, when modelPolicy === 'native-default', `--print-logs --log-level INFO`
+ *     is appended so older OpenCode versions print the CLI-selected model (the
+ *     log-scrape path) without a follow-up export call.
+ *
+ * @param {{prompt:string, model?:string, modelPolicy?:string}} input
+ * @returns {string[]}
+ */
+export function buildOpenCodeCliArgs(input) {
+  const cliArgs = ['run', input.prompt, '--format', 'json'];
+  if (input.model) {
+    cliArgs.push('--model', input.model);
+  } else if (input.modelPolicy === 'native-default') {
+    cliArgs.push('--print-logs', '--log-level', 'INFO');
+  }
+  return cliArgs;
+}
+
+/**
+ * Extract transcript from OpenCode JSON output.
+ * When run with --format json, OpenCode outputs JSON events to stdout.
+ * Preserved verbatim from the old adapter.
+ *
+ * @param {string|undefined|null} output
+ * @returns {string|undefined}
+ */
+export function extractTranscriptFromOutput(output) {
+  if (!output || !output.trim()) {
+    return undefined;
+  }
+
+  // The --format json output contains JSON events, one per line.
+  // Filter to only include lines that look like JSON objects.
+  const lines = output.split('\n').filter((line) => {
+    const trimmed = line.trim();
+    return trimmed.startsWith('{') && trimmed.endsWith('}');
+  });
+
+  if (lines.length === 0) {
+    return undefined;
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Scrape the OpenCode printed logs for the primary build model.
+ * Works on OpenCode <= 1.16.x, whose INFO log lines carry providerID/modelID.
+ * Preserved verbatim from the old adapter.
+ *
+ * @param {string} output
+ * @returns {string|undefined}
+ */
+export function extractObservedModelFromOpenCodeOutput(output) {
+  let observedModel;
+
+  for (const line of output.split('\n')) {
+    if (!line.includes('service=llm') || !line.includes('small=false') || !line.includes('agent=build')) {
+      continue;
+    }
+
+    const providerMatch = line.match(/providerID=([^\s]+)/);
+    const modelMatch = line.match(/modelID=([^\s]+)/);
+    const providerID = providerMatch?.[1];
+    const modelID = modelMatch?.[1];
+    if (providerID && modelID) {
+      observedModel = `${providerID}/${modelID}`;
+    }
+  }
+
+  return observedModel;
+}
+
+/**
+ * Extract the session id from the `--format json` event stream.
+ * Every emitted event carries a `sessionID` field.
+ * Preserved verbatim from the old adapter.
+ *
+ * @param {string|undefined} transcript
+ * @returns {string|undefined}
+ */
+export function extractSessionIdFromTranscript(transcript) {
+  if (!transcript) {
+    return undefined;
+  }
+
+  for (const line of transcript.split('\n')) {
+    try {
+      const event = JSON.parse(line);
+      if (typeof event.sessionID === 'string' && event.sessionID) {
+        return event.sessionID;
+      }
+    } catch {
+      // Skip non-JSON lines
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Extract the observed model from `opencode export <sessionID>` output.
+ * Assistant messages carry `providerID` and `modelID` in their info.
+ * Preserved verbatim from the old adapter.
+ *
+ * @param {string} exportOutput
+ * @returns {string|undefined}
+ */
+export function extractObservedModelFromSessionExport(exportOutput) {
+  const start = exportOutput.indexOf('{');
+  if (start === -1) {
+    return undefined;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(exportOutput.slice(start));
+  } catch {
+    return undefined;
+  }
+
+  const messages = parsed.messages;
+  if (!Array.isArray(messages)) {
+    return undefined;
+  }
+
+  for (const message of messages) {
+    const info = message.info;
+    if (info?.role !== 'assistant') {
+      continue;
+    }
+    if (
+      typeof info.providerID === 'string' && info.providerID &&
+      typeof info.modelID === 'string' && info.modelID
+    ) {
+      return `${info.providerID}/${info.modelID}`;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Run OpenCode over the workspace at `input.cwd` and return a RunnerResult.
+ *
+ * Auth (AI_GATEWAY_API_KEY, and OPENCODE_ENABLE_EXA when web research is on)
+ * arrives via process.env — the orchestrator sets it on the `node run.mjs`
+ * invocation, and we pass process.env straight through to the CLI. The runner
+ * never handles secrets itself.
+ *
+ * @param {import('../plugin/contract.js').AgentRunInput} input
+ * @returns {Promise<import('../plugin/contract.js').RunnerResult>}
+ */
+export async function runAgent(input) {
+  const args = buildOpenCodeCliArgs(input);
+
+  // spawnSync (not a shell string): the prompt is a plain argv element, so there
+  // is no shell quoting/escaping to get wrong. Blocking is fine — the runner has
+  // nothing else to do while the agent works. The sandbox-level timeout bounds it.
+  const res = spawnSync('opencode', args, {
+    cwd: input.cwd,
+    env: process.env,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+  const stdout = res.stdout || '';
+  const stderr = res.stderr || '';
+  // Preserve the old concatenation order: stdout THEN stderr.
+  const output = stdout + stderr;
+  // spawnSync sets status=null + error when the binary can't be spawned at all.
+  const agentExitCode = res.status == null ? -1 : res.status;
+
+  // Capture the transcript from the combined output (old: over stdout+stderr).
+  const transcript = extractTranscriptFromOutput(output) ?? null;
+
+  // Resolve the model OpenCode actually used. The `--format json` events never
+  // include it, so first try scraping the printed logs (works on OpenCode <=
+  // 1.16.x), then fall back to `opencode export <sessionID>`, whose assistant
+  // messages carry providerID/modelID (OpenCode 1.17.0 changed the log format,
+  // which broke the scrape). Observation must never fail the run.
+  let observedModel = extractObservedModelFromOpenCodeOutput(output);
+  if (!observedModel) {
+    const sessionId = extractSessionIdFromTranscript(transcript ?? undefined);
+    if (sessionId) {
+      try {
+        const exportRes = spawnSync('opencode', ['export', sessionId], {
+          cwd: input.cwd,
+          env: process.env,
+          encoding: 'utf8',
+          maxBuffer: 64 * 1024 * 1024,
+        });
+        if ((exportRes.status == null ? -1 : exportRes.status) === 0) {
+          observedModel = extractObservedModelFromSessionExport(exportRes.stdout || '');
+        }
+      } catch {
+        // Leave observedModel undefined.
+      }
+    }
+  }
+  const observedModelOrNull = observedModel ?? null;
+
+  if (res.error || agentExitCode !== 0) {
+    // Mirror the old error string: last 5 lines of output, else a coded fallback.
+    const errorLines = output.trim().split('\n').slice(-5).join('\n');
+    const fallback = res.error
+      ? `Failed to run opencode: ${res.error.message}`
+      : `OpenCode CLI exited with code ${agentExitCode}`;
+    return {
+      ok: false,
+      output,
+      transcript,
+      observedModel: observedModelOrNull,
+      error: errorLines || fallback,
+      agentExitCode,
+    };
+  }
+
+  return {
+    ok: true,
+    output,
+    transcript,
+    observedModel: observedModelOrNull,
+    error: null,
+    agentExitCode,
+  };
+}
+
+/* ─────────────────────────── runnable (CLI) entry ─────────────────────────── */
+
+// True when this file is executed directly (`node run.mjs ...`), false when imported.
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+
+if (isMain) {
+  // argv[2] is the AgentRunInput JSON (never contains secrets).
+  const input = JSON.parse(process.argv[2]);
+
+  // Always produce a RunnerResult, even if the runner itself throws, so the host
+  // always has a result file to read (node exit code stays 0 except on a truly
+  // unrecoverable crash before we can write).
+  let result;
+  try {
+    result = await runAgent(input);
+  } catch (e) {
+    result = {
+      ok: false,
+      output: '',
+      transcript: null,
+      observedModel: null,
+      error: e && e.message ? e.message : String(e),
+      agentExitCode: -1,
+    };
+  }
+
+  // Source of truth: the result file the host reads back via sandbox.readFile.
+  try {
+    mkdirSync(dirname(input.resultPath), { recursive: true });
+    writeFileSync(input.resultPath, JSON.stringify(result));
+  } catch {
+    // If the file can't be written, the host falls back to the marker line below.
+  }
+
+  // Fallback channel: a compact status line (no transcript — it can be huge).
+  process.stdout.write(
+    '__AGENT_RESULT__ ' +
+      JSON.stringify({
+        ok: result.ok,
+        observedModel: result.observedModel,
+        error: result.error,
+        agentExitCode: result.agentExitCode,
+      }) +
+      '\n'
+  );
+
+  // Exit 0: "the runner ran". Agent success/failure is conveyed via result.ok, not
+  // the node exit code (the host distinguishes the two).
+  process.exit(0);
+}

package/dist/lib/agents/plugin/contract.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Agent plugin contract.
+ *
+ * An agent is described in two halves:
+ *
+ *   1. an {@link AgentDefinition} — HOST-side data + tiny pure functions that say
+ *      *how to set up and authenticate* the agent (install commands, config files,
+ *      auth env). It performs NO sandbox lifecycle and NO CLI invocation itself.
+ *
+ *   2. a `run.mjs` — a SANDBOX-side script (one per agent) that actually invokes
+ *      the CLI and captures its transcript, returning a {@link RunnerResult}.
+ *
+ * The generic {@link runWithDefinition} orchestrator (orchestrator.ts) consumes a
+ * definition, drives the shared sandbox lifecycle, ships the agent's `run.mjs` into
+ * the sandbox, invokes it, and assembles the final `AgentRunResult`.
+ *
+ * This split exists so the invocation logic lives *in the sandbox* (where a future
+ * in-sandbox judge can `import { runAgent }` and reuse it) rather than only on the
+ * host. See the migration notes in the PR for the full rationale.
+ */
+import type { ModelTier } from '../../types.js';
+import type { AgentRunOptions } from '../types.js';
+/**
+ * One install action the orchestrator runs in the sandbox before invocation.
+ *
+ * Each step carries its own failure policy so the per-agent install error
+ * messages are preserved verbatim (e.g. claude throws `Claude Code install
+ * failed: <stderr>`, the project `npm install` throws `npm install failed
+ * (exit code N):\n<last 10 lines>` and is retried once).
+ */
+export interface InstallStep {
+    /** 'command' → sandbox.runCommand(cmd, args); 'shell' → sandbox.runShell(script). */
+    kind: 'command' | 'shell';
+    /** For kind:'command'. */
+    cmd?: string;
+    args?: string[];
+    /** For kind:'shell'. */
+    script?: string;
+    /** Retry once on a non-zero exit before failing (the project `npm install`). */
+    retryOnce?: boolean;
+    /** Prefix of the thrown Error on final failure, e.g. 'Claude Code install failed'. */
+    errorPrefix: string;
+    /**
+     * How the failure body is rendered in the thrown Error, to match today's wording:
+     *  - 'last10':  `${errorPrefix} (exit code N):\n<last 10 lines of stdout+stderr>`
+     *  - 'stderr':  `${errorPrefix}: <stderr>`
+     */
+    errorBody: 'last10' | 'stderr';
+}
+/**
+ * One config file an agent writes into the sandbox before invocation.
+ * Either a writeFiles target (relative to cwd) or a shell snippet — the latter is
+ * the escape hatch for absolute `~` paths that writeFiles cannot target (codex's
+ * `~/.codex/default.config.toml`).
+ */
+export interface ConfigFile {
+    /** writeFiles target path (relative to cwd). Mutually exclusive with viaShell. */
+    path?: string;
+    content?: string;
+    /** Exact shell to run instead, e.g. `mkdir -p ~/.codex && cat > ~/.codex/... << 'EOF' ...`. */
+    viaShell?: string;
+}
+/**
+ * Host-side plugin description for one agent. Pure data + tiny pure functions —
+ * no sandbox calls, no CLI invocation.
+ */
+export interface AgentDefinition {
+    /** Registry name, unchanged: 'claude-code' | 'vercel-ai-gateway/claude-code' | ... */
+    name: string;
+    /** Human-readable name (logs/UI), unchanged from the old adapter. */
+    displayName: string;
+    /** Default model tier when none is provided (old getDefaultModel()). */
+    defaultModel: ModelTier;
+    /** Parser name handed to parseTranscript() on the host ('claude-code'|'codex'|...). */
+    o11yAgentName: string;
+    /** Absolute path to this agent's run.mjs (resolved from the definition's import.meta.url). */
+    runnerPath: string;
+    /**
+     * Which host env var the apiKey is read from. Mirrors the old getApiKeyEnvVar()
+     * EXACTLY, including claude-code's 3-way runtime branch (gateway →
+     * CLAUDE_CODE_OAUTH_TOKEN → ANTHROPIC_API_KEY). Stays a function because it reads
+     * process.env at call time.
+     */
+    getApiKeyEnvVar(): string;
+    /** Ordered install steps (project deps + the agent CLI), run by the orchestrator. */
+    install(options: AgentRunOptions): InstallStep[];
+    /** Config files written before invocation (codex TOML, opencode.json). [] for most. */
+    configFiles(options: AgentRunOptions): ConfigFile[];
+    /**
+     * The agent-specific auth/env handed to the run.mjs process (merged with the
+     * neutral-workspace env by the orchestrator). This is the ONLY place provider
+     * auth branching lives. Receives the resolved apiKey via options.apiKey.
+     */
+    authEnv(options: AgentRunOptions): Record<string, string>;
+    /**
+     * OPTIONAL host-computed values threaded into the runner as `input.extra`.
+     *
+     * Use this when run.mjs needs a value that MUST be derived on the host (e.g.
+     * codex's parseModelString output — the resolved `--model`, reasoning effort,
+     * and verbosity — which must match the TOML config written by configFiles()).
+     * Keeping the derivation host-side avoids re-implementing host-only parsing in
+     * the zero-dependency runner. Must contain NO secrets (it rides in the argv
+     * JSON). Omit (or return undefined) for agents that don't need it.
+     */
+    runnerExtra?(options: AgentRunOptions): Record<string, unknown>;
+}
+/**
+ * What the host passes INTO run.mjs (serialized as argv[2] JSON).
+ *
+ * SECURITY: the apiKey is intentionally NOT here — it travels only via process.env
+ * (and, for codex, the CLI's stdin login). Never put secrets in argv (they show up
+ * in process listings).
+ */
+export interface AgentRunInput {
+    /** The prompt to run, verbatim (any host-side editPrompt was already applied upstream). */
+    prompt: string;
+    /** Model override, or undefined for the CLI's native default. */
+    model?: string;
+    /** 'agent-default' | 'native-default' (opencode toggles --print-logs on native). */
+    modelPolicy?: string;
+    /** Web-research toggle (claude --allowedTools, opencode permissions/env). */
+    webResearch?: boolean;
+    /** Passthrough of agentOptions (e.g. claude effort). Secrets must NOT be in here. */
+    agentOptions?: Record<string, unknown>;
+    /** Absolute sandbox cwd AFTER neutral-workspace relocation (transcript paths use it). */
+    cwd: string;
+    /** Where run.mjs writes its RunnerResult JSON (host reads it back). */
+    resultPath: string;
+    /**
+     * OPTIONAL host-computed values from {@link AgentDefinition.runnerExtra} — see
+     * there for what belongs here and the no-secrets constraint.
+     */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Host↔sandbox result contract. run.mjs writes this JSON to `input.resultPath`
+ * AND prints one `__AGENT_RESULT__ <json>` status line to stdout (a fallback the
+ * host uses only if the result file can't be read).
+ *
+ * The `ok` (agent CLI succeeded) vs the node exit code (the runner itself crashed)
+ * are deliberately separate signals — see the orchestrator's READ RESULT step.
+ */
+export interface RunnerResult {
+    /** True iff the agent CLI exited 0. */
+    ok: boolean;
+    /** Combined stdout + stderr of the agent CLI (old `agentOutput`). */
+    output: string;
+    /** Raw transcript string the runner located (JSONL/JSON), or null. */
+    transcript: string | null;
+    /** Observed model extracted by the runner (claude/codex/opencode), or null. */
+    observedModel: string | null;
+    /** Error message when !ok (old "last 5 lines" / "<Agent> exited with code N"). */
+    error: string | null;
+    /** The agent CLI's exit code (diagnostics; -1 if it could not be spawned). */
+    agentExitCode: number;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/lib/agents/plugin/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../../src/lib/agents/plugin/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,qFAAqF;IACrF,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;IAC1B,0BAA0B;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sFAAsF;IACtF,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,YAAY,EAAE,SAAS,CAAC;IACxB,uFAAuF;IACvF,aAAa,EAAE,MAAM,CAAC;IACtB,8FAA8F;IAC9F,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,eAAe,IAAI,MAAM,CAAC;IAE1B,qFAAqF;IACrF,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW,EAAE,CAAC;IAEjD,uFAAuF;IACvF,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,UAAU,EAAE,CAAC;IAEpD;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE1D;;;;;;;;;OASG;IACH,WAAW,CAAC,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,2FAA2F;IAC3F,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,yFAAyF;IACzF,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,EAAE,EAAE,OAAO,CAAC;IACZ,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,+EAA+E;IAC/E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kFAAkF;IAClF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/dist/lib/agents/plugin/contract.js

@@ -0,0 +1,22 @@
+/**
+ * Agent plugin contract.
+ *
+ * An agent is described in two halves:
+ *
+ *   1. an {@link AgentDefinition} — HOST-side data + tiny pure functions that say
+ *      *how to set up and authenticate* the agent (install commands, config files,
+ *      auth env). It performs NO sandbox lifecycle and NO CLI invocation itself.
+ *
+ *   2. a `run.mjs` — a SANDBOX-side script (one per agent) that actually invokes
+ *      the CLI and captures its transcript, returning a {@link RunnerResult}.
+ *
+ * The generic {@link runWithDefinition} orchestrator (orchestrator.ts) consumes a
+ * definition, drives the shared sandbox lifecycle, ships the agent's `run.mjs` into
+ * the sandbox, invokes it, and assembles the final `AgentRunResult`.
+ *
+ * This split exists so the invocation logic lives *in the sandbox* (where a future
+ * in-sandbox judge can `import { runAgent }` and reuse it) rather than only on the
+ * host. See the migration notes in the PR for the full rationale.
+ */
+export {};
+//# sourceMappingURL=contract.js.map

package/dist/lib/agents/plugin/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../../src/lib/agents/plugin/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}