@wix/pathgrade 0.29.0

package/dist/types.d.ts

@@ -0,0 +1,372 @@
+import type { DiagnosticsReport } from './reporters/diagnostics.js';
+import type { RuntimePolicyDescriptor } from './sdk/runtime-policy.js';
+import type { LLMPort } from './utils/llm-types.js';
+export interface CommandResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    timedOut?: boolean;
+    killed?: boolean;
+}
+export interface TurnCommand extends CommandResult {
+    command: string;
+}
+export type ConversationReplySource = 'opener' | 'reaction' | 'persona_llm';
+export interface ConversationTurn {
+    turn_number: number;
+    user_message: string;
+    user_message_source: ConversationReplySource;
+    raw_agent_output: string;
+    assistant_message: string;
+    duration_ms: number;
+    commands: TurnCommand[];
+    turn_status: 'completed' | 'error' | 'timeout';
+    step_scorer_results?: ScorerResult[];
+    tool_events?: import('./tool-events.js').ToolEvent[];
+}
+export type ConversationCompletionReason = 'max_turns' | 'signal' | 'done_phrase' | 'done_when' | 'timeout' | 'no_replies' | 'error';
+export interface ScorerResult {
+    scorer_type: string;
+    score: number;
+    weight: number;
+    details: string;
+    status?: import('./sdk/types.js').ScorerStatus;
+}
+/**
+ * JSON contract for deterministic scorer stdout.
+ * The scorer script must print a JSON object matching this shape to stdout.
+ */
+export interface ScorerOutput {
+    /** Score between 0.0 and 1.0 (required). Clamped by pathgrade. */
+    score: number;
+    /** Human-readable summary (optional). */
+    details?: string;
+    /** Per-check breakdown, rendered as checkmarks in reports (optional). */
+    checks?: ScorerCheck[];
+}
+/** Individual check result within a ScorerOutput. */
+export interface ScorerCheck {
+    name: string;
+    passed: boolean;
+    message?: string;
+}
+export interface JudgeToolCallLogData {
+    /** Tool name (readFile | listDir | grep | getToolEvents). */
+    name: string;
+    /** Arguments the LLM passed to the tool. */
+    input: unknown;
+    /** True if the tool returned content; false if it errored. */
+    ok: boolean;
+    /** Bytes of content returned to the LLM (0 on error). */
+    bytes: number;
+    /** Error message when ok is false. */
+    errorMessage?: string;
+    /** The owning judge scorer's name, for per-judge reporting. */
+    judge_name: string;
+}
+export interface LogEntry {
+    type: 'agent_start' | 'command' | 'agent_result' | 'scorer' | 'reward' | 'user_reply' | 'step_scorer' | 'tool_event' | 'conversation_end' | 'judge_tool_call' | 'ask_batch';
+    timestamp: string;
+    instruction?: string;
+    command?: string;
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number;
+    output?: string;
+    assistant_message?: string;
+    assistant_message_source?: VisibleAssistantMessageSource | 'blocked_prompt';
+    raw_assistant_message?: string;
+    value?: number;
+    scorer_result?: ScorerResult;
+    turn_number?: number;
+    reply_source?: ConversationReplySource;
+    step_scorer_key?: string;
+    tool_event?: import('./tool-events.js').ToolEvent;
+    judge_tool_call?: JudgeToolCallLogData;
+    /**
+     * @deprecated Read-only compatibility for snapshots predating the
+     * blocked-prompt synthesis deletion. New writers never emit any of the
+     * `blocked_prompt_*` / `synthetic_blocked_prompt` fields, but
+     * `loadRunSnapshot` still parses them so historical run-snapshots load.
+     * Do not set these fields from new code paths.
+     */
+    synthetic_blocked_prompt?: boolean;
+    /** @deprecated See `synthetic_blocked_prompt`. */
+    blocked_prompt_source_turn?: number;
+    /** @deprecated See `synthetic_blocked_prompt`. */
+    blocked_prompt_index?: number;
+    /** @deprecated See `synthetic_blocked_prompt`. */
+    blocked_prompt_count?: number;
+    /** @deprecated See `synthetic_blocked_prompt`. */
+    blocked_prompt_source_tool?: string;
+    /** @deprecated See `synthetic_blocked_prompt`. */
+    blocked_prompt_tool_use_id?: string;
+    runtime_policies_applied?: RuntimePolicyDescriptor[];
+    /**
+     * Per-turn agent cost in USD when the upstream provider reports it (the
+     * Claude Agent SDK populates `total_cost_usd` on result messages).
+     * Written by `buildModelAgentResultLogEntry` only when the turn result
+     * carries a `costUsd` value; absent for agents that do not expose cost.
+     */
+    cost_usd?: number;
+    completion_reason?: string;
+    completion_detail?: string;
+    turn_timings?: Array<{
+        turn: number;
+        durationMs: number;
+    }>;
+    duration_ms?: number;
+    output_lines?: number;
+    output_chars?: number;
+    turn_details?: Array<{
+        turn: number;
+        durationMs: number;
+        outputLines: number;
+        outputChars: number;
+    }>;
+    reactions_fired?: Array<{
+        turn: number;
+        reactionIndex: number;
+        pattern: string;
+        reply: string;
+    }>;
+    /** Upstream batch identifier (ToolRequestUserInput itemId when available; synthesized for adapters without one). */
+    batch_id?: string;
+    /** Agent/adapter that produced the batch. */
+    source?: import('./sdk/ask-bus/types.js').AskSource;
+    /** Lifecycle tag; determines whether answers flow back and when. */
+    lifecycle?: import('./sdk/ask-bus/types.js').AskLifecycle;
+    /** Upstream tool identifier (`AskUserQuestion` | `request_user_input` | `AskQuestion`). */
+    source_tool?: string;
+    /** Upstream tool-use correlation id when available. */
+    tool_use_id?: string;
+    /** Number of questions in the batch. */
+    question_count?: number;
+    /** Present for 'live' batches; absent for 'post-hoc'. */
+    resolved?: boolean;
+}
+export interface TrialResult {
+    trial_id: number;
+    name?: string;
+    reward: number;
+    scorer_results: ScorerResult[];
+    duration_ms: number;
+    n_commands: number;
+    input_tokens: number;
+    output_tokens: number;
+    conversation_input_tokens?: number;
+    conversation_output_tokens?: number;
+    /**
+     * Sum of agent-turn `costUsd` values accumulated during the
+     * conversation, attributed at evaluation time. Today only the Claude
+     * SDK driver populates per-turn cost, so this field is set on Claude
+     * trials and absent on Codex / Cursor trials.
+     */
+    conversation_cost_usd?: number;
+    /**
+     * Sum of all known cost components (conversation + judge + …).
+     * Conservative — emitted ONLY when every included component has a
+     * known cost. Today judge LLM providers do not expose cost, so this
+     * field is never emitted; `conversation_cost_usd` is the only
+     * guaranteed cost surface until that changes.
+     */
+    total_cost_usd?: number;
+    session_log: LogEntry[];
+    skills_used?: string[];
+    diagnostics?: DiagnosticsReport;
+    conversation?: {
+        turns: ConversationTurn[];
+        total_turns: number;
+        completion_reason: ConversationCompletionReason;
+        timeout_triggered_at_turn?: number;
+    };
+}
+export interface EvalReport {
+    task: string;
+    pass_rate: number;
+    pass_at_k: number;
+    pass_pow_k: number;
+    trials: TrialResult[];
+    skills_used: string[];
+}
+/**
+ * TrialResult with `session_log` and `conversation` stripped. These fields
+ * live only in the per-group trace files; the consolidated results.json keeps
+ * the rest so consumers (preview, `pathgrade report`) can compute summaries
+ * without loading trace data.
+ */
+export type StrippedTrialResult = Omit<TrialResult, 'session_log' | 'conversation'>;
+/**
+ * Per-group entry in the consolidated `.pathgrade/results.json` report.
+ */
+export type PathgradeGroupReport = Omit<EvalReport, 'trials'> & {
+    trials: StrippedTrialResult[];
+    /** Relative path from `.pathgrade/` to the trace file for this group. */
+    trace_file: string;
+};
+/**
+ * Selection metadata merged into `PathgradeReport.selection` when
+ * `pathgrade run --changed` produced the run. Wire shape uses `snake_case`
+ * and matches the `.pathgrade/selection.json` sidecar written by the CLI.
+ *
+ * Reasons mirror `SelectionReason` from `src/affected/types.ts` (single
+ * source of truth — new variants added there propagate here automatically).
+ */
+export interface PathgradeSelectionReport {
+    base_ref: string;
+    changed_files_count: number;
+    global_match?: string;
+    selected: string[];
+    skipped: Array<{
+        file: string;
+        reason: 'no-matching-deps';
+    }>;
+}
+/**
+ * Shape of `.pathgrade/results.json` — the consolidated consolidated pathgrade
+ * run report. `version` is pinned to 1 so the `pathgrade report` command and
+ * external consumers can gate on schema revisions.
+ */
+export interface PathgradeReport {
+    version: 1;
+    timestamp: string;
+    /** `ci.threshold` from the plugin config, if configured. */
+    threshold?: number;
+    /** Weighted average of every individual trial score across all groups. */
+    overall_pass_rate: number;
+    /**
+     * Threshold check result. When `threshold` is set: `'pass'` iff
+     * `overall_pass_rate >= threshold`. Otherwise: `'pass'` iff every trial
+     * in every group passed its vitest test.
+     */
+    status: 'pass' | 'fail';
+    groups: PathgradeGroupReport[];
+    /**
+     * Present when `pathgrade run --changed` produced the run. Absent on
+     * plain `pathgrade run`. Backward compatible — older consumers ignore
+     * this field.
+     */
+    selection?: PathgradeSelectionReport;
+}
+export interface TrialPaths {
+    root: string;
+    workspace: string;
+    home: string;
+    xdg?: string;
+    xdgState?: string;
+    xdgCache?: string;
+    tmp: string;
+}
+export interface TrialRuntime {
+    handle: string;
+    workspacePath: string;
+    env: Record<string, string>;
+    paths?: TrialPaths;
+}
+export type EnvironmentHandle = string | TrialRuntime;
+export type AgentCommandRunner = (cmd: string) => Promise<CommandResult>;
+export interface AgentTurnInput {
+    message: string;
+    continueSession?: boolean;
+}
+export type VisibleAssistantMessageSource = 'assistant_message';
+export interface AgentTurnResult {
+    rawOutput: string;
+    assistantMessage: string;
+    visibleAssistantMessage: string;
+    visibleAssistantMessageSource: VisibleAssistantMessageSource;
+    exitCode: number;
+    traceOutput?: string;
+    timedOut?: boolean;
+    toolEvents: import('./tool-events.js').ToolEvent[];
+    runtimePoliciesApplied?: RuntimePolicyDescriptor[];
+    inputTokens?: number;
+    outputTokens?: number;
+    /**
+     * Optional cache-token breakdown sourced from the Claude Agent SDK's
+     * `cache_creation_input_tokens` field. Additive only — `inputTokens`
+     * still includes cache-creation volume, matching pathgrade's existing
+     * convention.
+     */
+    cacheCreationInputTokens?: number;
+    /**
+     * Optional cache-token breakdown sourced from the Claude Agent SDK's
+     * `cache_read_input_tokens` field. Additive only — `inputTokens` still
+     * includes cache-read volume.
+     */
+    cacheReadInputTokens?: number;
+    /**
+     * Optional turn cost in USD reported by providers that expose exact
+     * pricing. The Claude Agent SDK populates this from the result
+     * message's `total_cost_usd`. Other drivers (Codex, Cursor) leave it
+     * undefined until their providers expose comparable metadata.
+     */
+    costUsd?: number;
+    /**
+     * Typed error subtype set when the turn ended in error; absent on success.
+     * Lets eval consumers triage failures correctly without regex on the
+     * result text.
+     *
+     * The `error_*` values are SDK-reported result subtypes (`SDKResultError`
+     * per `sdk.d.ts`). `'bus_rejection'` is driver-synthesized: when the live
+     * ask-user bridge captures a bus error (timeout, missing subscriber,
+     * subscriber throw), the Claude SDK driver constructs an error
+     * `AgentTurnResult` with this subtype rather than throwing, so the
+     * partial-turn observability pipeline (`ask_batch`, `model_agent_result`,
+     * turn timings/details) captures the rejected turn before the runner
+     * propagates the error. The naming distinction (no `error_` prefix)
+     * marks the layer of origin: SDK vs driver.
+     */
+    errorSubtype?: 'error_during_execution' | 'error_max_turns' | 'error_max_budget_usd' | 'error_max_structured_output_retries' | 'bus_rejection';
+    /**
+     * Populated when the agent subprocess died mid-turn under a stateful
+     * transport (Codex `app-server`). Consumers should translate this into
+     * `ConversationResult.crashDiagnostic` via `AgentCrashError`.
+     */
+    crashInfo?: {
+        pid?: number;
+        signal?: NodeJS.Signals | string | null;
+        exitCode?: number | null;
+    };
+}
+export interface AgentSession {
+    start(input: AgentTurnInput): Promise<AgentTurnResult>;
+    reply(input: AgentTurnInput): Promise<AgentTurnResult>;
+    /**
+     * Optional explicit teardown hook. Drivers that hold OS resources
+     * (subprocess, stdio pipes, long-lived promises) implement this so session
+     * wrappers can release them in a `finally` block. Must be idempotent and
+     * safe to call before any turn was ever run.
+     */
+    dispose?(): Promise<void>;
+}
+export declare function getWorkspacePath(handle: EnvironmentHandle): string;
+export declare function getRuntimeHandle(handle: EnvironmentHandle): string;
+export declare function getRuntimeEnv(handle: EnvironmentHandle): Record<string, string>;
+export interface AgentSessionOptions {
+    mcpConfigPath?: string;
+    model?: string;
+    conversationWindow?: import('./sdk/types.js').ConversationWindowConfig | false;
+    runtimePolicies?: RuntimePolicyDescriptor[];
+    /** LLM port for conversation window summarization. */
+    llm?: LLMPort;
+    /**
+     * Codex transport. Claude/Cursor ignore this. When `'app-server'`, the
+     * Codex driver swaps to the reliable ask-user channel. Resolved by
+     * `createManagedSession`; option/env plumbing that feeds it lands in slice #7.
+     */
+    transport?: import('./sdk/types.js').AgentTransport;
+    /**
+     * Per-conversation bus through which adapters emit ask_user question
+     * batches and subscribers respond. Constructed by `createManagedSession`.
+     * Drivers emitting `lifecycle: 'live'` batches (Codex app-server) MUST
+     * enforce presence via `requireAskBusForLiveBatches`; adapters emitting
+     * only `lifecycle: 'post-hoc'` no-op when absent.
+     */
+    askBus?: import('./sdk/ask-bus/types.js').AskBus;
+}
+export declare abstract class BaseAgent {
+    createSession(runtime: EnvironmentHandle, runCommand: AgentCommandRunner, options?: AgentSessionOptions): Promise<AgentSession>;
+    run(_instruction: string, _workspacePath: string, _runCommand: AgentCommandRunner): Promise<string>;
+}
+export declare function createAgentSession(agent: BaseAgent, runtime: EnvironmentHandle, runCommand: AgentCommandRunner, options?: AgentSessionOptions): Promise<AgentSession>;

package/dist/types.js

@@ -0,0 +1,37 @@
+export function getWorkspacePath(handle) {
+    return typeof handle === 'string' ? handle : handle.workspacePath;
+}
+export function getRuntimeHandle(handle) {
+    return typeof handle === 'string' ? handle : handle.handle;
+}
+export function getRuntimeEnv(handle) {
+    return typeof handle === 'string' ? {} : handle.env;
+}
+export class BaseAgent {
+    async createSession(runtime, runCommand, options) {
+        // Default: wrap run() into a session for simple agents
+        const runTurn = async (message) => {
+            const rawOutput = await this.run(message, getWorkspacePath(runtime), runCommand);
+            return {
+                rawOutput,
+                assistantMessage: rawOutput,
+                visibleAssistantMessage: rawOutput,
+                visibleAssistantMessageSource: 'assistant_message',
+                exitCode: 0,
+                traceOutput: rawOutput,
+                toolEvents: [],
+                runtimePoliciesApplied: [],
+            };
+        };
+        return {
+            start: async ({ message }) => runTurn(message),
+            reply: async ({ message }) => runTurn(message),
+        };
+    }
+    run(_instruction, _workspacePath, _runCommand) {
+        throw new Error('Agent must implement createSession() or run()');
+    }
+}
+export async function createAgentSession(agent, runtime, runCommand, options) {
+    return agent.createSession(runtime, runCommand, options);
+}

package/dist/utils/cli.d.ts

@@ -0,0 +1,55 @@
+/**
+ * CLI formatting utilities.
+ *
+ * Uses ANSI codes that work on both light and dark terminals.
+ * Respects NO_COLOR env var (https://no-color.org/).
+ */
+export declare const fmt: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    green: (s: string) => string;
+    red: (s: string) => string;
+    cyan: (s: string) => string;
+    pass: (s: string) => string;
+    fail: (s: string) => string;
+};
+/** Print a section header with a rule line */
+export declare function header(title: string, width?: number): void;
+/** Print a labeled key-value pair */
+export declare function kv(label: string, value: string, indent?: number): void;
+/** Print a trial result row */
+export declare function trialRow(trialId: number, total: number, reward: number, duration: string, commands: number, scorers: {
+    type: string;
+    score: number;
+}[]): void;
+/** Print the results summary block */
+export declare function resultsSummary(passRate: number, passAtK: number, passPowK: number, trials: number, preset?: string): void;
+/** Print a validation result */
+export declare function validationResult(passed: boolean, reward: number, scorers: {
+    type: string;
+    score: number;
+    details: string;
+}[]): void;
+/**
+ * In-place spinner that shows current phase + elapsed time on one line.
+ *
+ * Usage:
+ *   const s = new Spinner('1/3', 'building image');
+ *   s.update('running agent');
+ *   s.update('grading');
+ *   s.stop('PASS  0.85  120.3s  2 cmds');
+ */
+export declare class Spinner {
+    private frames;
+    private frameIdx;
+    private interval;
+    private prefix;
+    private phase;
+    private startTime;
+    constructor(label: string, initialPhase: string);
+    private render;
+    /** Update the spinner's phase text */
+    update(phase: string): void;
+    /** Stop the spinner and print the final line (replaces the spinner) */
+    stop(finalLine: string): void;
+}

package/dist/utils/cli.js

@@ -0,0 +1,131 @@
+/**
+ * CLI formatting utilities.
+ *
+ * Uses ANSI codes that work on both light and dark terminals.
+ * Respects NO_COLOR env var (https://no-color.org/).
+ */
+const NO_COLOR = !!process.env.NO_COLOR;
+const code = (n) => NO_COLOR ? '' : `\x1b[${n}m`;
+const reset = code('0');
+const bold = code('1');
+const dim = code('2');
+const green = code('32');
+const red = code('31');
+const cyan = code('36');
+export const fmt = {
+    bold: (s) => `${bold}${s}${reset}`,
+    dim: (s) => `${dim}${s}${reset}`,
+    green: (s) => `${green}${s}${reset}`,
+    red: (s) => `${red}${s}${reset}`,
+    cyan: (s) => `${cyan}${s}${reset}`,
+    pass: (s) => `${bold}${green}${s}${reset}`,
+    fail: (s) => `${bold}${red}${s}${reset}`,
+};
+/** Print a section header with a rule line */
+export function header(title, width = 60) {
+    const rule = '─'.repeat(Math.max(0, width - title.length - 3));
+    console.log(`\n${fmt.bold(`── ${title} `)}${fmt.dim(rule)}`);
+}
+/** Print a labeled key-value pair */
+export function kv(label, value, indent = 2) {
+    const pad = ' '.repeat(indent);
+    const labelPad = label.padEnd(12);
+    console.log(`${pad}${fmt.dim(labelPad)}${value}`);
+}
+/** Print a trial result row */
+export function trialRow(trialId, total, reward, duration, commands, scorers) {
+    const pad = '  ';
+    const status = reward >= 0.5 ? fmt.pass('PASS') : fmt.fail('FAIL');
+    const rewardStr = reward.toFixed(2);
+    const trialLabel = `${trialId}/${total}`.padEnd(6);
+    const scorerStr = scorers.map(g => {
+        const name = g.type === 'deterministic' ? 'deterministic' : 'llm_rubric';
+        const scoreStr = g.score.toFixed(2);
+        const color = g.score >= 0.5 ? fmt.green(scoreStr) : fmt.red(scoreStr);
+        return `${fmt.dim(name)} ${color}`;
+    }).join('  ');
+    console.log(`${pad}  ${fmt.dim(trialLabel)} ${status}  ${fmt.bold(rewardStr)}  ${fmt.dim(duration.padEnd(7))} ${fmt.dim(commands + ' cmds')}  ${scorerStr}`);
+}
+/** Print the results summary block */
+export function resultsSummary(passRate, passAtK, passPowK, trials, preset) {
+    const presetLabel = preset === 'smoke' ? ' (smoke test)'
+        : preset === 'reliable' ? ' (reliable)'
+            : preset === 'regression' ? ' (regression)'
+                : '';
+    header(`Results${presetLabel}`);
+    const fmtPct = (v) => `${(v * 100).toFixed(1)}%`.padStart(7);
+    const marker = (key) => preset === key ? fmt.cyan(' ◂') : '';
+    console.log(`    Pass Rate  ${fmt.bold(fmtPct(passRate))}${marker('reliable')}`);
+    console.log(`    pass@${trials}     ${fmtPct(passAtK)}${marker('smoke')}`);
+    console.log(`    pass^${trials}     ${fmtPct(passPowK)}${marker('regression')}`);
+    console.log();
+}
+/** Print a validation result */
+export function validationResult(passed, reward, scorers) {
+    for (const g of scorers) {
+        const scoreStr = g.score.toFixed(2);
+        const color = g.score >= 0.5 ? fmt.green(scoreStr) : fmt.red(scoreStr);
+        console.log(`    ${fmt.dim(g.type.padEnd(16))} ${color}  ${fmt.dim(g.details.substring(0, 60))}`);
+    }
+    console.log();
+    if (passed) {
+        console.log(`    ${fmt.pass('PASSED')}  reward ${fmt.bold(reward.toFixed(2))}`);
+    }
+    else {
+        console.log(`    ${fmt.fail('FAILED')}  reward ${fmt.bold(reward.toFixed(2))}`);
+    }
+    console.log();
+}
+/**
+ * In-place spinner that shows current phase + elapsed time on one line.
+ *
+ * Usage:
+ *   const s = new Spinner('1/3', 'building image');
+ *   s.update('running agent');
+ *   s.update('grading');
+ *   s.stop('PASS  0.85  120.3s  2 cmds');
+ */
+export class Spinner {
+    frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    frameIdx = 0;
+    interval = null;
+    prefix;
+    phase;
+    startTime;
+    constructor(label, initialPhase) {
+        this.prefix = `    ${fmt.dim(label.padEnd(6))}`;
+        this.phase = initialPhase;
+        this.startTime = Date.now();
+        if (process.stdout.isTTY && !NO_COLOR) {
+            this.interval = setInterval(() => this.render(), 80);
+            this.render();
+        }
+        else {
+            // Non-TTY: just print once
+            process.stdout.write(`${this.prefix} ${fmt.dim(this.phase)}\n`);
+        }
+    }
+    render() {
+        const frame = this.frames[this.frameIdx % this.frames.length];
+        this.frameIdx++;
+        const elapsed = ((Date.now() - this.startTime) / 1000).toFixed(0);
+        const line = `${this.prefix} ${fmt.cyan(frame)} ${fmt.dim(this.phase)}  ${fmt.dim(elapsed + 's')}`;
+        process.stdout.write(`\r\x1b[K${line}`);
+    }
+    /** Update the spinner's phase text */
+    update(phase) {
+        this.phase = phase;
+        if (!this.interval) {
+            // Non-TTY: print each phase
+            process.stdout.write(`${this.prefix} ${fmt.dim(this.phase)}\n`);
+        }
+    }
+    /** Stop the spinner and print the final line (replaces the spinner) */
+    stop(finalLine) {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+        process.stdout.write(`\r\x1b[K${this.prefix} ${finalLine}\n`);
+    }
+}

package/dist/utils/env.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared .env file parser.
+ */
+/**
+ * Parse a .env file content into key-value pairs.
+ * Supports: KEY=VALUE, KEY="VALUE", KEY='VALUE', comments (#), blank lines.
+ */
+export declare function parseEnvFile(content: string): Record<string, string>;

package/dist/utils/env.js

@@ -0,0 +1,26 @@
+/**
+ * Shared .env file parser.
+ */
+/**
+ * Parse a .env file content into key-value pairs.
+ * Supports: KEY=VALUE, KEY="VALUE", KEY='VALUE', comments (#), blank lines.
+ */
+export function parseEnvFile(content) {
+    const env = {};
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eqIdx = trimmed.indexOf('=');
+        if (eqIdx === -1)
+            continue;
+        const key = trimmed.substring(0, eqIdx).trim();
+        let value = trimmed.substring(eqIdx + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        env[key] = value;
+    }
+    return env;
+}

package/dist/utils/llm-mocks.d.ts

@@ -0,0 +1,43 @@
+import type { LLMPort, LLMCallOptions, ToolUseMessage, ToolUseBlock, CallWithToolsOptions } from './llm-types.js';
+export type MockResponse = string | {
+    text: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    provider?: 'anthropic' | 'openai' | 'cli';
+    model?: string;
+} | {
+    kind: 'tool_use';
+    blocks: ToolUseBlock[];
+    text?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+} | {
+    kind: 'final';
+    text: string;
+    inputTokens?: number;
+    outputTokens?: number;
+} | {
+    throws: Error;
+};
+export interface CreateMockLLMOptions {
+    responses?: MockResponse[];
+    /** Returned whenever the queue is empty. Overrides the default "out of responses" error. */
+    defaultResponse?: MockResponse;
+    /** When set, replaces the queue for `.call()`. Useful for dynamic / side-effecting tests. */
+    respond?: (prompt: string, opts?: LLMCallOptions) => MockResponse | Promise<MockResponse>;
+}
+export interface MockCallRecord {
+    prompt: string;
+    opts?: LLMCallOptions;
+}
+export interface MockToolCallRecord {
+    messages: ToolUseMessage[];
+    opts: CallWithToolsOptions;
+}
+export interface MockLLM extends LLMPort {
+    queueResponse(r: MockResponse): void;
+    clearCalls(): void;
+    readonly calls: readonly MockCallRecord[];
+    readonly toolCalls: readonly MockToolCallRecord[];
+}
+export declare function createMockLLM(opts?: CreateMockLLMOptions): MockLLM;