@vercel/agent-eval 1.1.0 → 1.2.0

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

@@ -0,0 +1,365 @@
+/**
+ * OpenAI Codex 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 `codex` 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 codex.test.ts).
+ *
+ * SECRETS: the apiKey is NOT in the AgentRunInput JSON. It arrives via process.env
+ * (AI_GATEWAY_API_KEY for the gateway, else OPENAI_API_KEY for direct OpenAI) and
+ * is piped into `codex login --with-api-key` over stdin — never on the argv.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Extract transcript from Codex JSON output.
+ * When run with --json, Codex outputs JSONL to stdout with the full transcript.
+ * Preserved verbatim from the old adapter.
+ *
+ * @param {string} output
+ * @returns {string|undefined}
+ */
+export function extractTranscriptFromOutput(output) {
+  if (!output || !output.trim()) {
+    return undefined;
+  }
+
+  // The --json output is already the transcript in JSONL format.
+  // 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');
+}
+
+/**
+ * Find the `thread.started` event's thread_id in Codex JSON stdout.
+ * Preserved verbatim from the old adapter. Non-JSON lines are ignored.
+ *
+ * @param {string} output
+ * @returns {string|undefined}
+ */
+export function extractCodexThreadId(output) {
+  for (const line of output.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const event = JSON.parse(line);
+      if (event.type === 'thread.started' && typeof event.thread_id === 'string') {
+        return event.thread_id;
+      }
+    } catch {
+      // Ignore non-JSON output lines.
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Scan a Codex session transcript (JSONL) for the last `turn_context` model seen.
+ * Preserved verbatim from the old adapter. Non-JSON lines are ignored.
+ *
+ * @param {string|undefined} transcript
+ * @returns {string|undefined}
+ */
+export function extractObservedModelFromCodexSession(transcript) {
+  if (!transcript) return undefined;
+
+  let observedModel;
+  for (const line of transcript.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const event = JSON.parse(line);
+      const model = event.payload?.model ?? event.payload?.collaboration_mode?.settings?.model;
+      if (event.type === 'turn_context' && typeof model === 'string') {
+        observedModel = model;
+      }
+    } catch {
+      // Ignore non-JSON transcript lines.
+    }
+  }
+
+  return observedModel;
+}
+
+/**
+ * Recursively collect every `*.jsonl` file path under `~/.codex/sessions`.
+ * The old adapter used `find ~/.codex/sessions -type f -name '*.jsonl'`.
+ *
+ * @param {string} dir
+ * @returns {string[]} absolute paths
+ */
+function listSessionFiles(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...listSessionFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith('.jsonl')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * Locate + read the Codex session transcript file.
+ *
+ * Codex writes JSONL session files under `~/.codex/sessions`. The old adapter, in
+ * shell, did:
+ *   - with a threadId: `find ... -name '*<threadId>*.jsonl' | head -1`
+ *   - without:         `find ... -name '*.jsonl' | sort | tail -1`
+ *
+ * We mirror that exactly: filter by threadId substring when present (first match),
+ * otherwise lexicographically sort all `.jsonl` paths and take the last. Codex
+ * session filenames are timestamp-prefixed, so the lexicographic max is the newest.
+ *
+ * Best-effort: any failure → undefined (never throws).
+ *
+ * @param {string|undefined} threadId
+ * @returns {string|undefined}
+ */
+function captureCodexSessionTranscript(threadId) {
+  try {
+    const sessionsDir = join(homedir(), '.codex', 'sessions');
+    const files = listSessionFiles(sessionsDir);
+    if (files.length === 0) return undefined;
+
+    let chosen;
+    if (threadId) {
+      // `find ... | head -1`: the first match in the traversal order.
+      chosen = files.find((f) => f.includes(threadId));
+    } else {
+      // `find ... | sort | tail -1`: lexicographic max.
+      chosen = files.slice().sort()[files.length - 1];
+    }
+    if (!chosen) return undefined;
+    return readFileSync(chosen, 'utf8');
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Build the `codex login --with-api-key` arg list. The key itself is piped over
+ * stdin (spawnSync { input }), never placed on the argv.
+ *
+ * @returns {string[]}
+ */
+export function buildCodexLoginArgs() {
+  return ['login', '--with-api-key'];
+}
+
+/**
+ * Build the `codex exec` arg list, reproducing the old shell command verbatim:
+ *   codex exec --profile default[ --model <m>] --dangerously-bypass-approvals-and-sandbox
+ *     --json --skip-git-repo-check[ -c model_reasoning_effort="<e>"]
+ *     [ -c model_verbosity="<v>"] '<prompt>'
+ *
+ * The model / reasoningEffort / verbosity values are HOST-computed (from
+ * parseModelString) and arrive via input.extra so they match the TOML profile.
+ *
+ * Note: with spawnSync (argv, not a shell), the `-c key="value"` tokens keep their
+ * literal quotes exactly as the old shell string had them, and the prompt is a
+ * plain argv element (no shell escaping needed).
+ *
+ * @param {{prompt:string, extra?:Record<string,unknown>}} input
+ * @returns {string[]}
+ */
+export function buildCodexExecArgs(input) {
+  const extra = input.extra ?? {};
+  const cliModel = extra.cliModel ?? null;
+  const reasoningEffort = extra.reasoningEffort ?? null;
+  const verbosity = extra.verbosity ?? null;
+
+  const args = ['exec', '--profile', 'default'];
+  if (cliModel) {
+    args.push('--model', String(cliModel));
+  }
+  args.push('--dangerously-bypass-approvals-and-sandbox', '--json', '--skip-git-repo-check');
+  if (reasoningEffort) {
+    args.push('-c', `model_reasoning_effort="${reasoningEffort}"`);
+  }
+  if (verbosity) {
+    args.push('-c', `model_verbosity="${verbosity}"`);
+  }
+  args.push(input.prompt);
+  return args;
+}
+
+/**
+ * Run Codex over the workspace at `input.cwd` and return a RunnerResult.
+ *
+ * Two-step, mirroring the old adapter's `codex login --with-api-key && codex exec`:
+ *   1. `codex login --with-api-key` with the key piped on stdin. If login exits
+ *      non-zero, short-circuit with ok:false WITHOUT running exec (the old `&&`).
+ *   2. `codex exec ...` — capture transcript + observedModel even on non-zero exit.
+ *
+ * Auth env (AI_GATEWAY_API_KEY / OPENAI_API_KEY) 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 login key is read from that same env.
+ *
+ * @param {import('../plugin/contract.js').AgentRunInput} input
+ * @returns {Promise<import('../plugin/contract.js').RunnerResult>}
+ */
+export async function runAgent(input) {
+  // The login key: gateway runs use AI_GATEWAY_API_KEY; direct OpenAI uses
+  // OPENAI_API_KEY. Reading both (gateway first) keeps the runner agnostic to the
+  // mode while never carrying the secret in the argv JSON.
+  const apiKey = process.env.AI_GATEWAY_API_KEY || process.env.OPENAI_API_KEY || '';
+
+  // Step 1: codex login --with-api-key (key piped on stdin). The built-in openai
+  // provider requires bearer auth; the gateway provider reads env_key but login is
+  // harmless/consistent there too. This is the left side of the old `&&`.
+  const login = spawnSync('codex', buildCodexLoginArgs(), {
+    cwd: input.cwd,
+    env: process.env,
+    input: apiKey,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+  const loginStdout = login.stdout || '';
+  const loginStderr = login.stderr || '';
+  const loginExit = login.status == null ? -1 : login.status;
+
+  if (login.error || loginExit !== 0) {
+    // Short-circuit: the old `codex login ... && codex exec ...` never ran exec
+    // when login failed. Surface the same kind of error (last 5 lines, else coded
+    // fallback) over the login output.
+    const loginOutput = loginStdout + loginStderr;
+    const errorLines = loginOutput.trim().split('\n').slice(-5).join('\n');
+    const fallback = login.error
+      ? `Failed to run codex: ${login.error.message}`
+      : `Codex CLI exited with code ${loginExit}`;
+    return {
+      ok: false,
+      output: loginOutput,
+      transcript: null,
+      observedModel: null,
+      error: errorLines || fallback,
+      agentExitCode: loginExit,
+    };
+  }
+
+  // Step 2: codex exec. Blocking is fine — the runner has nothing else to do while
+  // the agent works. The sandbox-level timeout bounds it.
+  const res = spawnSync('codex', buildCodexExecArgs(input), {
+    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 transcript + observed model regardless of success (the old adapter did
+  // this even on the non-zero-exit path). The inline --json on stdout is the
+  // transcript; observedModel comes from the saved session file under ~/.codex.
+  const transcript = extractTranscriptFromOutput(output) ?? null;
+  const threadId = extractCodexThreadId(output);
+  const sessionTranscript = captureCodexSessionTranscript(threadId);
+  const observedModel = extractObservedModelFromCodexSession(sessionTranscript) ?? 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 codex: ${res.error.message}`
+      : `Codex CLI exited with code ${agentExitCode}`;
+    return {
+      ok: false,
+      output,
+      transcript,
+      observedModel,
+      error: errorLines || fallback,
+      agentExitCode,
+    };
+  }
+
+  return { ok: true, output, transcript, observedModel, 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/cursor/agent.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cursor CLI agent — host-side definition + the thin Agent wrapper.
+ *
+ * The definition is pure data/auth; 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.
+ *
+ * Cursor uses direct Cursor API access only (no gateway branch), so auth is a single
+ * env var (CURSOR_API_KEY). It writes no config files — everything is CLI flags + env.
+ */
+import type { Agent } from '../types.js';
+import type { AgentDefinition } from '../plugin/contract.js';
+/**
+ * Build the Cursor CLI plugin definition.
+ *
+ * Preserved exactly from the old adapter:
+ *   - install: project `npm install` (retried once) then the official install script
+ *     `curl https://cursor.com/install -fsSL | bash` (a SHELL step, since it pipes).
+ *   - no config files.
+ *   - auth: CURSOR_API_KEY only (direct API, no gateway mode).
+ *   - o11y parser name: 'cursor'.
+ *   - default model tier: 'composer-1.5'.
+ */
+export declare function createCursorDefinition(): AgentDefinition;
+/**
+ * Create the Cursor CLI Agent. Thin wrapper over the generic orchestrator so the
+ * Agent interface (and thus registry.ts / index.ts / runner.ts) is unchanged.
+ *
+ * NOTE: keeps the old no-arg signature — index.ts calls `createCursorAgent()`.
+ */
+export declare function createCursorAgent(): Agent;
+//# sourceMappingURL=agent.d.ts.map

package/dist/lib/agents/cursor/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../../src/lib/agents/cursor/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAmB,MAAM,aAAa,CAAC;AAG1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG7D;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CA8CxD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,KAAK,CAWzC"}

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

@@ -0,0 +1,86 @@
+/**
+ * Cursor CLI agent — host-side definition + the thin Agent wrapper.
+ *
+ * The definition is pure data/auth; 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.
+ *
+ * Cursor uses direct Cursor API access only (no gateway branch), so auth is a single
+ * env var (CURSOR_API_KEY). It writes no config files — everything is CLI flags + env.
+ */
+import { fileURLToPath } from 'node:url';
+import { CURSOR_DIRECT } from '../shared.js';
+import { runWithDefinition } from '../plugin/orchestrator.js';
+/**
+ * Build the Cursor CLI plugin definition.
+ *
+ * Preserved exactly from the old adapter:
+ *   - install: project `npm install` (retried once) then the official install script
+ *     `curl https://cursor.com/install -fsSL | bash` (a SHELL step, since it pipes).
+ *   - no config files.
+ *   - auth: CURSOR_API_KEY only (direct API, no gateway mode).
+ *   - o11y parser name: 'cursor'.
+ *   - default model tier: 'composer-1.5'.
+ */
+export function createCursorDefinition() {
+    return {
+        name: 'cursor',
+        displayName: 'Cursor CLI',
+        defaultModel: 'composer-1.5',
+        o11yAgentName: 'cursor',
+        // 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)),
+        getApiKeyEnvVar() {
+            return CURSOR_DIRECT.apiKeyEnvVar;
+        },
+        install(_options) {
+            // Project deps (retried once), then the Cursor CLI via the official installer.
+            // The installer pipes curl→bash, so it must be a 'shell' step (not 'command').
+            return [
+                {
+                    kind: 'command',
+                    cmd: 'npm',
+                    args: ['install'],
+                    retryOnce: true,
+                    errorPrefix: 'npm install failed',
+                    errorBody: 'last10',
+                },
+                {
+                    kind: 'shell',
+                    script: 'curl https://cursor.com/install -fsSL | bash',
+                    errorPrefix: 'Cursor CLI install failed',
+                    errorBody: 'stderr',
+                },
+            ];
+        },
+        // Cursor is configured purely via CLI flags + env — no config files.
+        configFiles() {
+            return [];
+        },
+        authEnv(options) {
+            // Direct API only: a single key env var. (The neutral-workspace env is merged
+            // on top by the orchestrator.)
+            return { [CURSOR_DIRECT.apiKeyEnvVar]: options.apiKey };
+        },
+    };
+}
+/**
+ * Create the Cursor CLI Agent. Thin wrapper over the generic orchestrator so the
+ * Agent interface (and thus registry.ts / index.ts / runner.ts) is unchanged.
+ *
+ * NOTE: keeps the old no-arg signature — index.ts calls `createCursorAgent()`.
+ */
+export function createCursorAgent() {
+    const definition = createCursorDefinition();
+    return {
+        name: definition.name,
+        displayName: definition.displayName,
+        getApiKeyEnvVar: definition.getApiKeyEnvVar,
+        getDefaultModel() {
+            return definition.defaultModel;
+        },
+        run: (fixturePath, options) => runWithDefinition(definition, fixturePath, options),
+    };
+}
+//# sourceMappingURL=agent.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../../src/lib/agents/cursor/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAIzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,YAAY;QACzB,YAAY,EAAE,cAAc;QAC5B,aAAa,EAAE,QAAQ;QACvB,+EAA+E;QAC/E,6DAA6D;QAC7D,UAAU,EAAE,aAAa,CAAC,IAAI,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEhE,eAAe;YACb,OAAO,aAAa,CAAC,YAAY,CAAC;QACpC,CAAC;QAED,OAAO,CAAC,QAAyB;YAC/B,+EAA+E;YAC/E,+EAA+E;YAC/E,OAAO;gBACL;oBACE,IAAI,EAAE,SAAS;oBACf,GAAG,EAAE,KAAK;oBACV,IAAI,EAAE,CAAC,SAAS,CAAC;oBACjB,SAAS,EAAE,IAAI;oBACf,WAAW,EAAE,oBAAoB;oBACjC,SAAS,EAAE,QAAQ;iBACpB;gBACD;oBACE,IAAI,EAAE,OAAO;oBACb,MAAM,EAAE,8CAA8C;oBACtD,WAAW,EAAE,2BAA2B;oBACxC,SAAS,EAAE,QAAQ;iBACpB;aACF,CAAC;QACJ,CAAC;QAED,qEAAqE;QACrE,WAAW;YACT,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,OAAO,CAAC,OAAwB;YAC9B,8EAA8E;YAC9E,+BAA+B;YAC/B,OAAO,EAAE,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QAC1D,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,UAAU,GAAG,sBAAsB,EAAE,CAAC;IAC5C,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,eAAe,EAAE,UAAU,CAAC,eAAe;QAC3C,eAAe;YACb,OAAO,UAAU,CAAC,YAAY,CAAC;QACjC,CAAC;QACD,GAAG,EAAE,CAAC,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC,iBAAiB,CAAC,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC;KACnF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,183 @@
+/**
+ * Cursor CLI 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 `agent` (Cursor) 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.
+ *
+ * Cursor's transcript is the `--output-format stream-json` JSONL it prints to
+ * stdout/stderr — there is no on-disk session file to read, and (like gemini) no
+ * observed-model extraction, so observedModel is always null.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Build the Cursor CLI argument list.
+ *
+ * Order is regression-sensitive (preserved verbatim from the old adapter):
+ *   - the prompt is the FIRST positional argument.
+ *   - `--print`:  non-interactive mode (required for scripts/headless).
+ *   - `--force`:  auto-approve all tool operations.
+ *   - `--model`:  only when a model override is provided.
+ *   - `--output-format stream-json`: structured JSONL transcript (only works with
+ *     --print). Emitted LAST, exactly as the old adapter did.
+ *
+ * @param {{prompt:string, model?:string}} input
+ * @returns {string[]}
+ */
+export function buildCursorCliArgs(input) {
+  const cursorArgs = [input.prompt, '--print', '--force'];
+  if (input.model) {
+    cursorArgs.push('--model', input.model);
+  }
+  cursorArgs.push('--output-format', 'stream-json');
+  return cursorArgs;
+}
+
+/**
+ * Extract transcript from Cursor CLI stream-json output.
+ * When run with `--output-format stream-json`, Cursor outputs JSONL
+ * (newline-delimited JSON). Preserved verbatim from the old adapter: keep only the
+ * lines that look like a complete JSON object (start with `{` and end with `}`).
+ *
+ * @param {string|undefined|null} output
+ * @returns {string|undefined}
+ */
+export function extractTranscriptFromOutput(output) {
+  if (!output || !output.trim()) {
+    return undefined;
+  }
+
+  // The --output-format stream-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');
+}
+
+/**
+ * Run Cursor over the workspace at `input.cwd` and return a RunnerResult.
+ *
+ * Auth (CURSOR_API_KEY) 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 = buildCursorCliArgs(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.
+  // The Cursor binary is named `agent` (preserved from the old adapter).
+  const res = spawnSync('agent', 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;
+
+  // Transcript from the stream-json output; Cursor has no observed-model extraction.
+  const transcript = extractTranscriptFromOutput(output) ?? null;
+  const 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 agent: ${res.error.message}`
+      : `Cursor CLI exited with code ${agentExitCode}`;
+    return {
+      ok: false,
+      output,
+      transcript,
+      observedModel,
+      error: errorLines || fallback,
+      agentExitCode,
+    };
+  }
+
+  return { ok: true, output, transcript, observedModel, 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);
+}