@attest-ai/core 1.0.0-rc.1 → 1.0.0-rc.3

package/dist/cjs/index.d.cts

@@ -1,12 +1,12 @@
-import { InitializeResult, ProtocolLogger, ProtocolDiagnostic, Trace, Assertion, EvaluateBatchResult, DriftReport, SimulatePersona, ConversationMessage, SimulateFaultConfig, Step, AssertionResult, Outcome } from './proto/index.cjs';
-export { AgentId, AssertionId, AssertionSpec, BiasProbe, ConstraintSpec, ContentSpec, ERR_ASSERTION_ERROR, ERR_ENGINE_ERROR, ERR_INVALID_TRACE, ERR_PROVIDER_ERROR, ERR_SESSION_ERROR, ERR_TIMEOUT, EmbeddingSpec, EngineTimeoutError, ErrorData, EvaluateBatchParams, FailureClass, GenerateUserMessageParams, GenerateUserMessageResult, InitializeParams, JudgeAgreement, JudgeMetadata, LlmJudgeSpec, OUTCOME_FAIL, OUTCOME_PASS, OUTCOME_SKIP, PluginSpec, ProtocolDesyncError, ProtocolDiagnosticBuffer, ProtocolDiagnosticKind, ProtocolError, QueryDriftParams, QueryDriftResult, REASON_MISSING_EVIDENCE, REASON_PROVIDER_NOT_CONFIGURED, REASON_PROVIDER_UNAVAILABLE, REASON_SHORT_CIRCUITED, REASON_SIMULATION, RPCError, RPCRequest, RPCResponse, STATUS_HARD_FAIL, STATUS_NOT_EVALUATED, STATUS_PASS, STATUS_SOFT_FAIL, STEP_AGENT_CALL, STEP_LLM_CALL, STEP_RETRIEVAL, STEP_TOOL_CALL, SchemaSpec, ShutdownResult, SubmitPluginResultParams, TYPE_CONSTRAINT, TYPE_CONTENT, TYPE_EMBEDDING, TYPE_LLM_JUDGE, TYPE_PLUGIN, TYPE_SCHEMA, TYPE_TRACE, TYPE_TRACE_TREE, TraceId, TraceMetadata, TraceSpec, TraceTreeSpec, agentId, assertionId, decodeResponse, encodeRequest, extractId, extractResult, layerForType, previewLine, traceId } from './proto/index.cjs';
+import { InitializeResult, ProtocolLogger, ProtocolDiagnostic, Trace, Assertion, BatchBudget, EvaluateBatchResult, DriftReport, SimulatePersona, ConversationMessage, SimulateFaultConfig, Step, AssertionResult, Usage, Outcome } from './proto/index.cjs';
+export { AgentId, AssertionId, AssertionSpec, BiasProbe, ConstraintSpec, ContentSpec, ERR_ASSERTION_ERROR, ERR_ENGINE_ERROR, ERR_INVALID_TRACE, ERR_PROVIDER_ERROR, ERR_SESSION_ERROR, ERR_TIMEOUT, EffectSpec, EmbeddingSpec, EngineTimeoutError, ErrorData, EvaluateBatchParams, Exchange, FailureClass, GenerateUserMessageParams, GenerateUserMessageResult, Handoff, InitializeParams, JudgeAgreement, JudgeMetadata, LlmJudgeSpec, OTLPConversionError, OUTCOME_FAIL, OUTCOME_PASS, OUTCOME_SKIP, PluginSpec, ProtocolDesyncError, ProtocolDiagnosticBuffer, ProtocolDiagnosticKind, ProtocolError, QueryDriftParams, QueryDriftResult, REASON_BUDGET_EXHAUSTED, REASON_JUDGE_ABSTAINED, REASON_MISSING_EVIDENCE, REASON_PROVIDER_NOT_CONFIGURED, REASON_PROVIDER_UNAVAILABLE, REASON_REPLAY_MISS, REASON_SHORT_CIRCUITED, REASON_SIMULATION, RPCError, RPCRequest, RPCResponse, STATUS_HARD_FAIL, STATUS_NOT_EVALUATED, STATUS_PASS, STATUS_SOFT_FAIL, STEP_AGENT_CALL, STEP_LLM_CALL, STEP_RETRIEVAL, STEP_TOOL_CALL, SchemaSpec, ShutdownResult, StepError, SubmitPluginResultParams, TYPE_CONSTRAINT, TYPE_CONTENT, TYPE_EFFECT, TYPE_EMBEDDING, TYPE_LLM_JUDGE, TYPE_PLUGIN, TYPE_SCHEMA, TYPE_TRACE, TYPE_TRACE_TREE, TraceId, TraceMetadata, TraceSpec, TraceTreeSpec, Turn, agentId, assertionId, decodeResponse, encodeRequest, extractId, extractResult, layerForType, previewLine, traceId } from './proto/index.cjs';
 import { ChildProcess } from 'node:child_process';
 import { Interface } from 'node:readline';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { EventEmitter } from 'node:events';
 
-declare const VERSION = "1.0.0-rc.1";
-declare const ENGINE_VERSION = "1.0.0-rc.1";
+declare const VERSION = "1.0.0-rc.3";
+declare const ENGINE_VERSION = "1.0.0-rc.3";
 
 declare class EngineManager {
     private enginePath;
@@ -83,6 +83,7 @@ declare class AttestClient {
     sendRequest(method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
     evaluateBatch(trace: Trace, assertions: readonly Assertion[], options?: {
         timeout?: number;
+        budget?: BatchBudget;
     }): Promise<EvaluateBatchResult>;
     submitPluginResult(traceId: string, pluginName: string, assertionId: string, status: string, score: number, explanation: string, options?: {
         timeout?: number;
@@ -146,7 +147,9 @@ declare class AgentResult {
     readonly assertionResults: readonly AssertionResult[];
     readonly totalCost: number;
     readonly totalDurationMs: number;
-    constructor(trace: Trace, assertionResults?: readonly AssertionResult[], totalCost?: number, totalDurationMs?: number);
+    /** Attest model usage of the evaluation that produced this result. */
+    readonly usage: Usage;
+    constructor(trace: Trace, assertionResults?: readonly AssertionResult[], totalCost?: number, totalDurationMs?: number, usage?: Usage);
     /** True if every assertion has status "pass". */
     get passed(): boolean;
     /**
@@ -177,6 +180,29 @@ declare class AgentResult {
     skipReason(): string;
 }
 
+/** Usage of an evaluation that made no model calls. */
+declare function zeroUsage(): Usage;
+/** Field-wise sum of two usages. */
+declare function addUsage(a: Usage, b: Usage): Usage;
+/** Field-wise sum of any number of usages; zero for none. */
+declare function sumUsage(usages: Iterable<Usage>): Usage;
+/**
+ * Validate the `usage` object of an evaluate_batch result: all nine fields
+ * present, non-negative, integers except the two `*_usd` amounts.
+ */
+declare function parseUsage(raw: unknown): Usage;
+/**
+ * "{model_calls} model calls · {tokens} tokens ({cached} cached) · ${cost} · retry cost ${retry}",
+ * plus refused and unpriced calls when present. Same format as the engine's
+ * report.FormatUsage.
+ */
+declare function formatUsage(u: Usage): string;
+/**
+ * The run-summary line "attest usage: …" when the session made a model call
+ * or refused one by budget; undefined otherwise.
+ */
+declare function usageSummaryLine(u: Usage): string | undefined;
+
 /**
  * Terminal-grade rendering of Attest assertion failures.
  *
@@ -220,9 +246,54 @@ declare class TraceTree {
     get aggregateLatency(): number;
 }
 
+type TrajectoryMode = "strict" | "unordered" | "subset" | "superset";
+type ArgOperator = "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in";
+/** A resource's records filtered by exact field values. */
+type Where = Record<string, unknown>;
+/**
+ * Effect checks against one world snapshot, from {@link ExpectChain.world}. Each method adds
+ * an `effect` assertion (Layer 3) to the parent chain and returns it.
+ */
+declare class WorldChecks<C> {
+    private readonly _snapshot;
+    private readonly _add;
+    constructor(snapshot: Record<string, unknown> | null, add: (spec: Record<string, unknown>) => C);
+    private addCheck;
+    /**
+     * Assert how many records of `resource` match `where`. Give `equals`, or `atMost` and/or
+     * `atLeast`. A violation reads `effect violated: 2 refunds for O-1042 (expected 1)`.
+     *
+     * @throws Error when no bound is given, or `equals` is combined with another bound.
+     *
+     * @example
+     * ```ts
+     * expect(trace).world(await world.state()).count("refunds", { equals: 1, where: { order_id: "O-1042" } });
+     * ```
+     */
+    count(resource: string, opts: {
+        equals?: number;
+        atMost?: number;
+        atLeast?: number;
+        where?: Where;
+    }): C;
+    /** Assert no two matching records share the same values for field(s) `by`. */
+    unique(resource: string, opts: {
+        by: string | string[];
+        where?: Where;
+    }): C;
+    /**
+     * Assert every matching record carries a distinct value in field `key` (default
+     * `idempotency_key`), the record field that stores the idempotency key.
+     */
+    idempotent(resource: string, opts?: {
+        key?: string;
+        where?: Where;
+    }): C;
+}
 declare class ExpectChain {
     private readonly _result;
     private readonly _assertions;
+    private _worldBytes;
     constructor(result: AgentResult);
     get assertions(): Assertion[];
     get trace(): Trace;
@@ -484,6 +555,65 @@ declare class ExpectChain {
     forbiddenTools(tools: string[], opts?: {
         soft?: boolean;
     }): this;
+    /**
+     * Assert how many times a tool is called, per value of argument `per` when set.
+     *
+     * @example
+     * ```ts
+     * // fails with "issue_refund called 2× for order_id=O-1042 (max 1)"
+     * expect(result).toolCardinality("issue_refund", { per: "order_id", atMost: 1 });
+     * ```
+     */
+    toolCardinality(tool: string, opts: {
+        per?: string;
+        atMost?: number;
+        atLeast?: number;
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert the tool-call trajectory matches `tools`: `strict` (same sequence,
+     * the default), `unordered` (same calls, any order), `subset` (no call
+     * outside `tools`) or `superset` (every call in `tools` made). Use
+     * {@link trajectoryPartialOrder} for ordering constraints.
+     */
+    trajectory(tools: string[], opts?: {
+        mode?: TrajectoryMode;
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert every tool in `tools` and `order` is called and each
+     * `[before, after]` pair holds as in {@link toolCalledBefore}.
+     */
+    trajectoryPartialOrder(order: Array<[string, string]>, opts?: {
+        tools?: string[];
+        soft?: boolean;
+    }): this;
+    /** Assert every call to `after` has an earlier call to `before`; holds when `after` is never called. */
+    toolCalledBefore(before: string, after: string, opts?: {
+        soft?: boolean;
+    }): this;
+    /** Assert no block of `period` (1–4) tool calls repeats `minRepeats` (default 2) times in a row; A→B→A→B fails period 2. */
+    noToolCycles(period: number, opts?: {
+        minRepeats?: number;
+        soft?: boolean;
+    }): this;
+    /** Assert at most `maxStreak` consecutive tool calls end in error (trace v2). */
+    maxToolFailureStreak(maxStreak: number, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert every call to `tool` has argument `arg` (a dot path) satisfying
+     * `op value`; holds when `tool` is never called.
+     */
+    toolArgSatisfies(tool: string, arg: string, op: ArgOperator, value: unknown, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Check effects in a world snapshot:
+     * `expect(trace).world(await world.state()).count(...)`. `null` means the test ran without
+     * a world helper: the checks are `not_evaluated` (`missing_evidence`).
+     */
+    world(snapshot: Record<string, unknown> | null): WorldChecks<this>;
     /**
      * Assert the output message contains the given string.
      *
@@ -874,6 +1004,264 @@ declare class ExpectChain {
  */
 declare function attestExpect(result: AgentResult | Trace): ExpectChain;
 
+/**
+ * Capture: turn a run into a verified fixture, and fixtures into tests.
+ *
+ * `attest capture --name <name> -- <command>` (the engine) records a run's trace and model
+ * exchanges into `tests/attest/fixtures/<name>.attest.json`. This module is the TypeScript
+ * side:
+ *
+ * - `record()` captures the code in a callback in this process.
+ * - `loadFixture()` reads a fixture (`proto/attest/v1/fixture-v1.schema.json`).
+ * - `emitVitest()` writes the fixture's drafted contracts as a Vitest file, using the
+ *   `attestExpect()` DSL. `attest capture` and `record()` call it.
+ */
+
+/** A capture did not produce a fixture, or produced one that is not verified. */
+declare class CaptureError extends Error {
+    /** The fixture written, when the engine wrote one. */
+    readonly fixture: string | null;
+    constructor(message: string, fixture?: string | null);
+}
+/** A drafted contract: an engine assertion spec plus its id and description. */
+interface Contract {
+    id: string;
+    kind: string;
+    description: string;
+    type: string;
+    spec: Record<string, unknown>;
+}
+/** A contract's status on the captured trace. */
+interface ContractResult {
+    contract: string;
+    status: string;
+    explanation: string;
+}
+/** A capture fixture (fixture-v1). */
+interface Fixture {
+    name: string;
+    source: {
+        kind: string;
+        replay_capable: boolean;
+        command?: string[];
+        exit_code?: number;
+    };
+    trace: Trace;
+    exchanges: Record<string, unknown>[];
+    contracts: Contract[];
+    verification: {
+        verified: boolean;
+        expect_fail: boolean;
+        trace_check: {
+            ok: boolean;
+            errors: number;
+            warnings: number;
+        };
+        results: ContractResult[];
+        expected_failures: string[];
+    };
+    world: Record<string, unknown> | null;
+}
+/** Read a capture fixture written by `attest capture` or `record()`. */
+declare function loadFixture(file: string | URL): Fixture;
+/** The `ExpectChain` method call that emits `contract`'s spec; throws when there is none. */
+declare function dslCall(contract: Contract): string;
+/**
+ * Where the drafted test for a fixture goes: `tests/attest/<name>.test.ts` for
+ * `tests/attest/fixtures/<name>.attest.json`.
+ */
+declare function testPathFor(fixturePath: string): string;
+/**
+ * Render a fixture's drafted contracts as a Vitest module.
+ *
+ * A verified fixture becomes a test that enforces every contract with `evaluate`. An
+ * incident reproduction (`expect_fail`) becomes a test that checks, with `inspect`, that
+ * the expected failures still fail and the other contracts still pass; it stays green
+ * while it reproduces the incident.
+ */
+declare function renderVitest(fixture: Fixture, fixturePath: string, testPath: string): string;
+/**
+ * Write the drafted Vitest file for a fixture unless it already exists. Returns the path
+ * written, or null when a test file is already there (re-capturing never overwrites an
+ * edited test).
+ */
+declare function emitVitest(fixturePath: string): string | null;
+/** A running in-process capture. */
+interface Capture {
+    name: string;
+    /** The variables `record()` set in `process.env` for the callback. */
+    env: Record<string, string>;
+}
+interface RecordOptions {
+    /** Fixture directory (default `tests/attest/fixtures`). */
+    outDir?: string;
+    /** Save an incident reproduction: verified when drafted contracts fail. */
+    expectFail?: boolean;
+    /** Trace `agent_id` (default: the first turn's agent name). */
+    agentId?: string;
+    /** Write the drafted Vitest file (default true). */
+    emitTest?: boolean;
+    /** Engine binary (default: the SDK's engine discovery). */
+    enginePath?: string;
+    /**
+     * A `world.yaml` to host for the callback (the engine's `--world`): its base URL variable
+     * (`PAYMENTS_BASE_URL`) is set for the callback and the world's final state is saved in
+     * the fixture's `world` section.
+     */
+    world?: string;
+    /**
+     * Called after the callback returns and before the fixture is built; pass the tracer
+     * provider's `forceFlush` so batched spans reach the receiver.
+     */
+    flush?: () => unknown;
+}
+interface RecordResult<T> {
+    value: T;
+    fixture: string;
+    verified: boolean;
+    testFile: string | null;
+}
+/**
+ * Capture `fn` as fixture `<outDir>/<name>.attest.json`.
+ *
+ * Starts `attest-engine capture --serve`, which hosts the recording proxy and the
+ * OTLP/HTTP receiver on 127.0.0.1, and sets `OPENAI_BASE_URL`, `ANTHROPIC_BASE_URL` and
+ * `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` while `fn` runs. Model clients and the
+ * OpenTelemetry exporter read these when they are constructed, so construct them inside
+ * `fn`, and pass the tracer provider's `forceFlush` as `flush`. Afterwards the variables
+ * are restored and the engine writes the fixture; for a verified fixture with `emitTest`
+ * the drafted Vitest file is written unless one exists. If `fn` throws, the capture is
+ * abandoned and no fixture is written. Captures cannot overlap.
+ *
+ * @throws CaptureError when another capture is running, the engine writes no fixture,
+ *   or the fixture is not verified (its drafted contracts did not hold; the fixture is
+ *   still written and no test is drafted).
+ */
+declare function record<T>(name: string, fn: (capture: Capture) => T | Promise<T>, opts?: RecordOptions): Promise<RecordResult<T>>;
+
+/**
+ * Replay: run the agent's real code with model responses served from a fixture.
+ *
+ * `startReplay(name)` starts `attest-engine replay --serve`, which hosts the replay
+ * proxy on 127.0.0.1, and sets `OPENAI_BASE_URL`, `ANTHROPIC_BASE_URL` and
+ * `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` until `finish()`. The proxy answers every model
+ * request from `<fixturesDir>/<name>.attest.json` and makes no provider call. A request
+ * that matches no recording is a miss; `finish()` returns the engine's summary.
+ */
+type ReplayMode = "strict" | "auto";
+type ReplayModeSetting = ReplayMode | "off";
+/** One request the agent made during the replay. */
+interface ReplayRecord {
+    seq: number;
+    provider: string;
+    api: string;
+    outcome: "replayed" | "live" | "miss";
+    exchange?: number;
+    message?: string;
+}
+/** What the replay session served, as the engine reports it. */
+interface ReplaySummary {
+    fixture: string;
+    mode: ReplayMode;
+    replayed: number;
+    live: number;
+    misses: number;
+    unused: number;
+    live_cost_usd: number;
+    unpriced_live_calls: number;
+    records: ReplayRecord[];
+}
+/** A strict-mode replay request matched no recording. `message` is the engine's miss message. */
+declare class ReplayMissError extends Error {
+    readonly summary: ReplaySummary;
+    constructor(message: string, summary: ReplaySummary);
+}
+/** An auto-mode replay request matched no recording and no provider key was set: `not_evaluated: replay_miss`. */
+declare class ReplayNotEvaluatedError extends Error {
+    readonly summary: ReplaySummary;
+    constructor(message: string, summary: ReplaySummary);
+}
+declare class ReplayError extends Error {
+    constructor(message: string);
+}
+interface ReplayOptions {
+    /** Fixture directory (default `tests/attest/fixtures`). */
+    fixturesDir?: string;
+    /** `strict`, `auto` or `off`; default per `resolveMode`. `off` starts nothing. */
+    mode?: ReplayModeSetting;
+    /**
+     * Pass `--no-live` to the engine: no miss is forwarded live. Default: `ATTEST_EGRESS=block`.
+     * An installed egress guard always implies it.
+     */
+    noLive?: boolean;
+    /** Engine binary (default: the SDK's engine discovery). */
+    enginePath?: string;
+}
+interface ReplaySession {
+    readonly name: string;
+    readonly mode: ReplayModeSetting;
+    /** The variables the session set in `process.env`. */
+    readonly env: Record<string, string>;
+    /** The summary once `finish()` has run, else `null`. */
+    readonly summary: ReplaySummary | null;
+    /** Stop the engine, restore the environment and return the summary (`null` for `off`). Idempotent. */
+    finish(): Promise<ReplaySummary | null>;
+    /** The error a miss raises (valid after `finish()`): strict => miss, auto => not evaluated. */
+    error(): ReplayMissError | ReplayNotEvaluatedError | null;
+    /** `finish()`, then throw `error()` if any. */
+    check(): Promise<void>;
+}
+/**
+ * Replay mode from `explicit`, else `ATTEST_REPLAY` (`strict|auto|off`), else `strict`
+ * when `CI` is set, else `auto`.
+ */
+declare function resolveMode(explicit?: ReplayModeSetting, env?: NodeJS.ProcessEnv): ReplayModeSetting;
+/** Start a replay session for fixture `name`. Sessions cannot overlap. */
+declare function startReplay(name: string, opts?: ReplayOptions): Promise<ReplaySession>;
+/** The first miss message of a summary, or `null`. */
+declare function firstMiss(summary: ReplaySummary): string | null;
+/** `N live model calls · $X.XX`, plus ` (+N unpriced)`. */
+declare function liveLine(live: number, costUsd: number, unpriced?: number): string;
+
+/** A world-v1 snapshot. */
+type WorldSnapshot = Record<string, unknown>;
+declare class WorldError extends Error {
+    constructor(message: string);
+}
+interface WorldOptions {
+    /** Engine binary (default: the SDK's engine discovery). */
+    enginePath?: string;
+}
+interface WorldSession {
+    /** The absolute `world.yaml` path. */
+    readonly path: string;
+    /** The variable the session set in `process.env`: the world's base URL. */
+    readonly env: Record<string, string>;
+    /** The world's base URL. */
+    readonly baseUrl: string;
+    /** The current world-v1 snapshot, read from the running world. */
+    state(): Promise<WorldSnapshot>;
+    /** Stop the world, restore the environment and return the final snapshot. Idempotent. */
+    stop(): Promise<WorldSnapshot>;
+}
+/** Host the world defined by `worldFile` until the session stops. Worlds cannot overlap. */
+declare function startWorld(worldFile: string, opts?: WorldOptions): Promise<WorldSession>;
+
+declare class EgressBlockedError extends Error {
+    readonly host: string;
+    constructor(host: string);
+}
+declare function isProviderHost(host: string): boolean;
+/** True when `ATTEST_EGRESS=block`. */
+declare function egressBlockRequested(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Install the guard. Installs are counted: the returned function releases only this
+ * install (once), and the guard comes off when every install has been released.
+ */
+declare function installEgressGuard(): () => void;
+/** Remove the guard now, whatever the install count. */
+declare function uninstallEgressGuard(): void;
+
 declare class Agent {
     readonly name: string;
     private readonly fn;
@@ -1163,27 +1551,51 @@ declare class OllamaAdapter {
     }): Trace;
 }
 
-interface OTelSpanContext {
-    traceId: string;
-}
+type AttributeValue = string | number | boolean | readonly (string | number | boolean | null | undefined)[];
+/** The parts of an `@opentelemetry/sdk-trace-base` `ReadableSpan` the adapter reads. */
 interface OTelSpan {
-    name: string;
-    startTime: [number, number];
-    endTime: [number, number];
-    attributes?: Record<string, unknown>;
-    parentSpanId?: string;
-    spanContext(): OTelSpanContext;
+    readonly name: string;
+    /** `[seconds, nanoseconds]` */
+    readonly startTime: readonly [number, number];
+    readonly endTime: readonly [number, number];
+    readonly attributes?: Readonly<Record<string, AttributeValue | undefined>>;
+    /** Parent span id (sdk-trace-base 1.x). */
+    readonly parentSpanId?: string;
+    /** Parent span context (sdk-trace-base 2.x). */
+    readonly parentSpanContext?: {
+        readonly spanId: string;
+    };
+    readonly status?: {
+        readonly code: number;
+        readonly message?: string;
+    };
+    spanContext(): {
+        readonly traceId: string;
+        readonly spanId: string;
+    };
 }
+/** An OTLP/JSON export: a parsed `ExportTraceServiceRequest`, its JSON text, or its bytes. */
+type OTLPInput = Record<string, unknown> | string | Uint8Array;
 declare class OTelAdapter {
-    private readonly agentId;
-    constructor(agentId?: string);
-    static fromSpans(spans: OTelSpan[], agentId?: string): Trace;
-    private buildTrace;
-    private findRootSpan;
-    private classifySpan;
-    private extractLlmStep;
-    private extractToolStep;
-    private spanMetadata;
+    /**
+     * Build a trace from finished OpenTelemetry spans of one trace.
+     *
+     * @param agentId Trace `agent_id`; defaults to the first turn's `gen_ai.agent.name`.
+     * @throws OTLPConversionError when the engine rejects the spans.
+     */
+    static fromSpans(spans: readonly OTelSpan[], agentId?: string): Promise<Trace>;
+    /**
+     * Convert an OTLP/JSON export (`resourceSpans` → `scopeSpans` → `spans`).
+     *
+     * @param agentId Trace `agent_id`; defaults to the first turn's `gen_ai.agent.name`.
+     * @throws OTLPConversionError when the engine rejects the export (malformed JSON, invalid
+     *   ids or timestamps, more than one trace, non-numeric token counts, ...).
+     * @throws RangeError when a parsed export holds a non-finite number.
+     * @throws OTLPConversionError when the engine times out, overflows the output buffer or
+     *   prints no trace.
+     * @throws Error when the engine cannot start.
+     */
+    static fromOtlp(otlp: OTLPInput, agentId?: string): Promise<Trace>;
 }
 
 /**
@@ -1250,4 +1662,5 @@ interface TraceAdapter {
     traceFromResponse(response: unknown, options?: Record<string, unknown>): Trace;
 }
 
-export { ADVERSARIAL_USER, Agent, AgentResult, type AgreementResult, AlertDispatcher, type AlertPayload, AnthropicAdapter, Assertion, AssertionResult, AttestClient, type AttestClientOptions, type AttestPlugin, CONFUSED_USER, COOPERATIVE_USER, ContinuousEvalRunner, ConversationMessage, DriftReport, ENGINE_VERSION, EngineManager, EvaluateBatchResult, ExpectChain, FRIENDLY_USER, GeminiAdapter, InitializeResult, type LabelPair, type LabeledRecord, LangChainAdapter, ManualAdapter, OTelAdapter, OllamaAdapter, OpenAIAdapter, Outcome, PluginRegistry, type PluginResult, ProtocolDiagnostic, ProtocolLogger, type RenderOptions, Sampler, SimulateFaultConfig, SimulatePersona, Step, TIER_1, TIER_2, TIER_3, Trace, type TraceAdapter, TraceBuilder, TraceTree, VERSION, activeBuilder, agent, attestExpect, computeAgreement, config, delegate, executePluginAssertion, getSampleRate, isSimulationMode, loadLabelsCSV, loadLabelsJSONL, promptHash, renderAssertionFailure, renderDiagnostics, renderSummary, requireSimulationCapability, resetConfig, simulationEnvEnabled, tier };
+export { ADVERSARIAL_USER, Agent, AgentResult, AlertDispatcher, AnthropicAdapter, Assertion, AssertionResult, AttestClient, BatchBudget, CONFUSED_USER, COOPERATIVE_USER, CaptureError, ContinuousEvalRunner, ConversationMessage, DriftReport, ENGINE_VERSION, EgressBlockedError, EngineManager, EvaluateBatchResult, ExpectChain, FRIENDLY_USER, GeminiAdapter, InitializeResult, LangChainAdapter, ManualAdapter, OTelAdapter, OllamaAdapter, OpenAIAdapter, Outcome, PluginRegistry, ProtocolDiagnostic, ProtocolLogger, ReplayError, ReplayMissError, ReplayNotEvaluatedError, Sampler, SimulateFaultConfig, SimulatePersona, Step, TIER_1, TIER_2, TIER_3, Trace, TraceBuilder, TraceTree, Usage, VERSION, WorldChecks, WorldError, activeBuilder, addUsage, agent, attestExpect, computeAgreement, config, delegate, dslCall, egressBlockRequested, emitVitest, executePluginAssertion, firstMiss, formatUsage, getSampleRate, installEgressGuard, isProviderHost, isSimulationMode, liveLine, loadFixture, loadLabelsCSV, loadLabelsJSONL, parseUsage, promptHash, record, renderAssertionFailure, renderDiagnostics, renderSummary, renderVitest, requireSimulationCapability, resetConfig, resolveMode, simulationEnvEnabled, startReplay, startWorld, sumUsage, testPathFor, tier, uninstallEgressGuard, usageSummaryLine, zeroUsage };
+export type { AgreementResult, AlertPayload, AttestClientOptions, AttestPlugin, Capture, Contract, ContractResult, Fixture, LabelPair, LabeledRecord, PluginResult, RecordOptions, RecordResult, RenderOptions, ReplayMode, ReplayModeSetting, ReplayOptions, ReplayRecord, ReplaySession, ReplaySummary, TraceAdapter, WorldOptions, WorldSession, WorldSnapshot };

package/dist/cjs/proto/index.cjs

@@ -28,15 +28,19 @@ __export(proto_exports, {
   ERR_TIMEOUT: () => ERR_TIMEOUT,
   EngineTimeoutError: () => EngineTimeoutError,
   FailureClass: () => FailureClass,
+  OTLPConversionError: () => OTLPConversionError,
   OUTCOME_FAIL: () => OUTCOME_FAIL,
   OUTCOME_PASS: () => OUTCOME_PASS,
   OUTCOME_SKIP: () => OUTCOME_SKIP,
   ProtocolDesyncError: () => ProtocolDesyncError,
   ProtocolDiagnosticBuffer: () => ProtocolDiagnosticBuffer,
   ProtocolError: () => ProtocolError,
+  REASON_BUDGET_EXHAUSTED: () => REASON_BUDGET_EXHAUSTED,
+  REASON_JUDGE_ABSTAINED: () => REASON_JUDGE_ABSTAINED,
   REASON_MISSING_EVIDENCE: () => REASON_MISSING_EVIDENCE,
   REASON_PROVIDER_NOT_CONFIGURED: () => REASON_PROVIDER_NOT_CONFIGURED,
   REASON_PROVIDER_UNAVAILABLE: () => REASON_PROVIDER_UNAVAILABLE,
+  REASON_REPLAY_MISS: () => REASON_REPLAY_MISS,
   REASON_SHORT_CIRCUITED: () => REASON_SHORT_CIRCUITED,
   REASON_SIMULATION: () => REASON_SIMULATION,
   STATUS_HARD_FAIL: () => STATUS_HARD_FAIL,
@@ -49,6 +53,7 @@ __export(proto_exports, {
   STEP_TOOL_CALL: () => STEP_TOOL_CALL,
   TYPE_CONSTRAINT: () => TYPE_CONSTRAINT,
   TYPE_CONTENT: () => TYPE_CONTENT,
+  TYPE_EFFECT: () => TYPE_EFFECT,
   TYPE_EMBEDDING: () => TYPE_EMBEDDING,
   TYPE_LLM_JUDGE: () => TYPE_LLM_JUDGE,
   TYPE_PLUGIN: () => TYPE_PLUGIN,
@@ -81,12 +86,16 @@ var REASON_PROVIDER_NOT_CONFIGURED = "provider_not_configured";
 var REASON_SIMULATION = "simulation";
 var REASON_MISSING_EVIDENCE = "missing_evidence";
 var REASON_SHORT_CIRCUITED = "short_circuited";
+var REASON_BUDGET_EXHAUSTED = "budget_exhausted";
+var REASON_JUDGE_ABSTAINED = "judge_abstained";
+var REASON_REPLAY_MISS = "replay_miss";
 var OUTCOME_PASS = "pass";
 var OUTCOME_FAIL = "fail";
 var OUTCOME_SKIP = "skip";
 var TYPE_SCHEMA = "schema";
 var TYPE_CONSTRAINT = "constraint";
 var TYPE_TRACE = "trace";
+var TYPE_EFFECT = "effect";
 var TYPE_CONTENT = "content";
 var TYPE_EMBEDDING = "embedding";
 var TYPE_LLM_JUDGE = "llm_judge";
@@ -124,6 +133,7 @@ function layerForType(assertionType) {
       return 2;
     case "trace":
     case "trace_tree":
+    case "effect":
       return 3;
     case "content":
       return 4;
@@ -171,6 +181,12 @@ var ProtocolDesyncError = class extends Error {
     this.diagnostics = diagnostics;
   }
 };
+var OTLPConversionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OTLPConversionError";
+  }
+};
 
 // src/proto/diagnostics.ts
 var DEFAULT_BUFFER_SIZE = 32;
@@ -285,15 +301,19 @@ function extractId(response) {
   ERR_TIMEOUT,
   EngineTimeoutError,
   FailureClass,
+  OTLPConversionError,
   OUTCOME_FAIL,
   OUTCOME_PASS,
   OUTCOME_SKIP,
   ProtocolDesyncError,
   ProtocolDiagnosticBuffer,
   ProtocolError,
+  REASON_BUDGET_EXHAUSTED,
+  REASON_JUDGE_ABSTAINED,
   REASON_MISSING_EVIDENCE,
   REASON_PROVIDER_NOT_CONFIGURED,
   REASON_PROVIDER_UNAVAILABLE,
+  REASON_REPLAY_MISS,
   REASON_SHORT_CIRCUITED,
   REASON_SIMULATION,
   STATUS_HARD_FAIL,
@@ -306,6 +326,7 @@ function extractId(response) {
   STEP_TOOL_CALL,
   TYPE_CONSTRAINT,
   TYPE_CONTENT,
+  TYPE_EFFECT,
   TYPE_EMBEDDING,
   TYPE_LLM_JUDGE,
   TYPE_PLUGIN,