@wix/pathgrade 0.29.0

package/dist/agents/codex-app-server/wire-translators.d.ts

@@ -0,0 +1,19 @@
+import type { AskQuestion, AskResolution } from '../../sdk/ask-bus/types.js';
+import type { ToolRequestUserInputQuestion, ToolRequestUserInputResponse } from './protocol/index.js';
+/**
+ * Upstream `request_user_input` → bus-facing `AskQuestion`.
+ * - `header` preserves empty strings (never coerced to undefined).
+ * - `options: null` stays null; otherwise maps label+description verbatim
+ *   (empty-string description preserved).
+ * - Strips any fields not in `AskQuestion`; no raw passthrough.
+ */
+export declare function normalizeUpstreamQuestion(q: ToolRequestUserInputQuestion): AskQuestion;
+/**
+ * Bus-side `AskResolution` → upstream `UserInputAnswer` wire map.
+ * - Missing entries emit `{answers: []}` and warn (upstream stalls on
+ *   missing keys per protocol).
+ * - `null` resolution (contract violation) yields an empty map for every
+ *   question and warns. Driver's outer path should already have errored.
+ * - `isSecret` values pass through raw — redaction is the bus snapshot's job.
+ */
+export declare function toWireAnswerMap(resolution: AskResolution | null, upstreamQuestions: readonly ToolRequestUserInputQuestion[]): ToolRequestUserInputResponse['answers'];

package/dist/agents/codex-app-server/wire-translators.js

@@ -0,0 +1,52 @@
+/**
+ * Upstream `request_user_input` → bus-facing `AskQuestion`.
+ * - `header` preserves empty strings (never coerced to undefined).
+ * - `options: null` stays null; otherwise maps label+description verbatim
+ *   (empty-string description preserved).
+ * - Strips any fields not in `AskQuestion`; no raw passthrough.
+ */
+export function normalizeUpstreamQuestion(q) {
+    return {
+        id: q.id,
+        header: q.header,
+        question: q.question,
+        isOther: q.isOther,
+        isSecret: q.isSecret,
+        options: q.options === null
+            ? null
+            : q.options.map((o) => ({ label: o.label, description: o.description })),
+    };
+}
+/**
+ * Bus-side `AskResolution` → upstream `UserInputAnswer` wire map.
+ * - Missing entries emit `{answers: []}` and warn (upstream stalls on
+ *   missing keys per protocol).
+ * - `null` resolution (contract violation) yields an empty map for every
+ *   question and warns. Driver's outer path should already have errored.
+ * - `isSecret` values pass through raw — redaction is the bus snapshot's job.
+ */
+export function toWireAnswerMap(resolution, upstreamQuestions) {
+    const out = {};
+    if (resolution === null) {
+        console.warn(`toWireAnswerMap: received null resolution — filling empty answers for ${upstreamQuestions.length} question(s)`);
+        for (const q of upstreamQuestions) {
+            out[q.id] = { answers: [] };
+        }
+        return out;
+    }
+    const byId = new Map();
+    for (const a of resolution.answers) {
+        byId.set(a.questionId, a.values);
+    }
+    for (const q of upstreamQuestions) {
+        const values = byId.get(q.id);
+        if (values === undefined) {
+            console.warn(`toWireAnswerMap: no answer for question ${q.id} — emitting empty array`);
+            out[q.id] = { answers: [] };
+        }
+        else {
+            out[q.id] = { answers: [...values] };
+        }
+    }
+    return out;
+}

package/dist/agents/codex.d.ts

@@ -0,0 +1,7 @@
+import { AgentCommandRunner, AgentSessionOptions, AgentTurnResult } from '../types.js';
+import { ToolEvent } from '../tool-events.js';
+import { TranscriptAgent } from './transcript-agent.js';
+export declare class CodexAgent extends TranscriptAgent {
+    protected runTurn(instruction: string, runCommand: AgentCommandRunner, options?: AgentSessionOptions): Promise<AgentTurnResult>;
+}
+export declare function extractCodexToolEvents(traceOutput: string, turnNumber?: number): ToolEvent[];

package/dist/agents/codex.js

@@ -0,0 +1,164 @@
+import { TOOL_NAME_MAP, buildSummary, inferCodexExecAction, enrichSkillEvents } from '../tool-events.js';
+import { TranscriptAgent } from './transcript-agent.js';
+export class CodexAgent extends TranscriptAgent {
+    async runTurn(instruction, runCommand, options) {
+        const promptPath = await this.writePromptFile(instruction, runCommand);
+        const command = buildCodexExecCommand(promptPath, options?.model);
+        const result = await runCommand(command);
+        const rawOutput = result.stdout + '\n' + result.stderr;
+        const assistantMessage = result.stdout.trim() || rawOutput.trim();
+        if (result.exitCode !== 0) {
+            console.error('CodexAgent: Codex CLI failed to execute correctly.');
+        }
+        const toolEvents = extractCodexToolEvents(rawOutput);
+        return {
+            rawOutput,
+            assistantMessage,
+            visibleAssistantMessage: assistantMessage,
+            visibleAssistantMessageSource: 'assistant_message',
+            exitCode: result.exitCode,
+            traceOutput: rawOutput,
+            toolEvents,
+        };
+    }
+}
+const DEFAULT_CODEX_MODEL = 'gpt-5.3-codex';
+const CODEX_PROXY_PROVIDER_ID = 'pathgrade_openai_proxy';
+function buildCodexExecCommand(promptPath, model = DEFAULT_CODEX_MODEL) {
+    const quotedPromptPath = JSON.stringify(promptPath);
+    const quotedModel = JSON.stringify(model);
+    const execArgs = `--full-auto --skip-git-repo-check -m ${quotedModel} - < ${quotedPromptPath}`;
+    return [
+        'if [ -n "${OPENAI_BASE_URL:-}" ]; then',
+        `codex exec ${buildCodexProxyConfigArgs()} ${execArgs};`,
+        'else',
+        `codex exec ${execArgs};`,
+        'fi',
+    ].join(' ');
+}
+function buildCodexProxyConfigArgs() {
+    return [
+        `-c 'model_provider="${CODEX_PROXY_PROVIDER_ID}"'`,
+        `-c 'model_providers.${CODEX_PROXY_PROVIDER_ID}.name="PathGrade OpenAI Proxy"'`,
+        `-c "model_providers.${CODEX_PROXY_PROVIDER_ID}.base_url=\\"$OPENAI_BASE_URL\\""`,
+        `-c 'model_providers.${CODEX_PROXY_PROVIDER_ID}.env_key="OPENAI_API_KEY"'`,
+        `-c 'model_providers.${CODEX_PROXY_PROVIDER_ID}.wire_api="responses"'`,
+        `-c 'model_providers.${CODEX_PROXY_PROVIDER_ID}.supports_websockets=false'`,
+    ].join(' ');
+}
+const TOOL_LINE_REGEX = /^tool:\s+(\S+)\s+(\{.*\})\s*$/;
+const CODEX_EXEC_LINE_REGEX = /^(?<command>.+?) in .+? (?:succeeded|failed|exited)\b.*$/;
+const CODEX_EXEC_COMMAND_ONLY_REGEX = /^(?<command>.+?) in .+$/;
+const CODEX_EXEC_STATUS_LINE_REGEX = /^(?:succeeded|failed|exited)\b.*$/;
+const CODEX_FILE_PATH_REGEX = /^[A-Z?]+\s+(?<path>\/.+)$/;
+const CODEX_ABSOLUTE_PATH_REGEX = /^(?<path>\/.+)$/;
+function extractGenericToolLines(traceOutput, turnNumber) {
+    const events = [];
+    for (const line of traceOutput.split('\n')) {
+        const match = line.match(TOOL_LINE_REGEX);
+        if (!match)
+            continue;
+        const providerToolName = match[1];
+        const jsonStr = match[2];
+        let args;
+        try {
+            args = JSON.parse(jsonStr);
+        }
+        catch {
+            continue;
+        }
+        const action = TOOL_NAME_MAP[providerToolName] ?? 'unknown';
+        const summary = buildSummary(action, providerToolName, args);
+        const rawSnippet = line.length > 200 ? line.slice(0, 200) : line;
+        events.push({
+            action,
+            provider: 'codex',
+            providerToolName,
+            turnNumber,
+            arguments: args,
+            summary,
+            confidence: 'high',
+            rawSnippet,
+        });
+    }
+    return events;
+}
+export function extractCodexToolEvents(traceOutput, turnNumber) {
+    const events = extractGenericToolLines(traceOutput, turnNumber);
+    const seen = new Set(events.map((event) => `${event.providerToolName}:${event.action}:${event.summary}`));
+    const lines = traceOutput.split('\n');
+    const pushEvent = (action, providerToolName, summary, args, rawSnippet) => {
+        const key = `${providerToolName}:${action}:${summary}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        events.push({
+            action,
+            provider: 'codex',
+            providerToolName,
+            turnNumber,
+            arguments: args,
+            summary,
+            confidence: action === 'unknown' ? 'low' : 'medium',
+            rawSnippet: (rawSnippet || summary).slice(0, 200),
+        });
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        if (line === 'exec') {
+            const commandLine = lines[i + 1]?.trim();
+            if (!commandLine)
+                continue;
+            const command = extractCommand(commandLine);
+            if (!command)
+                continue;
+            const statusLine = lines[i + 2]?.trim();
+            const rawSnippetLines = [line, commandLine];
+            if (statusLine && CODEX_EXEC_STATUS_LINE_REGEX.test(statusLine)) {
+                rawSnippetLines.push(statusLine);
+                i += 2;
+            }
+            else {
+                i += 1;
+            }
+            pushEvent(inferCodexExecAction(command), 'exec', command, { command }, rawSnippetLines.join('\n'));
+            continue;
+        }
+        if (line === 'file update') {
+            const filePath = extractUpdatedPath(lines, i + 1);
+            pushEvent('edit_file', 'file update', filePath ? `edit_file ${filePath}` : 'edit_file via file update', filePath ? { path: filePath } : undefined, `${line}\n${lines[i + 1]?.trim() || ''}`);
+            i += 1;
+            continue;
+        }
+        if (line === 'apply patch' || line.startsWith('apply_patch(')) {
+            const filePath = extractUpdatedPath(lines, i + 1);
+            pushEvent('edit_file', line === 'apply patch' ? 'apply patch' : 'apply_patch', filePath ? `edit_file ${filePath}` : 'edit_file via apply_patch', filePath ? { path: filePath } : undefined, `${line}\n${lines[i + 1]?.trim() || ''}`);
+            continue;
+        }
+    }
+    return enrichSkillEvents(events);
+}
+function extractCommand(commandLine) {
+    const command = commandLine.match(CODEX_EXEC_LINE_REGEX)?.groups?.command
+        ?? commandLine.match(CODEX_EXEC_COMMAND_ONLY_REGEX)?.groups?.command;
+    if (!command) {
+        return undefined;
+    }
+    const shellWrapped = command.match(/^\/bin\/\w+\s+-lc\s+(['"])(?<inner>[\s\S]+)\1$/);
+    return shellWrapped?.groups?.inner ?? command;
+}
+function extractUpdatedPath(lines, startIndex) {
+    for (let i = startIndex; i < Math.min(lines.length, startIndex + 5); i++) {
+        const line = lines[i]?.trim();
+        if (!line)
+            continue;
+        const filePath = line.match(CODEX_FILE_PATH_REGEX)?.groups?.path
+            ?? line.match(CODEX_ABSOLUTE_PATH_REGEX)?.groups?.path;
+        if (filePath) {
+            return filePath;
+        }
+    }
+    return undefined;
+}

package/dist/agents/cursor.d.ts

@@ -0,0 +1,39 @@
+import type { TokenUsage } from '../sdk/types.js';
+import { AgentCommandRunner, AgentSession, AgentSessionOptions, BaseAgent, CommandResult, EnvironmentHandle } from '../types.js';
+import { ToolEvent } from '../tool-events.js';
+/**
+ * Pure function: scan Cursor NDJSON for `tool_call` events with
+ * `subtype: "started"` and emit a normalized `ToolEvent[]`. Enriched via
+ * `enrichSkillEvents` so `readToolCall` on a `SKILL.md` is reclassified as
+ * `use_skill`, matching Claude/Codex.
+ *
+ * `completed` subtypes are ignored (noisy, redundant for event-level scoring).
+ * `interaction_query` events are ignored (approval metadata, not tool calls).
+ */
+export declare function extractCursorStreamJsonEvents(traceOutput: string, turnNumber?: number): ToolEvent[];
+/**
+ * Shape returned by `parseCursorStreamJson`. Mirrors Claude's envelope shape
+ * plus an `interactionQueryCount` for diagnostics (approval round-trips from
+ * `--force` / `--approve-mcps` — discarded here, not surfaced as ToolEvents).
+ */
+export interface CursorEnvelopeParseResult {
+    sessionId?: string;
+    isError: boolean;
+    resultText: string;
+    tokenUsage?: TokenUsage;
+    interactionQueryCount: number;
+}
+/**
+ * Pure function: scan Cursor's NDJSON stream-json and return the terminal
+ * envelope's key fields. If no `type: "result"` event is present (e.g. the
+ * CLI emitted a plain-text "Workspace Trust Required" block), the raw stdout
+ * is surfaced as a truncated error payload so the diagnostic points at the
+ * real cause instead of a parser crash.
+ */
+export declare function parseCursorStreamJson(stdout: string): CursorEnvelopeParseResult;
+export declare class CursorAgent extends BaseAgent {
+    createSession(runtime: EnvironmentHandle, runCommand: AgentCommandRunner, options?: AgentSessionOptions): Promise<AgentSession>;
+    run(instruction: string, workspacePath: string, runCommand: (cmd: string) => Promise<CommandResult>): Promise<string>;
+    private runTurn;
+    private sanitizeSessionId;
+}

package/dist/agents/cursor.js

@@ -0,0 +1,233 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { BaseAgent, getWorkspacePath } from '../types.js';
+import { TOOL_NAME_MAP, buildSummary, enrichSkillEvents } from '../tool-events.js';
+import { getVisibleAssistantMessage } from '../sdk/visible-turn.js';
+import { prependRuntimePolicies } from '../sdk/runtime-policy.js';
+/**
+ * Cursor tool_call discriminants observed in the discovery spike. Probed in
+ * order — first present key wins. Explicit probing (vs. `Object.keys(…)[0]`)
+ * means a future metadata wrapper key like `id` or `ts` cannot silently
+ * misclassify.
+ */
+const CURSOR_TOOL_DISCRIMINANTS = [
+    'readToolCall',
+    'editToolCall',
+    'globToolCall',
+    'grepToolCall',
+    'shellToolCall',
+    'webFetchToolCall',
+    'updateTodosToolCall',
+];
+const RAW_SNIPPET_MAX_CHARS = 200;
+/**
+ * Pure function: scan Cursor NDJSON for `tool_call` events with
+ * `subtype: "started"` and emit a normalized `ToolEvent[]`. Enriched via
+ * `enrichSkillEvents` so `readToolCall` on a `SKILL.md` is reclassified as
+ * `use_skill`, matching Claude/Codex.
+ *
+ * `completed` subtypes are ignored (noisy, redundant for event-level scoring).
+ * `interaction_query` events are ignored (approval metadata, not tool calls).
+ */
+export function extractCursorStreamJsonEvents(traceOutput, turnNumber) {
+    const events = [];
+    for (const line of traceOutput.split('\n')) {
+        if (!line.trim())
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (parsed.type !== 'tool_call' || parsed.subtype !== 'started')
+            continue;
+        // Later cursor-agent builds nest the tool discriminant under a
+        // `tool_call` wrapper; earlier builds (see fixtures/cursor/tool-*.ndjson)
+        // place it at the top level. Probe the wrapper first, then the envelope.
+        const wrapper = parsed.tool_call && typeof parsed.tool_call === 'object'
+            ? parsed.tool_call
+            : parsed;
+        let discriminantKey;
+        for (const candidate of CURSOR_TOOL_DISCRIMINANTS) {
+            if (wrapper[candidate] && typeof wrapper[candidate] === 'object') {
+                discriminantKey = candidate;
+                break;
+            }
+        }
+        // Unknown discriminant — fall back to the first *ToolCall-suffixed key,
+        // or the first non-meta object. Preserves providerToolName so it's
+        // still visible for triage, action stays 'unknown'.
+        if (!discriminantKey) {
+            for (const key of Object.keys(wrapper)) {
+                if (key === 'type' || key === 'subtype')
+                    continue;
+                if (key === 'id' || key === 'ts')
+                    continue;
+                const value = wrapper[key];
+                if (value && typeof value === 'object') {
+                    discriminantKey = key;
+                    break;
+                }
+            }
+        }
+        if (!discriminantKey)
+            continue;
+        const block = wrapper[discriminantKey];
+        const args = block?.args;
+        const action = TOOL_NAME_MAP[discriminantKey] ?? 'unknown';
+        const summary = buildSummary(action, discriminantKey, args);
+        const rawSnippet = JSON.stringify(block).slice(0, RAW_SNIPPET_MAX_CHARS);
+        events.push({
+            action,
+            provider: 'cursor',
+            providerToolName: discriminantKey,
+            ...(turnNumber !== undefined ? { turnNumber } : {}),
+            ...(args ? { arguments: args } : {}),
+            summary,
+            confidence: 'high',
+            rawSnippet,
+        });
+    }
+    return enrichSkillEvents(events);
+}
+const RAW_ERROR_MAX_BYTES = 2048;
+/**
+ * Pure function: scan Cursor's NDJSON stream-json and return the terminal
+ * envelope's key fields. If no `type: "result"` event is present (e.g. the
+ * CLI emitted a plain-text "Workspace Trust Required" block), the raw stdout
+ * is surfaced as a truncated error payload so the diagnostic points at the
+ * real cause instead of a parser crash.
+ */
+export function parseCursorStreamJson(stdout) {
+    let result;
+    let interactionQueryCount = 0;
+    for (const line of stdout.split('\n')) {
+        if (!line.trim())
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (parsed.type === 'interaction_query') {
+            interactionQueryCount += 1;
+            continue;
+        }
+        if (parsed.type === 'result') {
+            result = parsed;
+        }
+    }
+    if (!result) {
+        return {
+            isError: true,
+            resultText: stdout.slice(0, RAW_ERROR_MAX_BYTES),
+            interactionQueryCount,
+        };
+    }
+    const tokenUsage = result.usage
+        ? {
+            inputTokens: (result.usage.input_tokens ?? 0)
+                + (result.usage.cache_creation_input_tokens ?? 0)
+                + (result.usage.cache_read_input_tokens ?? 0),
+            outputTokens: result.usage.output_tokens ?? 0,
+        }
+        : undefined;
+    return {
+        sessionId: result.session_id,
+        isError: !!result.is_error,
+        resultText: result.result ?? '',
+        tokenUsage,
+        interactionQueryCount,
+    };
+}
+// `cursor-agent --help` (2026.04.17-787b533) treats `--trust` and `--force`
+// as orthogonal: `--trust` unblocks workspace-trust, `--force` bypasses
+// per-command approvals. Discovery spikes saw hangs when `--trust` was
+// dropped, so we pass both by default.
+const CURSOR_EXECUTABLE = 'cursor-agent';
+export class CursorAgent extends BaseAgent {
+    async createSession(runtime, runCommand, options) {
+        const workspacePath = getWorkspacePath(runtime);
+        let sessionId;
+        return {
+            start: async ({ message }) => {
+                const result = await this.runTurn(message, workspacePath, runCommand, sessionId, options);
+                sessionId = result.sessionId ?? sessionId;
+                return result;
+            },
+            reply: async ({ message }) => {
+                const result = await this.runTurn(message, workspacePath, runCommand, sessionId, options);
+                sessionId = result.sessionId ?? sessionId;
+                return result;
+            },
+        };
+    }
+    async run(instruction, workspacePath, runCommand) {
+        const result = await this.runTurn(instruction, workspacePath, runCommand, undefined);
+        return getVisibleAssistantMessage(result);
+    }
+    async runTurn(instruction, workspacePath, runCommand, sessionId, options) {
+        // Runtime policies are injected into the first-turn prompt only.
+        // On resumed turns (sessionId set) the policy was already delivered,
+        // so we skip re-prepending. The Claude SDK driver does not prepend
+        // runtime policies at all (its transport is `'reliable'`), so Cursor
+        // and the Codex transcript agent are the only consumers of this path.
+        const appliedRuntimePolicies = sessionId ? [] : [...(options?.runtimePolicies ?? [])];
+        const effectiveInstruction = appliedRuntimePolicies.length > 0
+            ? prependRuntimePolicies(instruction, appliedRuntimePolicies, { agent: 'cursor' })
+            : instruction;
+        // Tempfile-via-argv approach: write the prompt to a shell-escape-safe
+        // tempfile and splice via $(cat …). The legacy Claude CLI driver used
+        // the same pattern; the SDK-based Claude driver passes `prompt`
+        // directly to `query()` and no longer needs this. Cursor still does
+        // because it shells out to the `cursor-agent` CLI.
+        const promptPath = '"${TMPDIR:-/tmp}/.pathgrade-cursor-prompt.md"';
+        const b64 = Buffer.from(effectiveInstruction).toString('base64');
+        await runCommand(`mkdir -p "\${TMPDIR:-/tmp}" && echo '${b64}' | base64 -d > ${promptPath}`);
+        // Materialize .cursor/mcp.json from pathgrade's MCP config so the
+        // CLI's native loader picks it up. Idempotent per turn.
+        if (options?.mcpConfigPath) {
+            const srcMcp = path.join(workspacePath, options.mcpConfigPath);
+            if (await fs.pathExists(srcMcp)) {
+                const cursorDir = path.join(workspacePath, '.cursor');
+                await fs.ensureDir(cursorDir);
+                await fs.copy(srcMcp, path.join(cursorDir, 'mcp.json'), { overwrite: true });
+            }
+        }
+        const modelFlag = options?.model ? ` --model ${options.model}` : '';
+        const mcpFlag = options?.mcpConfigPath ? ' --approve-mcps' : '';
+        const resumeFlag = sessionId ? ` --resume ${this.sanitizeSessionId(sessionId)}` : '';
+        const command = `${CURSOR_EXECUTABLE} -p --output-format stream-json --trust --force --workspace "${workspacePath}"${resumeFlag}${modelFlag}${mcpFlag} "$(cat ${promptPath})" < /dev/null`;
+        const result = await runCommand(command);
+        const parsed = parseCursorStreamJson(result.stdout);
+        const toolEvents = extractCursorStreamJsonEvents(result.stdout);
+        const rawOutput = parsed.isError && !parsed.sessionId
+            // No parseable result envelope — surface the CLI's raw text so
+            // diagnostics point at the real failure (workspace-trust block,
+            // auth error, etc.) instead of an empty string.
+            ? (result.stdout + (result.stderr ? '\n' + result.stderr : '')).trim()
+            : parsed.resultText;
+        return {
+            rawOutput,
+            assistantMessage: parsed.isError ? '' : parsed.resultText,
+            visibleAssistantMessage: parsed.isError ? '' : parsed.resultText,
+            visibleAssistantMessageSource: 'assistant_message',
+            exitCode: result.exitCode,
+            sessionId: parsed.sessionId,
+            traceOutput: result.stdout,
+            timedOut: result.timedOut,
+            toolEvents,
+            runtimePoliciesApplied: appliedRuntimePolicies,
+            ...(parsed.tokenUsage
+                ? { inputTokens: parsed.tokenUsage.inputTokens, outputTokens: parsed.tokenUsage.outputTokens }
+                : {}),
+        };
+    }
+    sanitizeSessionId(id) {
+        return id.replace(/[^a-zA-Z0-9_-]/g, '');
+    }
+}

package/dist/agents/registry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Agent registry — maps agent names to their implementations.
+ *
+ * Supported agents:
+ *   - claude: Anthropic Claude Code CLI
+ *   - codex: OpenAI Codex CLI
+ */
+import { BaseAgent } from '../types.js';
+import { AgentName, AgentTransport } from '../sdk/types.js';
+/** Get the list of supported agent names */
+export declare function getAgentNames(): AgentName[];
+/**
+ * Create an agent instance by name. Throws if the name is unknown.
+ * For `codex`, `transport` selects between `CodexAgent` (exec) and
+ * `CodexAppServerAgent` (default / app-server). Ignored for other agents.
+ */
+export declare function createAgentEnvironment(name: AgentName, transport?: AgentTransport): BaseAgent;

package/dist/agents/registry.js

@@ -0,0 +1,27 @@
+import { ClaudeAgent } from './claude.js';
+import { CodexAgent } from './codex.js';
+import { CodexAppServerAgent } from './codex-app-server/agent.js';
+import { CursorAgent } from './cursor.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(),
+};
+/** Get the list of supported agent names */
+export function getAgentNames() {
+    return Object.keys(AGENT_REGISTRY);
+}
+/**
+ * Create an agent instance by name. Throws if the name is unknown.
+ * For `codex`, `transport` selects between `CodexAgent` (exec) and
+ * `CodexAppServerAgent` (default / app-server). Ignored for other agents.
+ */
+export function createAgentEnvironment(name, transport) {
+    const factory = AGENT_REGISTRY[name];
+    if (!factory) {
+        const available = getAgentNames().join(', ');
+        throw new Error(`Unknown agent "${name}". Available agents: ${available}`);
+    }
+    return factory(transport);
+}

package/dist/agents/transcript-agent.d.ts

@@ -0,0 +1,14 @@
+import { AgentCommandRunner, AgentSession, AgentSessionOptions, AgentTurnResult, BaseAgent, CommandResult, EnvironmentHandle } from '../types.js';
+/**
+ * Base class for agents that manage multi-turn conversations via transcript
+ * re-injection (e.g. Codex). Handles session management, transcript
+ * accumulation, and prompt file writing.
+ */
+export declare abstract class TranscriptAgent extends BaseAgent {
+    createSession(_runtime: EnvironmentHandle, runCommand: AgentCommandRunner, options?: AgentSessionOptions): Promise<AgentSession>;
+    run(instruction: string, _workspacePath: string, runCommand: (cmd: string) => Promise<CommandResult>): Promise<string>;
+    private buildTranscriptPrompt;
+    protected writePromptFile(instruction: string, runCommand: AgentCommandRunner): Promise<string>;
+    /** Subclasses implement this to run the CLI command for one turn */
+    protected abstract runTurn(instruction: string, runCommand: AgentCommandRunner, options?: AgentSessionOptions): Promise<AgentTurnResult>;
+}

package/dist/agents/transcript-agent.js

@@ -0,0 +1,59 @@
+import { randomUUID } from 'crypto';
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { BaseAgent } from '../types.js';
+import { createConversationWindow } from '../sdk/conversation-window.js';
+import { prependRuntimePolicies } from '../sdk/runtime-policy.js';
+import { getVisibleAssistantMessage } from '../sdk/visible-turn.js';
+/**
+ * Base class for agents that manage multi-turn conversations via transcript
+ * re-injection (e.g. Codex). Handles session management, transcript
+ * accumulation, and prompt file writing.
+ */
+export class TranscriptAgent extends BaseAgent {
+    async createSession(_runtime, runCommand, options) {
+        const messages = [];
+        const runtimePolicies = options?.runtimePolicies ?? [];
+        const window = options?.conversationWindow !== false
+            ? createConversationWindow({ ...options?.conversationWindow, llm: options?.llm })
+            : null;
+        const runTranscriptTurn = async (message) => {
+            messages.push({ role: 'user', content: message });
+            const prompt = await this.buildTranscriptPrompt(messages, window, runtimePolicies);
+            const result = await this.runTurn(prompt, runCommand, options);
+            const enrichedResult = runtimePolicies.length > 0
+                ? { ...result, runtimePoliciesApplied: [...runtimePolicies] }
+                : result;
+            messages.push({ role: 'agent', content: getVisibleAssistantMessage(enrichedResult) });
+            return enrichedResult;
+        };
+        return {
+            start: async ({ message }) => runTranscriptTurn(message),
+            reply: async ({ message }) => runTranscriptTurn(message),
+        };
+    }
+    async run(instruction, _workspacePath, runCommand) {
+        const result = await this.runTurn(instruction, runCommand);
+        return getVisibleAssistantMessage(result);
+    }
+    async buildTranscriptPrompt(messages, window, runtimePolicies = []) {
+        const history = window
+            ? await window.getHistory(messages)
+            : messages.map(m => `${m.role === 'user' ? 'User' : 'Agent'}: ${m.content}`).join('\n\n');
+        const instruction = [
+            'Continue the conversation below. Respond to the latest user message and do not re-execute previous work unless it is necessary to answer correctly.',
+            history,
+        ].join('\n\n');
+        return runtimePolicies.length > 0
+            ? prependRuntimePolicies(instruction, runtimePolicies, { agent: 'codex' })
+            : instruction;
+    }
+    async writePromptFile(instruction, runCommand) {
+        void runCommand;
+        const promptPath = path.join(process.env.TMPDIR || os.tmpdir(), `.pathgrade-prompt-${randomUUID()}.md`);
+        await fs.ensureDir(path.dirname(promptPath));
+        await fs.writeFile(promptPath, instruction, 'utf8');
+        return promptPath;
+    }
+}

package/dist/analytics/engine.d.ts

@@ -0,0 +1,18 @@
+import { EvalReport } from '../types.js';
+export interface AggregateStats {
+    task: string;
+    passRateNoSkill: number;
+    passRateWithSkill: number;
+    normalizedGain: number;
+    avgDurationMs: number;
+    avgCommands: number;
+}
+/**
+ * Calculates Normalized Gain (NG) as defined in the Skill Eval paper.
+ * NG = (p_with - p_without) / (1 - p_without)
+ */
+export declare function calculateNormalizedGain(pWith: number, pWithout: number): number;
+export declare class AnalyticsEngine {
+    loadReports(logDir: string): Promise<EvalReport[]>;
+    aggregate(reports: EvalReport[]): AggregateStats[];
+}