@wix/pathgrade 0.29.0

package/dist/agents/codex-app-server/agent.js

@@ -0,0 +1,388 @@
+import { BaseAgent, getRuntimeEnv, getWorkspacePath, } from '../../types.js';
+import { requireAskBusForLiveBatches, } from '../../sdk/ask-bus/bus.js';
+import { toAskUserToolEvent } from '../../sdk/ask-bus/projection.js';
+import { spawnAppServerTransport, } from './transport.js';
+import { normalizeUpstreamQuestion, toWireAnswerMap, } from './wire-translators.js';
+const DEFAULT_MODEL = 'gpt-5.3-codex';
+const TURN_COMPLETED_METHOD = 'turn/completed';
+function projectItemIntoTurn(item, turn) {
+    if (item.type === 'agentMessage') {
+        const msg = item;
+        if (msg.text) {
+            turn.assistantMessageParts.push(msg.text);
+        }
+        return;
+    }
+    if (item.type === 'commandExecution') {
+        const cmd = item;
+        turn.nonAskToolEvents.push({
+            action: 'run_shell',
+            provider: 'codex',
+            providerToolName: 'commandExecution',
+            turnNumber: turn.turnNumber,
+            arguments: { command: cmd.command },
+            summary: `run_shell: ${cmd.command}`,
+            confidence: 'high',
+            rawSnippet: JSON.stringify(cmd),
+        });
+        return;
+    }
+    if (item.type === 'fileChange') {
+        const fc = item;
+        for (const change of fc.changes ?? []) {
+            turn.nonAskToolEvents.push({
+                action: 'edit_file',
+                provider: 'codex',
+                providerToolName: 'fileChange',
+                turnNumber: turn.turnNumber,
+                arguments: { file_path: change.path },
+                summary: `edit_file: ${change.path}`,
+                confidence: 'high',
+                rawSnippet: JSON.stringify(change),
+            });
+        }
+        return;
+    }
+}
+export class CodexAppServerAgent extends BaseAgent {
+    deps;
+    constructor(deps = {}) {
+        super();
+        this.deps = deps;
+    }
+    async createSession(runtime, _runCommand, options) {
+        const askBus = requireAskBusForLiveBatches(options, 'CodexAppServerAgent');
+        const workspacePath = getWorkspacePath(runtime);
+        const runtimeEnv = getRuntimeEnv(runtime);
+        const model = options?.model ?? DEFAULT_MODEL;
+        const sandboxMode = this.deps.sandboxMode ?? 'workspace-write';
+        let handle = null;
+        let threadId = null;
+        let turnCounter = 0;
+        let closeInfo = null;
+        let activeTurn = null;
+        let disposed = false;
+        const ensureTransport = async () => {
+            if (disposed)
+                throw new Error('CodexAppServerAgent session disposed');
+            if (handle)
+                return handle.transport;
+            const factory = this.deps.createTransport
+                ?? (async (ctx) => spawnAppServerTransport({ cwd: ctx.workspacePath, env: ctx.env }));
+            handle = await factory({ workspacePath, env: runtimeEnv });
+            const transport = handle.transport;
+            transport.onServerRequest((req) => this.dispatchServerRequest(req, {
+                transport,
+                askBus,
+                activeTurn: () => activeTurn,
+                onPermissionGrant: this.deps.onPermissionGrant,
+            }));
+            transport.onClose((info) => {
+                closeInfo = info;
+            });
+            transport.onNotification((n) => {
+                if (process.env.PATHGRADE_CODEX_DEBUG) {
+                    console.error(`[codex app-server] notification method=${n.method} params=${JSON.stringify(n.params).slice(0, 300)}`);
+                }
+                if (n.method !== 'item/completed')
+                    return;
+                const turn = activeTurn;
+                if (!turn)
+                    return;
+                const params = n.params;
+                if (!params?.item)
+                    return;
+                projectItemIntoTurn(params.item, turn);
+            });
+            await transport.sendRequest('initialize', {
+                clientInfo: { name: 'pathgrade', version: '0.5.0', title: null },
+                capabilities: { experimentalApi: true, optOutNotificationMethods: null },
+            });
+            // Upstream ClientNotification = { method: "initialized" }: send it
+            // before any thread/start so the handshake matches the v0.124
+            // contract and is forward-compatible with servers that enforce it.
+            transport.sendNotification('initialized', null);
+            return transport;
+        };
+        const runTurn = async (message) => {
+            const t = await ensureTransport();
+            turnCounter += 1;
+            const turn = {
+                turnNumber: turnCounter,
+                askBatchIds: [],
+                nonAskToolEvents: [],
+                assistantMessageParts: [],
+                turnFailed: false,
+            };
+            activeTurn = turn;
+            try {
+                if (threadId === null) {
+                    const resp = await t.sendRequest('thread/start', buildThreadStartParams({ cwd: workspacePath, model, sandboxMode }));
+                    threadId = resp.thread.id;
+                }
+                // Wait for TurnCompleted OR subprocess crash OR dispatcher failure.
+                const turnCompletion = new Promise((resolve, reject) => {
+                    let settled = false;
+                    const off = t.onNotification((n) => {
+                        if (settled)
+                            return;
+                        if (n.method === TURN_COMPLETED_METHOD) {
+                            settled = true;
+                            off();
+                            closeOff();
+                            resolve();
+                        }
+                    });
+                    const closeOff = t.onClose((info) => {
+                        if (settled)
+                            return;
+                        settled = true;
+                        off();
+                        closeOff();
+                        reject(Object.assign(new Error('app-server exited'), {
+                            exitCode: info.exitCode ?? 1,
+                            signal: info.signal,
+                            pid: info.pid,
+                        }));
+                    });
+                    turn.signalFailure = (msg) => {
+                        if (settled)
+                            return;
+                        settled = true;
+                        off();
+                        closeOff();
+                        turn.turnFailed = true;
+                        turn.failureMessage = msg;
+                        resolve();
+                    };
+                    // If already closed, settle immediately.
+                    if (closeInfo) {
+                        if (!settled) {
+                            settled = true;
+                            off();
+                            closeOff();
+                            reject(Object.assign(new Error('app-server exited'), {
+                                exitCode: closeInfo.exitCode ?? 1,
+                            }));
+                        }
+                    }
+                });
+                const startTurnResp = t
+                    .sendRequest('turn/start', {
+                    threadId,
+                    input: [{ type: 'text', text: message, text_elements: [] }],
+                })
+                    .catch((err) => {
+                    // A JSON-RPC error on turn/start means the server will
+                    // never send turn/completed — short-circuit the turn
+                    // through the existing signalFailure path instead of
+                    // waiting for an outer timeout.
+                    const msg = err instanceof Error
+                        ? err.message
+                        : typeof err === 'string'
+                            ? err
+                            : 'turn/start failed';
+                    turn.signalFailure?.(msg);
+                });
+                try {
+                    await turnCompletion;
+                }
+                catch (err) {
+                    const info = err;
+                    return assembleTurnResult({
+                        askBus,
+                        activeTurn: turn,
+                        exitCode: info.exitCode ?? 1,
+                        message: info.message ?? 'app-server exited',
+                        pid: info.pid,
+                        signal: info.signal,
+                    });
+                }
+                void startTurnResp;
+                if (turn.turnFailed) {
+                    return assembleTurnResult({
+                        askBus,
+                        activeTurn: turn,
+                        exitCode: 1,
+                        message: turn.failureMessage ?? 'turn failed',
+                    });
+                }
+                return assembleTurnResult({
+                    askBus,
+                    activeTurn: turn,
+                    exitCode: 0,
+                    message: turn.assistantMessageParts.join('\n\n'),
+                });
+            }
+            finally {
+                activeTurn = null;
+            }
+        };
+        const dispose = async () => {
+            if (disposed)
+                return;
+            disposed = true;
+            const turn = activeTurn;
+            if (turn) {
+                turn.signalFailure?.('session disposed');
+            }
+            activeTurn = null;
+            if (handle) {
+                try {
+                    await handle.close();
+                }
+                catch (err) {
+                    console.warn(`CodexAppServerAgent: handle.close() threw during dispose: ${String(err)}`);
+                }
+            }
+        };
+        const guardDisposed = () => {
+            if (disposed) {
+                throw new Error('CodexAppServerAgent session disposed');
+            }
+        };
+        return {
+            start: async ({ message }) => {
+                guardDisposed();
+                return runTurn(message);
+            },
+            reply: async ({ message }) => {
+                guardDisposed();
+                return runTurn(message);
+            },
+            dispose,
+        };
+    }
+    dispatchServerRequest(req, ctx) {
+        const { transport, askBus, activeTurn, onPermissionGrant } = ctx;
+        switch (req.method) {
+            case 'item/tool/requestUserInput':
+                void handleRequestUserInput(req, { transport, askBus, activeTurn });
+                return;
+            case 'item/permissions/requestApproval': {
+                const params = (req.params ?? {});
+                transport.sendResponse(req.id, {
+                    permissions: params.permissions ?? {},
+                    scope: 'turn',
+                    strictAutoReview: false,
+                });
+                const turn = activeTurn();
+                if (onPermissionGrant) {
+                    onPermissionGrant({
+                        type: 'permissions_granted',
+                        turnNumber: turn?.turnNumber ?? 0,
+                        requested: params.permissions ?? {},
+                        scope: 'turn',
+                        strictAutoReview: false,
+                    });
+                }
+                return;
+            }
+            case 'item/commandExecution/requestApproval':
+            case 'item/fileChange/requestApproval':
+            case 'applyPatchApproval':
+            case 'execCommandApproval':
+                transport.sendResponse(req.id, { decision: 'approved', scope: 'turn' });
+                return;
+            case 'item/tool/call':
+                transport.sendResponse(req.id, { status: 'declined' });
+                return;
+            case 'mcpServer/elicitation/request':
+                transport.sendResponse(req.id, { action: 'decline' });
+                return;
+            case 'account/chatgptAuthTokens/refresh': {
+                const message = 'codex app-server requires OPENAI_API_KEY for pathgrade and honors OPENAI_BASE_URL when set; ChatGPT/cached auth unsupported under transport=app-server';
+                transport.sendErrorResponse(req.id, -32001, message);
+                const turn = activeTurn();
+                if (turn) {
+                    turn.turnFailed = true;
+                    turn.failureMessage = message;
+                    turn.signalFailure?.(message);
+                }
+                return;
+            }
+            default:
+                transport.sendErrorResponse(req.id, -32601, `pathgrade: unknown server-request method '${req.method}'`);
+                console.warn(`CodexAppServerAgent: unknown server-request method '${req.method}' rejected`);
+                return;
+        }
+    }
+}
+async function handleRequestUserInput(req, ctx) {
+    const { transport, askBus, activeTurn } = ctx;
+    const params = req.params;
+    const turn = activeTurn();
+    const turnNumber = turn?.turnNumber ?? 0;
+    const questions = params.questions.map(normalizeUpstreamQuestion);
+    const handle = askBus.emit({
+        batchId: params.itemId,
+        turnNumber,
+        source: 'codex-app-server',
+        lifecycle: 'live',
+        sourceTool: 'request_user_input',
+        toolUseId: params.itemId,
+        questions,
+    });
+    if (turn)
+        turn.askBatchIds.push(params.itemId);
+    let resolution;
+    try {
+        resolution = await handle.resolution;
+    }
+    catch (err) {
+        console.warn(`CodexAppServerAgent: ask_user batch ${params.itemId} failed to resolve: ${String(err)}`);
+        transport.sendResponse(req.id, { answers: toWireAnswerMap(null, params.questions) });
+        return;
+    }
+    transport.sendResponse(req.id, {
+        answers: toWireAnswerMap(resolution, params.questions),
+    });
+}
+function buildThreadStartParams(opts) {
+    return {
+        cwd: opts.cwd,
+        approvalPolicy: 'never',
+        sandbox: opts.sandboxMode,
+        ephemeral: true,
+        experimentalRawEvents: false,
+        persistExtendedHistory: false,
+        model: opts.model,
+    };
+}
+function assembleTurnResult(args) {
+    const { askBus, activeTurn, exitCode, message, pid, signal } = args;
+    const askBatchIds = new Set(activeTurn.askBatchIds);
+    const askEvents = askBus
+        .snapshot()
+        .filter((s) => askBatchIds.has(s.batchId))
+        .map((s) => toAskUserToolEvent(s));
+    const toolEvents = [...askEvents, ...activeTurn.nonAskToolEvents];
+    const rawOutput = exitCode === 0
+        ? message
+        : [
+            message,
+            pid !== undefined ? `pid=${pid}` : '',
+            signal ? `signal=${signal}` : '',
+            `exitCode=${exitCode}`,
+        ]
+            .filter(Boolean)
+            .join(' ');
+    return {
+        rawOutput,
+        assistantMessage: exitCode === 0 ? message : '',
+        visibleAssistantMessage: exitCode === 0 ? message : '',
+        visibleAssistantMessageSource: 'assistant_message',
+        exitCode,
+        traceOutput: rawOutput,
+        toolEvents,
+        ...(exitCode !== 0
+            ? {
+                crashInfo: {
+                    ...(pid !== undefined ? { pid } : {}),
+                    ...(signal !== undefined ? { signal } : {}),
+                    exitCode,
+                },
+            }
+            : {}),
+    };
+}

package/dist/agents/codex-app-server/fixtures/app-server-client.d.ts

@@ -0,0 +1,19 @@
+import { ChildProcessWithoutNullStreams } from 'child_process';
+export declare function spawnCodexAppServer(binaryPath?: string, extraArgs?: string[]): Promise<ChildProcessWithoutNullStreams>;
+/**
+ * Minimal JSON-RPC 2.0 client over a line-delimited stdio child process.
+ * Drift detector only — not the production driver. Slice #6 ships the driver
+ * that reuses this helper's transport contract.
+ */
+export declare class AppServerClient {
+    private nextId;
+    private pending;
+    private readonly proc;
+    private readonly rl;
+    private closed;
+    constructor(proc: ChildProcessWithoutNullStreams);
+    private handleLine;
+    request(method: string, params: unknown, timeoutMs?: number): Promise<unknown>;
+    notify(method: string, params: unknown): void;
+    close(): Promise<void>;
+}

package/dist/agents/codex-app-server/fixtures/app-server-client.js

@@ -0,0 +1,104 @@
+import { spawn } from 'child_process';
+import { createInterface } from 'readline';
+export async function spawnCodexAppServer(binaryPath = 'codex', extraArgs = []) {
+    const proc = spawn(binaryPath, ['app-server', ...extraArgs], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: process.env,
+    });
+    // Surface spawn errors synchronously.
+    return new Promise((resolve, reject) => {
+        const onErr = (err) => reject(err);
+        proc.once('error', onErr);
+        // Give it a microtask to attach before returning.
+        setImmediate(() => {
+            proc.off('error', onErr);
+            resolve(proc);
+        });
+    });
+}
+/**
+ * Minimal JSON-RPC 2.0 client over a line-delimited stdio child process.
+ * Drift detector only — not the production driver. Slice #6 ships the driver
+ * that reuses this helper's transport contract.
+ */
+export class AppServerClient {
+    nextId = 1;
+    pending = new Map();
+    proc;
+    rl;
+    closed = false;
+    constructor(proc) {
+        this.proc = proc;
+        this.rl = createInterface({ input: proc.stdout });
+        this.rl.on('line', (line) => this.handleLine(line));
+        this.proc.stderr.on('data', () => {
+            // Surface stderr to help diagnose drift failures in CI.
+        });
+    }
+    handleLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            return;
+        }
+        if (typeof parsed.id === 'number') {
+            const resolver = this.pending.get(parsed.id);
+            if (resolver) {
+                this.pending.delete(parsed.id);
+                resolver(parsed);
+            }
+        }
+    }
+    request(method, params, timeoutMs = 10_000) {
+        if (this.closed)
+            throw new Error('AppServerClient closed');
+        const id = this.nextId++;
+        const payload = JSON.stringify({ jsonrpc: '2.0', id, method, params });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`codex app-server request '${method}' timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(id, (response) => {
+                clearTimeout(timer);
+                if (response.error) {
+                    reject(new Error(`codex app-server '${method}' returned error ${response.error.code}: ${response.error.message}`));
+                    return;
+                }
+                resolve(response.result);
+            });
+            this.proc.stdin.write(`${payload}\n`);
+        });
+    }
+    notify(method, params) {
+        const payload = JSON.stringify({ jsonrpc: '2.0', method, params });
+        this.proc.stdin.write(`${payload}\n`);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.rl.close();
+        try {
+            this.proc.stdin.end();
+        }
+        catch {
+            // ignore
+        }
+        const exitPromise = new Promise((resolve) => {
+            this.proc.once('exit', () => resolve());
+        });
+        // Give the process a moment to exit gracefully before killing.
+        const killTimer = setTimeout(() => {
+            if (!this.proc.killed)
+                this.proc.kill('SIGTERM');
+        }, 2_000);
+        await exitPromise;
+        clearTimeout(killTimer);
+    }
+}

package/dist/agents/codex-app-server/fixtures/run-gate.d.ts

@@ -0,0 +1,25 @@
+export interface ProtocolFixtureRunInputs {
+    env: Record<string, string | undefined>;
+    codexOnPath: boolean;
+}
+export interface ProtocolFixtureRunDecision {
+    shouldRun: boolean;
+    skipReason?: string;
+}
+/**
+ * Decide whether the protocol fixture suite should run given the environment.
+ * Pure function for easy unit testing; probes live in
+ * {@link probeProtocolFixturePreconditions}. The driver only uses the
+ * PATH-installed `codex` binary, so the gate no longer checks for the npm
+ * package (it is not a dependency post-v0.124 hardening).
+ */
+export declare function decideProtocolFixtureRun(inputs: ProtocolFixtureRunInputs): ProtocolFixtureRunDecision;
+/**
+ * Wrap a skip reason in a human-readable message that vitest will print when
+ * the suite is skipped. Callers pass this to `describe.skip()` or equivalent.
+ */
+export declare function protocolFixtureSkipMessage(reason: string): string;
+/**
+ * Live prerequisite probes. Result is consumed by `decideProtocolFixtureRun`.
+ */
+export declare function probeProtocolFixturePreconditions(): ProtocolFixtureRunInputs;

package/dist/agents/codex-app-server/fixtures/run-gate.js

@@ -0,0 +1,48 @@
+import { execSync } from 'child_process';
+/**
+ * Decide whether the protocol fixture suite should run given the environment.
+ * Pure function for easy unit testing; probes live in
+ * {@link probeProtocolFixturePreconditions}. The driver only uses the
+ * PATH-installed `codex` binary, so the gate no longer checks for the npm
+ * package (it is not a dependency post-v0.124 hardening).
+ */
+export function decideProtocolFixtureRun(inputs) {
+    if (inputs.env.PATHGRADE_RUN_PROTOCOL_FIXTURES !== '1') {
+        return {
+            shouldRun: false,
+            skipReason: 'PATHGRADE_RUN_PROTOCOL_FIXTURES is not set to "1"; local `npm test` stays fast',
+        };
+    }
+    if (!inputs.codexOnPath) {
+        return {
+            shouldRun: false,
+            skipReason: 'codex binary not found on PATH',
+        };
+    }
+    return { shouldRun: true };
+}
+/**
+ * Wrap a skip reason in a human-readable message that vitest will print when
+ * the suite is skipped. Callers pass this to `describe.skip()` or equivalent.
+ */
+export function protocolFixtureSkipMessage(reason) {
+    return `codex app-server protocol fixture suite skipped: ${reason}`;
+}
+/**
+ * Live prerequisite probes. Result is consumed by `decideProtocolFixtureRun`.
+ */
+export function probeProtocolFixturePreconditions() {
+    const codexOnPath = (() => {
+        try {
+            execSync('command -v codex', { stdio: 'ignore' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    })();
+    return {
+        env: process.env,
+        codexOnPath,
+    };
+}

package/dist/agents/codex-app-server/protocol/ClientRequest.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The 8 client-request methods the pathgrade driver may send to the Codex
+ * app-server. Scoped to this driver's surface rather than the full upstream
+ * protocol; phantom response-shaped entries are deliberately excluded because
+ * JSON-RPC responses to server-initiated requests flow through
+ * `transport.sendResponse(req.id, …)`, not through this union.
+ *
+ * - initialize
+ * - thread/start
+ * - turn/start
+ * - turn/interrupt
+ * - thread/inject_items
+ * - thread/read
+ * - thread/list
+ * - review/start
+ */
+export type ClientRequestMethod = 'initialize' | 'thread/start' | 'turn/start' | 'turn/interrupt' | 'thread/inject_items' | 'thread/read' | 'thread/list' | 'review/start';
+/**
+ * JSON-RPC 2.0 client→server request envelope the driver constructs.
+ * Generic over the params type for the chosen method.
+ */
+export interface ClientRequest<TParams> {
+    jsonrpc: '2.0';
+    id: number | string;
+    method: ClientRequestMethod;
+    params: TParams;
+}

package/dist/agents/codex-app-server/protocol/ClientRequest.js

@@ -0,0 +1,7 @@
+// Pathgrade-local composition; not a single upstream file.
+// Upstream ships the discriminated union at
+// `codex-rs/app-server-protocol/schema/typescript/ClientRequest.ts`
+// (top-level, NOT `typescript/v2/`). This module enumerates the subset of
+// method names the pathgrade Codex app-server driver actually sends. Refresh
+// from openai/codex@rust-v0.124.0 when bumping the vendored version.
+export {};

package/dist/agents/codex-app-server/protocol/DynamicToolCallParams.d.ts

@@ -0,0 +1,9 @@
+export type JsonValue = unknown;
+export type DynamicToolCallParams = {
+    threadId: string;
+    turnId: string;
+    callId: string;
+    namespace: string | null;
+    tool: string;
+    arguments: JsonValue;
+};

package/dist/agents/codex-app-server/protocol/DynamicToolCallParams.js

@@ -0,0 +1,4 @@
+// Vendored from openai/codex@rust-v0.124.0
+// Source: codex-rs/app-server-protocol/schema/typescript/v2/DynamicToolCallParams.ts
+// GENERATED CODE in upstream; do not modify locally either.
+export {};

package/dist/agents/codex-app-server/protocol/GrantedPermissionProfile.d.ts

@@ -0,0 +1,6 @@
+export type AdditionalFileSystemPermissions = unknown;
+export type AdditionalNetworkPermissions = unknown;
+export type GrantedPermissionProfile = {
+    network?: AdditionalNetworkPermissions;
+    fileSystem?: AdditionalFileSystemPermissions;
+};

package/dist/agents/codex-app-server/protocol/GrantedPermissionProfile.js

@@ -0,0 +1,7 @@
+// Vendored from openai/codex@rust-v0.124.0
+// Source: codex-rs/app-server-protocol/schema/typescript/v2/GrantedPermissionProfile.ts
+// GENERATED CODE in upstream; do not modify locally either.
+//
+// `AdditionalFileSystemPermissions` and `AdditionalNetworkPermissions` are modelled as
+// opaque aliases until the driver needs to destructure them.
+export {};

package/dist/agents/codex-app-server/protocol/McpElicitationRequestParams.d.ts

@@ -0,0 +1,23 @@
+export type JsonValue = unknown;
+export type McpElicitationSchema = unknown;
+export type McpElicitationRequestParams = {
+    threadId: string;
+    /**
+     * Active Codex turn when this elicitation was observed, if app-server could
+     * correlate one. Nullable because MCP models elicitation as a standalone
+     * server-to-client request identified by the MCP server request id.
+     */
+    turnId: string | null;
+    serverName: string;
+} & ({
+    mode: 'form';
+    _meta: JsonValue | null;
+    message: string;
+    requestedSchema: McpElicitationSchema;
+} | {
+    mode: 'url';
+    _meta: JsonValue | null;
+    message: string;
+    url: string;
+    elicitationId: string;
+});