@tangle-network/agent-eval 0.136.0 → 0.137.0

package/dist/types-CTvKfr5F.d.ts

@@ -0,0 +1,804 @@
+import { r as CaptureIntegrityError, t as AgentEvalError } from "./errors-DkfjIDvD.js";
+import { b as CustomTokenPricing, c as CostLedgerHandle, f as CostLedgerSummary, g as CostReceiptInput, x as MaximumCharge } from "./cost-ledger-D2o6JOrL.js";
+//#region src/trace/raw-provider-sink.d.ts
+/**
+ * RawProviderSink — first-class persistence for the actual HTTP-level
+ * request/response bodies of every LLM provider call.
+ *
+ * Why this is a separate sink from the structured `LlmSpan`:
+ *
+ *   - `LlmSpan` records the *intent* — model name, messages, output text,
+ *     usage. It's what dashboards read; it's NOT enough for forensics.
+ *   - When a downstream consumer reports "the verifier used the wrong route"
+ *     or "tokens look right but reasoning was missing," the only way to
+ *     answer is the raw HTTP body. Span fields can lie (a proxy can echo
+ *     a different `model` value than what actually answered); the raw
+ *     response is ground truth.
+ *
+ * Default behaviour: opt-in. Pass `rawSink` to `LlmClientOptions` (or the
+ * matrix runner / BuilderSession sets it up automatically) and every
+ * request, response, and error is recorded — including retries, with the
+ * attempt index attached so a flaky call's full event chain is recoverable.
+ *
+ * Redaction is enforced at sink time. The default redactor strips
+ * `Authorization`, `X-Api-Key`, `X-Auth-Token`, `Cookie` headers and any
+ * payload field whose key matches `apiKey | api_key | bearer | password |
+ * secret | token` (case-insensitive). Override via the sink constructor or
+ * the per-call `redactor`. The `redactedFields` array on the persisted
+ * event lets a reviewer see what was stripped without exposing the values.
+ */
+type RawProviderDirection = 'request' | 'response' | 'error';
+interface RawProviderEvent {
+  /** Stable id. Generated by the sink if omitted. */
+  eventId: string;
+  /** Trace context populated by `LlmClient` when the call is wrapped in a span. */
+  runId?: string;
+  spanId?: string;
+  /**
+   * Logical provider name. Free-form so callers can use whatever id matches
+   * their topology (`'openai'`, `'anthropic'`, `'tangle-router'`, …). When
+   * omitted, derived from `baseUrl` in `LlmClientOptions`.
+   */
+  provider: string;
+  model: string;
+  /** Endpoint path, e.g. `'/v1/chat/completions'`. */
+  endpoint: string;
+  /** Base URL used for the call (already-normalised — no trailing slash). */
+  baseUrl: string;
+  /** 0-indexed retry attempt. The first attempt is 0; a retried call gets 1, 2, … */
+  attemptIndex: number;
+  direction: RawProviderDirection;
+  /** Unix ms. */
+  timestamp: number;
+  /** Wall-clock duration of the call leg. Set on `response` and `error` events; null on `request`. */
+  durationMs?: number;
+  statusCode?: number;
+  requestHeaders?: Record<string, string>;
+  requestBody?: unknown;
+  responseHeaders?: Record<string, string>;
+  responseBody?: unknown;
+  /** Set on `direction: 'error'` events. */
+  errorMessage?: string;
+  /** Field paths the redactor stripped from this event ('header:Authorization', 'body.apiKey', …). */
+  redactedFields: string[];
+}
+interface RawProviderSinkFilter {
+  runId?: string;
+  spanId?: string;
+  direction?: RawProviderDirection;
+  attemptIndex?: number;
+}
+interface RawProviderSink {
+  record(event: RawProviderEvent): Promise<void>;
+  /** Optional listing — implementations that durably persist (file, db) should support this. */
+  list?(filter?: RawProviderSinkFilter): Promise<RawProviderEvent[]>;
+  /** Optional teardown for backed implementations. */
+  close?(): Promise<void>;
+}
+type ProviderRedactor = (event: RawProviderEvent) => RawProviderEvent;
+/**
+ * Default redactor — strips well-known auth headers and any body field whose
+ * key matches the credential pattern. Records every redacted path on
+ * `event.redactedFields` so a downstream reviewer can see what was removed.
+ */
+declare function defaultProviderRedactor(event: RawProviderEvent): RawProviderEvent;
+interface InMemoryRawProviderSinkOptions {
+  redactor?: ProviderRedactor;
+}
+declare class InMemoryRawProviderSink implements RawProviderSink {
+  private events;
+  private redactor;
+  constructor(opts?: InMemoryRawProviderSinkOptions);
+  record(event: RawProviderEvent): Promise<void>;
+  list(filter?: RawProviderSinkFilter): Promise<RawProviderEvent[]>;
+  size(): number;
+}
+declare class NoopRawProviderSink implements RawProviderSink {
+  record(): Promise<void>;
+  /**
+   * Returns an empty array. Implemented so `assertRunCaptured` does not
+   * trip the `no_raw_sink` issue when a caller explicitly opts out of
+   * capture by passing this sink — opt-out is a deliberate choice, not a
+   * misconfiguration.
+   */
+  list(): Promise<RawProviderEvent[]>;
+}
+interface FileSystemRawProviderSinkOptions {
+  /** Directory the NDJSON file is written into. Created if missing. */
+  dir: string;
+  /** File name; default `'raw-provider-events.ndjson'`. */
+  fileName?: string;
+  /** Bytes after which the writer rolls over to a new file (default 32 MiB). */
+  rollAtBytes?: number;
+  redactor?: ProviderRedactor;
+}
+declare class FileSystemRawProviderSink implements RawProviderSink {
+  private dir;
+  private fileName;
+  private rollAtBytes;
+  private redactor;
+  private bytesWritten;
+  private rollIndex;
+  private initPromise;
+  constructor(opts: FileSystemRawProviderSinkOptions);
+  private ensureInit;
+  private currentPath;
+  record(event: RawProviderEvent): Promise<void>;
+  list(filter?: RawProviderSinkFilter): Promise<RawProviderEvent[]>;
+}
+/**
+ * Best-effort provider id from a base URL. Falls back to the URL host when
+ * none of the well-known patterns match.
+ */
+declare function providerFromBaseUrl(baseUrl: string): string;
+//#endregion
+//#region src/llm-client.d.ts
+interface LlmMessage {
+  role: 'system' | 'user' | 'assistant';
+  /**
+   * Either a plain text content string OR a multimodal content array
+   * (text + image_url parts) for vision-capable models.
+   */
+  content: string | Array<{
+    type: 'text';
+    text: string;
+  } | {
+    type: 'image_url';
+    image_url: {
+      url: string;
+      detail?: 'auto' | 'low' | 'high';
+    };
+  }>;
+}
+type LlmThinkingMode = 'enabled' | 'disabled';
+interface LlmCallRequest {
+  model: string;
+  messages: LlmMessage[];
+  /** Optional JSON-mode response format (response_format: json_object). */
+  jsonMode?: boolean;
+  /** Optional structured output via JSON Schema. Falls back to json_object on 400. */
+  jsonSchema?: {
+    name: string;
+    schema: Record<string, unknown>;
+  };
+  temperature?: number;
+  maxTokens?: number;
+  /** OpenAI-compatible reasoning mode. Omitted when the provider default should apply. */
+  thinking?: LlmThinkingMode;
+  /** Per-call timeout, default 300s. */
+  timeoutMs?: number;
+}
+/** Conservative priced bound for the exact text request sent to a provider.
+ * Returns undefined when output or multimodal input is not bounded, causing a
+ * capped CostLedger to reject the call before execution. Pass
+ * `customTokenPricing` when package pricing does not cover the model or endpoint. */
+declare function maximumChargeForLlmRequest(request: Pick<LlmCallRequest, 'model' | 'messages' | 'jsonSchema' | 'maxTokens' | 'thinking'>, options?: LlmClientOptions): MaximumCharge | undefined;
+interface LlmUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  /** False when the provider omitted or malformed prompt/completion usage. */
+  captured?: boolean;
+  /** Reasoning-token subset of completionTokens, when reported. */
+  reasoningTokens?: number;
+  /** Proxies populate this when prompt caching is on. */
+  cachedPromptTokens?: number;
+}
+interface LlmCallResult {
+  /** The text content of the first choice. Empty string if none. */
+  content: string;
+  usage: LlmUsage;
+  /**
+   * Cost in USD. Uses the provider's reported cost when present, otherwise
+   * caller-supplied token pricing. `null` when neither is available.
+   */
+  costUsd: number | null;
+  /** Model name actually used (echoed from response). */
+  model: string;
+  /** Wall-clock duration of the HTTP call (last attempt, if retried). */
+  durationMs: number;
+  /**
+   * `finish_reason` echoed from the first choice (`stop`, `length`,
+   * `content_filter`, `tool_calls`, ...). `null` when the provider omits it.
+   * Exposed so a free-form `callLlm` caller CAN detect a truncated answer
+   * (`length`) instead of treating a cut-off completion as complete. Note:
+   * `callLlm` does not itself reject on it — acting on this signal is the
+   * caller's responsibility (in-repo free-form drivers do not yet enforce it).
+   */
+  finishReason?: string | null;
+  /**
+   * True when `content.trim()` is empty. An empty completion is a silent zero
+   * for free-form `callLlm` callers; this flag is the signal a caller can
+   * inspect to fail loud rather than proceed on an empty string. `callLlm`
+   * surfaces it but does not throw on it.
+   */
+  contentEmpty?: boolean;
+  /** Raw response body. */
+  raw: Record<string, unknown>;
+}
+type LlmCallMetadata = Pick<LlmCallResult, 'usage' | 'costUsd' | 'model' | 'durationMs'>;
+/** Convert a provider result into the canonical paid-call receipt input. */
+declare function costReceiptFromLlm(result: LlmCallResult, customTokenPricing?: CustomTokenPricing): CostReceiptInput;
+/** Structured-response failures retain their completed provider receipt. */
+declare function costReceiptFromLlmError(error: Error, customTokenPricing?: CustomTokenPricing): CostReceiptInput | undefined;
+declare class LlmCallError extends AgentEvalError {
+  readonly status: number;
+  readonly body: string;
+  readonly model: string;
+  constructor(message: string, status: number, body: string, model: string);
+}
+/** A provider response completed and incurred measurable usage, but its content
+ *  could not satisfy the caller's response contract. The response envelope is
+ *  retained so accounting can commit the receipt before the error propagates. */
+declare class LlmResponseError extends AgentEvalError {
+  readonly result: LlmCallResult;
+  constructor(message: string, result: LlmCallResult, options?: {
+    cause?: unknown;
+  });
+}
+interface LlmClientOptions {
+  /** Base URL (without trailing slash). Must end at the `/v1` prefix. */
+  baseUrl?: string;
+  /** Bearer token — either `apiKey` or `bearer` populates `Authorization: Bearer ...`. */
+  apiKey?: string;
+  bearer?: string;
+  /** Override for the `Authorization` header (e.g. `X-Auth: ...`). Takes precedence over apiKey/bearer. */
+  authHeader?: {
+    name: string;
+    value: string;
+  };
+  /** Stable provider idempotency key, reused across retries of this logical call. */
+  idempotencyKey?: string;
+  /** Default timeout in ms. Per-call can override. */
+  defaultTimeoutMs?: number;
+  /**
+   * Caller-supplied abort signal — e.g. a campaign-wide cancel. Linked to
+   * each attempt's per-attempt timeout controller, so aborting it cancels
+   * the in-flight fetch. A caller abort is FATAL: it is not retried even
+   * though an AbortError otherwise matches the transient patterns.
+   */
+  signal?: AbortSignal;
+  /**
+   * Cross-attempt wall-clock budget in ms, measured from the first attempt.
+   * Before launching each attempt the loop checks the remaining budget and
+   * stops retrying once it is exhausted, rather than waiting the full
+   * per-attempt timeout on every retry. Bounds total time independent of
+   * total attempts × `timeoutMs`.
+   */
+  deadlineMs?: number;
+  /** Total provider attempts. Default 3. */
+  maximumAttempts?: number;
+  /** Token rates used when the provider omits cost or package pricing does not cover the model. */
+  customTokenPricing?: CustomTokenPricing;
+  /**
+   * Transport for requests that declare `jsonSchema`. `native` sends
+   * `response_format: json_schema`; `json-object` sends the broadly supported
+   * JSON mode and relies on the caller to include the schema in model-visible
+   * instructions. Default: `native`.
+   */
+  jsonSchemaTransport?: 'native' | 'json-object';
+  /**
+   * JSON payload parsing policy. `extract` accepts fenced or prose-prefixed JSON.
+   * `exact` requires the complete response content to be one JSON value.
+   * Default: `extract`.
+   */
+  jsonPayloadMode?: 'extract' | 'exact';
+  /** Default provider reasoning mode. A per-call request value takes precedence. */
+  thinking?: LlmThinkingMode;
+  /** Fetch implementation — defaults to global `fetch`. Override for custom transport (e.g. tests). */
+  fetch?: typeof fetch;
+  /**
+   * Optional raw HTTP capture sink. When provided, every request, response,
+   * and error (across all retry attempts) is recorded to the sink, with auth
+   * headers and credential-shaped body fields redacted by default. This is
+   * the layer-1 forensics primitive: structured `LlmSpan`s record intent,
+   * raw events record what actually crossed the wire.
+   */
+  rawSink?: RawProviderSink;
+  /**
+   * Logical provider id attached to raw events. When omitted, derived from
+   * `baseUrl` via `providerFromBaseUrl`.
+   */
+  provider?: string;
+  /** Trace context attached to raw events; populated by emitter-aware callers. */
+  traceContext?: {
+    runId?: string;
+    spanId?: string;
+  };
+  /** Override the redaction strategy for this call. Defaults to `defaultProviderRedactor`. */
+  redactor?: ProviderRedactor;
+}
+/**
+ * True when an error is a transient transport/network fault worth retrying,
+ * as opposed to a deterministic failure (4xx schema reject, JSON parse) that
+ * a retry cannot fix. Inspects `LlmCallError.status`, then the error's
+ * name/message/code, then recurses into `error.cause` — undici nests the
+ * real socket fault one or more levels under `.cause`.
+ *
+ * This is the retry classifier for the package: `callLlm` and
+ * `withJudgeRetry` both route through it, so connection failures are treated
+ * consistently across transports.
+ */
+declare function isTransientLlmError(err: unknown): boolean;
+/** Exponential backoff: 500ms, 1s, 2s, 4s, ... capped at 16s. Attempt is 0-indexed. */
+declare function backoffMs(attempt: number): number;
+/**
+ * Strip a ```json / ``` code fence if the model emitted one.
+ * Idempotent for naked JSON. Some models (claude-code via router, certain
+ * deepseek models) wrap output even under json_object.
+ */
+declare function stripFencedJson(raw: string): string;
+/**
+ * Low-level call. Returns raw content + usage + cost. Retries on transient
+ * failures; does NOT degrade schema here — callers that want graceful
+ * degrade use `callLlmJson`.
+ */
+declare function callLlm(req: LlmCallRequest, opts?: LlmClientOptions): Promise<LlmCallResult>;
+/**
+ * Structured-output call. Returns parsed JSON plus the raw result envelope.
+ * Degrades `jsonSchema` → `jsonMode` on a 400 that names the schema param —
+ * critical for deepseek-v3/v4, kimi-k2.6, and other models that don't accept
+ * the `response_format.json_schema` shape but DO accept `json_object`.
+ */
+declare function callLlmJson<T = unknown>(req: LlmCallRequest, opts?: LlmClientOptions): Promise<{
+  value: T;
+  result: LlmCallResult;
+}>;
+type LlmRouteAssertionReason = 'no_explicit_base_url' | 'base_url_blocked' | 'base_url_not_allowed' | 'no_auth' | 'wrong_provider';
+declare class LlmRouteAssertionError extends CaptureIntegrityError {
+  readonly reason: LlmRouteAssertionReason;
+  readonly baseUrl: string;
+  constructor(message: string, reason: LlmRouteAssertionReason, baseUrl: string);
+}
+interface LlmRouteRequirements {
+  /**
+   * Throw if `opts.baseUrl` is undefined, i.e. the call would fall back to
+   * `DEFAULT_BASE_URL`. Set this for evaluation runs where silently using
+   * the public/free-tier router is a defect — the launch reviewer needs to
+   * know exactly which provider answered.
+   */
+  requireExplicitBaseUrl?: boolean;
+  /**
+   * Allowlist of acceptable base URLs. Strings match by prefix
+   * (case-insensitive); RegExps test against the full base URL.
+   */
+  allowedBaseUrls?: Array<string | RegExp>;
+  /** Blocklist that takes precedence over `allowedBaseUrls`. */
+  blockedBaseUrls?: Array<string | RegExp>;
+  /** Throw if no auth header / api key is configured. */
+  requireAuth?: boolean;
+  /**
+   * Logical provider id the configured `baseUrl` is expected to match (via
+   * `providerFromBaseUrl`). Mainly useful when paired with `requireExplicitBaseUrl`.
+   */
+  expectedProvider?: string;
+}
+/**
+ * Fail-loud assertion that the configured LLM client points at the route
+ * the caller intends. Designed for the matrix-runner preflight: invoke
+ * once before any LLM call to catch misconfiguration before a sweep burns
+ * dollars on the wrong provider.
+ *
+ * Throws `LlmRouteAssertionError`. Pure — no I/O — so it's safe to call
+ * from constructors and CI gates.
+ */
+declare function assertLlmRoute(opts: LlmClientOptions, req?: LlmRouteRequirements): void;
+/**
+ * Probe whether a model is reachable. Returns latency + null error on
+ * success; `ok=false` + error message on any failure (HTTP, timeout,
+ * network, parse). Designed for sweep preflights — fail loud at the
+ * boundary before burning a 30-leaf run on a misconfigured router.
+ *
+ * Sends a tiny `ping` message with `maxTokens=64`. Reasoning models
+ * (glm-5.1, deepseek-v4) can burn the entire budget on internal reasoning
+ * for short prompts, so don't tighten this further. We don't validate
+ * content; HTTP 200 means reachable.
+ */
+declare function probeLlm(model: string, opts?: LlmClientOptions & {
+  timeoutMs?: number;
+}): Promise<{
+  ok: boolean;
+  latencyMs: number;
+  error: string | null;
+}>;
+/**
+ * Stateful client — construct once with defaults, call many times.
+ * Thin wrapper around the free functions; exists for callers that want
+ * to inject a single configured instance into multiple primitives.
+ */
+declare class LlmClient {
+  readonly maximumAttempts: number;
+  private readonly opts;
+  constructor(opts?: LlmClientOptions);
+  call(req: LlmCallRequest, per?: LlmClientOptions): Promise<LlmCallResult>;
+  callJson<T = unknown>(req: LlmCallRequest, per?: LlmClientOptions): Promise<{
+    value: T;
+    result: LlmCallResult;
+  }>;
+}
+//#endregion
+//#region src/analyst/chat-client.d.ts
+/**
+ * Unified chat interface using the package's canonical LLM request and result.
+ */
+interface ChatClient {
+  /** Display name of the bound transport, included in telemetry. */
+  readonly transport: ChatTransport;
+  /** Default model when the caller omits one. */
+  readonly defaultModel?: string;
+  /** Total provider attempts this transport can make for one chat call. */
+  readonly maximumAttempts?: number;
+  /** Implementations must enforce `req.maxTokens` when it is present. */
+  chat(req: ChatRequest, opts?: ChatCallOpts): Promise<ChatResponse>;
+}
+type ChatTransport = 'router' | 'sandbox-sdk' | 'cli-bridge' | 'direct-provider' | 'custom' | 'mock';
+interface ChatRequest extends Omit<LlmCallRequest, 'model'> {
+  /** Optional — falls back to ChatClient.defaultModel. */
+  model?: string;
+}
+type ChatResponse = LlmCallResult;
+interface ChatCallOpts {
+  /** Cancel the in-flight request. */
+  signal?: AbortSignal;
+  /** Hard USD ceiling for this single call (informational; the underlying transport may not enforce). */
+  maxCostUsd?: number;
+  /** Correlation tag carried into request headers when the transport allows. */
+  correlationId?: string;
+  /** Stable provider idempotency key for retries/redrives of one paid call. */
+  idempotencyKey?: string;
+}
+type CreateChatClientOpts = RouterTransportOpts | CliBridgeTransportOpts | DirectProviderTransportOpts | SandboxSdkTransportOpts | CustomTransportOpts | MockTransportOpts;
+interface BaseTransportOpts {
+  defaultModel?: string;
+  /** Total provider attempts. Required for opaque transports used in capped runs. */
+  maximumAttempts?: number;
+}
+interface RouterTransportOpts extends BaseTransportOpts {
+  transport: 'router';
+  baseUrl?: string;
+  apiKey: string;
+}
+interface CliBridgeTransportOpts extends BaseTransportOpts {
+  transport: 'cli-bridge';
+  baseUrl?: string;
+  bearer?: string;
+}
+interface DirectProviderTransportOpts extends BaseTransportOpts {
+  transport: 'direct-provider';
+  baseUrl: string;
+  apiKey: string;
+}
+/**
+ * Sandbox-SDK transport. The caller supplies a canonical chat function for an
+ * already-configured Sandbox handle, so agent-eval does not import the SDK.
+ */
+interface SandboxSdkTransportOpts extends BaseTransportOpts {
+  transport: 'sandbox-sdk';
+  chat: (req: ChatRequest, opts?: ChatCallOpts) => Promise<ChatResponse>;
+}
+/** Caller-adapted SDK or transport returning the canonical ChatResponse shape. */
+interface CustomTransportOpts extends BaseTransportOpts {
+  transport: 'custom';
+  chat: (req: ChatRequest, opts?: ChatCallOpts) => Promise<ChatResponse>;
+}
+/**
+ * Mock transport for tests. The handler receives the request and returns
+ * whatever the test wants. No retries, no JSON-schema degrade.
+ */
+interface MockTransportOpts extends BaseTransportOpts {
+  transport: 'mock';
+  handler: (req: ChatRequest, opts?: ChatCallOpts) => Promise<ChatResponse>;
+}
+/**
+ * Build a ChatClient bound to a specific transport. The returned client
+ * is safe to share across analysts in a single registry run.
+ */
+declare function createChatClient(opts: CreateChatClientOpts): ChatClient;
+//#endregion
+//#region src/types.d.ts
+interface Scenario {
+  id: string;
+  persona: string;
+  label: string;
+  thesis: string;
+  dimensions: string[];
+  turns: Turn[];
+  artifactChecks: ArtifactCheck[];
+  systemPromptAppend?: string;
+}
+interface Turn {
+  user: string;
+  expectedBehaviors: string[];
+  adversarial?: boolean;
+  feedbackType?: 'correction' | 'rejection' | 'vague' | 'contradictory' | 'escalation';
+}
+interface ArtifactCheck {
+  type: 'vault_file_exists' | 'vault_file_contains' | 'block_extracted' | 'code_valid' | 'generation_produced' | 'tool_created' | string;
+  target: string;
+  contains?: string;
+  minCount?: number;
+  description: string;
+}
+interface JudgeConfig {
+  model: string;
+  temperature: number;
+  rubric: JudgeRubric;
+}
+interface JudgeRubric {
+  name: string;
+  description: string;
+  dimensions: RubricDimension[];
+}
+interface RubricDimension {
+  name: string;
+  description: string;
+  anchor_low: string;
+  anchor_high: string;
+  weight: number;
+}
+interface ScenarioResult {
+  scenarioId: string;
+  persona: string;
+  turns: TurnResult[];
+  artifactResults: ArtifactResult[];
+  judgeScores: JudgeScore[];
+  judgeErrors: number;
+  overallScore: number;
+  totalDurationMs: number;
+  artifacts: CollectedArtifacts;
+  /** Agent and judge spend attributed to this scenario. */
+  cost?: CostLedgerSummary;
+}
+interface TurnResult {
+  turnIndex: number;
+  userMessage: string;
+  agentResponse: string;
+  durationMs: number;
+  blocksExtracted: {
+    type: string;
+    title: string;
+  }[];
+  containsCode: boolean;
+  containsToolCall: boolean;
+}
+interface ArtifactResult {
+  check: ArtifactCheck;
+  passed: boolean;
+  detail?: string;
+}
+interface JudgeScore {
+  judgeName: string;
+  dimension: string;
+  score: number;
+  reasoning: string;
+  evidence?: string;
+}
+interface CollectedArtifacts {
+  vaultFiles: {
+    path: string;
+    content: string;
+  }[];
+  blocksExtracted: {
+    type: string;
+    fields: Record<string, string>;
+  }[];
+  codeBlocks: {
+    language: string;
+    code: string;
+  }[];
+  toolCalls: string[];
+}
+interface BenchmarkReport {
+  timestamp: string;
+  generation: number;
+  promptVersion: string;
+  scenarioCount: number;
+  results: ScenarioResult[];
+  cost?: CostLedgerSummary;
+  summary: {
+    overallAvg: number;
+    byPersona: Record<string, {
+      avg: number;
+      passed: number;
+      total: number;
+    }>;
+    byDimension: Record<string, {
+      avg: number;
+      scores: number[];
+    }>;
+    weakest: {
+      scenario: string;
+      score: number;
+      reason: string;
+    }[];
+    strongest: {
+      scenario: string;
+      score: number;
+      reason: string;
+    }[];
+  };
+}
+interface RouteMap {
+  signup?: string;
+  login?: string;
+  workspaces?: string;
+  threads?: string;
+  chat?: string;
+  tasks?: string;
+  events?: string;
+  approvals?: string;
+  vault?: string;
+  generations?: string;
+  [key: string]: string | undefined;
+}
+interface ProductClientConfig {
+  baseUrl: string;
+  routes: RouteMap;
+  /** Per-request timeout in ms before the request is aborted. Default 30s. */
+  timeoutMs?: number;
+}
+interface ScenarioFile {
+  id: string;
+  category: string;
+  persona: string;
+  label: string;
+  thesis: string;
+  isControl?: boolean;
+  rubric?: {
+    dimensions: {
+      name: string;
+      description: string;
+      weight: number;
+    }[];
+  };
+  turns: Turn[];
+  artifactChecks: ArtifactCheck[];
+}
+interface CompletionCriterion {
+  name: string;
+  check: (state: DriverState) => boolean;
+  progress?: (state: DriverState) => number;
+}
+interface FeedbackPattern {
+  trigger: string;
+  response: string;
+}
+/**
+ * How hard the simulated user pushes back. The driver LLM scales its tone
+ * and follow-up aggression to this:
+ *   cooperative — forgiving early adopter; accepts reasonable answers.
+ *   demanding   — experienced professional; rejects vague or hedged answers.
+ *   relentless  — senior partner reviewing for a client who will litigate;
+ *                 interrogates every claim, accepts nothing undefended.
+ */
+type PersonaRigor = 'cooperative' | 'demanding' | 'relentless';
+interface PersonaConfig {
+  id: string;
+  role: string;
+  goal: string;
+  completionCriteria: CompletionCriterion[];
+  feedbackPatterns?: FeedbackPattern[];
+  maxTurns: number;
+  driverModel?: string;
+  /** How adversarial the simulated user is. Defaults to 'demanding'. */
+  rigor?: PersonaRigor;
+  /**
+   * Domain expertise the simulated user holds — quoted into the driver
+   * prompt so it challenges the agent with authority instead of vague
+   * dissatisfaction. e.g. "a 15-year M&A partner who knows GAAP
+   * working-capital mechanics cold".
+   */
+  expertise?: string;
+  /**
+   * Substantive issues a senior professional in this role would
+   * interrogate — traps the scenario hides, claims that must be defended.
+   * The driver probes these without revealing them verbatim; the agent
+   * must surface them on its own.
+   */
+  pressurePoints?: string[];
+  /**
+   * Curveballs the driver may inject once the agent is coasting — changed
+   * facts, a hostile counterparty position, a new constraint. Forces the
+   * agent to re-derive rather than recite.
+   */
+  curveballs?: string[];
+}
+interface DriverState {
+  tasks: number;
+  events: number;
+  proposals: {
+    pending: number;
+    approved: number;
+    rejected: number;
+  };
+  vaultFiles: string[];
+  codeBlocks: number;
+  generations: number;
+}
+interface TurnMetrics {
+  turn: number;
+  timestamp: string;
+  tasks: number;
+  events: number;
+  proposals: {
+    pending: number;
+    approved: number;
+    rejected: number;
+  };
+  vaultFiles: number;
+  responseLatencyMs: number;
+  responseChars: number;
+  codeBlocksProduced: number;
+  blocksExtracted: number;
+  qualityScore?: number;
+  inputTokens: number;
+  outputTokens: number;
+  estimatedCostUsd: number;
+  totalCostUsd: number;
+  completionPercent: number;
+}
+interface DriverResult {
+  personaId: string;
+  /** True when the simulated user professionally signed off (driver said DONE). */
+  completed: boolean;
+  /** Turn at which the simulated user signed off, or null if it never did. */
+  turnsToCompletion: number | null;
+  /**
+   * Turn at which nominal completionCriteria were first all met, or null.
+   * Distinct from turnsToCompletion: criteria can be met while the
+   * simulated professional is still unsatisfied with the work's rigor.
+   */
+  criteriaMetAtTurn: number | null;
+  totalTurns: number;
+  metrics: TurnMetrics[];
+  finalState: DriverState;
+  convergenceCurve: number[];
+  totalCostUsd: number;
+  finalQualityScore: number | null;
+}
+interface BenchmarkRunnerConfig {
+  scenarios: Scenario[];
+  judges: JudgeFn[];
+  systemPrompt: string;
+  model?: string;
+  judgeModel?: string;
+  passThreshold?: number;
+  generation?: number;
+  promptVersion?: string;
+  /** Shared ledger for agent and judge calls made by the benchmark. */
+  costLedger?: CostLedgerHandle;
+}
+interface JudgeInput {
+  scenario: Scenario;
+  turns: TurnResult[];
+  artifacts: CollectedArtifacts;
+  /** Shared ledger for paid built-in judges. Direct calls default to an uncapped ledger. */
+  costLedger?: CostLedgerHandle;
+  costPhase?: string;
+  costTags?: Record<string, string>;
+  signal?: AbortSignal;
+}
+type JudgeFn = (chat: ChatClient, input: JudgeInput) => Promise<JudgeScore[]>;
+interface TestResult {
+  name: string;
+  passed: boolean;
+  duration: number;
+  detail?: string;
+  checks: CheckResult[];
+}
+interface CheckResult {
+  name: string;
+  passed: boolean;
+  expected: string;
+  actual: string;
+}
+interface EvalResult {
+  scenario: string;
+  status: 'pass' | 'fail' | 'skip';
+  duration: number;
+  detail?: string;
+  artifact?: string;
+}
+//#endregion
+export { assertLlmRoute as $, ChatClient as A, SandboxSdkTransportOpts as B, ScenarioFile as C, TurnMetrics as D, Turn as E, CreateChatClientOpts as F, LlmCallResult as G, LlmCallError as H, CustomTransportOpts as I, LlmMessage as J, LlmClient as K, DirectProviderTransportOpts as L, ChatResponse as M, ChatTransport as N, TurnResult as O, CliBridgeTransportOpts as P, LlmUsage as Q, MockTransportOpts as R, Scenario as S, TestResult as T, LlmCallMetadata as U, createChatClient as V, LlmCallRequest as W, LlmRouteAssertionError as X, LlmResponseError as Y, LlmRouteRequirements as Z, PersonaConfig as _, RawProviderSink as _t, CheckResult as a, isTransientLlmError as at, RouteMap as b, providerFromBaseUrl as bt, DriverResult as c, stripFencedJson as ct, FeedbackPattern as d, InMemoryRawProviderSink as dt, backoffMs as et, JudgeConfig as f, InMemoryRawProviderSinkOptions as ft, JudgeScore as g, RawProviderEvent as gt, JudgeRubric as h, RawProviderDirection as ht, BenchmarkRunnerConfig as i, costReceiptFromLlmError as it, ChatRequest as j, ChatCallOpts as k, DriverState as l, FileSystemRawProviderSink as lt, JudgeInput as m, ProviderRedactor as mt, ArtifactResult as n, callLlmJson as nt, CollectedArtifacts as o, maximumChargeForLlmRequest as ot, JudgeFn as p, NoopRawProviderSink as pt, LlmClientOptions as q, BenchmarkReport as r, costReceiptFromLlm as rt, CompletionCriterion as s, probeLlm as st, ArtifactCheck as t, callLlm as tt, EvalResult as u, FileSystemRawProviderSinkOptions as ut, PersonaRigor as v, RawProviderSinkFilter as vt, ScenarioResult as w, RubricDimension as x, ProductClientConfig as y, defaultProviderRedactor as yt, RouterTransportOpts as z };
+//# sourceMappingURL=types-CTvKfr5F.d.ts.map