@wix/pathgrade 1.0.5 → 1.0.7

package/README.md

@@ -1,6 +1,6 @@
 # Pathgrade
 
-**Evaluate AI coding agents with Vitest or Jest.** Write evals as normal `.eval.ts` files, run Claude Code, Codex, or Cursor in isolated sandboxes, and score the result with deterministic checks, rubric judges, and tool-usage assertions.
+**Evaluate AI coding agents with Vitest or Jest.** Write evals as normal `.eval.ts` files, run Claude Code, Codex, Cursor, or trusted-internal OpenCode fixtures in isolated workspaces, and score the result with deterministic checks, rubric judges, and tool-usage assertions.
 
 ## Why Pathgrade?
 
@@ -13,7 +13,7 @@
 
 ## Quick Start
 
-**Prerequisites**: Node.js 20.11+, Vitest 4+ or Jest 30+, and at least one configured agent runtime. Claude uses the bundled `@anthropic-ai/claude-agent-sdk` binary by default; Codex requires the `codex` CLI; Cursor requires the `cursor-agent` CLI.
+**Prerequisites**: Node.js 20.11+, Vitest 4+ or Jest 30+, and at least one configured agent runtime. Claude uses the bundled `@anthropic-ai/claude-agent-sdk` binary by default; Codex requires the `codex` CLI; Cursor requires the `cursor-agent` CLI. OpenCode requires the exact v1.18.18 macOS ARM64 or Linux ARM64 executable.
 
 ```bash
 yarn add -D @wix/pathgrade
@@ -40,6 +40,9 @@ By default, Pathgrade tries to reuse the agent CLI's native auth before falling
   - forwards `CURSOR_API_KEY` when set
   - macOS: reuses `cursor-agent login` OAuth tokens from the login Keychain
   - surfaces a clear error when neither is available (run `cursor-agent login` or set `CURSOR_API_KEY`)
+- **OpenCode**
+  - requires an explicit `ANTHROPIC_API_KEY` in `createAgent({ env })`; ambient credentials and login state are never read
+  - accepts an optional explicit HTTPS `ANTHROPIC_BASE_URL` ending in `/v1`
 
 If you set `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL`, or `CURSOR_API_BASE_URL`, set the matching API key too.
 
@@ -231,7 +234,24 @@ toolUsage('expected-workflow', [
 
 ## Conversations
 
-Pathgrade currently supports three agent backends: `claude`, `codex`, and `cursor`. Set the backend per test via `createAgent({ agent: 'claude' })`, or omit `agent` and use `PATHGRADE_AGENT` as the process-wide fallback.
+Pathgrade supports `claude`, `codex`, `cursor`, and `opencode`. Set the backend per test via `createAgent({ agent: 'claude' })`, or omit `agent` and use `PATHGRADE_AGENT` as the process-wide fallback.
+
+### OpenCode trusted-internal backend
+
+OpenCode v1 is only for fixtures, prompts, skills, and generated MCP mocks controlled by trusted Pathgrade maintainers. It is not a security sandbox: OpenCode and Bash children run with the host user's filesystem, process, and network authority and receive the provider credentials. Do not use it for external repositories, user-supplied prompts, or adversarial fixtures.
+
+```typescript
+const agent = await createAgent({
+    agent: 'opencode',
+    opencodeExecutable: '/absolute/path/to/opencode-v1.18.18',
+    env: {
+        ANTHROPIC_API_KEY: process.env.APP_ANTHROPIC_API_KEY!,
+        ANTHROPIC_BASE_URL: 'https://api.example.com/v1',
+    },
+});
+```
+
+The backend supports only `anthropic/claude-sonnet-5`, generated stdio `mcpMock` servers, and clean hosts without system-managed OpenCode configuration. `PATHGRADE_AGENT=opencode` selects the backend but does not supply the required executable or credentials.
 
 ### `agent.prompt()` - One shot
 
@@ -409,13 +429,13 @@ Notes:
 
 | Variable | Purpose |
 |----------|---------|
-| `ANTHROPIC_API_KEY` | Claude auth and the required key when using `ANTHROPIC_BASE_URL` |
+| `ANTHROPIC_API_KEY` | Claude auth; also required explicitly in `AgentOptions.env` for OpenCode |
 | `OPENAI_API_KEY` | Codex auth and the required key when using `OPENAI_BASE_URL` |
 | `CURSOR_API_KEY` | Cursor auth and the required key when using `CURSOR_API_BASE_URL` |
 | `ANTHROPIC_BASE_URL` | Custom Anthropic-compatible endpoint |
 | `OPENAI_BASE_URL` | Custom OpenAI-compatible endpoint |
 | `CURSOR_API_BASE_URL` | Custom Cursor-compatible endpoint |
-| `PATHGRADE_AGENT` | Fallback agent for all tests (`claude`, `codex`, or `cursor`). `createAgent({ agent })` wins over this. |
+| `PATHGRADE_AGENT` | Fallback agent for all tests (`claude`, `codex`, `cursor`, or `opencode`). `createAgent({ agent })` wins over this. |
 | `PATHGRADE_CODEX_TRANSPORT` | Fallback Codex transport (`exec` or `app-server`). `createAgent({ transport })` wins over this. |
 | `PATHGRADE_VERBOSE` | `1` enables live per-turn streaming to stderr |
 | `PATHGRADE_DIAGNOSTICS` | `1` prints full diagnostics for passing evals too |

package/dist/agents/opencode-contract.d.ts

@@ -0,0 +1,24 @@
+import type { MockMcpServerDescriptor } from '../core/mcp-mock.types.js';
+import type { AgentName, AgentOptions } from '../sdk/types.js';
+export declare const OPENCODE_MODEL = "anthropic/claude-sonnet-5";
+export declare const OPENCODE_VERSION = "1.18.18";
+export interface OpenCodeRuntimeLockEntry {
+    version: typeof OPENCODE_VERSION;
+    executableSha256: string;
+}
+export declare const OPENCODE_RUNTIME_LOCK: {
+    readonly 'darwin-arm64': {
+        readonly version: "1.18.18";
+        readonly executableSha256: "4f5979c2dadb06fbff1335335afaaea274e58f92e79aa43cf2ed98618d555422";
+    };
+    readonly 'linux-arm64': {
+        readonly version: "1.18.18";
+        readonly executableSha256: "a63ef0c7271383e48ffe36c156b4146087bbbc97929dec40e8be95ed4f4d76ae";
+    };
+};
+export type OpenCodePlatformKey = keyof typeof OPENCODE_RUNTIME_LOCK;
+export declare function getOpenCodePlatformKey(platform: NodeJS.Platform, arch: string): OpenCodePlatformKey | undefined;
+export declare function currentOpenCodePlatformKey(): OpenCodePlatformKey | undefined;
+export declare function validateOpenCodeDeclaration(agent: AgentName, opts: AgentOptions): void;
+export declare function sanitizeOpenCodeToolName(value: string): string;
+export declare function collectOpenCodeMcpToolNames(declaration: MockMcpServerDescriptor | MockMcpServerDescriptor[] | undefined): string[];

package/dist/agents/opencode-contract.js

@@ -0,0 +1,84 @@
+import * as path from 'node:path';
+export const OPENCODE_MODEL = 'anthropic/claude-sonnet-5';
+export const OPENCODE_VERSION = '1.18.18';
+export const OPENCODE_RUNTIME_LOCK = {
+    'darwin-arm64': {
+        version: OPENCODE_VERSION,
+        executableSha256: '4f5979c2dadb06fbff1335335afaaea274e58f92e79aa43cf2ed98618d555422',
+    },
+    'linux-arm64': {
+        version: OPENCODE_VERSION,
+        executableSha256: 'a63ef0c7271383e48ffe36c156b4146087bbbc97929dec40e8be95ed4f4d76ae',
+    },
+};
+export function getOpenCodePlatformKey(platform, arch) {
+    const key = `${platform}-${arch}`;
+    return key in OPENCODE_RUNTIME_LOCK ? key : undefined;
+}
+export function currentOpenCodePlatformKey() {
+    return getOpenCodePlatformKey(process.platform, process.arch);
+}
+function hasOwn(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key);
+}
+function assertOpenCodeBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error('OpenCode ANTHROPIC_BASE_URL must be an absolute HTTPS API root ending in /v1');
+    }
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || !url.pathname.endsWith('/v1')) {
+        throw new Error('OpenCode ANTHROPIC_BASE_URL must be an absolute HTTPS API root ending in /v1');
+    }
+}
+export function validateOpenCodeDeclaration(agent, opts) {
+    if (agent !== 'opencode') {
+        if (opts.opencodeExecutable !== undefined) {
+            throw new Error('opencodeExecutable is valid only for agent: "opencode"');
+        }
+        return;
+    }
+    if (!currentOpenCodePlatformKey()) {
+        throw new Error(`OpenCode is not supported on ${process.platform}-${process.arch}`);
+    }
+    if (!opts.opencodeExecutable || !path.isAbsolute(opts.opencodeExecutable)) {
+        throw new Error('OpenCode requires an absolute opencodeExecutable path');
+    }
+    if (opts.model !== undefined && opts.model !== OPENCODE_MODEL) {
+        throw new Error(`OpenCode v1 supports only model ${OPENCODE_MODEL}`);
+    }
+    const env = opts.env ?? {};
+    if (!hasOwn(env, 'ANTHROPIC_API_KEY') || !env.ANTHROPIC_API_KEY?.trim()) {
+        throw new Error('OpenCode requires a nonempty own env.ANTHROPIC_API_KEY');
+    }
+    if (hasOwn(env, 'ANTHROPIC_BASE_URL')) {
+        if (!env.ANTHROPIC_BASE_URL) {
+            throw new Error('OpenCode ANTHROPIC_BASE_URL must be a nonempty absolute HTTPS API root ending in /v1');
+        }
+        assertOpenCodeBaseUrl(env.ANTHROPIC_BASE_URL);
+    }
+    if (opts.copyFromHome !== undefined)
+        throw new Error('OpenCode does not support copyFromHome');
+    if (opts.mcpConfigFile !== undefined)
+        throw new Error('OpenCode v1 supports generated mcpMock only, not mcpConfigFile');
+    if (opts.mcpSafety !== undefined)
+        throw new Error('OpenCode v1 does not support mcpSafety');
+    if (opts.transport !== undefined)
+        throw new Error('OpenCode does not support transport overrides');
+    for (const key of Object.keys(env)) {
+        if (key === 'HOME' || key.startsWith('XDG_') || key.startsWith('OPENCODE_')) {
+            throw new Error(`OpenCode reserves env.${key}`);
+        }
+    }
+}
+export function sanitizeOpenCodeToolName(value) {
+    return value.replace(/[^A-Za-z0-9_-]/g, '_');
+}
+export function collectOpenCodeMcpToolNames(declaration) {
+    if (!declaration)
+        return [];
+    const descriptors = Array.isArray(declaration) ? declaration : [declaration];
+    return descriptors.flatMap((descriptor) => descriptor.config.tools.map((tool) => `${sanitizeOpenCodeToolName(descriptor.config.name)}_${sanitizeOpenCodeToolName(tool.name)}`));
+}

package/dist/agents/opencode.d.ts

@@ -0,0 +1,27 @@
+import { BaseAgent, type AgentCommandRunner, type AgentSession, type AgentSessionOptions, type AgentTurnResult, type EnvironmentHandle } from '../types.js';
+interface SpawnResult {
+    stdout: string;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    overflow: boolean;
+    aborted: boolean;
+}
+interface SpawnOpenCodeOptions {
+    cwd: string;
+    env: Record<string, string>;
+    stdin: string;
+    signal?: AbortSignal;
+    outputCapBytes?: number;
+}
+export declare function spawnOpenCode(executable: string, args: string[], options: SpawnOpenCodeOptions): Promise<SpawnResult>;
+interface ParsedOpenCodeTurn {
+    result: AgentTurnResult;
+    sessionId: string;
+}
+export declare function parseOpenCodeOutput(stdout: string, processResult: Pick<SpawnResult, 'exitCode' | 'overflow' | 'aborted'>, mcpToolNames: ReadonlySet<string>): ParsedOpenCodeTurn;
+export declare function managedOpenCodeConfigPaths(platform?: NodeJS.Platform, username?: string): string[];
+export declare function assertCleanManagedOpenCodeHost(candidates?: string[]): Promise<void>;
+export declare class OpenCodeAgent extends BaseAgent {
+    createSession(runtime: EnvironmentHandle, _runCommand: AgentCommandRunner, options?: AgentSessionOptions): Promise<AgentSession>;
+}
+export {};

package/dist/agents/opencode.js

@@ -0,0 +1,508 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import fs from 'fs-extra';
+import { BaseAgent, getRuntimeEnv, getWorkspacePath, } from '../types.js';
+import { buildSummary, enrichSkillEvents } from '../tool-events.js';
+import { readStagedMcpServers } from '../providers/mcp-config.js';
+import { currentOpenCodePlatformKey, OPENCODE_MODEL, OPENCODE_RUNTIME_LOCK, } from './opencode-contract.js';
+const OUTPUT_CAP_BYTES = 16 * 1024 * 1024;
+const FIXED_OPENCODE_ENV = {
+    OPENCODE_CLIENT: 'pathgrade',
+    OPENCODE_DISABLE_AUTOUPDATE: '1',
+    OPENCODE_DISABLE_PRUNE: '1',
+    OPENCODE_DISABLE_MODELS_FETCH: '1',
+    OPENCODE_DISABLE_DEFAULT_PLUGINS: '1',
+    OPENCODE_DISABLE_EXTERNAL_SKILLS: '1',
+    OPENCODE_DISABLE_LSP_DOWNLOAD: '1',
+    OPENCODE_DISABLE_SHARE: '1',
+    OPENCODE_PURE: '1',
+};
+const OPENCODE_PERMISSION = JSON.stringify({
+    read: 'allow',
+    edit: 'allow',
+    glob: 'allow',
+    grep: 'allow',
+    list: 'allow',
+    bash: 'allow',
+    todowrite: 'allow',
+    lsp: 'allow',
+    skill: 'allow',
+    task: 'deny',
+    question: 'deny',
+    plan_enter: 'deny',
+    plan_exit: 'deny',
+    external_directory: 'deny',
+    webfetch: 'deny',
+    websearch: 'deny',
+});
+const NATIVE_TOOL_ACTIONS = {
+    bash: 'run_shell',
+    read: 'read_file',
+    write: 'write_file',
+    edit: 'edit_file',
+    grep: 'search_code',
+    glob: 'list_files',
+    list: 'list_files',
+    skill: 'use_skill',
+    todowrite: 'update_todos',
+    lsp: 'search_code',
+};
+const ALLOWED_EVENT_TYPES = new Set([
+    'tool_use',
+    'step_start',
+    'step_finish',
+    'text',
+    'reasoning',
+    'error',
+]);
+export function spawnOpenCode(executable, args, options) {
+    return new Promise((resolve, reject) => {
+        const stdout = [];
+        const cap = options.outputCapBytes ?? OUTPUT_CAP_BYTES;
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let overflow = false;
+        let aborted = false;
+        let killTimer;
+        let settled = false;
+        const child = spawn(executable, args, {
+            cwd: options.cwd,
+            env: options.env,
+            shell: false,
+            detached: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const killGroup = (signal) => {
+            if (!child.pid)
+                return;
+            try {
+                process.kill(-child.pid, signal);
+            }
+            catch {
+                // The process may have exited between the state check and kill.
+            }
+        };
+        const terminate = () => {
+            killGroup('SIGTERM');
+            killTimer ??= setTimeout(() => killGroup('SIGKILL'), 250);
+            killTimer.unref();
+        };
+        const onAbort = () => {
+            aborted = true;
+            terminate();
+        };
+        const onOverflow = () => {
+            overflow = true;
+            terminate();
+        };
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+        if (options.signal?.aborted)
+            onAbort();
+        child.stdout.on('data', (chunk) => {
+            stdoutBytes += chunk.length;
+            if (stdoutBytes <= cap)
+                stdout.push(chunk);
+            else
+                onOverflow();
+        });
+        child.stderr.on('data', (chunk) => {
+            stderrBytes += chunk.length;
+            if (stderrBytes > cap)
+                onOverflow();
+        });
+        child.stdin.on('error', () => undefined);
+        if (!aborted)
+            child.stdin.end(options.stdin);
+        else
+            child.stdin.destroy();
+        child.once('error', (error) => finish(undefined, undefined, error));
+        child.once('close', (code, signal) => finish(code, signal));
+        function finish(code, signal, error) {
+            if (settled)
+                return;
+            settled = true;
+            options.signal?.removeEventListener('abort', onAbort);
+            if (killTimer)
+                clearTimeout(killTimer);
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve({
+                stdout: Buffer.concat(stdout).toString('utf8'),
+                exitCode: code ?? null,
+                signal: signal ?? null,
+                overflow,
+                aborted,
+            });
+        }
+    });
+}
+function record(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`OpenCode protocol error: ${label} must be an object`);
+    }
+    return value;
+}
+function finiteNumber(value, label) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        throw new Error(`OpenCode protocol error: ${label} must be a nonnegative finite number`);
+    }
+    return value;
+}
+function requiredString(value, label) {
+    if (typeof value !== 'string' || !value) {
+        throw new Error(`OpenCode protocol error: ${label} must be a nonempty string`);
+    }
+    return value;
+}
+function sanitizedProviderError(event) {
+    const error = record(event.error, 'error');
+    const data = error.data && typeof error.data === 'object' && !Array.isArray(error.data)
+        ? error.data
+        : {};
+    const message = typeof data.message === 'string' && data.message.trim()
+        ? data.message.trim().slice(0, 1_000)
+        : 'OpenCode provider error';
+    const status = typeof data.statusCode === 'number' ? ` status=${data.statusCode}` : '';
+    const retryable = typeof data.isRetryable === 'boolean' ? ` retryable=${data.isRetryable}` : '';
+    return new Error(`${message}${status}${retryable}`);
+}
+export function parseOpenCodeOutput(stdout, processResult, mcpToolNames) {
+    if (processResult.overflow)
+        throw new Error('OpenCode output exceeded the 16 MiB limit');
+    if (processResult.aborted)
+        throw new Error('OpenCode turn aborted');
+    const textParts = [];
+    const toolEvents = [];
+    const sanitizedTrace = [];
+    const seenParts = new Map();
+    let sessionId;
+    let stepFinishCount = 0;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheCreationInputTokens = 0;
+    let cacheReadInputTokens = 0;
+    let costUsd = 0;
+    let providerError;
+    for (const [index, line] of stdout.split('\n').entries()) {
+        if (!line.trim())
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            throw new Error(`OpenCode protocol error: invalid JSON on line ${index + 1}`);
+        }
+        const event = record(parsed, `line ${index + 1}`);
+        const type = requiredString(event.type, `line ${index + 1} type`);
+        if (!ALLOWED_EVENT_TYPES.has(type)) {
+            throw new Error(`OpenCode protocol error: unsupported event type ${type}`);
+        }
+        const currentSessionId = requiredString(event.sessionID, `line ${index + 1} sessionID`);
+        if (sessionId && sessionId !== currentSessionId) {
+            throw new Error('OpenCode protocol error: mixed session IDs');
+        }
+        sessionId = currentSessionId;
+        if (type === 'error') {
+            providerError = sanitizedProviderError(event);
+            sanitizedTrace.push({ type: 'error', message: providerError.message });
+            continue;
+        }
+        const part = record(event.part, `${type} part`);
+        const partId = requiredString(part.id, `${type} part.id`);
+        const fingerprint = JSON.stringify({ type, part });
+        const prior = seenParts.get(partId);
+        if (prior !== undefined) {
+            if (prior !== fingerprint) {
+                throw new Error(`OpenCode protocol error: conflicting duplicate part ID ${partId}`);
+            }
+            continue;
+        }
+        seenParts.set(partId, fingerprint);
+        if (type === 'text') {
+            const text = typeof part.text === 'string' ? part.text : undefined;
+            const time = record(part.time, 'text part.time');
+            if (text === undefined || typeof time.end !== 'number') {
+                throw new Error('OpenCode protocol error: incomplete text part');
+            }
+            textParts.push(text);
+            sanitizedTrace.push({ type, text });
+            continue;
+        }
+        if (type === 'tool_use') {
+            const tool = requiredString(part.tool, 'tool_use part.tool');
+            const state = record(part.state, 'tool_use part.state');
+            if (state.status !== 'completed' && state.status !== 'error') {
+                throw new Error(`OpenCode protocol error: incomplete tool ${tool}`);
+            }
+            const input = state.input === undefined ? undefined : record(state.input, 'tool_use state.input');
+            const action = mcpToolNames.has(tool)
+                ? 'mcp_tool_call'
+                : NATIVE_TOOL_ACTIONS[tool] ?? 'unknown';
+            toolEvents.push({
+                action,
+                provider: 'opencode',
+                providerToolName: tool,
+                ...(input ? { arguments: input } : {}),
+                summary: buildSummary(action, tool, input),
+                confidence: action === 'unknown' ? 'low' : 'high',
+                rawSnippet: JSON.stringify({ tool, status: state.status, input }).slice(0, 2_000),
+            });
+            sanitizedTrace.push({ type, tool, status: state.status, input });
+            continue;
+        }
+        if (type === 'step_finish') {
+            const tokens = record(part.tokens, 'step_finish part.tokens');
+            const cache = record(tokens.cache, 'step_finish part.tokens.cache');
+            const input = finiteNumber(tokens.input, 'tokens.input');
+            const output = finiteNumber(tokens.output, 'tokens.output');
+            const reasoning = finiteNumber(tokens.reasoning, 'tokens.reasoning');
+            const cacheWrite = finiteNumber(cache.write, 'tokens.cache.write');
+            const cacheRead = finiteNumber(cache.read, 'tokens.cache.read');
+            const cost = finiteNumber(part.cost, 'step_finish part.cost');
+            inputTokens += input + cacheWrite + cacheRead;
+            outputTokens += output + reasoning;
+            cacheCreationInputTokens += cacheWrite;
+            cacheReadInputTokens += cacheRead;
+            costUsd += cost;
+            stepFinishCount++;
+            sanitizedTrace.push({
+                type,
+                tokens: { input, output, reasoning, cache: { write: cacheWrite, read: cacheRead } },
+                cost,
+            });
+            continue;
+        }
+        sanitizedTrace.push({ type });
+    }
+    if (providerError)
+        throw providerError;
+    if (processResult.exitCode !== 0) {
+        throw new Error(`OpenCode process exited with code ${processResult.exitCode ?? 'unknown'}`);
+    }
+    if (!sessionId)
+        throw new Error('OpenCode protocol error: no events');
+    if (stepFinishCount === 0)
+        throw new Error('OpenCode protocol error: missing step_finish');
+    const assistantMessage = textParts.join('');
+    const traceOutput = sanitizedTrace.map((event) => JSON.stringify(event)).join('\n');
+    return {
+        sessionId,
+        result: {
+            rawOutput: traceOutput,
+            traceOutput,
+            assistantMessage,
+            visibleAssistantMessage: assistantMessage,
+            visibleAssistantMessageSource: 'assistant_message',
+            exitCode: 0,
+            toolEvents: enrichSkillEvents(toolEvents),
+            inputTokens,
+            outputTokens,
+            cacheCreationInputTokens,
+            cacheReadInputTokens,
+            costUsd,
+        },
+    };
+}
+function sha256File(filename) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        const stream = createReadStream(filename);
+        stream.on('error', reject);
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('end', () => resolve(hash.digest('hex')));
+    });
+}
+async function assertNoProjectConfig(workspacePath) {
+    for (const name of ['opencode.json', 'opencode.jsonc', '.opencode']) {
+        if (await fs.pathExists(path.join(workspacePath, name))) {
+            throw new Error(`OpenCode workspace configuration is not allowed: ${name}`);
+        }
+    }
+}
+export function managedOpenCodeConfigPaths(platform = process.platform, username = os.userInfo().username) {
+    return platform === 'linux'
+        ? ['/etc/opencode/opencode.json', '/etc/opencode/opencode.jsonc']
+        : [
+            '/Library/Application Support/opencode/opencode.json',
+            '/Library/Application Support/opencode/opencode.jsonc',
+            `/Library/Managed Preferences/${username}/ai.opencode.managed.plist`,
+            '/Library/Managed Preferences/ai.opencode.managed.plist',
+        ];
+}
+export async function assertCleanManagedOpenCodeHost(candidates = managedOpenCodeConfigPaths()) {
+    for (const candidate of candidates) {
+        if (await fs.pathExists(candidate)) {
+            throw new Error(`OpenCode managed host configuration is not supported: ${candidate}`);
+        }
+    }
+}
+async function projectMcpConfig(workspacePath, mcpConfigPath) {
+    if (!mcpConfigPath)
+        return {};
+    const servers = await readStagedMcpServers(workspacePath, mcpConfigPath);
+    const config = {};
+    for (const [name, entry] of Object.entries(servers ?? {})) {
+        if (!('command' in entry)) {
+            throw new Error(`OpenCode MCP server "${name}" must remain a stdio server`);
+        }
+        const stdio = entry;
+        config[name] = {
+            type: 'local',
+            command: [stdio.command, ...(stdio.args ?? [])],
+            ...(stdio.env ? { environment: stdio.env } : {}),
+            cwd: '.',
+            enabled: true,
+        };
+    }
+    return config;
+}
+class OpenCodeSession {
+    workspacePath;
+    runtimeEnv;
+    executable;
+    mcpConfigPath;
+    mcpToolNames;
+    getAbortSignal;
+    xdgDirs;
+    resolvedExecutable;
+    preflightDone = false;
+    running = false;
+    failed = false;
+    disposed = false;
+    sessionId;
+    inFlight;
+    constructor(runtime, options) {
+        this.workspacePath = getWorkspacePath(runtime);
+        this.runtimeEnv = getRuntimeEnv(runtime);
+        this.executable = options.opencodeExecutable;
+        this.mcpConfigPath = options.mcpConfigPath;
+        this.mcpToolNames = new Set(options.opencodeMcpToolNames ?? []);
+        this.getAbortSignal = options.getAbortSignal ?? (() => options.abortSignal);
+        const home = this.runtimeEnv.HOME;
+        if (!home)
+            throw new Error('OpenCode requires a managed HOME');
+        this.xdgDirs = [
+            path.join(home, '.local', 'share'),
+            path.join(home, '.config'),
+            path.join(home, '.local', 'state'),
+            path.join(home, '.cache'),
+        ];
+    }
+    start({ message }) {
+        if (this.sessionId)
+            throw new Error('OpenCode session has already started');
+        return this.execute(message);
+    }
+    reply({ message }) {
+        if (!this.sessionId)
+            throw new Error('OpenCode session has not started');
+        return this.execute(message);
+    }
+    execute(message) {
+        if (this.disposed)
+            return Promise.reject(new Error('OpenCode session is disposed'));
+        if (this.failed)
+            return Promise.reject(new Error('OpenCode session is unusable after a failed turn'));
+        if (this.running)
+            return Promise.reject(new Error('OpenCode does not allow concurrent turns'));
+        this.running = true;
+        const task = this.runTurn(message);
+        this.inFlight = task;
+        void task.finally(() => {
+            this.running = false;
+            if (this.inFlight === task)
+                this.inFlight = undefined;
+        }).catch(() => undefined);
+        return task;
+    }
+    async runTurn(message) {
+        try {
+            await this.ensurePreflight();
+            await assertNoProjectConfig(this.workspacePath);
+            const mcp = await projectMcpConfig(this.workspacePath, this.mcpConfigPath);
+            const env = this.buildEnvironment(mcp);
+            const args = [
+                'run', '--format', 'json', '--thinking', '--dir', this.workspacePath,
+                '--model', OPENCODE_MODEL, '--agent', 'build',
+                ...(this.sessionId ? ['--session', this.sessionId] : []),
+            ];
+            const processResult = await spawnOpenCode(this.resolvedExecutable, args, {
+                cwd: this.workspacePath,
+                env,
+                stdin: message,
+                signal: this.getAbortSignal(),
+            });
+            const parsed = parseOpenCodeOutput(processResult.stdout, processResult, this.mcpToolNames);
+            if (this.sessionId && parsed.sessionId !== this.sessionId) {
+                throw new Error('OpenCode protocol error: resumed session ID changed');
+            }
+            this.sessionId = parsed.sessionId;
+            return parsed.result;
+        }
+        catch (error) {
+            this.failed = true;
+            await this.cleanupState();
+            throw error;
+        }
+    }
+    async ensurePreflight() {
+        if (this.preflightDone)
+            return;
+        const platformKey = currentOpenCodePlatformKey();
+        if (!platformKey)
+            throw new Error(`OpenCode is not supported on ${process.platform}-${process.arch}`);
+        const resolved = await fs.realpath(this.executable);
+        const actualHash = await sha256File(resolved);
+        const expectedHash = OPENCODE_RUNTIME_LOCK[platformKey].executableSha256;
+        if (actualHash !== expectedHash) {
+            throw new Error(`OpenCode executable hash mismatch for ${platformKey}`);
+        }
+        await assertCleanManagedOpenCodeHost();
+        await assertNoProjectConfig(this.workspacePath);
+        await Promise.all(this.xdgDirs.map((directory) => fs.ensureDir(directory)));
+        this.resolvedExecutable = resolved;
+        this.preflightDone = true;
+    }
+    buildEnvironment(mcp) {
+        const [data, config, state, cache] = this.xdgDirs;
+        return {
+            ...this.runtimeEnv,
+            XDG_DATA_HOME: data,
+            XDG_CONFIG_HOME: config,
+            XDG_STATE_HOME: state,
+            XDG_CACHE_HOME: cache,
+            ...FIXED_OPENCODE_ENV,
+            OPENCODE_CONFIG_CONTENT: JSON.stringify({
+                share: 'disabled',
+                model: OPENCODE_MODEL,
+                skills: { paths: ['.agents/skills'], urls: [] },
+                mcp,
+            }),
+            OPENCODE_PERMISSION,
+        };
+    }
+    async cleanupState() {
+        await Promise.all(this.xdgDirs.map((directory) => fs.remove(directory)));
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        await this.inFlight?.catch(() => undefined);
+        await this.cleanupState();
+    }
+}
+export class OpenCodeAgent extends BaseAgent {
+    async createSession(runtime, _runCommand, options = {}) {
+        if (!options.opencodeExecutable) {
+            throw new Error('OpenCode requires opencodeExecutable');
+        }
+        return new OpenCodeSession(runtime, options);
+    }
+}

package/dist/agents/registry.js

@@ -2,11 +2,13 @@ import { ClaudeAgent } from './claude.js';
 import { CodexAgent } from './codex.js';
 import { CodexAppServerAgent } from './codex-app-server/agent.js';
 import { CursorAgent } from './cursor.js';
+import { OpenCodeAgent } from './opencode.js';
 /** Registry of available agent implementations. Codex routing is transport-aware. */
 const AGENT_REGISTRY = {
     claude: () => new ClaudeAgent(),
     codex: (transport) => transport === 'exec' ? new CodexAgent() : new CodexAppServerAgent(),
     cursor: () => new CursorAgent(),
+    opencode: () => new OpenCodeAgent(),
 };
 /** Get the list of supported agent names */
 export function getAgentNames() {

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/sdk/agent-resolution.d.ts

@@ -1,4 +1,4 @@
-import type { AgentName, AgentTransport, AgentOptions } from './types.js';
+import type { AgentExecutionTransport, AgentName, AgentTransport, AgentOptions } from './types.js';
 export declare class InvalidTransportEnvError extends Error {
     constructor(value: string);
 }
@@ -10,3 +10,4 @@ export declare function resolveCodexTransport(opts: {
 }, env: {
     PATHGRADE_CODEX_TRANSPORT?: string;
 }): AgentTransport;
+export declare function resolveExecutionTransport(agentName: AgentName, codexTransport?: AgentTransport): AgentExecutionTransport;

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)
@@ -19,3 +24,10 @@ export function resolveCodexTransport(opts, env) {
     }
     return 'app-server';
 }
+export function resolveExecutionTransport(agentName, codexTransport) {
+    if (agentName === 'claude')
+        return 'claude-agent-sdk';
+    if (agentName === 'cursor')
+        return 'cursor-agent';
+    return codexTransport ?? 'app-server';
+}

package/dist/sdk/agent.js

@@ -1,5 +1,5 @@
 import { prepareWorkspace } from '../providers/workspace.js';
-import { resolveAgentName, resolveCodexTransport } from './agent-resolution.js';
+import { resolveAgentName, resolveCodexTransport, resolveExecutionTransport, } from './agent-resolution.js';
 import { lifecycleCore } from './lifecycle.js';
 import { ChatSessionImpl } from './chat.js';
 import { runConversation } from './converse.js';
@@ -14,6 +14,7 @@ import { getCurrentCaseContext } from './case-context.js';
 import { createVerboseEmitter } from '../reporters/verbose-emitter.js';
 import fs from 'fs-extra';
 import * as path from 'path';
+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 +42,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 +58,8 @@ class AgentImpl {
         this.verbose = verbose;
         this.transport = transport;
         this.mcpSafety = mcpSafety;
+        this.opencodeExecutable = opencodeExecutable;
+        this.opencodeMcpToolNames = opencodeMcpToolNames;
     }
     get messages() {
         return this._messages;
@@ -73,7 +79,7 @@ class AgentImpl {
         return {
             name: this.agentName,
             ...(this.modelOpt ? { requestedModel: this.modelOpt } : {}),
-            ...(this.transport ? { transport: this.transport } : {}),
+            transport: resolveExecutionTransport(this.agentName, this.transport),
             ...(interactionMode ? { interactionMode } : {}),
         };
     }
@@ -96,6 +102,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 +203,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,6 +319,8 @@ class AgentImpl {
         // Runner-owned agents stay tracked until flush consumes metadata.
         // Manual agents have no runner flush, so dispose releases them.
         lifecycleCore.releaseAgent(this);
+        await this.activeChatSession?.dispose?.();
+        this.activeChatSession = undefined;
         if (this.debugOpt) {
             const dest = typeof this.debugOpt === 'string'
                 ? this.debugOpt
@@ -354,13 +365,14 @@ function resolveCaseDebugContext() {
 }
 export async function createAgent(opts) {
     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 +390,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, AgentInteractionMode, } from './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 { 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,18 +5,22 @@ 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';
 /** Privacy-safe execution dimensions exposed to result observers. */
 export interface AgentExecutionMetadata {
     name: AgentName;
     /** Model override requested by the caller; not necessarily the provider-resolved model. */
     requestedModel?: string;
-    transport?: AgentTransport;
+    transport?: AgentExecutionTransport;
     interactionMode?: AgentInteractionMode;
 }
 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;
@@ -70,7 +74,7 @@ export interface Agent {
     readonly messages: Message[];
     readonly log: LogEntry[];
     readonly workspace: string;
-    /** Provider/configuration metadata only; never contains prompts or paths. */
+    /** Provider/runtime metadata only; never contains prompts or paths. */
     readonly executionMetadata?: AgentExecutionMetadata;
     dispose(): Promise<void>;
 }

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>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/pathgrade",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "packageManager": "yarn@4.12.0",
   "description": "Evaluate whether AI agents discover and use your skills correctly",
   "exports": {
@@ -76,6 +76,7 @@
     "gemini",
     "claude",
     "codex",
+    "opencode",
     "openai",
     "llm",
     "testing"
@@ -127,5 +128,5 @@
     "typescript": "^5.9.3",
     "zod": "4.3.6"
   },
-  "falconPackageHash": "0d0bd8f233a4d538524961fc02c50f608b46cb42353be3b9ad1c4cde"
+  "falconPackageHash": "6dec3f88035544895dd8e99741e3c9a69e73651415b4999e32ddefd6"
 }