@wix/pathgrade 1.0.10 → 1.0.12

package/README.md

@@ -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. OpenCode requires the exact v1.18.18 macOS ARM64 or Linux ARM64 executable.
+**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 Wix-registry v1.18.14 macOS ARM64 or Linux ARM64 executable.
 
 ```bash
 yarn add -D @wix/pathgrade
@@ -41,8 +41,9 @@ By default, Pathgrade tries to reuse the agent CLI's native auth before falling
   - 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`
+  - defaults to `anthropic/claude-sonnet-5` with an explicit or host `ANTHROPIC_API_KEY` and optional HTTPS `/v1` proxy
+  - supports `model: 'openai/gpt-5.4'` with an explicit or host `OPENAI_API_KEY`
+  - when no OpenAI key or proxy is set, stages the validated OpenAI access record with a disabled refresh sentinel; it never copies the host refresh token or writes credentials back
 
 If you set `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL`, or `CURSOR_API_BASE_URL`, set the matching API key too.
 
@@ -243,15 +244,13 @@ OpenCode v1 is only for fixtures, prompts, skills, and generated MCP mocks contr
 ```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',
-    },
+    opencodeExecutable: '/absolute/path/to/opencode-v1.18.14',
 });
 ```
 
-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.
+The backend supports `anthropic/claude-sonnet-5` (default) and `openai/gpt-5.4`, 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. Selecting GPT-5.4 opts into the ChatGPT Codex endpoint/account plane. A custom `OPENAI_BASE_URL` always requires a matching key and never receives the local OAuth bearer token. Explicit API keys use only an explicitly paired base URL; they never inherit an ambient host proxy.
+
+Pathgrade's default persona, summarization, and plain-judge helpers follow the selected OpenCode provider. GPT-5.4 API-key runs use the OpenAI helper provider and never fall through to Claude CLI. Local OAuth authenticates only the isolated OpenCode process; OAuth-only runs must inject an LLM for helper calls or provide an explicit `OPENAI_API_KEY`. Tool-using judges still require the Anthropic HTTP provider.
 
 ### `agent.prompt()` - One shot
 
@@ -430,8 +429,8 @@ Notes:
 
 | Variable | Purpose |
 |----------|---------|
-| `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` |
+| `ANTHROPIC_API_KEY` | Claude auth; explicit or host API-key auth for OpenCode's default model |
+| `OPENAI_API_KEY` | Codex auth; optional explicit or host API-key auth for OpenCode GPT-5.4, and required with `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 |

package/dist/agents/claude/sdk-message-projector.d.ts

@@ -19,9 +19,12 @@ import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
 import type { AgentTurnResult } from '../../types.js';
 import type { AskUserAnswerStore } from './ask-user-answer-store.js';
 import type { ClaudeDeniedMcpEventStore } from './denied-mcp-event-store.js';
+import { type ClaudeSdkMessageTiming } from './tool-results.js';
 export interface ProjectTurnInput {
     /** Buffered typed-message stream from one `query()` call. */
     messages: SDKMessage[];
+    /** Local receive timing captured while consuming each corresponding SDK message. */
+    messageTimings?: readonly (ClaudeSdkMessageTiming | undefined)[];
     /** Forwarded onto `ToolEvent.turnNumber`; optional for projector unit use. */
     turnNumber?: number;
     /** First user message of the turn — used for slash-command skill detection. */
@@ -39,6 +42,8 @@ export interface ProjectTurnInput {
     mcpServerNames?: readonly string[];
     /** Policy-denied MCP events recorded by the per-turn permission bridge. */
     deniedMcpEvents?: ClaudeDeniedMcpEventStore;
+    /** Exact runtime credential values to redact before tool results become trace data. */
+    sensitiveValues?: readonly string[];
 }
 export interface ProjectedTurn {
     result: AgentTurnResult;

package/dist/agents/claude/sdk-message-projector.js

@@ -23,6 +23,7 @@ const SDK_ERROR_SUBTYPES = [
 ];
 import { TOOL_NAME_MAP, buildSummary, enrichSkillEvents } from '../../tool-events.js';
 import { parseClaudeSdkMcpToolName } from './mcp-tool-name.js';
+import { applyObservedToolResult, extractObservedToolResults, } from './tool-results.js';
 export function projectSdkMessages(input) {
     let sessionId;
     let initSkills;
@@ -37,7 +38,9 @@ export function projectSdkMessages(input) {
     let costUsd;
     let errorSubtype;
     const toolEvents = [];
-    for (const msg of input.messages) {
+    const pendingTools = new Map();
+    for (const [messageIndex, msg] of input.messages.entries()) {
+        const timing = input.messageTimings?.[messageIndex];
         switch (msg.type) {
             case 'system': {
                 const sid = msg.session_id;
@@ -60,13 +63,30 @@ export function projectSdkMessages(input) {
                         continue;
                     }
                     if (block.type === 'tool_use') {
-                        const event = buildToolEvent(block, input.turnNumber, input.answerStore, input.mcpServerNames ?? [], input.deniedMcpEvents);
-                        if (event)
+                        const event = buildToolEvent(block, input.turnNumber, input.answerStore, input.mcpServerNames ?? [], input.deniedMcpEvents, timing);
+                        if (event) {
                             toolEvents.push(event);
+                            if (event.toolUseId) {
+                                pendingTools.set(event.toolUseId, {
+                                    event,
+                                    startedMonotonicMs: timing?.receivedMonotonicMs,
+                                });
+                            }
+                        }
                     }
                 }
                 break;
             }
+            case 'user': {
+                for (const observed of extractObservedToolResults(msg, timing)) {
+                    const pending = pendingTools.get(observed.toolUseId);
+                    if (!pending)
+                        continue;
+                    applyObservedToolResult(pending.event, observed, pending.startedMonotonicMs, input.sensitiveValues);
+                    pendingTools.delete(observed.toolUseId);
+                }
+                break;
+            }
             case 'result': {
                 const r = msg;
                 if (r.session_id)
@@ -167,7 +187,7 @@ function prependSlashCommandSkillEvent(events, firstMessage, initSkills) {
         ...events,
     ];
 }
-function buildToolEvent(block, turnNumber, answerStore, mcpServerNames, deniedMcpEvents) {
+function buildToolEvent(block, turnNumber, answerStore, mcpServerNames, deniedMcpEvents, timing) {
     const providerToolName = String(block.name || 'unknown');
     const rawInput = block.input ?? undefined;
     const toolUseId = typeof block.id === 'string' ? block.id : undefined;
@@ -180,15 +200,18 @@ function buildToolEvent(block, turnNumber, answerStore, mcpServerNames, deniedMc
             ...(rawInput ?? {}),
             server: mcpTool.server,
             tool: mcpTool.tool,
-            status: 'completed',
+            status: 'incomplete',
         };
         return {
             action: 'mcp_tool_call',
             provider: 'claude',
             providerToolName: normalizedProviderToolName,
+            ...(toolUseId ? { toolUseId } : {}),
             turnNumber,
             arguments: args,
-            summary: `MCP tool ${normalizedProviderToolName} completed`,
+            status: 'incomplete',
+            ...(timing ? { startedAt: timing.receivedAt } : {}),
+            summary: `MCP tool ${normalizedProviderToolName}`,
             confidence: 'high',
             rawSnippet: JSON.stringify(block).slice(0, 200),
         };
@@ -203,8 +226,11 @@ function buildToolEvent(block, turnNumber, answerStore, mcpServerNames, deniedMc
         action,
         provider: 'claude',
         providerToolName,
+        ...(toolUseId ? { toolUseId } : {}),
         turnNumber,
         arguments: args,
+        status: 'incomplete',
+        ...(timing ? { startedAt: timing.receivedAt } : {}),
         summary,
         confidence: 'high',
         rawSnippet,

package/dist/agents/claude/tool-results.d.ts

@@ -0,0 +1,19 @@
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { ToolEvent } from '../../tool-events.js';
+export declare const TOOL_RESULT_MAX_CHARS: number;
+export interface ClaudeSdkMessageTiming {
+    receivedAt: string;
+    receivedMonotonicMs: number;
+}
+export interface ObservedToolResult {
+    toolUseId: string;
+    isError: boolean;
+    structuredResult?: Record<string, unknown>;
+    content?: string;
+    completedAt?: string;
+    completedMonotonicMs?: number;
+}
+export declare function hasToolLifecycleBoundary(message: SDKMessage): boolean;
+export declare function extractObservedToolResults(message: SDKMessage, timing?: ClaudeSdkMessageTiming): ObservedToolResult[];
+export declare function applyObservedToolResult(event: ToolEvent, observed: ObservedToolResult, startedMonotonicMs?: number, sensitiveValues?: readonly string[]): void;
+export declare function collectSensitiveEnvValues(env: Readonly<Record<string, string>>): string[];

package/dist/agents/claude/tool-results.js

@@ -0,0 +1,117 @@
+export const TOOL_RESULT_MAX_CHARS = 64 * 1024;
+const SECRET_ENV_KEY_PATTERN = /(^|[_-])(api[_-]?key|token|secret|password|authorization|auth|bearer)([_-]|$)/i;
+export function hasToolLifecycleBoundary(message) {
+    if (message.type !== 'assistant' && message.type !== 'user')
+        return false;
+    const content = message.message?.content;
+    return Array.isArray(content) && content.some((block) => isRecord(block) && (block.type === 'tool_use' || block.type === 'tool_result'));
+}
+export function extractObservedToolResults(message, timing) {
+    if (message.type !== 'user')
+        return [];
+    const user = message;
+    const content = user.message?.content;
+    if (!Array.isArray(content))
+        return [];
+    const blocks = content.filter(isToolResultBlock);
+    const structuredResult = blocks.length === 1 && isRecord(user.tool_use_result)
+        ? user.tool_use_result
+        : undefined;
+    return blocks.flatMap((block) => {
+        if (typeof block.tool_use_id !== 'string')
+            return [];
+        const text = extractTextContent(block.content);
+        return [{
+                toolUseId: block.tool_use_id,
+                isError: block.is_error === true,
+                ...(structuredResult ? { structuredResult } : {}),
+                ...(text === undefined ? {} : { content: text }),
+                ...(timing ? {
+                    completedAt: timing.receivedAt,
+                    completedMonotonicMs: timing.receivedMonotonicMs,
+                } : {}),
+            }];
+    });
+}
+export function applyObservedToolResult(event, observed, startedMonotonicMs, sensitiveValues = []) {
+    const remainsBackgrounded = event.arguments?.run_in_background === true;
+    const result = buildBoundedToolResult(observed, sensitiveValues);
+    const failedExit = result.exitCode !== undefined && result.exitCode !== 0;
+    const failed = observed.isError || failedExit;
+    event.status = failed ? 'error' : (remainsBackgrounded ? 'incomplete' : 'completed');
+    if (!remainsBackgrounded || failed) {
+        if (observed.completedAt)
+            event.completedAt = observed.completedAt;
+        if (startedMonotonicMs !== undefined && observed.completedMonotonicMs !== undefined) {
+            event.durationMs = Math.max(0, observed.completedMonotonicMs - startedMonotonicMs);
+        }
+    }
+    if (Object.keys(result).length > 0)
+        event.result = result;
+    if (event.action === 'mcp_tool_call' && event.arguments) {
+        event.arguments.status = event.status;
+    }
+}
+export function collectSensitiveEnvValues(env) {
+    return [...new Set(Object.entries(env)
+            .filter(([key, value]) => SECRET_ENV_KEY_PATTERN.test(key) && value.length > 0)
+            .map(([, value]) => value))]
+        .sort((a, b) => b.length - a.length);
+}
+function buildBoundedToolResult(observed, sensitiveValues) {
+    const raw = observed.structuredResult;
+    const result = {};
+    let truncated = false;
+    const addBounded = (key, value) => {
+        if (typeof value !== 'string')
+            return;
+        const bounded = boundText(redactSensitiveValues(value, sensitiveValues));
+        result[key] = bounded.value;
+        truncated ||= bounded.truncated;
+    };
+    addBounded('stdout', raw?.stdout);
+    addBounded('stderr', raw?.stderr);
+    if (observed.content !== raw?.stdout)
+        addBounded('content', observed.content);
+    const exitCode = raw?.exitCode ?? raw?.exit_code;
+    if (typeof exitCode === 'number' && Number.isFinite(exitCode))
+        result.exitCode = exitCode;
+    if (truncated)
+        result.truncated = true;
+    return result;
+}
+function redactSensitiveValues(value, sensitiveValues) {
+    let redacted = value;
+    for (const secret of sensitiveValues) {
+        if (secret.length > 0)
+            redacted = redacted.split(secret).join('<redacted>');
+    }
+    return redacted;
+}
+function boundText(value) {
+    if (value.length <= TOOL_RESULT_MAX_CHARS)
+        return { value, truncated: false };
+    const marker = '\n[truncated by PathGrade]';
+    return {
+        value: `${value.slice(0, TOOL_RESULT_MAX_CHARS - marker.length)}${marker}`,
+        truncated: true,
+    };
+}
+function extractTextContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return undefined;
+    const text = content
+        .filter(isRecord)
+        .filter((block) => block.type === 'text' && typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('');
+    return text || undefined;
+}
+function isToolResultBlock(value) {
+    return isRecord(value) && value.type === 'tool_result';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/agents/claude.d.ts

@@ -39,6 +39,10 @@ export interface ClaudeAgentDeps {
     envExecutable?: string;
     /** Optional macOS sandbox-exec profile. None today; preserves the seam. */
     sandboxProfile?: string;
+    /** Local wall-clock seam for deterministic tool lifecycle tests. */
+    now?: () => Date;
+    /** Monotonic clock seam for deterministic tool duration tests. */
+    monotonicNow?: () => number;
 }
 export interface ClaudeAgentOptions {
     /**

package/dist/agents/claude.js

@@ -22,11 +22,13 @@
  *                                   parser wholesale.
  */
 import { query as sdkQuery, } from '@anthropic-ai/claude-agent-sdk';
+import { performance } from 'node:perf_hooks';
 import { BaseAgent, getRuntimeEnv, getWorkspacePath, } from '../types.js';
 import { createSandboxedClaudeSpawn } from '../providers/sandboxed-claude-spawn.js';
 import { assertClaudeLiveMcpSafetyPreflight, assertStdioMcpServersStartForClaudeSdk, mountMcpForClaudeSdk, } from '../providers/mcp-runtime-mounting.js';
 import { buildClaudeSdkOptions, resolveClaudeCodeExecutable, } from './claude/sdk-options.js';
 import { projectSdkMessages } from './claude/sdk-message-projector.js';
+import { collectSensitiveEnvValues, hasToolLifecycleBoundary, } from './claude/tool-results.js';
 import { createAskUserAnswerStore } from './claude/ask-user-answer-store.js';
 import { createClaudeToolPermissionBridge } from './claude/tool-permission-bridge.js';
 import { createClaudeDeniedMcpEventStore } from './claude/denied-mcp-event-store.js';
@@ -63,6 +65,8 @@ export class ClaudeAgent extends BaseAgent {
         const platform = this.deps.platform ?? process.platform;
         const hostEnv = this.deps.hostEnv ?? process.env;
         const envExecutable = this.deps.envExecutable ?? process.env.PATHGRADE_CLAUDE_CODE_EXECUTABLE;
+        const runtimeEnv = getRuntimeEnv(runtime);
+        const sensitiveValues = collectSensitiveEnvValues(runtimeEnv);
         const sandboxedSpawn = createSandboxedClaudeSpawn({
             platform,
             hostEnv,
@@ -75,7 +79,7 @@ export class ClaudeAgent extends BaseAgent {
         const mcpMountOptions = {
             workspacePath,
             mcpConfigPath: sessionOptions?.mcpConfigPath,
-            runtimeEnv: getRuntimeEnv(runtime),
+            runtimeEnv,
         };
         await assertClaudeLiveMcpSafetyPreflight({
             ...mcpMountOptions,
@@ -117,7 +121,7 @@ export class ClaudeAgent extends BaseAgent {
                 workspacePath,
                 spawnClaudeCodeProcess: sandboxedSpawn,
                 canUseTool: bridge,
-                runtimeEnv: getRuntimeEnv(runtime),
+                runtimeEnv,
                 model: sessionOptions?.model,
                 claudeCodeExecutable,
                 resume: priorSessionId,
@@ -125,9 +129,18 @@ export class ClaudeAgent extends BaseAgent {
                 abortController: createLinkedAbortController(getTurnAbortSignal(sessionOptions)),
             });
             const messages = [];
+            const messageTimings = [];
+            const now = this.deps.now ?? (() => new Date());
+            const monotonicNow = this.deps.monotonicNow ?? (() => performance.now());
             const stream = queryFn({ prompt: message, options: sdkOptions });
             for await (const msg of stream) {
                 messages.push(msg);
+                messageTimings.push(hasToolLifecycleBoundary(msg)
+                    ? {
+                        receivedAt: now().toISOString(),
+                        receivedMonotonicMs: monotonicNow(),
+                    }
+                    : undefined);
             }
             // The legacy NDJSON parser only synthesized the slash-command
             // `use_skill` event from the *opening* user message. The Claude
@@ -140,11 +153,13 @@ export class ClaudeAgent extends BaseAgent {
             const projectorFirstMessage = turnNumber === 1 ? message : undefined;
             const projected = projectSdkMessages({
                 messages,
+                messageTimings,
                 turnNumber,
                 firstMessage: projectorFirstMessage,
                 answerStore,
                 mcpServerNames: mcpServers ? Object.keys(mcpServers) : [],
                 deniedMcpEvents,
+                sensitiveValues,
             });
             // Capture the SDK-reported session id BEFORE checking for a bus
             // rejection so the next turn's `Options.resume` points at this

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

@@ -1,24 +1,60 @@
 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 declare const OPENCODE_VERSION = "1.18.14";
+export declare const DEFAULT_OPENCODE_MODEL = "anthropic/claude-sonnet-5";
+export interface OpenCodeModelContract {
+    provider: 'anthropic' | 'openai';
+    apiKeyEnv: 'ANTHROPIC_API_KEY' | 'OPENAI_API_KEY';
+    baseUrlEnv: 'ANTHROPIC_BASE_URL' | 'OPENAI_BASE_URL';
+    allowsLocalOAuth: boolean;
+}
+export declare const OPENCODE_MODELS: {
+    readonly 'anthropic/claude-sonnet-5': {
+        readonly provider: "anthropic";
+        readonly apiKeyEnv: "ANTHROPIC_API_KEY";
+        readonly baseUrlEnv: "ANTHROPIC_BASE_URL";
+        readonly allowsLocalOAuth: false;
+    };
+    readonly 'openai/gpt-5.4': {
+        readonly provider: "openai";
+        readonly apiKeyEnv: "OPENAI_API_KEY";
+        readonly baseUrlEnv: "OPENAI_BASE_URL";
+        readonly allowsLocalOAuth: true;
+    };
+};
+export type OpenCodeModel = keyof typeof OPENCODE_MODELS;
+export declare const OPENCODE_DISABLED_REFRESH_TOKEN = "pathgrade-refresh-disabled";
+export interface OpenCodeOAuthRecord {
+    type: 'oauth';
+    access: string;
+    refresh: string;
+    expires: number;
+    accountId?: string;
+    enterpriseUrl?: string;
+}
+export declare function sanitizeOpenCodeOAuthRecord(value: unknown): OpenCodeOAuthRecord | undefined;
+export declare function resolveOpenCodeModel(model?: string): {
+    model: OpenCodeModel;
+    contract: OpenCodeModelContract;
+};
 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 version: "1.18.14";
+        readonly executableSha256: "8b7c4e116c1ac5163c02fa85eee5a13d4d00c8a08e677dac4100f55aa56532fa";
     };
     readonly 'linux-arm64': {
-        readonly version: "1.18.18";
-        readonly executableSha256: "a63ef0c7271383e48ffe36c156b4146087bbbc97929dec40e8be95ed4f4d76ae";
+        readonly version: "1.18.14";
+        readonly executableSha256: "79d42436517e485e9444cfc6e92582bf9224a9e36fa77fb3957b343486fec81d";
     };
 };
 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 validateOpenCodeBaseUrl(value: string, variable?: string): void;
 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

@@ -1,14 +1,54 @@
 import * as path from 'node:path';
-export const OPENCODE_MODEL = 'anthropic/claude-sonnet-5';
-export const OPENCODE_VERSION = '1.18.18';
+export const OPENCODE_VERSION = '1.18.14';
+export const DEFAULT_OPENCODE_MODEL = 'anthropic/claude-sonnet-5';
+export const OPENCODE_MODELS = {
+    'anthropic/claude-sonnet-5': {
+        provider: 'anthropic', apiKeyEnv: 'ANTHROPIC_API_KEY',
+        baseUrlEnv: 'ANTHROPIC_BASE_URL', allowsLocalOAuth: false,
+    },
+    'openai/gpt-5.4': {
+        provider: 'openai', apiKeyEnv: 'OPENAI_API_KEY',
+        baseUrlEnv: 'OPENAI_BASE_URL', allowsLocalOAuth: true,
+    },
+};
+export const OPENCODE_DISABLED_REFRESH_TOKEN = 'pathgrade-refresh-disabled';
+export function sanitizeOpenCodeOAuthRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (record.type !== 'oauth'
+        || typeof record.access !== 'string' || !record.access.trim()
+        || typeof record.refresh !== 'string' || !record.refresh.trim()
+        || typeof record.expires !== 'number' || !Number.isSafeInteger(record.expires) || record.expires < 0
+        || (record.accountId !== undefined && typeof record.accountId !== 'string')
+        || (record.enterpriseUrl !== undefined && typeof record.enterpriseUrl !== 'string')) {
+        return undefined;
+    }
+    return {
+        type: 'oauth',
+        access: record.access,
+        refresh: record.refresh,
+        expires: record.expires,
+        ...(record.accountId !== undefined ? { accountId: record.accountId } : {}),
+        ...(record.enterpriseUrl !== undefined ? { enterpriseUrl: record.enterpriseUrl } : {}),
+    };
+}
+export function resolveOpenCodeModel(model) {
+    const selected = model ?? DEFAULT_OPENCODE_MODEL;
+    if (!hasOwn(OPENCODE_MODELS, selected)) {
+        throw new Error(`OpenCode supports only models ${Object.keys(OPENCODE_MODELS).join(' and ')}`);
+    }
+    const normalized = selected;
+    return { model: normalized, contract: OPENCODE_MODELS[normalized] };
+}
 export const OPENCODE_RUNTIME_LOCK = {
     'darwin-arm64': {
         version: OPENCODE_VERSION,
-        executableSha256: '4f5979c2dadb06fbff1335335afaaea274e58f92e79aa43cf2ed98618d555422',
+        executableSha256: '8b7c4e116c1ac5163c02fa85eee5a13d4d00c8a08e677dac4100f55aa56532fa',
     },
     'linux-arm64': {
         version: OPENCODE_VERSION,
-        executableSha256: 'a63ef0c7271383e48ffe36c156b4146087bbbc97929dec40e8be95ed4f4d76ae',
+        executableSha256: '79d42436517e485e9444cfc6e92582bf9224a9e36fa77fb3957b343486fec81d',
     },
 };
 export function getOpenCodePlatformKey(platform, arch) {
@@ -21,16 +61,17 @@ export function currentOpenCodePlatformKey() {
 function hasOwn(record, key) {
     return Object.prototype.hasOwnProperty.call(record, key);
 }
-function assertOpenCodeBaseUrl(value) {
+export function validateOpenCodeBaseUrl(value, variable = 'ANTHROPIC_BASE_URL') {
+    const error = `OpenCode ${variable} must be an absolute HTTPS API root ending in /v1`;
     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');
+        throw new Error(error);
     }
     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');
+        throw new Error(error);
     }
 }
 export function validateOpenCodeDeclaration(agent, opts) {
@@ -46,18 +87,20 @@ export function validateOpenCodeDeclaration(agent, opts) {
     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 { contract } = resolveOpenCodeModel(opts.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, contract.apiKeyEnv) && !env[contract.apiKeyEnv]?.trim()) {
+        throw new Error(`OpenCode env.${contract.apiKeyEnv} must be nonempty when provided`);
     }
-    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');
+    if (hasOwn(env, contract.baseUrlEnv)) {
+        if (!env[contract.baseUrlEnv]) {
+            throw new Error(`OpenCode ${contract.baseUrlEnv} must be a nonempty absolute HTTPS API root ending in /v1`);
+        }
+        validateOpenCodeBaseUrl(env[contract.baseUrlEnv], contract.baseUrlEnv);
+        if (!hasOwn(env, contract.apiKeyEnv)) {
+            throw new Error(`OpenCode env.${contract.baseUrlEnv} requires an explicit env.${contract.apiKeyEnv}; ` +
+                'host credentials are never sent to caller-provided endpoints.');
         }
-        assertOpenCodeBaseUrl(env.ANTHROPIC_BASE_URL);
     }
     if (opts.copyFromHome !== undefined)
         throw new Error('OpenCode does not support copyFromHome');

package/dist/agents/opencode/runtime-policy.d.ts

@@ -0,0 +1,18 @@
+import { type OpenCodeModel } from './contract.js';
+export declare const OPENCODE_PERMISSION: string;
+export declare class OpenCodeRuntimePolicy {
+    readonly model: OpenCodeModel;
+    readonly oauth: boolean;
+    private readonly authPath;
+    private readonly expectedAuthDigest;
+    private readonly expectedAuthFingerprint;
+    private authWatcher;
+    private authMutationObserved;
+    private constructor();
+    static create(runtimeEnv: Record<string, string>, requestedModel?: string): Promise<OpenCodeRuntimePolicy>;
+    environment(): Record<string, string>;
+    beforeTurn(remainingMs: number, now?: number): Promise<void>;
+    afterTurn(): Promise<void>;
+    private startAuthMonitor;
+    private readUnchanged;
+}