@sebastiantuyu/agest 0.3.2 → 0.3.3-next.10

package/dist/preview.js

@@ -189,6 +189,91 @@ function renderFailedCases(cases) {
           </ul>
         </details>`;
 }
+const WF_MODEL = "#38bdf8";
+const WF_TOOL = "#facc15";
+const WF_ERROR = "#f87171";
+function fmtUsdHtml(n) {
+    if (n === 0)
+        return "$0";
+    return "$" + Number(n.toFixed(4)).toString();
+}
+/**
+ * Chrome-DevTools-style waterfall for a report's per-scene timelines. Bars are
+ * absolutely positioned within a track by start_ms / duration_ms. Returns "" if
+ * the report carries no timeline data (older reports / non-traced executors).
+ */
+function renderWaterfallHtml(report) {
+    const scenes = (report.scenes ?? []).filter((s) => s.timeline && s.timeline.length > 0);
+    if (scenes.length === 0)
+        return "";
+    const sceneBlocks = scenes
+        .map((scene) => {
+        const events = scene.timeline;
+        const t0 = Math.min(...events.map((e) => e.startMs));
+        const tEnd = Math.max(...events.map((e) => e.startMs + e.durationMs));
+        const span = Math.max(1, tEnd - t0);
+        const rows = events
+            .map((e) => {
+            const left = ((e.startMs - t0) / span) * 100;
+            const width = Math.max(0.6, (e.durationMs / span) * 100);
+            const bg = e.error ? WF_ERROR : e.kind === "model" ? WF_MODEL : WF_TOOL;
+            const icon = e.kind === "model" ? "◆" : "▸";
+            const tip = [
+                `${e.kind}: ${e.name}`,
+                `start ${Math.round(e.startMs)}ms · ${Math.round(e.durationMs)}ms`,
+                e.tokens ? `${e.tokens.input}→${e.tokens.output} tok` : "",
+                e.cachedInputTokens ? `${e.cachedInputTokens} cached` : "",
+                e.costUsd != null ? fmtUsdHtml(e.costUsd) : "",
+                e.error ? `error: ${e.error}` : "",
+            ]
+                .filter(Boolean)
+                .join(" · ");
+            const cost = e.costUsd != null ? fmtUsdHtml(e.costUsd) : "";
+            return `
+            <div class="flex items-center gap-2 text-[11px] leading-5">
+              <span class="w-44 shrink-0 truncate ${e.error ? "text-red-400" : "text-zinc-400"}" title="${escHtml(e.name)}">
+                <span style="color:${bg}">${icon}</span> ${escHtml(e.name)}
+              </span>
+              <div class="relative flex-1 h-3 bg-zinc-800/40 rounded">
+                <div class="absolute top-0 h-3 rounded" style="left:${left.toFixed(2)}%;width:${width.toFixed(2)}%;background:${bg}" title="${escHtml(tip)}"></div>
+              </div>
+              <span class="w-16 shrink-0 text-right text-zinc-500">${Math.round(e.durationMs)}ms</span>
+              <span class="w-16 shrink-0 text-right text-zinc-500">${cost}</span>
+            </div>`;
+        })
+            .join("\n");
+        const meta = [
+            scene.tokens ? `${scene.tokens.input}→${scene.tokens.output} tok` : "",
+            scene.costUsd != null ? fmtUsdHtml(scene.costUsd) : "",
+            scene.costSource ? scene.costSource : "",
+            scene.durationMs != null ? `${Math.round(scene.durationMs)}ms` : "",
+        ]
+            .filter(Boolean)
+            .join(" · ");
+        return `
+        <div>
+          <div class="flex items-center justify-between mb-1.5">
+            <span class="text-xs text-zinc-300 truncate" title="${escHtml(scene.prompt)}">${escHtml(scene.prompt)}</span>
+            <span class="text-[11px] text-zinc-500 shrink-0 ml-3">${escHtml(meta)}</span>
+          </div>
+          <div class="space-y-1">${rows}</div>
+        </div>`;
+    })
+        .join("\n");
+    return `
+    <details class="mt-2" open>
+      <summary class="text-xs text-sky-400 cursor-pointer hover:text-sky-300 select-none">
+        waterfall &middot; ${scenes.length} scene${scenes.length !== 1 ? "s" : ""}
+      </summary>
+      <div class="mt-3 mb-2 pl-3 border-l border-zinc-800 space-y-5">
+        <div class="flex gap-4 text-[10px] text-zinc-500">
+          <span><span style="color:${WF_MODEL}">◆</span> model</span>
+          <span><span style="color:${WF_TOOL}">▸</span> tool</span>
+        </div>
+        ${sceneBlocks}
+      </div>
+    </details>`;
+}
 function renderRunRow(entry, idx) {
     const { report, delta, diffLines } = entry;
     const pct = report.successRate * 100;
@@ -233,6 +318,7 @@ function renderRunRow(entry, idx) {
           </div>
           <div class="ml-10 mt-0.5 flex gap-3 flex-wrap">${dimTags}</div>
           ${diffHtml}
+          <div class="ml-10">${renderWaterfallHtml(report)}</div>
         </div>`;
 }
 // ---------------------------------------------------------------------------
@@ -990,6 +1076,12 @@ function renderSingleRun(report) {
           <p class="text-zinc-300">${Math.round(report.averageOutputTokensPerCase)}</p>
         </div>`
         : ""}
+        ${report.totalCostUsd != null
+        ? `<div>
+          <span class="text-zinc-500">Total Cost</span>
+          <p class="text-zinc-300">${fmtUsdHtml(report.totalCostUsd)}${report.totalInputTokens != null ? ` <span class="text-zinc-600">· ${report.totalInputTokens}→${report.totalOutputTokens} tok</span>` : ""}</p>
+        </div>`
+        : ""}
         ${report.tools && report.tools.length > 0
         ? `<div>
           <span class="text-zinc-500">Tools</span>
@@ -997,6 +1089,7 @@ function renderSingleRun(report) {
         </div>`
         : ""}
       </div>
+      ${renderWaterfallHtml(report)}
       ${failedSection}
     </div>`;
 }

package/dist/pricing/index.d.ts

@@ -0,0 +1,32 @@
+export interface ModelPrice {
+    /** USD per 1M input tokens */
+    input: number;
+    /** USD per 1M output tokens */
+    output: number;
+    /**
+     * USD per 1M cached (prompt-cache-hit) input tokens. When omitted, cached
+     * tokens are billed at `DEFAULT_CACHE_MULTIPLIER` × the input rate.
+     */
+    cachedInput?: number;
+}
+/** Fraction of the input rate charged for cache-hit tokens when no explicit rate is set. */
+export declare const DEFAULT_CACHE_MULTIPLIER = 0.1;
+export type CostSource = "provider" | "table" | "unavailable";
+export interface CostBreakdown {
+    inputUsd?: number;
+    outputUsd?: number;
+    totalUsd?: number;
+    source: CostSource;
+}
+export declare function setPricingOverrides(table?: Record<string, ModelPrice>): void;
+export declare function lookupPrice(model: string | undefined): ModelPrice | undefined;
+export interface ComputeCostInput {
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    /** Cache-hit input tokens (subset of inputTokens), billed at the cached rate. */
+    cachedInputTokens?: number;
+    /** USD cost the provider already reported (takes precedence) */
+    providerCost?: number;
+}
+export declare function computeCost(input: ComputeCostInput): CostBreakdown;

package/dist/pricing/index.js

@@ -0,0 +1,48 @@
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+/** Fraction of the input rate charged for cache-hit tokens when no explicit rate is set. */
+export const DEFAULT_CACHE_MULTIPLIER = 0.1;
+const here = dirname(fileURLToPath(import.meta.url));
+const builtIn = JSON.parse(readFileSync(join(here, "models.json"), "utf-8"));
+let overrides = {};
+export function setPricingOverrides(table) {
+    overrides = table ?? {};
+}
+export function lookupPrice(model) {
+    if (!model)
+        return undefined;
+    if (overrides[model])
+        return overrides[model];
+    if (builtIn[model])
+        return builtIn[model];
+    // Loose suffix/prefix match — pick the longest matching key
+    const lowered = model.toLowerCase();
+    const keys = Object.keys({ ...builtIn, ...overrides })
+        .filter((k) => lowered.includes(k.toLowerCase()) || k.toLowerCase().includes(lowered))
+        .sort((a, b) => b.length - a.length);
+    if (keys.length > 0) {
+        return overrides[keys[0]] ?? builtIn[keys[0]];
+    }
+    return undefined;
+}
+export function computeCost(input) {
+    if (input.providerCost != null && Number.isFinite(input.providerCost)) {
+        return { totalUsd: input.providerCost, source: "provider" };
+    }
+    const price = lookupPrice(input.model);
+    if (!price)
+        return { source: "unavailable" };
+    const totalInput = input.inputTokens ?? 0;
+    const cached = Math.min(input.cachedInputTokens ?? 0, totalInput);
+    const uncached = totalInput - cached;
+    const cachedRate = price.cachedInput ?? price.input * DEFAULT_CACHE_MULTIPLIER;
+    const inputUsd = (uncached / 1_000_000) * price.input + (cached / 1_000_000) * cachedRate;
+    const outputUsd = ((input.outputTokens ?? 0) / 1_000_000) * price.output;
+    return {
+        inputUsd,
+        outputUsd,
+        totalUsd: inputUsd + outputUsd,
+        source: "table",
+    };
+}

package/dist/pricing/models.json

@@ -0,0 +1,21 @@
+{
+  "claude-opus-4-7": { "input": 15, "output": 75 },
+  "claude-opus-4-6": { "input": 15, "output": 75 },
+  "claude-opus-4-5": { "input": 15, "output": 75 },
+  "claude-sonnet-4-6": { "input": 3, "output": 15 },
+  "claude-sonnet-4-5": { "input": 3, "output": 15 },
+  "claude-haiku-4-5": { "input": 1, "output": 5 },
+  "claude-3-5-sonnet-20241022": { "input": 3, "output": 15 },
+  "claude-3-5-haiku-20241022": { "input": 0.8, "output": 4 },
+  "claude-3-opus-20240229": { "input": 15, "output": 75 },
+  "gpt-4o": { "input": 2.5, "output": 10 },
+  "gpt-4o-mini": { "input": 0.15, "output": 0.6 },
+  "gpt-4.1": { "input": 2, "output": 8 },
+  "gpt-4.1-mini": { "input": 0.4, "output": 1.6 },
+  "gpt-4.1-nano": { "input": 0.1, "output": 0.4 },
+  "gpt-5": { "input": 1.25, "output": 10 },
+  "gpt-5-mini": { "input": 0.25, "output": 2 },
+  "o1": { "input": 15, "output": 60 },
+  "o1-mini": { "input": 1.1, "output": 4.4 },
+  "o3-mini": { "input": 1.1, "output": 4.4 }
+}

package/dist/reporter.d.ts

@@ -1,4 +1,4 @@
 import type { AgentReport } from "./types";
-export declare function formatReport(report: AgentReport): string;
+export declare function formatReport(report: AgentReport<unknown>): string;
 export declare function writeReport(content: string, timestamp: string, name?: string, dimensions?: Record<string, string>): Promise<string>;
 export declare function writeDiffEntry(hash: string, systemPrompt: string, tools: string[], model?: string): Promise<void>;

package/dist/reporter.js

@@ -1,6 +1,7 @@
 import { access, mkdir, writeFile } from "fs/promises";
 import { createHash } from "crypto";
 import { join } from "path";
+import { resolveText } from "./resolve";
 export function formatReport(report) {
     const lines = ["agent:"];
     if (report.name)
@@ -24,8 +25,9 @@ export function formatReport(report) {
                 lines.push(`          reason: "${reason}"`);
             }
             const result = report.results.find((r) => r.prompt === c);
-            if (result?.response.text) {
-                const escaped = result.response.text.replace(/"/g, '\\"').replace(/\n/g, '\\n');
+            const responseText = result ? resolveText(result.response) : "";
+            if (responseText) {
+                const escaped = responseText.replace(/"/g, '\\"').replace(/\n/g, '\\n');
                 lines.push(`          response: "${escaped}"`);
             }
         }
@@ -51,8 +53,9 @@ export function formatReport(report) {
                     if (r.error) {
                         lines.push(`                reason: "${r.error}"`);
                     }
-                    if (r.response.text) {
-                        const escaped = r.response.text.replace(/"/g, '\\"').replace(/\n/g, '\\n');
+                    const responseText = resolveText(r.response);
+                    if (responseText) {
+                        const escaped = responseText.replace(/"/g, '\\"').replace(/\n/g, '\\n');
                         lines.push(`                response: "${escaped}"`);
                     }
                 }
@@ -78,8 +81,78 @@ export function formatReport(report) {
     if (report.averageOutputTokensPerCase != null) {
         lines.push(`    average_output_tokens_per_case: ${report.averageOutputTokensPerCase}`);
     }
+    if (report.totalInputTokens != null) {
+        lines.push(`    total_input_tokens: ${report.totalInputTokens}`);
+    }
+    if (report.totalOutputTokens != null) {
+        lines.push(`    total_output_tokens: ${report.totalOutputTokens}`);
+    }
+    if (report.totalCostUsd != null) {
+        lines.push(`    total_cost_usd: ${formatUsd(report.totalCostUsd)}`);
+    }
+    const observedScenes = report.results.filter((r) => r.tokens || r.costUsd != null || (r.events && r.events.length));
+    if (observedScenes.length > 0) {
+        lines.push(`    scenes:`);
+        for (const r of observedScenes) {
+            lines.push(...renderSceneObservability(r));
+        }
+    }
     return lines.join("\n");
 }
+function renderSceneObservability(r) {
+    const out = [];
+    const promptLabel = r.prompt.length > 80 ? r.prompt.slice(0, 77) + "..." : r.prompt;
+    out.push(`        - prompt: "${escapeYaml(promptLabel)}"`);
+    out.push(`          duration_ms: ${Math.round(r.duration)}`);
+    if (r.tokens) {
+        out.push(`          tokens: { input: ${r.tokens.input}, output: ${r.tokens.output} }`);
+    }
+    if (r.costUsd != null) {
+        const source = r.costSource ?? "table";
+        out.push(`          cost_usd: ${formatUsd(r.costUsd)}`);
+        out.push(`          cost_source: ${source}`);
+    }
+    if (r.events && r.events.length) {
+        out.push(`          timeline:`);
+        for (const e of r.events) {
+            out.push(...renderTimelineEvent(e));
+        }
+    }
+    return out;
+}
+function renderTimelineEvent(e) {
+    const out = [];
+    out.push(`              - kind: ${e.kind}`);
+    out.push(`                name: "${escapeYaml(e.name)}"`);
+    out.push(`                start_ms: ${Math.round(e.startMs)}`);
+    out.push(`                duration_ms: ${Math.round(e.durationMs)}`);
+    if (e.tokens) {
+        out.push(`                tokens: { input: ${e.tokens.input}, output: ${e.tokens.output} }`);
+    }
+    if (e.cachedInputTokens != null && e.cachedInputTokens > 0) {
+        out.push(`                cached_input_tokens: ${e.cachedInputTokens}`);
+    }
+    if (e.cost?.totalUsd != null) {
+        out.push(`                cost_usd: ${formatUsd(e.cost.totalUsd)}`);
+        out.push(`                cost_source: ${e.cost.source}`);
+    }
+    if (e.runIndex != null) {
+        out.push(`                run_index: ${e.runIndex}`);
+    }
+    if (e.error) {
+        out.push(`                error: "${escapeYaml(e.error)}"`);
+    }
+    return out;
+}
+function formatUsd(n) {
+    if (n === 0)
+        return "0";
+    // Up to 6 decimal places, but trim trailing zeros for compactness
+    return Number(n.toFixed(6)).toString();
+}
+function escapeYaml(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
 export async function writeReport(content, timestamp, name, dimensions) {
     const reportsDir = join(process.cwd(), ".reports");
     await mkdir(reportsDir, { recursive: true });

package/dist/reports.d.ts

@@ -9,6 +9,32 @@ export interface ParsedSuiteResult {
         response?: string;
     }>;
 }
+export interface ParsedTimelineEvent {
+    kind: "model" | "tool";
+    name: string;
+    startMs: number;
+    durationMs: number;
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    cachedInputTokens?: number;
+    costUsd?: number;
+    costSource?: string;
+    runIndex?: number;
+    error?: string;
+}
+export interface ParsedScene {
+    prompt: string;
+    durationMs?: number;
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    costUsd?: number;
+    costSource?: string;
+    timeline?: ParsedTimelineEvent[];
+}
 export interface ParsedReport {
     name?: string;
     systemPromptHash?: string;
@@ -28,6 +54,10 @@ export interface ParsedReport {
     timestamp: string;
     averageInputTokensPerCase?: number;
     averageOutputTokensPerCase?: number;
+    totalInputTokens?: number;
+    totalOutputTokens?: number;
+    totalCostUsd?: number;
+    scenes?: ParsedScene[];
     suites?: ParsedSuiteResult[];
     source: string;
 }
@@ -44,6 +74,13 @@ export declare function parseFailedCases(content: string): Array<{
 }>;
 export declare function parseDimensions(content: string): Record<string, string> | undefined;
 export declare function parseSuites(content: string): ParsedSuiteResult[] | undefined;
+/**
+ * Parse the `scenes:` block (per-scene tokens/cost + timeline waterfall) from a
+ * report. The emitted format is fixed (see reporter.ts `renderSceneObservability`),
+ * so this hand-parses by indentation: scenes start at 8 spaces, scene fields at
+ * 10, timeline events at 14, event fields at 16.
+ */
+export declare function parseScenes(content: string): ParsedScene[] | undefined;
 export declare function parseReport(content: string, source: string): ParsedReport;
 export declare function findReports(dir: string, depth?: number): Promise<string[]>;
 export declare function loadDiffEntry(hash: string): Promise<DiffEntry | null>;

package/dist/reports.js

@@ -124,6 +124,124 @@ export function parseSuites(content) {
         suites.push(current);
     return suites.length > 0 ? suites : undefined;
 }
+function parseTokens(raw) {
+    const m = raw.match(/input:\s*(\d+),\s*output:\s*(\d+)/);
+    if (!m)
+        return undefined;
+    return { input: parseInt(m[1], 10), output: parseInt(m[2], 10) };
+}
+/**
+ * Parse the `scenes:` block (per-scene tokens/cost + timeline waterfall) from a
+ * report. The emitted format is fixed (see reporter.ts `renderSceneObservability`),
+ * so this hand-parses by indentation: scenes start at 8 spaces, scene fields at
+ * 10, timeline events at 14, event fields at 16.
+ */
+export function parseScenes(content) {
+    const lines = content.split("\n");
+    const startIdx = lines.findIndex((l) => l === "    scenes:");
+    if (startIdx === -1)
+        return undefined;
+    const scenes = [];
+    let scene;
+    let inTimeline = false;
+    let event;
+    const pushEvent = () => {
+        if (event && scene) {
+            (scene.timeline ??= []).push(event);
+            event = undefined;
+        }
+    };
+    const pushScene = () => {
+        pushEvent();
+        if (scene)
+            scenes.push(scene);
+        scene = undefined;
+        inTimeline = false;
+    };
+    for (let i = startIdx + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === "")
+            continue;
+        const indent = line.length - line.trimStart().length;
+        // A new top-level agent field (<= 4 spaces, not part of scenes) ends the block.
+        if (indent <= 4)
+            break;
+        const sceneStart = line.match(/^        - prompt: "(.*)"$/);
+        if (sceneStart) {
+            pushScene();
+            scene = { prompt: sceneStart[1].replace(/\\"/g, '"').replace(/\\n/g, "\n") };
+            continue;
+        }
+        if (!scene)
+            continue;
+        const eventStart = line.match(/^              - kind: (model|tool)$/);
+        if (eventStart) {
+            pushEvent();
+            event = { kind: eventStart[1], name: "", startMs: 0, durationMs: 0 };
+            inTimeline = true;
+            continue;
+        }
+        if (line.match(/^          timeline:$/)) {
+            inTimeline = true;
+            continue;
+        }
+        const trimmed = line.trim();
+        const target = inTimeline && event ? "event" : "scene";
+        const kv = trimmed.match(/^([a-z_]+):\s*(.*)$/);
+        if (!kv)
+            continue;
+        const [, key, value] = kv;
+        if (target === "event" && event) {
+            switch (key) {
+                case "name":
+                    event.name = value.replace(/^"|"$/g, "").replace(/\\"/g, '"');
+                    break;
+                case "start_ms":
+                    event.startMs = parseFloat(value);
+                    break;
+                case "duration_ms":
+                    event.durationMs = parseFloat(value);
+                    break;
+                case "tokens":
+                    event.tokens = parseTokens(value);
+                    break;
+                case "cached_input_tokens":
+                    event.cachedInputTokens = parseInt(value, 10);
+                    break;
+                case "cost_usd":
+                    event.costUsd = parseFloat(value);
+                    break;
+                case "cost_source":
+                    event.costSource = value;
+                    break;
+                case "run_index":
+                    event.runIndex = parseInt(value, 10);
+                    break;
+                case "error":
+                    event.error = value.replace(/^"|"$/g, "").replace(/\\"/g, '"');
+                    break;
+            }
+        }
+        else if (scene) {
+            switch (key) {
+                case "duration_ms":
+                    scene.durationMs = parseFloat(value);
+                    break;
+                case "tokens":
+                    scene.tokens = parseTokens(value);
+                    break;
+                case "cost_usd":
+                    scene.costUsd = parseFloat(value);
+                    break;
+                case "cost_source":
+                    scene.costSource = value;
+                    break;
+            }
+        }
+    }
+    pushScene();
+    return scenes.length > 0 ? scenes : undefined;
+}
 export function parseReport(content, source) {
     const num = (key, fallback = 0) => parseFloat(extractField(content, key) ?? String(fallback));
     const avgIn = extractField(content, "average_input_tokens_per_case");
@@ -158,9 +276,17 @@ export function parseReport(content, source) {
         timestamp: extractField(content, "timestamp") ?? "",
         averageInputTokensPerCase: avgIn != null ? parseFloat(avgIn) : undefined,
         averageOutputTokensPerCase: avgOut != null ? parseFloat(avgOut) : undefined,
+        totalInputTokens: optNum("total_input_tokens"),
+        totalOutputTokens: optNum("total_output_tokens"),
+        totalCostUsd: optNum("total_cost_usd"),
+        scenes: parseScenes(content),
         suites: parseSuites(content),
         source,
     };
+    function optNum(key) {
+        const v = extractField(content, key);
+        return v != null ? parseFloat(v) : undefined;
+    }
 }
 export async function findReports(dir, depth = 0) {
     if (depth > 6)

package/dist/resolve.d.ts

@@ -0,0 +1,25 @@
+import type { AgentResponse } from "./types";
+/**
+ * Serialize an arbitrary agent value to the string view the judge model and
+ * the text matchers consume. Strings pass through untouched; everything else
+ * is JSON. This is the ONLY place a structured value is forced to a string,
+ * and it happens lazily — never before a matcher actually needs text.
+ */
+export declare function serializeValue(value: unknown): string;
+/**
+ * The agent's native output — the source of truth for deterministic,
+ * structural assertions. Tolerates a legacy `{ text }`-only response (no
+ * `value`) so executors can migrate incrementally.
+ */
+export declare function resolveValue<T>(response: AgentResponse<T>): T | string | undefined;
+/**
+ * The string view for the judge and text matchers. An explicit `text` wins
+ * (it's the enriched projection the executor chose to expose); otherwise we
+ * serialize `value` on demand.
+ */
+export declare function resolveText<T>(response: AgentResponse<T>): string;
+/**
+ * Walk a dot-path (with numeric array indices) into an arbitrary object.
+ * Returns `undefined` if any segment is missing. e.g. "plan_items.0.options".
+ */
+export declare function navigatePath(root: unknown, path: string): unknown;

package/dist/resolve.js

@@ -0,0 +1,62 @@
+/**
+ * Serialize an arbitrary agent value to the string view the judge model and
+ * the text matchers consume. Strings pass through untouched; everything else
+ * is JSON. This is the ONLY place a structured value is forced to a string,
+ * and it happens lazily — never before a matcher actually needs text.
+ */
+export function serializeValue(value) {
+    if (typeof value === "string")
+        return value;
+    if (value === null || value === undefined)
+        return "";
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * The agent's native output — the source of truth for deterministic,
+ * structural assertions. Tolerates a legacy `{ text }`-only response (no
+ * `value`) so executors can migrate incrementally.
+ */
+export function resolveValue(response) {
+    if (response.value !== undefined)
+        return response.value;
+    return response.text;
+}
+/**
+ * The string view for the judge and text matchers. An explicit `text` wins
+ * (it's the enriched projection the executor chose to expose); otherwise we
+ * serialize `value` on demand.
+ */
+export function resolveText(response) {
+    if (typeof response.text === "string")
+        return response.text;
+    return serializeValue(response.value);
+}
+/**
+ * Walk a dot-path (with numeric array indices) into an arbitrary object.
+ * Returns `undefined` if any segment is missing. e.g. "plan_items.0.options".
+ */
+export function navigatePath(root, path) {
+    let cur = root;
+    for (const seg of path.split(".")) {
+        if (cur == null)
+            return undefined;
+        if (Array.isArray(cur)) {
+            const idx = Number(seg);
+            if (!Number.isInteger(idx))
+                return undefined;
+            cur = cur[idx];
+        }
+        else if (typeof cur === "object" && seg in cur) {
+            cur = cur[seg];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return cur;
+}

package/dist/runner.d.ts

@@ -1,4 +1,13 @@
 import type { AgentExecutor, AgentResponse, SceneDefinition, SceneResult } from "./types";
 import type { JudgeConfig } from "./config";
-export declare function extractField(response: AgentResponse, field: string): unknown;
-export declare function executeScene(executor: AgentExecutor, scene: SceneDefinition, globalTimeout?: number, judgeConfig?: JudgeConfig, globalTurns?: number, globalRuns?: number): Promise<SceneResult>;
+/**
+ * Extract a named field from an agent response for assertion.
+ * - "response" / "value" → the native structured value (deterministic matchers)
+ * - "text"               → the serialized/judge view (lazy; text matchers)
+ * - "metadata"/"refusal" → the corresponding response property
+ * - dot-path             → navigated into the structured value first
+ *                          (e.g. "plan_items.0.options"), falling back to
+ *                          metadata so existing metadata paths keep resolving.
+ */
+export declare function extractField<T>(response: AgentResponse<T>, field: string): unknown;
+export declare function executeScene<T = string>(executor: AgentExecutor<T>, scene: SceneDefinition, globalTimeout?: number, judgeConfig?: JudgeConfig, globalTurns?: number, globalRuns?: number): Promise<SceneResult<T>>;