@wix/pathgrade 0.29.0

package/dist/reporters/loader.js

@@ -0,0 +1,36 @@
+import fs from 'fs-extra';
+import * as path from 'path';
+async function hydrateTraces(report, traceFile, resolved) {
+    const tracePath = path.resolve(resolved, traceFile);
+    if (!await fs.pathExists(tracePath))
+        return;
+    const traceTrials = await fs.readJSON(tracePath);
+    if (!Array.isArray(traceTrials) || !Array.isArray(report.trials))
+        return;
+    report.trials = report.trials.map((t, i) => ({ ...t, ...traceTrials[i] }));
+}
+export async function loadReports(resultsDir, opts) {
+    const resolved = path.resolve(resultsDir);
+    const files = (await fs.readdir(resolved))
+        .filter(f => f.endsWith('.json'))
+        .reverse();
+    const results = [];
+    for (const file of files) {
+        try {
+            const raw = await fs.readJSON(path.join(resolved, file));
+            if (!raw.version || !Array.isArray(raw.groups)) {
+                results.push({ file, ...raw });
+                continue;
+            }
+            for (const group of raw.groups) {
+                const report = { file, timestamp: raw.timestamp, ...group };
+                if (!opts?.skipTraces && group.trace_file) {
+                    await hydrateTraces(report, group.trace_file, resolved);
+                }
+                results.push(report);
+            }
+        }
+        catch { /* skip malformed */ }
+    }
+    return results;
+}

package/dist/reporters/results-path.d.ts

@@ -0,0 +1,2 @@
+export declare function getPathgradeDir(projectDir: string): string;
+export declare function getResultsDir(projectDir: string, baseDir?: string): string;

package/dist/reporters/results-path.js

@@ -0,0 +1,10 @@
+import * as path from 'path';
+export function getPathgradeDir(projectDir) {
+    return path.join(projectDir, '.pathgrade');
+}
+export function getResultsDir(projectDir, baseDir) {
+    if (baseDir) {
+        return path.join(baseDir, path.basename(projectDir), 'results');
+    }
+    return getPathgradeDir(projectDir);
+}

package/dist/reporters/verbose-emitter.d.ts

@@ -0,0 +1,69 @@
+/** Maximum characters retained in a prompt/reply preview before truncation. */
+export declare const PREVIEW_MAX_CHARS = 80;
+/** Maximum characters retained in a retry error message before truncation. */
+export declare const RETRY_ERROR_MAX_CHARS = 120;
+/** Ellipsis appended to truncated strings. */
+export declare const TRUNCATION_SUFFIX = "\u2026";
+/** Newline replacement in single-line previews. */
+export declare const NEWLINE_REPLACEMENT = "\u23CE";
+export interface VerboseSink {
+    write(line: string): void;
+}
+export interface VerboseEmitterOptions {
+    enabled: boolean;
+    /** Output sink. Defaults to a stderr-backed sink. */
+    sink?: VerboseSink;
+    /**
+     * Optional test-name header printed once before the first real event.
+     * Helps the reader locate the beginning of each test block.
+     */
+    testName?: string;
+}
+export interface TurnStartArgs {
+    turn: number;
+    kind: 'agent_start' | 'user_reply';
+    message: string;
+}
+export interface ToolEventArgs {
+    action: string;
+    summary: string;
+}
+export interface TurnEndArgs {
+    turn: number;
+    durationMs: number;
+    outputLines: number;
+    messagePreview: string;
+}
+export interface RetryArgs {
+    attempt: number;
+    maxAttempts: number;
+    errorMessage: string;
+}
+export interface ReactionFiredArgs {
+    turn: number;
+    reactionIndex: number;
+    pattern: string;
+    reply: string;
+}
+export interface ConversationEndArgs {
+    reason: string;
+    turns: number;
+    durationMs: number;
+    /** Present when `reason === 'error'` / `'timeout'` / `'agent_crashed'`. */
+    detail?: string;
+}
+export interface VerboseEmitter {
+    readonly enabled: boolean;
+    turnStart(args: TurnStartArgs): void;
+    toolEvent(args: ToolEventArgs): void;
+    turnEnd(args: TurnEndArgs): void;
+    retry(args: RetryArgs): void;
+    reactionFired(args: ReactionFiredArgs): void;
+    conversationEnd(args: ConversationEndArgs): void;
+}
+/**
+ * Build a preview string: strip newlines, truncate to a max length.
+ * `null` / `undefined` becomes an empty string so formatting never throws.
+ */
+export declare function preview(text: string | null | undefined, max?: number): string;
+export declare function createVerboseEmitter(opts: VerboseEmitterOptions): VerboseEmitter;

package/dist/reporters/verbose-emitter.js

@@ -0,0 +1,103 @@
+/**
+ * Verbose live-streaming emitter.
+ *
+ * Formats per-turn agent events into one-line human-readable output and
+ * writes them to a sink (default: `process.stderr`). The emitter is
+ * orthogonal to `--diagnostics`: it streams while the agent runs, rather
+ * than summarizing after the fact.
+ *
+ * See `docs/prds/PRD_VERBOSE_LIVE_STREAMING.md` for the full design.
+ */
+import { fmt } from '../utils/cli.js';
+/** Maximum characters retained in a prompt/reply preview before truncation. */
+export const PREVIEW_MAX_CHARS = 80;
+/** Maximum characters retained in a retry error message before truncation. */
+export const RETRY_ERROR_MAX_CHARS = 120;
+/** Ellipsis appended to truncated strings. */
+export const TRUNCATION_SUFFIX = '…';
+/** Newline replacement in single-line previews. */
+export const NEWLINE_REPLACEMENT = '⏎';
+/**
+ * Build a preview string: strip newlines, truncate to a max length.
+ * `null` / `undefined` becomes an empty string so formatting never throws.
+ */
+export function preview(text, max = PREVIEW_MAX_CHARS) {
+    const normalized = (text ?? '').replace(/\r?\n/g, NEWLINE_REPLACEMENT);
+    if (normalized.length <= max)
+        return normalized;
+    return normalized.slice(0, max) + TRUNCATION_SUFFIX;
+}
+function stderrSink() {
+    return {
+        write(line) {
+            // Bypass vitest's stdout capture: vitest's default reporter
+            // does not hijack stderr, so writes here reach the user's
+            // terminal while a test is still running.
+            process.stderr.write(line + '\n');
+        },
+    };
+}
+function formatDurationSeconds(ms) {
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+function disabledEmitter() {
+    return {
+        enabled: false,
+        turnStart() { },
+        toolEvent() { },
+        turnEnd() { },
+        retry() { },
+        reactionFired() { },
+        conversationEnd() { },
+    };
+}
+export function createVerboseEmitter(opts) {
+    if (!opts.enabled) {
+        return disabledEmitter();
+    }
+    const sink = opts.sink ?? stderrSink();
+    const testName = opts.testName;
+    let headerPrinted = false;
+    const emitHeaderOnce = () => {
+        if (headerPrinted)
+            return;
+        headerPrinted = true;
+        if (testName) {
+            sink.write(fmt.bold(`▶ ${testName}`));
+        }
+    };
+    const writeLine = (line) => {
+        emitHeaderOnce();
+        sink.write(line);
+    };
+    return {
+        enabled: true,
+        turnStart({ turn, kind, message }) {
+            const p = preview(message, PREVIEW_MAX_CHARS);
+            writeLine(`${fmt.cyan('→')} Turn ${fmt.bold(String(turn))} ${fmt.dim(`[${kind}]`)} "${p}"`);
+        },
+        toolEvent({ action, summary }) {
+            writeLine(`  ${fmt.dim('·')} ${fmt.cyan(action)} ${summary}`);
+        },
+        turnEnd({ turn, durationMs, outputLines, messagePreview }) {
+            const p = preview(messagePreview, PREVIEW_MAX_CHARS);
+            const duration = formatDurationSeconds(durationMs);
+            writeLine(`${fmt.green('←')} Turn ${fmt.bold(String(turn))}  ${fmt.dim(duration)}  ${fmt.dim(`${outputLines}l`)}  "${p}"`);
+        },
+        retry({ attempt, maxAttempts, errorMessage }) {
+            const msg = preview(errorMessage, RETRY_ERROR_MAX_CHARS);
+            writeLine(`  ${fmt.red('⟲')} retry ${attempt}/${maxAttempts}: ${msg}`);
+        },
+        reactionFired({ reactionIndex, pattern, reply }) {
+            const p = preview(reply, PREVIEW_MAX_CHARS);
+            writeLine(`  ${fmt.cyan('⚡')} reaction ${fmt.bold(`#${reactionIndex}`)} ${fmt.dim(pattern)} → "${p}"`);
+        },
+        conversationEnd({ reason, turns, durationMs, detail }) {
+            const duration = formatDurationSeconds(durationMs);
+            const detailSuffix = detail
+                ? `  ${fmt.red('detail=')}${preview(detail, RETRY_ERROR_MAX_CHARS)}`
+                : '';
+            writeLine(`${fmt.bold('■')} end  ${fmt.dim('reason=')}${reason}  ${fmt.dim('turns=')}${turns}  ${fmt.dim(duration)}${detailSuffix}`);
+        },
+    };
+}

package/dist/sdk/agent-crash.d.ts

@@ -0,0 +1,19 @@
+import type { ToolEvent } from '../tool-events.js';
+/**
+ * Error thrown by an agent driver when the subprocess dies mid-turn under a
+ * stateful transport (e.g. Codex `app-server`). Carries enough diagnostic
+ * information for `runConversation` to build `ConversationResult.crashDiagnostic`.
+ */
+export declare class AgentCrashError extends Error {
+    readonly pid?: number;
+    readonly signal?: NodeJS.Signals | null;
+    readonly exitCode?: number | null;
+    /** Non-ask-user tool events captured before the crash, if available. */
+    partialToolEvents?: ToolEvent[];
+    constructor(message: string, info: {
+        pid?: number;
+        signal?: NodeJS.Signals | string | null;
+        exitCode?: number | null;
+        partialToolEvents?: ToolEvent[];
+    });
+}

package/dist/sdk/agent-crash.js

@@ -0,0 +1,20 @@
+/**
+ * Error thrown by an agent driver when the subprocess dies mid-turn under a
+ * stateful transport (e.g. Codex `app-server`). Carries enough diagnostic
+ * information for `runConversation` to build `ConversationResult.crashDiagnostic`.
+ */
+export class AgentCrashError extends Error {
+    pid;
+    signal;
+    exitCode;
+    /** Non-ask-user tool events captured before the crash, if available. */
+    partialToolEvents;
+    constructor(message, info) {
+        super(message);
+        this.name = 'AgentCrashError';
+        this.pid = info.pid;
+        this.signal = info.signal;
+        this.exitCode = info.exitCode ?? null;
+        this.partialToolEvents = info.partialToolEvents;
+    }
+}

package/dist/sdk/agent-resolution.d.ts

@@ -0,0 +1,12 @@
+import type { AgentName, AgentTransport, AgentOptions } from './types.js';
+export declare class InvalidTransportEnvError extends Error {
+    constructor(value: string);
+}
+export declare function resolveAgentName(opts: Pick<AgentOptions, 'agent'>, env: {
+    PATHGRADE_AGENT?: string;
+}): AgentName;
+export declare function resolveCodexTransport(opts: {
+    transport?: AgentTransport;
+}, env: {
+    PATHGRADE_CODEX_TRANSPORT?: string;
+}): AgentTransport;

package/dist/sdk/agent-resolution.js

@@ -0,0 +1,21 @@
+export class InvalidTransportEnvError extends Error {
+    constructor(value) {
+        super(`Invalid PATHGRADE_CODEX_TRANSPORT value: '${value}'. Valid options: 'exec', 'app-server'.`);
+        this.name = 'InvalidTransportEnvError';
+    }
+}
+export function resolveAgentName(opts, env) {
+    return (opts.agent || env.PATHGRADE_AGENT || 'claude');
+}
+export function resolveCodexTransport(opts, env) {
+    if (opts.transport)
+        return opts.transport;
+    const envValue = env.PATHGRADE_CODEX_TRANSPORT;
+    if (envValue) {
+        if (envValue !== 'exec' && envValue !== 'app-server') {
+            throw new InvalidTransportEnvError(envValue);
+        }
+        return envValue;
+    }
+    return 'app-server';
+}

package/dist/sdk/agent-result-log.d.ts

@@ -0,0 +1,19 @@
+import type { AgentTurnResult, LogEntry } from '../types.js';
+import type { AskBus } from './ask-bus/types.js';
+export declare function buildModelAgentResultLogEntry(params: {
+    timestamp: string;
+    turnNumber?: number;
+    durationMs?: number;
+    turnResult: AgentTurnResult;
+    assistantMessage?: string;
+}): LogEntry;
+/**
+ * Build one `ask_batch` LogEntry per AskBus batch emitted in the given turn.
+ * Callers push these to the session log before the `agent_result` entry for
+ * that turn.
+ */
+export declare function buildAskBatchLogEntries(params: {
+    askBus: AskBus;
+    turnNumber: number;
+    timestamp: string;
+}): LogEntry[];

package/dist/sdk/agent-result-log.js

@@ -0,0 +1,45 @@
+import { getTurnResultLogMetadata, getVisibleAssistantMessage } from './visible-turn.js';
+function getOutputMetrics(message) {
+    return {
+        output_lines: message.split('\n').length,
+        output_chars: message.length,
+    };
+}
+export function buildModelAgentResultLogEntry(params) {
+    const assistantMessage = params.assistantMessage ?? getVisibleAssistantMessage(params.turnResult);
+    return {
+        type: 'agent_result',
+        timestamp: params.timestamp,
+        ...(params.turnNumber === undefined ? {} : { turn_number: params.turnNumber }),
+        output: params.turnResult.rawOutput,
+        assistant_message: assistantMessage,
+        ...getTurnResultLogMetadata(params.turnResult),
+        ...(params.durationMs === undefined ? {} : { duration_ms: params.durationMs }),
+        // Per-turn cost when the upstream provider reports it.
+        // Conditionally spread so agents without cost data
+        // never produce a zero-valued field that could be mistaken for
+        // a free turn.
+        ...(params.turnResult.costUsd !== undefined ? { cost_usd: params.turnResult.costUsd } : {}),
+        ...getOutputMetrics(assistantMessage),
+    };
+}
+/**
+ * Build one `ask_batch` LogEntry per AskBus batch emitted in the given turn.
+ * Callers push these to the session log before the `agent_result` entry for
+ * that turn.
+ */
+export function buildAskBatchLogEntries(params) {
+    const batches = params.askBus.snapshot(params.turnNumber);
+    return batches.map((batch) => ({
+        type: 'ask_batch',
+        timestamp: params.timestamp,
+        turn_number: batch.turnNumber,
+        batch_id: batch.batchId,
+        source: batch.source,
+        lifecycle: batch.lifecycle,
+        source_tool: batch.sourceTool,
+        ...(batch.toolUseId ? { tool_use_id: batch.toolUseId } : {}),
+        question_count: batch.questions.length,
+        ...(batch.lifecycle === 'live' ? { resolved: batch.resolution !== null } : {}),
+    }));
+}

package/dist/sdk/agent.d.ts

@@ -0,0 +1,4 @@
+import type { Agent, AgentOptions } from './types.js';
+import { type VerboseSink } from '../reporters/verbose-emitter.js';
+export declare function __setVerboseSinkForTesting(sink: VerboseSink | null): void;
+export declare function createAgent(opts: AgentOptions): Promise<Agent>;