@wix/pathgrade 1.0.6 → 1.0.8

package/dist/pathgrade.js

@@ -18,11 +18,13 @@ import { runPreviewReactions } from './commands/preview-reactions.js';
 import { runReport } from './commands/report.js';
 import { runAffected } from './commands/affected.js';
 import { runChanged } from './commands/run-changed.js';
+import { parseCleanArgs, runClean } from './commands/clean.js';
 import { clearSidecar } from './affected/sidecar.js';
 import { resolvePathgradeConfig } from './config/pathgrade.js';
 import { loadRunnerInvocationAdapter } from './runners/adapter-loader.js';
 import { fmt } from './utils/cli.js';
 import { shutdown } from './utils/shutdown.js';
+import { buildRunnerEnv } from './commands/runner-env.js';
 function loadDotenv() {
     const envPath = path.resolve(process.cwd(), '.env');
     if (!fs.existsSync(envPath))
@@ -100,6 +102,13 @@ async function main() {
         await runInit(process.cwd(), { force: hasForce });
         return;
     }
+    if (command === 'clean') {
+        const result = await runClean(process.cwd(), parseCleanArgs(args.slice(1)));
+        const action = result.dryRun ? 'would remove' : 'removed';
+        console.log(`pathgrade: ${action} ${result.removed} debug run(s); ` +
+            `retained ${result.retained}; active ${result.active}`);
+        return;
+    }
     if (command === 'preview') {
         const previewArgs = args.slice(1);
         const mode = previewArgs.includes('browser') ? 'browser' : 'cli';
@@ -164,11 +173,7 @@ async function main() {
         // previous `--changed` run so it doesn't leak into this full-suite
         // run (the reporter would otherwise merge old metadata).
         await clearSidecar(process.cwd());
-        const env = {
-            ...process.env,
-            ...(parsed.forceDiagnostics ? { PATHGRADE_DIAGNOSTICS: '1' } : {}),
-            ...(parsed.forceVerbose ? { PATHGRADE_VERBOSE: '1' } : {}),
-        };
+        const env = buildRunnerEnv(parsed);
         try {
             const config = await resolvePathgradeConfig({ cwd: process.cwd() });
             const runner = await loadRunnerInvocationAdapter({
@@ -209,6 +214,9 @@ function printHelp() {
     pathgrade analyze [--skill=X]    Analyze skills and output JSON
     pathgrade validate <file>        Validate an .eval.ts file
     pathgrade validate --affected    Strict: every eval must be anchored or have valid __pathgradeMeta
+    pathgrade clean --debug          Remove completed debug runs
+                     [--keep=N]      Keep the N newest completed debug runs
+                     [--dry-run]     Report removals without changing files
     pathgrade preview [browser]      View results (CLI default, or browser)
                      [--last=N]     Show only the N most recent reports
                      [--filter=X]   Filter reports by test name (substring)

package/dist/providers/credentials.js

@@ -60,10 +60,22 @@ export async function resolveCredentials(agent, userEnv, ports) {
             return resolveCodex(userEnv, p);
         case 'cursor':
             return resolveCursor(userEnv, p);
+        case 'opencode':
+            return resolveOpenCode(userEnv);
         default:
             return EMPTY;
     }
 }
+function resolveOpenCode(userEnv) {
+    const env = {};
+    if (userEnv.ANTHROPIC_API_KEY) {
+        env.ANTHROPIC_API_KEY = userEnv.ANTHROPIC_API_KEY;
+    }
+    if (userEnv.ANTHROPIC_BASE_URL) {
+        env.ANTHROPIC_BASE_URL = userEnv.ANTHROPIC_BASE_URL;
+    }
+    return { env, setupCommands: [], copyFromHome: [] };
+}
 async function resolveClaude(userEnv, ports) {
     // User explicitly provided API key — trust it, nothing to add
     if (userEnv.ANTHROPIC_API_KEY) {

package/dist/providers/debug-runs.d.ts

@@ -0,0 +1,23 @@
+export declare const DEBUG_ROOT_MARKER = ".pathgrade-debug-root.json";
+export declare const DEBUG_RUN_MARKER = ".pathgrade-debug-run.json";
+export declare const DEFAULT_DEBUG_RETAIN_RUNS = 3;
+export declare function resolveDebugRunId(): string;
+export interface CleanDebugRunsResult {
+    removed: number;
+    retained: number;
+    active: number;
+    dryRun: boolean;
+}
+export declare function prepareManagedDebugRun(input: {
+    rootDir: string;
+    debugName: string;
+}): Promise<{
+    destination: string;
+    rootDir: string;
+    runId: string;
+}>;
+export declare function cleanDebugRuns(input: {
+    rootDir: string;
+    keep?: number;
+    dryRun?: boolean;
+}): Promise<CleanDebugRunsResult>;

package/dist/providers/debug-runs.js

@@ -0,0 +1,208 @@
+import fs from 'fs-extra';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+export const DEBUG_ROOT_MARKER = '.pathgrade-debug-root.json';
+export const DEBUG_RUN_MARKER = '.pathgrade-debug-run.json';
+export const DEFAULT_DEBUG_RETAIN_RUNS = 3;
+let generatedRunId;
+function createRunId() {
+    generatedRunId ??= `${new Date().toISOString().replace(/[:.]/g, '-')}-${Math.random().toString(36).slice(2, 8)}`;
+    return generatedRunId;
+}
+export function resolveDebugRunId() {
+    const configured = process.env.PATHGRADE_DEBUG_RUN_ID;
+    if (configured && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(configured))
+        return configured;
+    return createRunId();
+}
+async function readJsonFile(filePath) {
+    try {
+        const stat = await fs.lstat(filePath);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return undefined;
+        return await fs.readJson(filePath);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function isOwnedDebugRoot(rootDir) {
+    try {
+        const stat = await fs.lstat(rootDir);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const marker = await readJsonFile(path.join(rootDir, DEBUG_ROOT_MARKER));
+    return marker?.version === 1;
+}
+async function ensureOwnedDebugRoot(rootDir) {
+    await fs.ensureDir(rootDir);
+    const rootStat = await fs.lstat(rootDir);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw new Error(`Pathgrade debug root must be a real directory: ${rootDir}`);
+    }
+    const markerPath = path.join(rootDir, DEBUG_ROOT_MARKER);
+    let markerExists = false;
+    try {
+        const markerStat = await fs.lstat(markerPath);
+        markerExists = true;
+        if (!markerStat.isFile() || markerStat.isSymbolicLink()) {
+            throw new Error(`Pathgrade debug root has an unsafe ownership marker: ${rootDir}`);
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (!markerExists) {
+        await fs.writeJson(markerPath, { version: 1 }, { spaces: 2 });
+        return;
+    }
+    const existing = await readJsonFile(markerPath);
+    if (existing?.version !== 1) {
+        throw new Error(`Pathgrade debug root has an unsupported ownership marker: ${rootDir}`);
+    }
+}
+async function isRealDirectory(directory) {
+    try {
+        const stat = await fs.lstat(directory);
+        return stat.isDirectory() && !stat.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureRealChildDirectory(directory) {
+    try {
+        await fs.mkdir(directory);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    if (!await isRealDirectory(directory)) {
+        throw new Error(`Pathgrade managed debug path must be a real directory: ${directory}`);
+    }
+}
+async function ensureRunMarker(runDir, runId) {
+    const markerPath = path.join(runDir, DEBUG_RUN_MARKER);
+    const temporaryMarker = `${markerPath}.${process.pid}.${randomUUID()}.tmp`;
+    await fs.writeJson(temporaryMarker, {
+        version: 1,
+        runId,
+        createdAt: new Date().toISOString(),
+    }, { spaces: 2 });
+    try {
+        await fs.link(temporaryMarker, markerPath);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    finally {
+        await fs.remove(temporaryMarker);
+    }
+    const marker = await readJsonFile(markerPath);
+    if (marker?.version !== 1 ||
+        marker.runId !== runId ||
+        typeof marker.createdAt !== 'string' ||
+        !Number.isFinite(Date.parse(marker.createdAt))) {
+        throw new Error(`Pathgrade debug run has an unsafe ownership marker: ${runDir}`);
+    }
+}
+export async function prepareManagedDebugRun(input) {
+    const rootDir = path.resolve(input.rootDir);
+    await ensureOwnedDebugRoot(rootDir);
+    const runId = resolveDebugRunId();
+    const runsDir = path.join(rootDir, 'runs');
+    const runDir = path.join(runsDir, runId);
+    const activeDir = path.join(runDir, '.pathgrade-active');
+    await ensureRealChildDirectory(runsDir);
+    await ensureRealChildDirectory(runDir);
+    await ensureRealChildDirectory(activeDir);
+    await fs.writeFile(path.join(activeDir, String(process.pid)), '');
+    await ensureRunMarker(runDir, runId);
+    return {
+        destination: input.debugName ? path.join(runDir, input.debugName) : runDir,
+        rootDir,
+        runId,
+    };
+}
+async function readOwnedRun(runDir) {
+    const marker = await readJsonFile(path.join(runDir, DEBUG_RUN_MARKER));
+    if (marker?.version !== 1 ||
+        typeof marker.runId !== 'string' ||
+        typeof marker.createdAt !== 'string' ||
+        !Number.isFinite(Date.parse(marker.createdAt))) {
+        return undefined;
+    }
+    if (path.basename(runDir) !== marker.runId)
+        return undefined;
+    return marker;
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+async function isRunActive(runDir) {
+    const activeDir = path.join(runDir, '.pathgrade-active');
+    const entries = await fs.readdir(activeDir, { withFileTypes: true }).catch(() => []);
+    return entries.some(entry => {
+        if (!entry.isFile() || entry.isSymbolicLink() || !/^\d+$/.test(entry.name))
+            return false;
+        const pid = Number(entry.name);
+        return Number.isSafeInteger(pid) && pid > 0 && isProcessAlive(pid);
+    });
+}
+export async function cleanDebugRuns(input) {
+    const dryRun = input.dryRun ?? false;
+    if (!await isOwnedDebugRoot(input.rootDir)) {
+        return { removed: 0, retained: 0, active: 0, dryRun };
+    }
+    const runsDir = path.join(input.rootDir, 'runs');
+    if (!await isRealDirectory(runsDir)) {
+        return { removed: 0, retained: 0, active: 0, dryRun };
+    }
+    const entries = await fs.readdir(runsDir, { withFileTypes: true }).catch(() => []);
+    const ownedRuns = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.isSymbolicLink())
+            continue;
+        const dir = path.join(runsDir, entry.name);
+        const marker = await readOwnedRun(dir);
+        if (marker)
+            ownedRuns.push({ dir, marker, active: await isRunActive(dir) });
+    }
+    const activeRuns = ownedRuns.filter(run => run.active);
+    const completedRuns = ownedRuns.filter(run => !run.active);
+    completedRuns.sort((a, b) => b.marker.createdAt.localeCompare(a.marker.createdAt));
+    const keep = input.keep ?? 0;
+    const retained = completedRuns.slice(0, keep);
+    const removable = completedRuns.slice(keep);
+    let removed = removable.length;
+    let newlyActive = 0;
+    if (!dryRun) {
+        const removalResults = await Promise.all(removable.map(async (run) => {
+            if (await isRunActive(run.dir))
+                return false;
+            await fs.remove(run.dir);
+            return true;
+        }));
+        removed = removalResults.filter(Boolean).length;
+        newlyActive = removalResults.length - removed;
+    }
+    return {
+        removed,
+        retained: retained.length,
+        active: activeRuns.length + newlyActive,
+        dryRun,
+    };
+}

package/dist/sdk/agent-resolution.js

@@ -4,8 +4,13 @@ export class InvalidTransportEnvError extends Error {
         this.name = 'InvalidTransportEnvError';
     }
 }
+const AGENT_NAMES = ['claude', 'codex', 'cursor', 'opencode'];
 export function resolveAgentName(opts, env) {
-    return (opts.agent || env.PATHGRADE_AGENT || 'claude');
+    const value = opts.agent || env.PATHGRADE_AGENT || 'claude';
+    if (!AGENT_NAMES.includes(value)) {
+        throw new Error(`Unknown agent "${value}". Available agents: ${AGENT_NAMES.join(', ')}`);
+    }
+    return value;
 }
 export function resolveCodexTransport(opts, env) {
     if (opts.transport)

package/dist/sdk/agent.js

@@ -14,6 +14,8 @@ import { getCurrentCaseContext } from './case-context.js';
 import { createVerboseEmitter } from '../reporters/verbose-emitter.js';
 import fs from 'fs-extra';
 import * as path from 'path';
+import { cleanDebugRuns, DEFAULT_DEBUG_RETAIN_RUNS, prepareManagedDebugRun, } from '../providers/debug-runs.js';
+import { collectOpenCodeMcpToolNames, validateOpenCodeDeclaration } from '../agents/opencode-contract.js';
 /**
  * Test-only injection point: override the sink used by the next emitter
  * built inside `createAgent`. Pass `null` to restore the default (stderr).
@@ -41,7 +43,10 @@ class AgentImpl {
     verbose;
     transport;
     mcpSafety;
-    constructor(ws, agentName, llm, timeoutSetting, conversationWindow, modelOpt, debugOpt, debugName, debugBaseDir, verbose, transport, mcpSafety) {
+    opencodeExecutable;
+    opencodeMcpToolNames;
+    activeChatSession;
+    constructor(ws, agentName, llm, timeoutSetting, conversationWindow, modelOpt, debugOpt, debugName, debugBaseDir, verbose, transport, mcpSafety, opencodeExecutable, opencodeMcpToolNames) {
         this.ws = ws;
         this.agentName = agentName;
         this.llm = llm;
@@ -54,6 +59,8 @@ class AgentImpl {
         this.verbose = verbose;
         this.transport = transport;
         this.mcpSafety = mcpSafety;
+        this.opencodeExecutable = opencodeExecutable;
+        this.opencodeMcpToolNames = opencodeMcpToolNames;
     }
     get messages() {
         return this._messages;
@@ -96,6 +103,8 @@ class AgentImpl {
             ...(askUserTimeoutMs !== undefined ? { askUserTimeoutMs } : {}),
             ...(this.transport !== undefined ? { transport: this.transport } : {}),
             ...(this.mcpSafety !== undefined ? { mcpSafety: this.mcpSafety } : {}),
+            ...(this.opencodeExecutable !== undefined ? { opencodeExecutable: this.opencodeExecutable } : {}),
+            ...(this.opencodeMcpToolNames !== undefined ? { opencodeMcpToolNames: this.opencodeMcpToolNames } : {}),
         });
     }
     resolveTimeoutSec(mode, maxTurns) {
@@ -195,6 +204,7 @@ class AgentImpl {
         }
         const timeoutSec = this.resolveTimeoutSec('startChat');
         const ms = this.createSession(timeoutSec);
+        this.activeChatSession = ms;
         const turnResult = await this.executeLoggedTurnResult(ms, firstMessage, 1, 'agent_start');
         return new ChatSessionImpl(turnResult, {
             messages: this._messages,
@@ -310,24 +320,46 @@ class AgentImpl {
         // Runner-owned agents stay tracked until flush consumes metadata.
         // Manual agents have no runner flush, so dispose releases them.
         lifecycleCore.releaseAgent(this);
-        if (this.debugOpt) {
-            const dest = typeof this.debugOpt === 'string'
-                ? this.debugOpt
-                : path.join(this.debugBaseDir, 'pathgrade-debug', this.debugName);
-            await fs.remove(dest);
-            await fs.copy(this.ws.path, dest);
-            if (this.interactionMode === 'runConversation' && this.lastConversationResult) {
-                const snapshot = buildRunSnapshot({
-                    agent: this.agentName,
-                    messages: this._messages,
-                    log: this._log,
-                    conversationResult: this.lastConversationResult,
-                    workspace: dest,
-                });
-                await fs.writeJSON(path.join(dest, 'run-snapshot.json'), snapshot, { spaces: 2 });
+        try {
+            await this.activeChatSession?.dispose?.();
+            this.activeChatSession = undefined;
+            if (this.debugOpt) {
+                const managedOptions = typeof this.debugOpt === 'object' ? this.debugOpt : undefined;
+                const managed = managedOptions
+                    ? await prepareManagedDebugRun({
+                        rootDir: managedOptions.directory
+                            ? path.resolve(this.debugBaseDir, managedOptions.directory)
+                            : path.join(this.debugBaseDir, 'pathgrade-debug'),
+                        debugName: this.debugName,
+                    })
+                    : undefined;
+                const dest = typeof this.debugOpt === 'string'
+                    ? this.debugOpt
+                    : managed?.destination ?? path.join(this.debugBaseDir, 'pathgrade-debug', this.debugName);
+                await fs.remove(dest);
+                await fs.copy(this.ws.path, dest);
+                if (this.interactionMode === 'runConversation' && this.lastConversationResult) {
+                    const snapshot = buildRunSnapshot({
+                        agent: this.agentName,
+                        messages: this._messages,
+                        log: this._log,
+                        conversationResult: this.lastConversationResult,
+                        workspace: dest,
+                    });
+                    await fs.writeJSON(path.join(dest, 'run-snapshot.json'), snapshot, { spaces: 2 });
+                }
+                if (managed) {
+                    const retainRuns = managedOptions.retainRuns ?? DEFAULT_DEBUG_RETAIN_RUNS;
+                    await cleanDebugRuns({
+                        rootDir: managed.rootDir,
+                        keep: Math.max(0, retainRuns - 1),
+                    });
+                }
             }
         }
-        await this.ws.dispose();
+        finally {
+            await this.ws.dispose();
+        }
     }
 }
 /**
@@ -353,14 +385,21 @@ function resolveCaseDebugContext() {
     };
 }
 export async function createAgent(opts) {
+    if (typeof opts.debug === 'object') {
+        const retainRuns = opts.debug.retainRuns ?? DEFAULT_DEBUG_RETAIN_RUNS;
+        if (!Number.isSafeInteger(retainRuns) || retainRuns < 1) {
+            throw new Error('Pathgrade debug retainRuns must be a positive integer');
+        }
+    }
     const agentName = resolveAgentName(opts, process.env);
+    validateOpenCodeDeclaration(agentName, opts);
     const transport = agentName === 'codex'
         ? resolveCodexTransport(opts, process.env)
         : undefined;
     const timeoutSetting = opts.timeout ?? 300;
     // Capture runner context now; adapters own installation and restoration.
     const testCtx = opts.debug ? resolveCaseDebugContext() : { name: '', dir: '' };
-    const { timeout: _, mcpMock, mcpConfigFile, agent: __, debug: ___, model: ____, transport: _____, mcpSafety: ______, ...rest } = opts;
+    const { timeout: _, mcpMock, mcpConfigFile, agent: __, debug: ___, model: ____, transport: _____, mcpSafety: ______, opencodeExecutable, ...rest } = opts;
     const workspace = await prepareWorkspace({
         ...rest,
         agent: agentName,
@@ -378,7 +417,7 @@ export async function createAgent(opts) {
         sink: verboseSinkOverride ?? undefined,
         testName: testCtx.name || undefined,
     });
-    const agent = new AgentImpl(workspace, agentName, llm, timeoutSetting, opts.conversationWindow, opts.model, opts.debug, debugName, debugBaseDir, verbose, transport, opts.mcpSafety);
+    const agent = new AgentImpl(workspace, agentName, llm, timeoutSetting, opts.conversationWindow, opts.model, opts.debug, debugName, debugBaseDir, verbose, transport, opts.mcpSafety, opencodeExecutable, agentName === 'opencode' ? collectOpenCodeMcpToolNames(mcpMock) : undefined);
     lifecycleCore.registerAgent(agent);
     return agent;
 }

package/dist/sdk/converse.js

@@ -175,7 +175,9 @@ export async function runConversation(opts, deps) {
         const turnStart = Date.now();
         // Under app-server the child process holds thread state; a crashed
         // turn is not safely replayable, so retries are suppressed.
-        const maxRetries = deps.transport === 'app-server' ? 0 : MAX_TURN_RETRIES;
+        const maxRetries = deps.transport === 'app-server' || deps.agentName === 'opencode'
+            ? 0
+            : MAX_TURN_RETRIES;
         let lastError;
         let turnResult;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {

package/dist/sdk/index.d.ts

@@ -21,7 +21,7 @@ export { emitEvalResult, resetAllResultObserversForTests, resetUserResultObserve
 export { getAgentCapabilities } from './types.js';
 export type { AgentTransport, AgentCapabilities, AgentName, McpRunMode, McpSafetyOptions, McpToolPolicy, McpToolPolicyRule, } from './types.js';
 export type { AskBus, AskBatch, AskQuestion, AskOption, AskAnswer, AskResolution, AskBatchSnapshot, AskAnswerSnapshot, AskResolutionSnapshot, AskHandle, AskHandler, AskSource, AskLifecycle, AskAnswerSource, Unsubscribe as AskBusUnsubscribe, } from './ask-bus/types.js';
-export type { Agent, AgentOptions, Message, Scorer, CheckScorer, ScoreScorer, JudgeScorer, ToolUsageScorer, ScorerContext, EvalResult, ScorerResultEntry, ScorerStatus, ChatSession, ConversationResult, ConverseOptions, UntilPredicate, UntilContext, Reaction, TextReaction, AskUserReaction, AskUserQuestion, AskUserOption, ReactionPreviewEntry, TextReactionPreviewEntry, AskUserReactionPreviewEntry, ReactionPreviewResult, ReactionPreviewTurn, StepScorer, Persona, PersonaConfig, ConversationWindowConfig, TurnDetail, ReactionFiredEntry, PathgradePluginOptions, PathgradeMeta, TurnTiming, TokenUsage, EvaluateOptions, ReactionPreviewStatus, ScoreResult, JudgeInput, CodeJudgeToolName, ToolExpectation, SessionArtifactMatchOptions, SessionArtifactContent, SessionArtifacts, RecordedEvalResult, PathgradeTestMeta, EvaluationResultKind, AgentExecutionMetadata, AgentExecutionTransport, AgentInteractionMode, } from './types.js';
+export type { Agent, AgentOptions, DebugOptions, Message, Scorer, CheckScorer, ScoreScorer, JudgeScorer, ToolUsageScorer, ScorerContext, EvalResult, ScorerResultEntry, ScorerStatus, ChatSession, ConversationResult, ConverseOptions, UntilPredicate, UntilContext, Reaction, TextReaction, AskUserReaction, AskUserQuestion, AskUserOption, ReactionPreviewEntry, TextReactionPreviewEntry, AskUserReactionPreviewEntry, ReactionPreviewResult, ReactionPreviewTurn, StepScorer, Persona, PersonaConfig, ConversationWindowConfig, TurnDetail, ReactionFiredEntry, PathgradePluginOptions, PathgradeMeta, TurnTiming, TokenUsage, EvaluateOptions, ReactionPreviewStatus, ScoreResult, JudgeInput, CodeJudgeToolName, ToolExpectation, SessionArtifactMatchOptions, SessionArtifactContent, SessionArtifacts, RecordedEvalResult, PathgradeTestMeta, EvaluationResultKind, AgentExecutionMetadata, AgentExecutionTransport, AgentInteractionMode, } from './types.js';
 export type { ConversationWindow, ConversationWindowOptions } from './conversation-window.js';
 export type { JudgePipelineOptions } from './judge-pipeline.js';
 export type { RunScorerOptions } from './run-scorer.js';

package/dist/sdk/managed-session.d.ts

@@ -31,6 +31,8 @@ export interface ManagedSessionDeps {
     transport?: AgentTransport;
     /** Live MCP Server Safety policy to enforce in supported harnesses. */
     mcpSafety?: McpSafetyOptions;
+    opencodeExecutable?: string;
+    opencodeMcpToolNames?: string[];
 }
 export interface ManagedSession {
     /** Full lifecycle: log start/result, push messages, check exit code. */

package/dist/sdk/managed-session.js

@@ -24,6 +24,8 @@ export function createManagedSession(deps) {
         askBus,
         ...(transport !== undefined ? { transport } : {}),
         ...(deps.mcpSafety !== undefined ? { mcpSafety: deps.mcpSafety } : {}),
+        ...(deps.opencodeExecutable !== undefined ? { opencodeExecutable: deps.opencodeExecutable } : {}),
+        ...(deps.opencodeMcpToolNames !== undefined ? { opencodeMcpToolNames: deps.opencodeMcpToolNames } : {}),
         getAbortSignal: () => currentSignal,
     };
     let session = null;

package/dist/sdk/runtime-policy.js

@@ -7,6 +7,7 @@ const INTERACTIVE_TOOL_NAMES = {
     claude: 'AskUserQuestion',
     codex: 'request_user_input',
     cursor: 'AskQuestion',
+    opencode: 'question',
 };
 export function planRuntimePolicies(agent, transport) {
     const capabilities = getAgentCapabilities(agent, transport);

package/dist/sdk/snapshots.d.ts

@@ -1,9 +1,9 @@
 import type { LogEntry } from '../types.js';
 import type { ToolEvent } from '../tool-events.js';
 import type { AgentName, ConversationResult, Message, TurnTiming } from './types.js';
-export declare const RUN_SNAPSHOT_VERSION = 1;
+export declare const RUN_SNAPSHOT_VERSION = 2;
 export interface RunSnapshot {
-    version: 1;
+    version: 1 | 2;
     timestamp: string;
     agent: AgentName;
     messages: Message[];

package/dist/sdk/snapshots.js

@@ -1,12 +1,12 @@
 import fs from 'fs-extra';
-export const RUN_SNAPSHOT_VERSION = 1;
+export const RUN_SNAPSHOT_VERSION = 2;
 export function buildRunSnapshot(params) {
     const { agent, messages, log, conversationResult, workspace, timestamp } = params;
     const toolEvents = log
         .filter((entry) => entry.type === 'tool_event' && entry.tool_event)
         .map((entry) => entry.tool_event);
     return {
-        version: RUN_SNAPSHOT_VERSION,
+        version: agent === 'opencode' ? 2 : 1,
         timestamp: timestamp ?? new Date().toISOString(),
         agent,
         messages: [...messages],
@@ -102,6 +102,9 @@ function validateRunSnapshot(input) {
     if (snapshot.version > RUN_SNAPSHOT_VERSION) {
         throw new SnapshotVersionError(snapshot.version);
     }
+    if (snapshot.version !== 1 && snapshot.version !== 2) {
+        throw new SnapshotVersionError(snapshot.version);
+    }
     if (!Array.isArray(snapshot.messages)) {
         throw new SnapshotParseError('Snapshot is missing required field: messages');
     }
@@ -127,10 +130,16 @@ function validateRunSnapshot(input) {
     const turnTimings = Array.isArray(snapshot.turnTimings)
         ? snapshot.turnTimings
         : snapshot.conversationResult.turnTimings;
+    const legacyAgents = ['claude', 'codex', 'cursor'];
+    const currentAgents = [...legacyAgents, 'opencode'];
+    const allowedAgents = snapshot.version === 1 ? legacyAgents : currentAgents;
+    if (typeof snapshot.agent !== 'string' || !allowedAgents.includes(snapshot.agent)) {
+        throw new SnapshotParseError(`Snapshot version ${snapshot.version} has invalid agent: ${String(snapshot.agent)}`);
+    }
     return {
-        version: RUN_SNAPSHOT_VERSION,
+        version: snapshot.version,
         timestamp: typeof snapshot.timestamp === 'string' ? snapshot.timestamp : new Date(0).toISOString(),
-        agent: snapshot.agent === 'claude' || snapshot.agent === 'codex' || snapshot.agent === 'cursor' ? snapshot.agent : 'claude',
+        agent: snapshot.agent,
         messages: snapshot.messages,
         log: snapshot.log,
         toolEvents: snapshot.toolEvents,

package/dist/sdk/types.d.ts

@@ -5,7 +5,7 @@ import type { TrialResult } from '../types.js';
 import type { DiagnosticsReport } from './diagnostics.js';
 import type { LLMPort } from '../utils/llm-types.js';
 import type { McpSafetyOptions } from './mcp-safety.js';
-export type AgentName = 'claude' | 'codex' | 'cursor';
+export type AgentName = 'claude' | 'codex' | 'cursor' | 'opencode';
 export type AgentInteractionMode = 'prompt' | 'start_chat' | 'conversation';
 /** Runtime channel that actually executed the agent. */
 export type AgentExecutionTransport = AgentTransport | 'claude-agent-sdk' | 'cursor-agent';
@@ -19,6 +19,8 @@ export interface AgentExecutionMetadata {
 }
 export interface AgentOptions {
     agent?: AgentName;
+    /** Absolute path to the pinned OpenCode executable. Valid only for `agent: 'opencode'`. */
+    opencodeExecutable?: string;
     model?: string;
     timeout?: number | 'auto';
     workspace?: string;
@@ -29,8 +31,8 @@ export interface AgentOptions {
     mcpConfigFile?: string;
     /** Configure the conversation window for transcript-based agents. Set false to disable. */
     conversationWindow?: ConversationWindowConfig | false;
-    /** Copy workspace to a persistent location before cleanup. true = ./pathgrade-debug/{test-name}/, string = custom path. */
-    debug?: boolean | string;
+    /** Preserve the workspace. true uses the legacy path; strings are exact paths; objects enable managed retention. */
+    debug?: boolean | string | DebugOptions;
     /**
      * Glob patterns to ignore when copying workspace and skill directories.
      * Replaces the default ignore list entirely. Pass `[]` to disable filtering.
@@ -51,6 +53,12 @@ export interface AgentOptions {
      */
     mcpSafety?: McpSafetyOptions;
 }
+export interface DebugOptions {
+    /** Managed debug root. Relative paths resolve next to the eval file. */
+    directory?: string;
+    /** Maximum managed runs to retain, including the current run. Default: 3. */
+    retainRuns?: number;
+}
 export type { McpRunMode, McpSafetyOptions, McpToolPolicy, McpToolPolicyRule, } from './mcp-safety.js';
 export interface ConversationWindowConfig {
     /** Number of recent messages to keep verbatim. Default: 4 */

package/dist/sdk/types.js

@@ -2,6 +2,7 @@ const BASE_CAPABILITIES = {
     claude: { mcp: true, nativeSession: true, interactiveQuestionTransport: 'reliable' },
     codex: { mcp: false, nativeSession: true, interactiveQuestionTransport: 'noninteractive' },
     cursor: { mcp: true, nativeSession: true, interactiveQuestionTransport: 'noninteractive' },
+    opencode: { mcp: true, nativeSession: true, interactiveQuestionTransport: 'noninteractive' },
 };
 export function getAgentCapabilities(agent, transport) {
     const base = BASE_CAPABILITIES[agent];

package/dist/tool-events.d.ts

@@ -1,7 +1,7 @@
 export type ToolAction = 'run_shell' | 'read_file' | 'write_file' | 'edit_file' | 'search_code' | 'list_files' | 'ask_user' | 'web_fetch' | 'use_skill' | 'update_todos' | 'mcp_tool_call' | 'unknown';
 export interface ToolEvent {
     action: ToolAction;
-    provider: 'claude' | 'codex' | 'cursor';
+    provider: 'claude' | 'codex' | 'cursor' | 'opencode';
     providerToolName: string;
     turnNumber?: number;
     arguments?: Record<string, unknown>;

package/dist/types.d.ts

@@ -379,6 +379,10 @@ export interface AgentSessionOptions {
     abortSignal?: AbortSignal;
     /** Supplies the current timeout/cancellation signal for reused sessions. */
     getAbortSignal?: () => AbortSignal | undefined;
+    /** Absolute pinned runtime path for the OpenCode adapter. */
+    opencodeExecutable?: string;
+    /** Exact generated MCP tool names accepted by the OpenCode event normalizer. */
+    opencodeMcpToolNames?: string[];
 }
 export declare abstract class BaseAgent {
     createSession(runtime: EnvironmentHandle, runCommand: AgentCommandRunner, options?: AgentSessionOptions): Promise<AgentSession>;