@jonaspauleta/cursor-bridge 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 João Paulo Santos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# cursor-bridge
+
+A thin MCP server bridging coding-agent CLIs to Claude Code (Opus). It exposes two
+tools: `run_cursor_agent`, which offloads implementation/review tasks to Cursor's
+`cursor-agent` CLI (Composer 2.5 Fast by default), and `generate_image`, which
+generates/edits images with `gpt-image-2` by driving the Codex CLI. The final review
+gate stays on Opus.
+
+## Use via npx (recommended)
+
+Published as [`@jonaspauleta/cursor-bridge`](https://www.npmjs.com/package/@jonaspauleta/cursor-bridge). No clone or build needed:
+
+    # one-off
+    CURSOR_BRIDGE_ALLOWED_ROOT="$(pwd)" npx -y @jonaspauleta/cursor-bridge
+
+Register with Claude Code:
+
+    claude mcp add --transport stdio --scope project \
+      --env CURSOR_BRIDGE_ALLOWED_ROOT="$(pwd)" \
+      cursor-bridge -- npx -y @jonaspauleta/cursor-bridge
+
+Or as project-scoped `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cursor-bridge": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@jonaspauleta/cursor-bridge"],
+      "env": {
+        "CURSOR_API_KEY": "${CURSOR_API_KEY:-}",
+        "CURSOR_BRIDGE_ALLOWED_ROOT": "${CLAUDE_PROJECT_DIR}"
+      }
+    }
+  }
+}
+```
+
+You can also run straight from GitHub without npm: `npx github:jonaspauleta/cursor-bridge`
+(npx clones and builds via the `prepare` hook).
+
+**Prerequisites (not bundled):** the `cursor-agent` CLI (for `run_cursor_agent`) and/or
+the `codex` CLI v0.134.0+ (for `generate_image`) must be installed on PATH and logged in
+(`cursor-agent login` / `codex login`). `CURSOR_BRIDGE_ALLOWED_ROOT` is required and must
+be an absolute path. (This repo's own committed `.mcp.json` intentionally keeps pointing
+at local `dist/` for development.)
+
+## Build & run
+
+    npm install
+    npm run build          # -> dist/index.js
+    node dist/index.js     # stdio MCP server (Claude Code launches this for you)
+
+## Register with Claude Code
+
+Either commit `.mcp.json` (project scope) or run:
+
+    # Export CURSOR_API_KEY in your shell profile — do NOT put it on argv (ps/history leak).
+    claude mcp add --transport stdio --scope project \
+      --env CURSOR_BRIDGE_ALLOWED_ROOT="$(pwd)" \
+      cursor-bridge -- node dist/index.js
+
+`CURSOR_API_KEY` is read from the ambient environment via `.mcp.json`'s
+`${CURSOR_API_KEY}` and never hardcoded or passed on a command line. If unset,
+`cursor-agent` falls back to your interactive `cursor-agent login` session.
+`CURSOR_BRIDGE_ALLOWED_ROOT` is required and must be an absolute path.
+
+## The tool: `run_cursor_agent`
+
+| input | type | default | notes |
+|-------|------|---------|-------|
+| `prompt` | string | — | task/prompt sent to the worker |
+| `cwd` | string | — | working dir; validated against `CURSOR_BRIDGE_ALLOWED_ROOT` |
+| `mode` | `default`/`plan`/`ask` | `default` | default = read-write (`--force`); plan/ask = read-only |
+| `model` | string | `composer-2.5-fast` | allowlisted (`composer-2.5-fast`, `composer-2.5`, `claude-4.6-sonnet-medium`) |
+| `timeoutMs` | number | `270000` | wall-clock; wrapper SIGKILLs cursor-agent past this |
+
+Returns the worker's final text on `SUCCESS` (plus `structuredContent` with usage).
+Every other outcome returns `isError: true` with a taxonomy-tagged message.
+
+## The tool: `generate_image`
+
+Generates or edits images with `gpt-image-2` by driving `codex exec` with the
+`$imagegen` skill. **Subscription-only:** it uses your `codex login` (ChatGPT/Codex
+plan) auth and counts toward your Codex usage limits — no API key. `OPENAI_API_KEY` is
+scrubbed from the child env so an ambient key can't silently switch you to API billing.
+
+| input | type | default | notes |
+|-------|------|---------|-------|
+| `prompt` | string | — | image task; free-form, may include edit/iterate instructions |
+| `outputDir` | string | `<allowedRoot>/generated-images` | absolute, validated inside the allowed root |
+| `referenceImages` | string[] | — | paths attached via Codex `-i` (edit/iterate); png/jpg/jpeg/webp, inside root, max 8 |
+| `count` | number | `1` | 1–10 (gpt-image-2 ceiling) |
+| `size` | enum | `auto` | `auto`/`1024x1024`/`1536x1024`/`1024x1536` (best-effort directive) |
+| `quality` | enum | `auto` | `auto`/`low`/`medium`/`high` (best-effort directive) |
+| `inlineImages` | boolean | `false` | also return generated images as base64 blocks (first 4) |
+| `timeoutMs` | number | `300000` | wall-clock; wrapper SIGKILLs codex past this |
+
+Each call writes into a fresh `<outputDir>/<runId>/` subdir. On `SUCCESS` it returns the
+generated file paths (and Codex's summary); every other outcome returns `isError: true`.
+`size`/`quality`/`count` are natural-language directives templated into the prompt (the
+built-in `image_gen` tool is invoked by the model, not via CLI flags), so they are
+best-effort rather than hard API parameters.
+
+**Status taxonomy:** `SUCCESS | NO_IMAGE | AUTH_REQUIRED | TIMEOUT | TOOL_ERROR`. Success
+means ≥1 image file actually landed on disk — the exit code is not trusted.
+
+**Requirements:** the `codex` CLI (v0.134.0+) must be installed and on the server's PATH,
+and you must be logged in (`codex login`; check with `codex login status`). Override the
+binary with `CODEX_AGENT_BIN`. Unlike `cursor-agent`, Codex's `-s workspace-write`
+sandbox is genuinely enforced, so the image worker can only write within the workspace
+root and cannot run destructive shell outside it.
+
+Smoke test: `npm run test:smoke:codex` (live gpt-image-2 call; requires `codex login`).
+
+## Status taxonomy
+
+`SUCCESS | AUTH_REQUIRED | TIMEOUT | TOOL_ERROR | MALFORMED`. Success requires a
+parsed `{"type":"result"}` envelope with `is_error:false`; the exit code is NOT
+trusted (the auth-failure path is exit-code-unstable).
+
+## Auth pre-flight
+
+    cursor-agent status --format json   # {"isAuthenticated":true,...}
+
+The server exposes `preflightAuth()` for a fail-fast check before a real call.
+
+## Security notes
+
+- argv is always an array; `spawn` runs with no shell — no command injection via the wrapper.
+- All MCP-tool inputs pass `src/validate.ts` (mode/model allowlist, cwd allowlist + symlink-safe) before reaching argv. The git-diff SHAs used by the *final review gate* are NOT validated here — they live in the orchestrator's shell (Part B) and are resolved mechanically with `git rev-parse`, never taken from task text.
+- Secrets come from env only; the logger redacts secret-looking values and never logs prompt bodies or raw output (stderr only). Never pass `CURSOR_API_KEY` on a command line (`ps`/history leak) — export it in your shell profile so `.mcp.json`'s `${CURSOR_API_KEY}` picks it up.
+- `CURSOR_BRIDGE_ALLOWED_ROOT` is REQUIRED and must be absolute; the server refuses to start otherwise and logs the resolved root. Set it as narrowly as possible.
+- **Blast radius — VERIFIED on `cursor-agent` v2026.05.28: `--sandbox enabled` does NOT contain a `--force` worker on this build.** A probe worker wrote a file outside `--workspace` (into `$HOME`) despite `--sandbox enabled`. `--mode plan`/`ask` are genuinely read-only and safe. But `mode:default` passes `--force` (auto-approves arbitrary shell + writes) and `--workspace` is only a cwd, not a jail — so a default-mode worker is effectively **full user-level shell**: it can read `~/.ssh`, exfiltrate over the network, or `git push`. The wrapper still passes `--sandbox enabled` (harmless future-proofing should a later build enforce it — re-run the Task A20 Step 5 probe to recheck), but **today you MUST treat `mode:default` as unsandboxed** and run workers ONLY in disposable/throwaway git worktrees with NO access to real secrets. The `assertWorkspacePath` allow-root and the Opus security gate are the real controls; cwd validation alone does not contain `--force`.
+
+## Tests
+
+    npm test               # unit + in-memory round-trip (no network)
+    npm run test:smoke     # RUN_CURSOR_SMOKE=1; live call to Composer 2.5 Fast

package/dist/classify.d.ts

@@ -0,0 +1,8 @@
+import type { CursorResult } from "./errors.js";
+export declare const stripAnsi: (s: string) => string;
+/**
+ * Pure classification of captured streams into a CursorResult.
+ * Never spawns, never times. The exit code is intentionally ignored: the
+ * auth-failure path is exit-code-unstable and emits no result envelope.
+ */
+export declare function classify(stdout: string, stderr: string): CursorResult;

package/dist/classify.js

@@ -0,0 +1,62 @@
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+export const stripAnsi = (s) => s.replace(ANSI_RE, "");
+const AUTH_MARKERS = [
+    /API key is invalid/i,
+    /not logged in/i,
+    /\bauthenticate\b/i,
+    /unauthorized/i,
+    /session expired/i,
+    /provided API key/i,
+];
+const RESULT_HINT = /"type"\s*:\s*"result"/;
+/**
+ * Pure classification of captured streams into a CursorResult.
+ * Never spawns, never times. The exit code is intentionally ignored: the
+ * auth-failure path is exit-code-unstable and emits no result envelope.
+ */
+export function classify(stdout, stderr) {
+    let envelope = null;
+    let sawUnparseableResultLine = false;
+    for (const rawLine of stripAnsi(stdout).split("\n")) {
+        const line = rawLine.trim();
+        if (!line || line[0] !== "{")
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            // Looks like JSON, mentions a result envelope, but won't parse -> malformed candidate.
+            if (RESULT_HINT.test(line))
+                sawUnparseableResultLine = true;
+            continue;
+        }
+        if (obj && typeof obj === "object" && obj.type === "result") {
+            envelope = obj;
+            break;
+        }
+    }
+    if (envelope) {
+        if (envelope.is_error === false && typeof envelope.result === "string") {
+            return {
+                status: "SUCCESS",
+                result: envelope.result,
+                usage: envelope.usage,
+                sessionId: envelope.session_id,
+                requestId: envelope.request_id,
+                raw: stdout,
+            };
+        }
+        // Parsed a result envelope, but it's an error / has no string result.
+        return { status: "TOOL_ERROR", error: "cursor-agent returned an error result", raw: stdout };
+    }
+    if (sawUnparseableResultLine) {
+        return { status: "MALFORMED", error: "result line present but unparseable", raw: stdout };
+    }
+    const scan = stripAnsi(`${stdout}\n${stderr}`);
+    if (AUTH_MARKERS.some((re) => re.test(scan))) {
+        return { status: "AUTH_REQUIRED", error: "cursor-agent reported an auth problem", raw: scan };
+    }
+    return { status: "TOOL_ERROR", error: "no result envelope emitted", raw: scan };
+}
+//# sourceMappingURL=classify.js.map

package/dist/classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../src/classify.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,GAAG,iBAAiB,CAAC;AAClC,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAEvE,MAAM,YAAY,GAAsB;IACtC,qBAAqB;IACrB,gBAAgB;IAChB,mBAAmB;IACnB,eAAe;IACf,kBAAkB;IAClB,mBAAmB;CACpB,CAAC;AAEF,MAAM,WAAW,GAAG,uBAAuB,CAAC;AAW5C;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAc,EAAE,MAAc;IACrD,IAAI,QAAQ,GAA0B,IAAI,CAAC;IAC3C,IAAI,wBAAwB,GAAG,KAAK,CAAC;IAErC,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG;YAAE,SAAS;QACvC,IAAI,GAAY,CAAC;QACjB,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,uFAAuF;YACvF,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,wBAAwB,GAAG,IAAI,CAAC;YAC5D,SAAS;QACX,CAAC;QACD,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAK,GAA0B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACpF,QAAQ,GAAG,GAAqB,CAAC;YACjC,MAAM;QACR,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,QAAQ,CAAC,QAAQ,KAAK,KAAK,IAAI,OAAO,QAAQ,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACvE,OAAO;gBACL,MAAM,EAAE,SAAS;gBACjB,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,KAAK,EAAE,QAAQ,CAAC,KAAK;gBACrB,SAAS,EAAE,QAAQ,CAAC,UAAU;gBAC9B,SAAS,EAAE,QAAQ,CAAC,UAAU;gBAC9B,GAAG,EAAE,MAAM;aACZ,CAAC;QACJ,CAAC;QACD,sEAAsE;QACtE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,uCAAuC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAC/F,CAAC;IAED,IAAI,wBAAwB,EAAE,CAAC;QAC7B,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,qCAAqC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAC5F,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,KAAK,MAAM,EAAE,CAAC,CAAC;IAC/C,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,uCAAuC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;IAChG,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,4BAA4B,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;AAClF,CAAC"}

package/dist/codex.classify.d.ts

@@ -0,0 +1,15 @@
+import type { ImageResult } from "./errors.js";
+export interface ClassifyImageInput {
+    /** Image files found in the run subdir (absolute paths). */
+    files: string[];
+    /** Contents of --output-last-message (may be empty). */
+    summary: string;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Pure classification of an image-generation run. Success is determined by the
+ * FILESYSTEM (image files on disk), never the exit code. The caller (codex.ts)
+ * handles TIMEOUT and spawn/validation TOOL_ERROR before calling this.
+ */
+export declare function classifyImage(input: ClassifyImageInput): ImageResult;

package/dist/codex.classify.js

@@ -0,0 +1,34 @@
+import { stripAnsi } from "./classify.js";
+const AUTH_MARKERS = [
+    /not logged in/i,
+    /codex login/i,
+    /unauthorized/i,
+    /\b401\b/,
+    /please (?:run )?login/i,
+];
+/**
+ * Pure classification of an image-generation run. Success is determined by the
+ * FILESYSTEM (image files on disk), never the exit code. The caller (codex.ts)
+ * handles TIMEOUT and spawn/validation TOOL_ERROR before calling this.
+ */
+export function classifyImage(input) {
+    if (input.files.length > 0) {
+        return {
+            status: "SUCCESS",
+            images: input.files,
+            summary: input.summary.trim() || undefined,
+            count: input.files.length,
+        };
+    }
+    const scan = stripAnsi(`${input.stdout}\n${input.stderr}`);
+    if (AUTH_MARKERS.some((re) => re.test(scan))) {
+        return { status: "AUTH_REQUIRED", error: "codex reported an auth problem", raw: scan };
+    }
+    return {
+        status: "NO_IMAGE",
+        error: "codex produced no image file",
+        summary: input.summary.trim() || undefined,
+        raw: scan,
+    };
+}
+//# sourceMappingURL=codex.classify.js.map

package/dist/codex.classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex.classify.js","sourceRoot":"","sources":["../src/codex.classify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAG1C,MAAM,YAAY,GAAsB;IACtC,gBAAgB;IAChB,cAAc;IACd,eAAe;IACf,SAAS;IACT,wBAAwB;CACzB,CAAC;AAWF;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,OAAO;YACL,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,KAAK,CAAC,KAAK;YACnB,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,SAAS;YAC1C,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;SAC1B,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3D,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,gCAAgC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;IACzF,CAAC;IACD,OAAO;QACL,MAAM,EAAE,UAAU;QAClB,KAAK,EAAE,8BAA8B;QACrC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,SAAS;QAC1C,GAAG,EAAE,IAAI;KACV,CAAC;AACJ,CAAC"}

package/dist/codex.d.ts

@@ -0,0 +1,20 @@
+import { type Runner } from "./runner.js";
+import { type ImageSize, type ImageQuality } from "./validate.js";
+import { type LogFields } from "./logger.js";
+import type { ImageResult } from "./errors.js";
+export interface GenerateImageOptions {
+    outputDir?: string;
+    referenceImages?: string[];
+    count?: number;
+    size?: ImageSize;
+    quality?: ImageQuality;
+    timeoutMs?: number;
+    allowedRoot?: string;
+    env?: NodeJS.ProcessEnv;
+    runner?: Runner;
+    log?: (fields: LogFields) => void;
+    bin?: string;
+    /** Injectable for deterministic test output subdirs; defaults to timestamp+random. */
+    runId?: string;
+}
+export declare function generateImage(prompt: string, opts?: GenerateImageOptions): Promise<ImageResult>;

package/dist/codex.js

@@ -0,0 +1,158 @@
+import { mkdirSync, readdirSync, readFileSync, rmSync, copyFileSync } from "node:fs";
+import { join, isAbsolute } from "node:path";
+import { tmpdir, homedir } from "node:os";
+import { realRunner, collectStream } from "./runner.js";
+import { classifyImage } from "./codex.classify.js";
+import { assertOutputDir, assertReferenceImages, assertCount, assertSize, assertQuality, } from "./validate.js";
+import { createLogger } from "./logger.js";
+import { ValidationError } from "./errors.js";
+const DEFAULT_TIMEOUT_MS = 300_000;
+const IMAGE_EXT_RE = /\.(png|jpe?g|webp)$/i;
+/** Builds the natural-language directive sent to codex (size/quality/count are best-effort hints). */
+function buildDirective(prompt, count, size, quality, runSubdir) {
+    const sizeClause = size === "auto" ? "at the most appropriate size" : `at ${size}`;
+    const qualityClause = quality === "auto" ? "" : ` Use ${quality} quality.`;
+    return (`$imagegen\n${prompt}\n\n` +
+        `Generate exactly ${count} image${count === 1 ? "" : "s"} ${sizeClause}.${qualityClause} ` +
+        `Save every generated image as a PNG file into the directory ${runSubdir}. ` +
+        `Do not write any other files.`);
+}
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function scanImages(dir) {
+    return safeReaddir(dir)
+        .filter((f) => IMAGE_EXT_RE.test(f))
+        .map((f) => join(dir, f))
+        .sort();
+}
+export async function generateImage(prompt, opts = {}) {
+    const runner = opts.runner ?? realRunner;
+    const log = opts.log ?? createLogger();
+    const bin = opts.bin ?? process.env.CODEX_AGENT_BIN ?? "codex";
+    const env = opts.env ?? process.env;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let refs;
+    let count;
+    let size;
+    let quality;
+    let runSubdir;
+    let allowedRoot;
+    try {
+        allowedRoot = opts.allowedRoot ?? process.env.CURSOR_BRIDGE_ALLOWED_ROOT ?? "";
+        if (!allowedRoot || !isAbsolute(allowedRoot)) {
+            throw new ValidationError("CURSOR_BRIDGE_ALLOWED_ROOT must be set to an absolute path (refusing to default to cwd)");
+        }
+        const outputDir = assertOutputDir(opts.outputDir ?? join(allowedRoot, "generated-images"), allowedRoot);
+        count = assertCount(opts.count ?? 1);
+        size = assertSize(opts.size ?? "auto");
+        quality = assertQuality(opts.quality ?? "auto");
+        refs = assertReferenceImages(opts.referenceImages ?? [], allowedRoot);
+        const runId = opts.runId ?? `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        runSubdir = join(outputDir, runId);
+        mkdirSync(runSubdir, { recursive: true });
+    }
+    catch (e) {
+        const r = { status: "TOOL_ERROR", error: e instanceof ValidationError ? e.message : String(e) };
+        log({ event: "codex_imagegen", level: "error", status: r.status });
+        return r;
+    }
+    const promptText = buildDirective(prompt, count, size, quality, runSubdir);
+    const lastMsgFile = join(tmpdir(), `codex-lastmsg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.txt`);
+    const args = [
+        "exec",
+        promptText,
+        "-C", allowedRoot,
+        "-s", "workspace-write",
+        "--skip-git-repo-check",
+        "--add-dir", runSubdir,
+        "--output-last-message", lastMsgFile,
+        "--color", "never",
+    ];
+    for (const ref of refs) {
+        args.push("--image", ref);
+    }
+    // Subscription-only: scrub OPENAI_API_KEY so an ambient key can't switch codex to API billing.
+    const childEnv = { ...env };
+    delete childEnv.OPENAI_API_KEY;
+    // Snapshot codex's default image dir so we can recover images if it ignores the save-path directive.
+    const homeImagesDir = join(env.CODEX_HOME ?? join(homedir(), ".codex"), "generated_images");
+    const beforeHome = new Set(safeReaddir(homeImagesDir));
+    const startedAt = Date.now();
+    const child = runner(bin, args, { env: childEnv, cwd: allowedRoot });
+    const outP = collectStream(child.stdout);
+    const errP = collectStream(child.stderr);
+    try {
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, timeoutMs);
+        let spawnError;
+        try {
+            await child.done;
+        }
+        catch (e) {
+            spawnError = e;
+        }
+        clearTimeout(timer);
+        const durationMs = Date.now() - startedAt;
+        if (timedOut) {
+            const r = { status: "TIMEOUT", error: `killed after ${timeoutMs}ms`, raw: outP.current() };
+            log({ event: "codex_imagegen", level: "warn", status: r.status, durationMs });
+            return r;
+        }
+        if (spawnError) {
+            const r = { status: "TOOL_ERROR", error: spawnError.message };
+            log({ event: "codex_imagegen", level: "error", status: r.status, durationMs });
+            return r;
+        }
+        const [out, err] = await Promise.all([outP.done, errP.done]);
+        let summary = "";
+        try {
+            summary = readFileSync(lastMsgFile, "utf8");
+        }
+        catch {
+            /* no last-message file — summary stays empty */
+        }
+        let files = scanImages(runSubdir);
+        if (files.length === 0) {
+            // Fallback: codex may have saved to its default ~/.codex/generated_images instead.
+            // Copy any NEW images (by filename) into our run subdir. Defensive; covered by smoke.
+            for (const f of safeReaddir(homeImagesDir)) {
+                if (IMAGE_EXT_RE.test(f) && !beforeHome.has(f)) {
+                    try {
+                        copyFileSync(join(homeImagesDir, f), join(runSubdir, f));
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            }
+            files = scanImages(runSubdir);
+        }
+        const r = classifyImage({ files, summary, stdout: out, stderr: err });
+        log({
+            event: "codex_imagegen",
+            level: r.status === "SUCCESS" ? "info" : "warn",
+            status: r.status,
+            durationMs,
+            count: r.count,
+        });
+        return r;
+    }
+    finally {
+        try {
+            rmSync(lastMsgFile, { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+//# sourceMappingURL=codex.js.map

package/dist/codex.js.map

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

package/dist/codex.preflight.d.ts

@@ -0,0 +1,14 @@
+import { type Runner } from "./runner.js";
+export interface CodexPreflightResult {
+    ok: boolean;
+    reason?: string;
+}
+/**
+ * Fail-fast auth check via `codex login status`. "Not logged in" is checked BEFORE
+ * "logged in" because the negative string contains the positive substring.
+ */
+export declare function preflightCodexAuth(opts?: {
+    env?: NodeJS.ProcessEnv;
+    runner?: Runner;
+    bin?: string;
+}): Promise<CodexPreflightResult>;

package/dist/codex.preflight.js

@@ -0,0 +1,27 @@
+import { realRunner, collectStream } from "./runner.js";
+import { stripAnsi } from "./classify.js";
+/**
+ * Fail-fast auth check via `codex login status`. "Not logged in" is checked BEFORE
+ * "logged in" because the negative string contains the positive substring.
+ */
+export async function preflightCodexAuth(opts = {}) {
+    const runner = opts.runner ?? realRunner;
+    const bin = opts.bin ?? process.env.CODEX_AGENT_BIN ?? "codex";
+    const child = runner(bin, ["login", "status"], { env: opts.env ?? process.env });
+    const outP = collectStream(child.stdout);
+    const errP = collectStream(child.stderr);
+    try {
+        await child.done;
+    }
+    catch (e) {
+        return { ok: false, reason: e.message };
+    }
+    const [out, err] = await Promise.all([outP.done, errP.done]);
+    const clean = stripAnsi(`${out}\n${err}`);
+    if (/not logged in/i.test(clean))
+        return { ok: false, reason: "codex reports not logged in" };
+    if (/logged in/i.test(clean))
+        return { ok: true };
+    return { ok: false, reason: "could not determine codex login status" };
+}
+//# sourceMappingURL=codex.preflight.js.map

package/dist/codex.preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex.preflight.js","sourceRoot":"","sources":["../src/codex.preflight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,aAAa,EAAe,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAO1C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAmE,EAAE;IAErE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,UAAU,CAAC;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,OAAO,CAAC;IAC/D,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACjF,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,IAAI,CAAC;IACnB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAG,CAAW,CAAC,OAAO,EAAE,CAAC;IACrD,CAAC;IACD,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,GAAG,KAAK,GAAG,EAAE,CAAC,CAAC;IAC1C,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,6BAA6B,EAAE,CAAC;IAC9F,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IAClD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wCAAwC,EAAE,CAAC;AACzE,CAAC"}

package/dist/cursor.d.ts

@@ -0,0 +1,17 @@
+import { type Runner } from "./runner.js";
+import { type CursorMode } from "./validate.js";
+import { type LogFields } from "./logger.js";
+import type { CursorResult } from "./errors.js";
+export interface RunOptions {
+    cwd: string;
+    mode?: CursorMode;
+    model?: string;
+    timeoutMs?: number;
+    allowedRoot?: string;
+    sandbox?: "enabled" | "disabled";
+    env?: NodeJS.ProcessEnv;
+    runner?: Runner;
+    log?: (fields: LogFields) => void;
+    bin?: string;
+}
+export declare function runCursorAgent(prompt: string, opts: RunOptions): Promise<CursorResult>;

package/dist/cursor.js

@@ -0,0 +1,88 @@
+import { isAbsolute } from "node:path";
+import { realRunner, collectStream } from "./runner.js";
+import { classify } from "./classify.js";
+import { assertMode, assertModel, assertWorkspacePath } from "./validate.js";
+import { createLogger } from "./logger.js";
+import { ValidationError } from "./errors.js";
+const DEFAULT_TIMEOUT_MS = 270_000; // under cursor-agent's ~5min ceiling
+export async function runCursorAgent(prompt, opts) {
+    const runner = opts.runner ?? realRunner;
+    const log = opts.log ?? createLogger();
+    const bin = opts.bin ?? process.env.CURSOR_AGENT_BIN ?? "cursor-agent";
+    const env = opts.env ?? process.env;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let mode;
+    let model;
+    let cwd;
+    try {
+        mode = assertMode(opts.mode ?? "default");
+        model = assertModel(opts.model ?? "composer-2.5-fast");
+        // No cwd fallback: an unset root must fail loudly, never silently widen to the launch cwd (often $HOME).
+        const allowedRoot = opts.allowedRoot ?? process.env.CURSOR_BRIDGE_ALLOWED_ROOT;
+        if (!allowedRoot || !isAbsolute(allowedRoot)) {
+            throw new ValidationError("CURSOR_BRIDGE_ALLOWED_ROOT must be set to an absolute path (refusing to default to cwd)");
+        }
+        cwd = assertWorkspacePath(opts.cwd, allowedRoot);
+    }
+    catch (e) {
+        const r = {
+            status: "TOOL_ERROR",
+            error: e instanceof ValidationError ? e.message : String(e),
+        };
+        log({ event: "cursor_agent", level: "error", status: r.status });
+        return r;
+    }
+    // --sandbox enabled bounds filesystem/network for the --force write path (defense in depth).
+    // It must be VERIFIED on your cursor-agent build (see Task A20); --workspace alone is only a cwd, not a jail.
+    const sandbox = opts.sandbox ?? (process.env.CURSOR_BRIDGE_SANDBOX === "disabled" ? "disabled" : "enabled");
+    const args = ["-p", prompt, "--model", model, "--output-format", "json", "--workspace", cwd, "--trust", "--sandbox", sandbox];
+    if (mode === "default") {
+        args.push("--force"); // auto-approve writes/shell (headless cannot prompt)
+    }
+    else {
+        args.push("--mode", mode); // plan|ask -> read-only enforcement
+    }
+    const startedAt = Date.now();
+    const child = runner(bin, args, { env, cwd });
+    const outP = collectStream(child.stdout);
+    const errP = collectStream(child.stderr);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGKILL");
+    }, timeoutMs);
+    let spawnError;
+    try {
+        await child.done;
+    }
+    catch (e) {
+        spawnError = e;
+    }
+    clearTimeout(timer);
+    const durationMs = Date.now() - startedAt;
+    if (timedOut) {
+        const r = { status: "TIMEOUT", error: `killed after ${timeoutMs}ms`, raw: outP.current() };
+        log({ event: "cursor_agent", level: "warn", status: r.status, durationMs, model, mode });
+        return r;
+    }
+    if (spawnError) {
+        const r = { status: "TOOL_ERROR", error: spawnError.message };
+        log({ event: "cursor_agent", level: "error", status: r.status, durationMs, model, mode });
+        return r;
+    }
+    const [out, err] = await Promise.all([outP.done, errP.done]);
+    const r = classify(out, err);
+    log({
+        event: "cursor_agent",
+        level: r.status === "SUCCESS" ? "info" : "warn",
+        status: r.status,
+        durationMs,
+        model,
+        mode,
+        sessionId: r.sessionId,
+        requestId: r.requestId,
+        tokens: r.usage,
+    });
+    return r;
+}
+//# sourceMappingURL=cursor.js.map

package/dist/cursor.js.map

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