@wix/pathgrade 0.29.0

package/dist/plugin/reporter.js

@@ -0,0 +1,275 @@
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { extractSkillsFromLog } from '../tool-events.js';
+import { fmt } from '../utils/cli.js';
+import { getPathgradeDir } from '../reporters/results-path.js';
+import fs from 'fs-extra';
+import { formatDiagnostics, formatDiagnosticsSummary } from '../reporters/diagnostics.js';
+import { readSidecar } from '../affected/sidecar.js';
+/**
+ * Custom vitest reporter that layers pathgrade aggregate statistics
+ * on top of vitest's default output.
+ */
+export class PathgradeReporter {
+    opts;
+    constructor(opts) {
+        this.opts = opts ?? {};
+    }
+    async onTestRunEnd(testModules) {
+        const groups = this.collectGroups(testModules);
+        if (groups.length === 0)
+            return;
+        const mode = this.opts.reporter ?? 'cli';
+        if (mode === 'cli' || mode === 'browser') {
+            this.printCliSummary(groups);
+        }
+        await this.writeJsonResults(groups);
+        if (mode === 'browser') {
+            this.openBrowserViewer(groups);
+        }
+        // CI threshold check
+        if (this.opts.ci?.threshold != null) {
+            const allScores = groups.flatMap((g) => g.tests.map((t) => t.score));
+            if (allScores.length > 0) {
+                const avg = allScores.reduce((a, b) => a + b, 0) / allScores.length;
+                if (avg < this.opts.ci.threshold) {
+                    console.log(`\n  ${fmt.fail('CI THRESHOLD FAILED')}  avg score ${fmt.bold(avg.toFixed(3))} < threshold ${fmt.bold(String(this.opts.ci.threshold))}\n`);
+                    process.exitCode = 1;
+                }
+            }
+        }
+    }
+    collectGroups(testModules) {
+        const groupMap = new Map();
+        for (const mod of testModules) {
+            for (const testCase of mod.children.allTests()) {
+                const groupKey = this.getGroupKey(testCase);
+                const entry = this.toTestEntry(testCase);
+                if (!groupMap.has(groupKey)) {
+                    groupMap.set(groupKey, []);
+                }
+                groupMap.get(groupKey).push(entry);
+            }
+        }
+        return Array.from(groupMap.entries()).map(([groupName, tests]) => ({
+            groupName,
+            tests,
+        }));
+    }
+    /**
+     * Group key is the parent suite's full name (file + describe hierarchy).
+     * Tests without a describe wrapper are grouped by module path.
+     */
+    getGroupKey(testCase) {
+        const parent = testCase.parent;
+        const modulePath = testCase.module.relativeModuleId;
+        if (parent.type === 'suite') {
+            return `${modulePath} > ${parent.fullName}`;
+        }
+        return modulePath;
+    }
+    toTestEntry(testCase) {
+        const meta = testCase.meta();
+        const pathgradeMeta = meta.pathgrade;
+        const diag = testCase.diagnostic();
+        const result = testCase.result();
+        let score = 0;
+        let trial;
+        let diagnostics;
+        if (pathgradeMeta === undefined) {
+            // Test didn't use pathgrade — infer from test pass/fail
+            score = result.state === 'passed' ? 1 : 0;
+        }
+        else if (pathgradeMeta.length === 0) {
+            // Anomaly: pathgrade was set up but evaluate() was never called
+            console.warn(`  [pathgrade] warning: empty results for "${testCase.name}" — evaluate() may not have been called`);
+            score = result.state === 'passed' ? 1 : 0;
+        }
+        else {
+            // Use the last eval result's score
+            score = pathgradeMeta[pathgradeMeta.length - 1].score;
+            trial = pathgradeMeta[pathgradeMeta.length - 1].trial;
+            diagnostics = pathgradeMeta[pathgradeMeta.length - 1].diagnostics;
+        }
+        return {
+            name: testCase.name,
+            score,
+            durationMs: diag?.duration ?? 0,
+            state: result.state === 'pending' ? 'pending' : result.state,
+            trial,
+            diagnostics,
+        };
+    }
+    printCliSummary(groups) {
+        console.log(`\n${fmt.bold('── pathgrade summary ')}${fmt.dim('─'.repeat(40))}\n`);
+        const forceVerbose = this.opts.diagnostics === true || process.env.PATHGRADE_DIAGNOSTICS === '1';
+        const currentTimeoutMs = this.opts.timeout != null ? this.opts.timeout * 1000 : undefined;
+        for (const group of groups) {
+            const k = group.tests.length;
+            const passRate = this.computePassRate(group.tests);
+            const passAtK = this.computePassAtK(passRate, k);
+            const passPowK = this.computePassPowK(passRate, k);
+            const avgDuration = this.computeAvgDuration(group.tests);
+            const prColor = passRate >= 0.5 ? fmt.green : fmt.red;
+            console.log(`  ${fmt.bold(group.groupName)}`);
+            console.log(`    ${fmt.dim('pass rate'.padEnd(12))} ${prColor((passRate * 100).toFixed(1) + '%')}`);
+            console.log(`    ${fmt.dim(`pass@${k}`.padEnd(12))} ${(passAtK * 100).toFixed(1)}%`);
+            console.log(`    ${fmt.dim(`pass^${k}`.padEnd(12))} ${(passPowK * 100).toFixed(1)}%`);
+            console.log(`    ${fmt.dim('avg time'.padEnd(12))} ${(avgDuration / 1000).toFixed(1)}s`);
+            console.log(`    ${fmt.dim('trials'.padEnd(12))} ${k}`);
+            console.log();
+            for (const test of group.tests) {
+                if (!test.diagnostics)
+                    continue;
+                const shouldPrintFull = forceVerbose || test.state !== 'passed' || test.diagnostics.completionReason === 'timeout' || test.diagnostics.completionReason === 'agent_crashed';
+                console.log(`    ${fmt.bold(test.name)}`);
+                const formatted = shouldPrintFull
+                    ? formatDiagnostics(test.diagnostics, { verbose: true, currentTimeoutMs })
+                    : formatDiagnosticsSummary(test.diagnostics);
+                for (const line of formatted.split('\n')) {
+                    console.log(`      ${line}`);
+                }
+                console.log();
+            }
+        }
+    }
+    async writeJsonResults(groups) {
+        const outputDir = getPathgradeDir(process.cwd());
+        const tracesDir = path.join(outputDir, 'traces');
+        await fs.ensureDir(tracesDir);
+        // Auto-create .gitignore if it doesn't exist
+        const gitignorePath = path.join(outputDir, '.gitignore');
+        if (!(await fs.pathExists(gitignorePath))) {
+            await fs.writeFile(gitignorePath, '*\n');
+        }
+        const allScores = groups.flatMap((g) => g.tests.map((t) => t.score));
+        const overallPassRate = allScores.length > 0
+            ? allScores.reduce((a, b) => a + b, 0) / allScores.length
+            : 0;
+        const threshold = this.opts.ci?.threshold;
+        const status = threshold != null
+            ? (overallPassRate >= threshold ? 'pass' : 'fail')
+            : (groups.every(g => g.tests.every(t => t.state === 'passed')) ? 'pass' : 'fail');
+        const consolidatedGroups = [];
+        for (const group of groups) {
+            const report = this.buildEvalReport(group);
+            const slug = this.slug(group.groupName);
+            const traceFile = `traces/${slug}.json`;
+            // Write full trace data (with session_log and conversation)
+            await fs.writeJson(path.join(outputDir, traceFile), report.trials, { spaces: 2 });
+            // Strip session_log and conversation from trials in consolidated report
+            const strippedTrials = report.trials.map(t => {
+                const { session_log, conversation, ...rest } = t;
+                return rest;
+            });
+            const { trials: _omitted, ...rest } = report;
+            consolidatedGroups.push({
+                ...rest,
+                trials: strippedTrials,
+                trace_file: traceFile,
+            });
+        }
+        // Merge selection metadata from the CLI-written sidecar, if any.
+        // Missing sidecar → plain run; malformed → warn and proceed without it.
+        const selection = await readSidecar(process.cwd(), msg => {
+            console.warn(`[pathgrade] ${msg}`);
+        });
+        const consolidated = {
+            version: 1,
+            timestamp: new Date().toISOString(),
+            ...(threshold != null ? { threshold } : {}),
+            overall_pass_rate: overallPassRate,
+            status,
+            groups: consolidatedGroups,
+            ...(selection ? { selection } : {}),
+        };
+        await fs.writeJson(path.join(outputDir, 'results.json'), consolidated, { spaces: 2 });
+        console.log(`\n  ${fmt.dim('Results written to')} ${outputDir}\n`);
+    }
+    buildEvalReport(group) {
+        const trials = group.tests.map((test, index) => this.toTrialResult(test, index));
+        const passRate = this.computePassRate(group.tests);
+        // Aggregate skills_used across all trials (deduplicated)
+        const allSkills = new Set();
+        for (const trial of trials) {
+            for (const skill of trial.skills_used ?? []) {
+                allSkills.add(skill);
+            }
+        }
+        return {
+            task: group.groupName,
+            pass_rate: passRate,
+            pass_at_k: this.computePassAtK(passRate, trials.length),
+            pass_pow_k: this.computePassPowK(passRate, trials.length),
+            trials,
+            skills_used: [...allSkills],
+        };
+    }
+    toTrialResult(test, index) {
+        const base = test.trial ?? {
+            trial_id: index + 1,
+            reward: test.score,
+            scorer_results: [],
+            duration_ms: test.durationMs,
+            n_commands: 0,
+            input_tokens: 0,
+            output_tokens: 0,
+            session_log: [],
+        };
+        // Extract skills_used from session_log tool events if not already present
+        const skills = base.skills_used ?? extractSkillsFromLog(base.session_log);
+        return {
+            ...base,
+            trial_id: index + 1,
+            name: test.name,
+            duration_ms: base.duration_ms || test.durationMs,
+            diagnostics: test.diagnostics ?? base.diagnostics,
+            ...(skills.length > 0 ? { skills_used: skills } : {}),
+        };
+    }
+    slug(value) {
+        return value
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-+|-+$/g, '') || 'report';
+    }
+    openBrowserViewer(_groups) {
+        // Write results JSON first, then open the viewer
+        const viewerPath = path.resolve(import.meta.dirname, '..', 'viewer.html');
+        try {
+            const openCmd = process.platform === 'darwin' ? 'open'
+                : process.platform === 'win32' ? 'start'
+                    : 'xdg-open';
+            execSync(`${openCmd} "${viewerPath}"`, { stdio: 'ignore' });
+            console.log(`\n  ${fmt.dim('Opened viewer in browser')}\n`);
+        }
+        catch {
+            console.log(`\n  ${fmt.dim('Open manually:')} ${viewerPath}\n`);
+        }
+    }
+    computePassRate(tests) {
+        if (tests.length === 0)
+            return 0;
+        const passed = tests.filter((t) => t.state === 'passed').length;
+        return passed / tests.length;
+    }
+    /**
+     * pass@k = 1 - (1 - p)^k
+     * Probability of at least 1 success in k trials.
+     */
+    computePassAtK(passRate, k) {
+        return 1 - Math.pow(1 - passRate, k);
+    }
+    /**
+     * pass^k = p^k
+     * Probability of all k trials succeeding.
+     */
+    computePassPowK(passRate, k) {
+        return Math.pow(passRate, k);
+    }
+    computeAvgDuration(tests) {
+        if (tests.length === 0)
+            return 0;
+        return tests.reduce((sum, t) => sum + t.durationMs, 0) / tests.length;
+    }
+}

package/dist/plugin/setup.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/plugin/setup.js

@@ -0,0 +1,3 @@
+import { afterAll, afterEach } from 'vitest';
+import { lifecycle } from './lifecycle.js';
+lifecycle.install(afterEach, afterAll);

package/dist/providers/copy-filter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Default ignore patterns applied when copying workspace and skill directories.
+ * Matches against the basename (filename or directory name) of each entry.
+ *
+ * - Plain names (no wildcards) match exact directory/file names at any depth.
+ * - Glob patterns (with wildcards) match filenames at any depth.
+ */
+export declare const DEFAULT_COPY_IGNORE: readonly string[];
+/**
+ * Creates a filter function suitable for use with `fs.copy()`.
+ *
+ * The filter matches ignore patterns against the **basename** of each path.
+ * Returns `true` to include the file/directory, `false` to exclude it.
+ *
+ * @param ignorePatterns - Array of patterns to filter. Replaces defaults entirely.
+ *   Pass `[]` to disable filtering. Invalid glob patterns are silently ignored.
+ */
+export declare function createCopyFilter(ignorePatterns: readonly string[]): (src: string) => boolean;

package/dist/providers/copy-filter.js

@@ -0,0 +1,66 @@
+/**
+ * Copy filter for workspace and skill directory copies.
+ *
+ * Filters out junk directories and files (node_modules, .git, dist, etc.)
+ * when copying workspace/skill directories into the sandbox.
+ */
+import * as path from 'path';
+import picomatch from 'picomatch';
+/**
+ * Default ignore patterns applied when copying workspace and skill directories.
+ * Matches against the basename (filename or directory name) of each entry.
+ *
+ * - Plain names (no wildcards) match exact directory/file names at any depth.
+ * - Glob patterns (with wildcards) match filenames at any depth.
+ */
+export const DEFAULT_COPY_IGNORE = Object.freeze([
+    'node_modules',
+    '.git',
+    'dist',
+    '.DS_Store',
+    '__pycache__',
+    'npm-debug.log*',
+    'yarn-debug.log*',
+    'yarn-error.log*',
+]);
+/**
+ * Creates a filter function suitable for use with `fs.copy()`.
+ *
+ * The filter matches ignore patterns against the **basename** of each path.
+ * Returns `true` to include the file/directory, `false` to exclude it.
+ *
+ * @param ignorePatterns - Array of patterns to filter. Replaces defaults entirely.
+ *   Pass `[]` to disable filtering. Invalid glob patterns are silently ignored.
+ */
+export function createCopyFilter(ignorePatterns) {
+    if (ignorePatterns.length === 0) {
+        return () => true;
+    }
+    // Build matchers from the patterns, silently skipping invalid ones
+    const matchers = [];
+    for (const pattern of ignorePatterns) {
+        try {
+            matchers.push(picomatch(pattern));
+        }
+        catch {
+            // Invalid glob pattern: silently ignore per PRD
+        }
+    }
+    if (matchers.length === 0) {
+        return () => true;
+    }
+    return (src) => {
+        const basename = path.basename(src);
+        // Don't filter if basename is empty (shouldn't happen, but be safe)
+        if (!basename) {
+            return true;
+        }
+        // Check if any matcher matches the basename
+        for (const matcher of matchers) {
+            if (matcher(basename)) {
+                return false;
+            }
+        }
+        return true;
+    };
+}

package/dist/providers/credentials.d.ts

@@ -0,0 +1,36 @@
+import type { AgentName } from '../sdk/types.js';
+export interface CredentialPorts {
+    /** Read a host environment variable. */
+    hostEnv(key: string): string | undefined;
+    /** Host platform. */
+    platform: NodeJS.Platform;
+    /** Host home directory. */
+    homedir: string;
+    /** Read a macOS Keychain credential. Returns undefined on failure. */
+    readKeychainToken(service: string): Promise<string | undefined>;
+    /**
+     * Check whether a macOS Keychain entry exists for the given service/account
+     * without decrypting it (no user prompt, no value returned). Returns false
+     * on non-darwin or when the entry is absent.
+     */
+    keychainEntryExists(service: string, account: string): Promise<boolean>;
+    /** Check if a path exists on the host filesystem. */
+    fileExists(absolutePath: string): Promise<boolean>;
+}
+export interface CredentialResult {
+    /** Env vars to merge into sandbox env. */
+    env: Record<string, string>;
+    /** Shell commands to run inside sandbox before first agent turn. */
+    setupCommands: string[];
+    /** Relative paths from host HOME to copy into sandbox HOME. */
+    copyFromHome: string[];
+    /**
+     * Relative paths from host HOME to symlink into sandbox HOME. Used when
+     * the target would be too large to copy or must stay in sync with the
+     * host (e.g. macOS `Library/Keychains`). Optional; defaults to none.
+     */
+    linkFromHome?: string[];
+}
+/** Default ports using real process.env, Keychain, and filesystem. */
+export declare function defaultPorts(): CredentialPorts;
+export declare function resolveCredentials(agent: AgentName, userEnv: Record<string, string>, ports?: CredentialPorts): Promise<CredentialResult>;

package/dist/providers/credentials.js

@@ -0,0 +1,202 @@
+/**
+ * Credential resolution — determines what auth env vars an agent needs.
+ *
+ * This module owns the single question: "given user intent and ambient
+ * credentials, what auth environment should the agent get?"
+ *
+ * Precedence (highest to lowest):
+ *   1. User-provided env vars (explicit intent — never overridden)
+ *   2. Host env vars (forwarded when compatible)
+ *   3. macOS Keychain OAuth (Claude only, skipped when explicit intent detected)
+ *
+ * All external dependencies (Keychain, host env, filesystem) are injectable
+ * via CredentialPorts for testability.
+ */
+import { execSync, execFileSync } from 'child_process';
+import * as os from 'os';
+import * as path from 'path';
+import fs from 'fs-extra';
+const EMPTY = { env: {}, setupCommands: [], copyFromHome: [] };
+/** Default ports using real process.env, Keychain, and filesystem. */
+export function defaultPorts() {
+    return {
+        hostEnv: (key) => process.env[key],
+        platform: process.platform,
+        homedir: os.homedir(),
+        async readKeychainToken(service) {
+            try {
+                const raw = execSync(`security find-generic-password -s "${service}" -w 2>/dev/null`, { encoding: 'utf8', timeout: 5000 }).trim();
+                const parsed = JSON.parse(raw);
+                return parsed?.claudeAiOauth?.accessToken || undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async keychainEntryExists(service, account) {
+            if (process.platform !== 'darwin')
+                return false;
+            try {
+                // execFileSync with argv avoids shell interpretation entirely —
+                // no injection surface even if service/account become untrusted.
+                execFileSync('security', ['find-generic-password', '-s', service, '-a', account], { timeout: 5000, stdio: 'ignore' });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        async fileExists(absolutePath) {
+            return fs.pathExists(absolutePath);
+        },
+    };
+}
+export async function resolveCredentials(agent, userEnv, ports) {
+    const p = ports ?? defaultPorts();
+    switch (agent) {
+        case 'claude':
+            return resolveClaude(userEnv, p);
+        case 'codex':
+            return resolveCodex(userEnv, p);
+        case 'cursor':
+            return resolveCursor(userEnv, p);
+        default:
+            return EMPTY;
+    }
+}
+async function resolveClaude(userEnv, ports) {
+    // User explicitly provided API key — trust it, nothing to add
+    if (userEnv.ANTHROPIC_API_KEY) {
+        return EMPTY;
+    }
+    // User provided a custom base URL → they're targeting a proxy.
+    // Keychain OAuth only works with direct Anthropic, so skip it
+    // and forward the host's API key instead.
+    if (userEnv.ANTHROPIC_BASE_URL) {
+        const hostKey = ports.hostEnv('ANTHROPIC_API_KEY');
+        if (!hostKey) {
+            throw new Error('ANTHROPIC_BASE_URL is set but no ANTHROPIC_API_KEY found. ' +
+                'Provide ANTHROPIC_API_KEY in env or set it in your host environment.');
+        }
+        return { env: { ANTHROPIC_API_KEY: hostKey }, setupCommands: [], copyFromHome: [] };
+    }
+    // No explicit Anthropic intent — try auto-resolution.
+    // Host-level proxy intent (ANTHROPIC_BASE_URL set on host env) makes the
+    // Keychain OAuth token unusable — it's scoped to direct Anthropic, not to
+    // a proxy. Skip the Keychain branch so the host-forward fallback wins.
+    const hostSignalsProxy = !!ports.hostEnv('ANTHROPIC_BASE_URL');
+    // On macOS, prefer Keychain OAuth (direct Anthropic token).
+    if (ports.platform === 'darwin' && !hostSignalsProxy) {
+        const token = await ports.readKeychainToken('Claude Code-credentials');
+        if (token) {
+            return { env: { ANTHROPIC_API_KEY: token }, setupCommands: [], copyFromHome: [] };
+        }
+    }
+    // Fallback: forward host API key and base URL.
+    const env = {};
+    const hostKey = ports.hostEnv('ANTHROPIC_API_KEY');
+    const hostBaseUrl = ports.hostEnv('ANTHROPIC_BASE_URL');
+    if (hostKey)
+        env.ANTHROPIC_API_KEY = hostKey;
+    if (hostBaseUrl)
+        env.ANTHROPIC_BASE_URL = hostBaseUrl;
+    return { env, setupCommands: [], copyFromHome: [] };
+}
+async function resolveCursor(userEnv, ports) {
+    // User explicitly provided API key — trust it, nothing to add
+    if (userEnv.CURSOR_API_KEY) {
+        return EMPTY;
+    }
+    // User provided a custom base URL → they're targeting a proxy.
+    // Forward the host's API key; error if missing.
+    if (userEnv.CURSOR_API_BASE_URL) {
+        const hostKey = ports.hostEnv('CURSOR_API_KEY');
+        if (!hostKey) {
+            throw new Error('CURSOR_API_BASE_URL is set but no CURSOR_API_KEY found. ' +
+                'Provide CURSOR_API_KEY in env or set it in your host environment.');
+        }
+        return { env: { CURSOR_API_KEY: hostKey }, setupCommands: [], copyFromHome: [] };
+    }
+    // Forward host key + base URL when user provided neither. OAuth via
+    // `cursor-agent login` remains the fallback when neither is set.
+    const env = {};
+    const hostKey = ports.hostEnv('CURSOR_API_KEY');
+    const hostBaseUrl = ports.hostEnv('CURSOR_API_BASE_URL');
+    if (hostKey)
+        env.CURSOR_API_KEY = hostKey;
+    if (hostBaseUrl)
+        env.CURSOR_API_BASE_URL = hostBaseUrl;
+    // On macOS, `cursor-agent login` stores OAuth tokens in the host's login
+    // keychain at `~/Library/Keychains`. The sandbox runs with an isolated
+    // HOME so the CLI looks in the sandbox's (empty) Library/Keychains and
+    // reports "Authentication required". Symlink the host keychain dir in
+    // so the token is visible. Only meaningful when no explicit API key is
+    // set — otherwise cursor-agent uses the env var and ignores the keychain.
+    const linkFromHome = [];
+    if (!hostKey) {
+        if (ports.platform === 'darwin') {
+            // cursor-agent stores OAuth tokens under the `cursor-access-token`
+            // service / `cursor-user` account. Probe before sandbox creation:
+            // if the user hasn't run `cursor-agent login`, surface that now
+            // rather than 17s into the first turn.
+            const loggedIn = await ports.keychainEntryExists('cursor-access-token', 'cursor-user');
+            if (!loggedIn) {
+                throw new Error('Cursor authentication required but no OAuth tokens were found in the login keychain. ' +
+                    'Run `cursor-agent login` first, or set CURSOR_API_KEY in your environment.');
+            }
+            linkFromHome.push('Library/Keychains');
+        }
+        else {
+            // No API key and no keychain-equivalent we know how to wire up.
+            throw new Error('Cursor authentication required but CURSOR_API_KEY is not set. ' +
+                'Auto-detection via `cursor-agent login` is only supported on macOS. ' +
+                'On other platforms, generate an API key from the Cursor dashboard ' +
+                'and set CURSOR_API_KEY in your environment.');
+        }
+    }
+    return { env, setupCommands: [], copyFromHome: [], linkFromHome };
+}
+async function resolveCodex(userEnv, ports) {
+    const env = {};
+    const setupCommands = [];
+    const copyFromHome = [];
+    const hasUserKey = !!userEnv.OPENAI_API_KEY;
+    const hasUserBaseUrl = !!userEnv.OPENAI_BASE_URL;
+    // User provided a custom base URL → they're targeting a proxy.
+    // Forward the host key; error if missing.
+    if (hasUserBaseUrl && !hasUserKey) {
+        const hostKey = ports.hostEnv('OPENAI_API_KEY');
+        if (!hostKey) {
+            throw new Error('OPENAI_BASE_URL is set but no OPENAI_API_KEY found. ' +
+                'Provide OPENAI_API_KEY in env or set it in your host environment.');
+        }
+        env.OPENAI_API_KEY = hostKey;
+    }
+    // Forward host keys when user didn't provide them
+    if (!hasUserKey && !hasUserBaseUrl) {
+        const hostKey = ports.hostEnv('OPENAI_API_KEY');
+        const hostBaseUrl = ports.hostEnv('OPENAI_BASE_URL');
+        if (hostKey)
+            env.OPENAI_API_KEY = hostKey;
+        if (hostBaseUrl)
+            env.OPENAI_BASE_URL = hostBaseUrl;
+    }
+    // Determine if we have a key (user-provided or host-forwarded)
+    const hasKey = hasUserKey || !!env.OPENAI_API_KEY;
+    const hasBaseUrl = hasUserBaseUrl || !!env.OPENAI_BASE_URL;
+    if (hasKey) {
+        // Proxied OpenAI-compatible endpoints use a custom Codex provider that
+        // reads OPENAI_API_KEY directly from env, so no auth cache/login is needed.
+        if (!hasBaseUrl) {
+            setupCommands.push('if [ ! -d "$HOME/.codex" ] && [ -n "${OPENAI_API_KEY:-}" ]; then printenv OPENAI_API_KEY | codex login --with-api-key >/dev/null 2>&1; fi');
+        }
+    }
+    else {
+        // No key — check for cached auth.json
+        const authCachePath = path.join(ports.homedir, '.codex', 'auth.json');
+        if (await ports.fileExists(authCachePath)) {
+            copyFromHome.push('.codex/auth.json');
+        }
+    }
+    return { env, setupCommands, copyFromHome };
+}

package/dist/providers/mcp-config.d.ts

@@ -0,0 +1,34 @@
+import type { MockMcpServerDescriptor } from '../core/mcp-mock.types.js';
+/**
+ * Stdio-server shape pathgrade writes to `.pathgrade-mcp.json`. Lines up
+ * directly with the SDK's `McpStdioServerConfig` (`sdk.d.ts:1005`) — the
+ * optional `type: 'stdio'` discriminator is omitted because the JSON
+ * `writeMcpConfig` produces does not include it.
+ */
+export interface McpStdioEntry {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+/** Object form of MCP server entries the SDK driver passes to `Options.mcpServers`. */
+export type McpServersObject = Record<string, McpStdioEntry>;
+export type McpSpec = {
+    configFile: string;
+} | {
+    mock: MockMcpServerDescriptor | MockMcpServerDescriptor[];
+};
+export interface McpConfigResult {
+    mcpConfigPath: string | undefined;
+}
+export declare function writeMcpConfig(workspacePath: string, mcp: McpSpec | undefined): Promise<McpConfigResult>;
+/**
+ * Read the JSON `writeMcpConfig` writes into `<workspace>/.pathgrade-mcp.json`
+ * and return the inner `mcpServers` object the Claude SDK driver hands to
+ * `Options.mcpServers`. Returns `undefined` when the file is absent (the
+ * "no MCP" path through the driver — the fixture didn't declare an `mcp` spec).
+ *
+ * The on-disk path is preserved because the Cursor agent driver still
+ * consumes it via `mcpConfigPath` (`src/agents/cursor.ts`) — Claude moves to
+ * the object form, Cursor stays on the file.
+ */
+export declare function loadMcpServersForSdk(workspacePath: string): Promise<McpServersObject | undefined>;