@attest-ai/core 0.4.2 → 0.6.0

package/dist/cjs/index.d.cts

@@ -0,0 +1,1111 @@
+import { InitializeResult, Trace, Assertion, EvaluateBatchResult, DriftReport, SimulatePersona, ConversationMessage, SimulateFaultConfig, Step, AssertionResult } from './proto/index.cjs';
+export { AgentId, AssertionId, AssertionSpec, ConstraintSpec, ContentSpec, ERR_ASSERTION_ERROR, ERR_ENGINE_ERROR, ERR_INVALID_TRACE, ERR_PROVIDER_ERROR, ERR_SESSION_ERROR, ERR_TIMEOUT, EmbeddingSpec, EngineTimeoutError, ErrorData, EvaluateBatchParams, GenerateUserMessageParams, GenerateUserMessageResult, InitializeParams, LlmJudgeSpec, PluginSpec, ProtocolError, QueryDriftParams, QueryDriftResult, RPCError, RPCRequest, RPCResponse, STATUS_HARD_FAIL, 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, 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 = "0.6.0";
+declare const ENGINE_VERSION = "0.6.0";
+
+declare class EngineManager {
+    private enginePath;
+    private readonly logLevel;
+    private process;
+    private reader;
+    private initialized;
+    private requestId;
+    private initResult;
+    constructor(options?: {
+        enginePath?: string;
+        logLevel?: string;
+    });
+    start(): Promise<InitializeResult>;
+    stop(): Promise<void>;
+    sendRequest(method: string, params: Record<string, unknown>): Promise<unknown>;
+    private sendRequestInternal;
+    get isRunning(): boolean;
+    /** Expose process for AttestClient reader loop access */
+    get childProcess(): ChildProcess | null;
+    /** Expose readline interface for AttestClient reader loop */
+    get readlineInterface(): Interface | null;
+}
+
+declare class AttestClient {
+    private readonly engine;
+    private requestId;
+    private readonly pending;
+    private writeChain;
+    private readerActive;
+    private lineHandler;
+    constructor(engine: EngineManager);
+    startReader(): void;
+    stopReader(): void;
+    private handleLine;
+    private failAll;
+    sendRequest(method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    evaluateBatch(trace: Trace, assertions: readonly Assertion[], options?: {
+        timeout?: number;
+    }): Promise<EvaluateBatchResult>;
+    submitPluginResult(traceId: string, pluginName: string, assertionId: string, status: string, score: number, explanation: string, options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    queryDrift(assertionId: string, windowSize?: number, options?: {
+        timeout?: number;
+    }): Promise<DriftReport>;
+    generateUserMessage(persona: SimulatePersona, conversationHistory: readonly ConversationMessage[], faultConfig?: SimulateFaultConfig, options?: {
+        timeout?: number;
+    }): Promise<string>;
+}
+
+declare class TraceBuilder {
+    private traceId;
+    private agentId;
+    private input;
+    private readonly steps;
+    private output;
+    private metadata;
+    private parentTraceId;
+    constructor(agentId?: string);
+    setTraceId(traceId: string): this;
+    setInput(input: Record<string, unknown>): this;
+    addLlmCall(name: string, options?: {
+        args?: Record<string, unknown>;
+        result?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+    }): this;
+    addToolCall(name: string, options?: {
+        args?: Record<string, unknown>;
+        result?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+    }): this;
+    addRetrieval(name: string, options?: {
+        args?: Record<string, unknown>;
+        result?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+    }): this;
+    addStep(step: Step): this;
+    setOutput(output: Record<string, unknown>): this;
+    setMetadata(metadata: {
+        total_tokens?: number;
+        cost_usd?: number;
+        latency_ms?: number;
+        model?: string;
+        timestamp?: string;
+    }): this;
+    getTraceId(): string;
+    setParentTraceId(parentId: string): this;
+    build(): Trace;
+}
+
+declare class AgentResult {
+    readonly trace: Trace;
+    readonly assertionResults: readonly AssertionResult[];
+    readonly totalCost: number;
+    readonly totalDurationMs: number;
+    constructor(trace: Trace, assertionResults?: readonly AssertionResult[], totalCost?: number, totalDurationMs?: number);
+    get passed(): boolean;
+    get failedAssertions(): readonly AssertionResult[];
+    get hardFailures(): readonly AssertionResult[];
+    get softFailures(): readonly AssertionResult[];
+    get passCount(): number;
+    get failCount(): number;
+}
+
+declare class TraceTree {
+    readonly root: Trace;
+    constructor(root: Trace);
+    get agents(): string[];
+    private collectAgents;
+    findAgent(agentId: string): Trace | undefined;
+    private findAgentIn;
+    get depth(): number;
+    private computeDepth;
+    flatten(): Trace[];
+    private flattenInto;
+    get delegations(): [string, string][];
+    private collectDelegations;
+    allToolCalls(): Step[];
+    get aggregateTokens(): number;
+    get aggregateCost(): number;
+    get aggregateLatency(): number;
+}
+
+declare class ExpectChain {
+    private readonly _result;
+    private readonly _assertions;
+    constructor(result: AgentResult);
+    get assertions(): Assertion[];
+    get trace(): Trace;
+    private add;
+    /**
+     * Assert that `output.structured` conforms to the given JSON Schema.
+     *
+     * @param schema - A JSON Schema object to validate against.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).outputMatchesSchema({ type: "object", required: ["answer"] });
+     * ```
+     */
+    outputMatchesSchema(schema: Record<string, unknown>): this;
+    /**
+     * Assert that a specific output field conforms to the given JSON Schema.
+     *
+     * @param field - Dot-delimited path under `output` (e.g. `"structured.items"`).
+     * @param schema - A JSON Schema object to validate against.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).outputFieldMatchesSchema("structured.items", { type: "array" });
+     * ```
+     */
+    outputFieldMatchesSchema(field: string, schema: Record<string, unknown>): this;
+    /**
+     * Assert that a named tool's arguments conform to the given JSON Schema.
+     *
+     * @param toolName - The tool name to match in `steps`.
+     * @param schema - A JSON Schema object to validate against.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).toolArgsMatchSchema("search", { type: "object", required: ["query"] });
+     * ```
+     */
+    toolArgsMatchSchema(toolName: string, schema: Record<string, unknown>): this;
+    /**
+     * Assert that a named tool's result conforms to the given JSON Schema.
+     *
+     * @param toolName - The tool name to match in `steps`.
+     * @param schema - A JSON Schema object to validate against.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).toolResultMatchesSchema("search", { type: "object" });
+     * ```
+     */
+    toolResultMatchesSchema(toolName: string, schema: Record<string, unknown>): this;
+    /**
+     * Assert total cost (in USD) is at or below `maxCost`.
+     *
+     * @param maxCost - Maximum allowed cost in USD.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).costUnder(0.05);
+     * expect(result).costUnder(0.05, { soft: true });
+     * ```
+     */
+    costUnder(maxCost: number, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert total latency is at or below `maxMs` milliseconds.
+     *
+     * @param maxMs - Maximum allowed latency in milliseconds.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).latencyUnder(2000);
+     * ```
+     */
+    latencyUnder(maxMs: number, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert total token usage is at or below `maxTokens`.
+     *
+     * @param maxTokens - Maximum allowed token count.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).tokensUnder(500);
+     * ```
+     */
+    tokensUnder(maxTokens: number, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert total token usage is between `minTokens` and `maxTokens` (inclusive).
+     *
+     * @param minTokens - Minimum allowed token count.
+     * @param maxTokens - Maximum allowed token count.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).tokensBetween(100, 500);
+     * ```
+     */
+    tokensBetween(minTokens: number, maxTokens: number, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert the number of steps satisfies the given comparison.
+     *
+     * @param operator - Comparison operator (e.g. `"eq"`, `"lte"`, `"gte"`).
+     * @param value - The reference count to compare against.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).stepCount("lte", 5);
+     * ```
+     */
+    stepCount(operator: string, value: number, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert the number of tool-call steps satisfies the given comparison.
+     *
+     * @param operator - Comparison operator (e.g. `"eq"`, `"lte"`, `"gte"`).
+     * @param value - The reference count to compare against.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).toolCallCount("gte", 1);
+     * ```
+     */
+    toolCallCount(operator: string, value: number, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Generic constraint assertion on any field.
+     *
+     * @param field - Dot-delimited path into the trace (e.g. `"metadata.cost_usd"`).
+     * @param operator - Comparison operator.
+     * @param opts.value - Reference value for single-operand operators.
+     * @param opts.min - Minimum for `"between"` operator.
+     * @param opts.max - Maximum for `"between"` operator.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).constraint("metadata.cost_usd", "lte", { value: 0.1 });
+     * ```
+     */
+    constraint(field: string, operator: string, opts?: {
+        value?: number;
+        min?: number;
+        max?: number;
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert that tools were called in the given order (non-contiguous allowed).
+     *
+     * @param tools - Ordered list of tool names expected.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).toolsCalledInOrder(["search", "write"]);
+     * ```
+     */
+    toolsCalledInOrder(tools: string[], opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert that tools were called in exact contiguous order.
+     *
+     * @param tools - Exact ordered list of tool names.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).toolsCalledExactly(["search", "summarize", "respond"]);
+     * ```
+     */
+    toolsCalledExactly(tools: string[], opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert a tool is not called more than `maxRepetitions` times consecutively.
+     *
+     * @param tool - The tool name to check.
+     * @param maxRepetitions - Maximum allowed consecutive calls (default `1`).
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).noToolLoops("fetch", 2);
+     * ```
+     */
+    noToolLoops(tool: string, maxRepetitions?: number, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert no tool is called more than once.
+     *
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).noDuplicateTools();
+     * ```
+     */
+    noDuplicateTools(opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert that all listed tools were called at least once.
+     *
+     * @param tools - Tool names that must appear in the trace.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).requiredTools(["search", "respond"]);
+     * ```
+     */
+    requiredTools(tools: string[], opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert that none of the listed tools were called.
+     *
+     * @param tools - Tool names that must not appear in the trace.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).forbiddenTools(["delete_user", "drop_table"]);
+     * ```
+     */
+    forbiddenTools(tools: string[], opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert the output message contains the given string.
+     *
+     * @param value - Substring to search for.
+     * @param opts.caseSensitive - Enable case-sensitive matching (default `false`).
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).outputContains("refund approved");
+     * ```
+     */
+    outputContains(value: string, opts?: {
+        caseSensitive?: boolean;
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert the output message does not contain the given string.
+     *
+     * @param value - Substring that must be absent.
+     * @param opts.caseSensitive - Enable case-sensitive matching (default `false`).
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).outputNotContains("internal error");
+     * ```
+     */
+    outputNotContains(value: string, opts?: {
+        caseSensitive?: boolean;
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert the output message matches the given regular expression.
+     *
+     * @param pattern - Regex pattern string.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).outputMatchesRegex("order #\\d{5}");
+     * ```
+     */
+    outputMatchesRegex(pattern: string, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert the output message contains all of the given keywords.
+     *
+     * @param keywords - Keywords that must all be present.
+     * @param opts.caseSensitive - Enable case-sensitive matching (default `false`).
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).outputHasAllKeywords(["refund", "processed"]);
+     * ```
+     */
+    outputHasAllKeywords(keywords: string[], opts?: {
+        caseSensitive?: boolean;
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert the output message contains at least one of the given keywords.
+     *
+     * @param keywords - Keywords where at least one must be present.
+     * @param opts.caseSensitive - Enable case-sensitive matching (default `false`).
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).outputHasAnyKeyword(["yes", "confirmed"]);
+     * ```
+     */
+    outputHasAnyKeyword(keywords: string[], opts?: {
+        caseSensitive?: boolean;
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert the output message contains none of the forbidden terms.
+     *
+     * @param terms - Terms that must not appear in the output.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).outputForbids(["password", "api_key"]);
+     * ```
+     */
+    outputForbids(terms: string[]): this;
+    /**
+     * Generic content-contains check on any target path.
+     *
+     * @param target - Dot-delimited path into the trace.
+     * @param value - Substring to search for.
+     * @param opts.caseSensitive - Enable case-sensitive matching (default `false`).
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).contentContains("steps[0].result.text", "success");
+     * ```
+     */
+    contentContains(target: string, value: string, opts?: {
+        caseSensitive?: boolean;
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert the output is semantically similar to a reference string via embeddings.
+     *
+     * @param reference - The reference text to compare against.
+     * @param opts.threshold - Minimum cosine similarity (default `0.8`).
+     * @param opts.model - Override the embedding model.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).outputSimilarTo("The order has been refunded", { threshold: 0.85 });
+     * ```
+     */
+    outputSimilarTo(reference: string, opts?: {
+        threshold?: number | "dynamic";
+        model?: string;
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert the output passes LLM judge evaluation against given criteria.
+     *
+     * @param criteria - Natural language description of what makes a good response.
+     * @param opts.rubric - Rubric name (default `"default"`).
+     * @param opts.threshold - Minimum passing score (default `0.8`).
+     * @param opts.model - Override the judge model.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).passesJudge("Response is polite and helpful", { threshold: 0.9 });
+     * ```
+     */
+    passesJudge(criteria: string, opts?: {
+        rubric?: string;
+        threshold?: number | "dynamic";
+        model?: string;
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert that a specific agent was called in the trace tree.
+     *
+     * @param agentId - The agent identifier to look for.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).agentCalled("summarizer");
+     * ```
+     */
+    agentCalled(agentId: string, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert the trace tree delegation depth does not exceed `maxDepth`.
+     *
+     * @param maxDepth - Maximum allowed delegation depth.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).delegationDepth(3);
+     * ```
+     */
+    delegationDepth(maxDepth: number, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert a sub-agent's output contains the given string.
+     *
+     * @param agentId - The agent whose output to check.
+     * @param value - Substring to search for.
+     * @param opts.caseSensitive - Enable case-sensitive matching (default `false`).
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).agentOutputContains("summarizer", "key findings");
+     * ```
+     */
+    agentOutputContains(agentId: string, value: string, opts?: {
+        caseSensitive?: boolean;
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert data flows from one agent's output to another agent's input.
+     *
+     * @param fromAgent - Source agent ID.
+     * @param toAgent - Destination agent ID.
+     * @param field - The data field that must flow between agents.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).crossAgentDataFlow("researcher", "writer", "findings");
+     * ```
+     */
+    crossAgentDataFlow(fromAgent: string, toAgent: string, field: string, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert agent delegations follow the specified transitions.
+     *
+     * @param transitions - Array of `[fromAgent, toAgent]` pairs.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).followsTransitions([["root", "planner"], ["planner", "executor"]]);
+     * ```
+     */
+    followsTransitions(transitions: [string, string][], opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert aggregate cost across the entire trace tree is at or below `maxCost`.
+     *
+     * @param maxCost - Maximum allowed aggregate cost in USD.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).aggregateCostUnder(0.50);
+     * ```
+     */
+    aggregateCostUnder(maxCost: number, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert aggregate tokens across the entire trace tree is at or below `maxTokens`.
+     *
+     * @param maxTokens - Maximum allowed aggregate token count.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).aggregateTokensUnder(10000);
+     * ```
+     */
+    aggregateTokensUnder(maxTokens: number, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert `agentA` started before `agentB` in the trace tree.
+     *
+     * @param agentA - The agent expected to run first.
+     * @param agentB - The agent expected to run second.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).agentOrderedBefore("planner", "executor");
+     * ```
+     */
+    agentOrderedBefore(agentA: string, agentB: string, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert `agentA` and `agentB` ran concurrently (overlapping wall-clock time).
+     *
+     * @param agentA - First agent ID.
+     * @param agentB - Second agent ID.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).agentsOverlap("worker-1", "worker-2");
+     * ```
+     */
+    agentsOverlap(agentA: string, agentB: string, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert a specific agent's wall-clock duration is under `maxMs` milliseconds.
+     *
+     * @param agentId - The agent to check.
+     * @param maxMs - Maximum allowed wall-clock time in milliseconds.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).agentWallTimeUnder("summarizer", 5000);
+     * ```
+     */
+    agentWallTimeUnder(agentId: string, maxMs: number, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert agents ran in ordered groups (parallel within each group, sequential across groups).
+     *
+     * @param groups - Array of agent-ID arrays. Each sub-array is a parallel group.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).orderedAgents([["planner"], ["worker-1", "worker-2"], ["aggregator"]]);
+     * ```
+     */
+    orderedAgents(groups: string[][], opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert via a registered plugin (Layer 8).
+     *
+     * @param pluginId - Identifier of the plugin registered with the engine.
+     * @param config - Plugin-specific configuration passed at evaluation time.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).plugin("custom-safety-check", { threshold: 0.95 });
+     * ```
+     */
+    plugin(pluginId: string, config?: Record<string, unknown>, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert aggregate latency across the trace tree is at or below `maxMs`.
+     *
+     * @param maxMs - Maximum allowed aggregate latency in milliseconds.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).aggregateLatencyUnder(5000);
+     * ```
+     */
+    aggregateLatencyUnder(maxMs: number, opts?: {
+        soft?: boolean;
+    }): this;
+    /**
+     * Assert that all specified tools were called across the entire trace tree.
+     *
+     * @param toolNames - Tool names that must appear somewhere in the tree.
+     * @param opts.soft - When `true` the failure is non-blocking.
+     * @returns The chain for fluent composition.
+     *
+     * @example
+     * ```ts
+     * expect(result).allToolsCalled(["search", "summarize"]);
+     * ```
+     */
+    allToolsCalled(toolNames: string[], opts?: {
+        soft?: boolean;
+    }): this;
+}
+/**
+ * Create an assertion chain for an agent result.
+ *
+ * Accepts either an {@link AgentResult} or a raw {@link Trace}. When a
+ * `Trace` is passed it is automatically wrapped in an `AgentResult`.
+ *
+ * @param result - An `AgentResult` or raw `Trace` to build assertions on.
+ * @returns A new {@link ExpectChain} for fluent assertion building.
+ *
+ * @example
+ * ```ts
+ * attestExpect(result).outputContains("hello").costUnder(0.05);
+ * attestExpect(trace).requiredTools(["search"]);
+ * ```
+ */
+declare function attestExpect(result: AgentResult | Trace): ExpectChain;
+
+declare class Agent {
+    readonly name: string;
+    private readonly fn;
+    constructor(name: string, fn?: (builder: TraceBuilder, args: Record<string, unknown>) => unknown);
+    run(args?: Record<string, unknown>): AgentResult;
+    arun(args?: Record<string, unknown>): Promise<AgentResult>;
+    private setOutput;
+    withTrace(trace: Trace): AgentResult;
+}
+declare function agent(name: string, fn: (builder: TraceBuilder, args: Record<string, unknown>) => unknown): (args?: Record<string, unknown>) => AgentResult;
+
+declare function delegate(agentId: string, fn: (child: TraceBuilder) => Promise<void> | void): Promise<void>;
+
+declare const activeBuilder: AsyncLocalStorage<TraceBuilder>;
+
+declare const TIER_1: 1;
+declare const TIER_2: 2;
+declare const TIER_3: 3;
+declare function tier(level: number): <T extends (...args: never[]) => unknown>(fn: T) => T;
+
+/**
+ * Configure global SDK options.
+ *
+ * @param options.simulation - Enable simulation mode. All `evaluateBatch` calls
+ *   return deterministic pass results without spawning the engine or calling any
+ *   LLM. Equivalent to setting `ATTEST_SIMULATION=1` in the environment.
+ * @param options.sampleRate - Sampling rate for continuous evaluation (0.0–1.0).
+ *   Equivalent to setting `ATTEST_SAMPLE_RATE` in the environment.
+ */
+declare function config(options: {
+    simulation?: boolean;
+    sampleRate?: number;
+}): void;
+/**
+ * Returns true when simulation mode is active via either the programmatic API
+ * or the `ATTEST_SIMULATION` environment variable.
+ */
+declare function isSimulationMode(): boolean;
+/**
+ * Returns the sampling rate for continuous evaluation. Priority:
+ * programmatic `config({ sampleRate })` > `ATTEST_SAMPLE_RATE` env var > 0.
+ */
+declare function getSampleRate(): number;
+/**
+ * Reset all programmatic config to defaults. Primarily for use in tests.
+ * Environment variables are not affected.
+ */
+declare function resetConfig(): void;
+
+/**
+ * Return a deterministic all-pass result for every assertion without
+ * contacting the engine or any LLM provider. Used when simulation mode
+ * is active (`ATTEST_SIMULATION=1` or `config({ simulation: true })`).
+ */
+declare function simulationEvaluateBatch(assertions: readonly Assertion[]): EvaluateBatchResult;
+
+interface PluginResult {
+    readonly status: string;
+    readonly score: number;
+    readonly explanation: string;
+    readonly metadata?: Record<string, unknown>;
+}
+interface AttestPlugin {
+    readonly name: string;
+    readonly pluginType: string;
+    execute(trace: Trace, spec: Record<string, unknown>): PluginResult | Promise<PluginResult>;
+}
+declare class PluginRegistry {
+    private readonly plugins;
+    register(name: string, plugin: AttestPlugin): void;
+    get(pluginType: string, name: string): AttestPlugin | undefined;
+    listPlugins(pluginType?: string): string[];
+}
+declare function executePluginAssertion(plugin: AttestPlugin, trace: Trace, spec: Record<string, unknown>, client: AttestClient, traceId: string, assertionId: string, timeoutMs?: number): Promise<PluginResult>;
+
+declare class Sampler {
+    private readonly rate;
+    constructor(rate: number);
+    shouldSample(): boolean;
+}
+interface AlertPayload {
+    drift_type: string;
+    score: number | string;
+    trace_id: string;
+    [key: string]: unknown;
+}
+declare class AlertDispatcher extends EventEmitter {
+    private readonly webhookUrl;
+    private readonly slackUrl;
+    constructor(webhookUrl?: string, slackUrl?: string);
+    dispatch(alert: AlertPayload): Promise<void>;
+    private postJson;
+}
+declare class ContinuousEvalRunner {
+    private readonly client;
+    private readonly assertions;
+    private readonly sampler;
+    private readonly dispatcher;
+    private readonly queue;
+    private readonly maxSize;
+    private running;
+    private loopTimer;
+    constructor(client: AttestClient, assertions: readonly Assertion[], options?: {
+        sampleRate?: number;
+        alertWebhook?: string;
+        alertSlackUrl?: string;
+        maxSize?: number;
+    });
+    get alertEmitter(): AlertDispatcher;
+    evaluateTrace(trace: Trace): Promise<EvaluateBatchResult | null>;
+    submit(trace: Trace): boolean;
+    start(): void;
+    stop(): void;
+    get queueLength(): number;
+    get isRunning(): boolean;
+    private scheduleNext;
+}
+
+declare const FRIENDLY_USER: SimulatePersona;
+declare const ADVERSARIAL_USER: SimulatePersona;
+declare const CONFUSED_USER: SimulatePersona;
+declare const COOPERATIVE_USER: SimulatePersona;
+
+declare class ManualAdapter {
+    private readonly agentId;
+    constructor(agentId?: string);
+    capture(builderFn: (builder: TraceBuilder) => void): Trace;
+    createBuilder(): TraceBuilder;
+}
+
+interface OpenAIUsage {
+    total_tokens?: number;
+}
+interface OpenAIToolCall {
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface OpenAIMessage {
+    content: string | null;
+    tool_calls?: OpenAIToolCall[];
+}
+interface OpenAIChoice {
+    message: OpenAIMessage;
+}
+interface OpenAIChatCompletion {
+    model?: string;
+    usage?: OpenAIUsage;
+    choices: OpenAIChoice[];
+}
+declare class OpenAIAdapter {
+    private readonly agentId;
+    constructor(agentId?: string);
+    traceFromResponse(response: OpenAIChatCompletion, options?: {
+        inputMessages?: Record<string, unknown>[];
+        costUsd?: number;
+        latencyMs?: number;
+        structuredOutput?: Record<string, unknown>;
+    }): Trace;
+}
+
+interface AnthropicTextBlock {
+    type: "text";
+    text: string;
+}
+interface AnthropicToolUseBlock {
+    type: "tool_use";
+    name: string;
+    input: Record<string, unknown>;
+}
+type AnthropicContentBlock = AnthropicTextBlock | AnthropicToolUseBlock;
+interface AnthropicUsage {
+    input_tokens: number;
+    output_tokens: number;
+}
+interface AnthropicMessage {
+    model?: string;
+    usage?: AnthropicUsage;
+    content: AnthropicContentBlock[];
+}
+declare class AnthropicAdapter {
+    private readonly agentId;
+    constructor(agentId?: string);
+    traceFromResponse(response: AnthropicMessage, options?: {
+        inputMessages?: Record<string, unknown>[];
+        costUsd?: number;
+        latencyMs?: number;
+    }): Trace;
+}
+
+interface GeminiFunctionCall {
+    name: string;
+    args?: Record<string, unknown>;
+}
+interface GeminiPart {
+    text?: string;
+    functionCall?: GeminiFunctionCall;
+}
+interface GeminiCandidate {
+    content: {
+        parts: GeminiPart[];
+    };
+}
+interface GeminiResponse {
+    text?: string;
+    candidates?: GeminiCandidate[];
+}
+declare class GeminiAdapter {
+    private readonly agentId;
+    constructor(agentId?: string);
+    traceFromResponse(response: GeminiResponse, options?: {
+        inputText?: string;
+        costUsd?: number;
+        latencyMs?: number;
+        model?: string;
+    }): Trace;
+}
+
+interface OllamaResponse {
+    model?: string;
+    message?: {
+        content?: string;
+    };
+    eval_count?: number;
+    prompt_eval_count?: number;
+}
+declare class OllamaAdapter {
+    private readonly agentId;
+    constructor(agentId?: string);
+    traceFromResponse(response: OllamaResponse, options?: {
+        inputMessages?: Record<string, unknown>[];
+        latencyMs?: number;
+    }): Trace;
+}
+
+interface OTelSpanContext {
+    traceId: string;
+}
+interface OTelSpan {
+    name: string;
+    startTime: [number, number];
+    endTime: [number, number];
+    attributes?: Record<string, unknown>;
+    parentSpanId?: string;
+    spanContext(): OTelSpanContext;
+}
+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;
+}
+
+/**
+ * Minimal type definitions for `@langchain/core` callback handler.
+ * These avoid a hard dependency on `@langchain/core` — the actual types
+ * are checked at runtime when the user provides real LangChain objects.
+ */
+interface LangChainLLMResult {
+    generations: Array<Array<{
+        text: string;
+        [key: string]: unknown;
+    }>>;
+    llmOutput?: Record<string, unknown>;
+}
+interface LangChainToolEnd {
+    name?: string;
+    output: string;
+    [key: string]: unknown;
+}
+interface LangChainChainValues {
+    [key: string]: unknown;
+}
+declare class LangChainAdapter {
+    private readonly agentId;
+    private readonly llmCalls;
+    private readonly toolCalls;
+    private chainOutput;
+    private startTime;
+    constructor(agentId?: string);
+    /**
+     * Reset accumulated state for a new trace capture session.
+     */
+    reset(): void;
+    /**
+     * Call this when a chain starts (maps to `handleChainStart`).
+     */
+    handleChainStart(): void;
+    /**
+     * Call this when an LLM call completes (maps to `handleLLMEnd`).
+     */
+    handleLLMEnd(output: LangChainLLMResult): void;
+    /**
+     * Call this when a tool call completes (maps to `handleToolEnd`).
+     */
+    handleToolEnd(output: string, metadata?: LangChainToolEnd): void;
+    /**
+     * Call this when a chain completes (maps to `handleChainEnd`).
+     */
+    handleChainEnd(output: LangChainChainValues): void;
+    /**
+     * Build a Trace from accumulated callback events.
+     *
+     * @param options.costUsd - Total cost override.
+     * @param options.model - Model name override.
+     * @returns A finalized Trace object.
+     */
+    buildTrace(options?: {
+        costUsd?: number;
+        model?: string;
+    }): Trace;
+}
+
+interface TraceAdapter {
+    traceFromResponse(response: unknown, options?: Record<string, unknown>): Trace;
+}
+
+export { ADVERSARIAL_USER, Agent, AgentResult, AlertDispatcher, type AlertPayload, AnthropicAdapter, Assertion, AssertionResult, AttestClient, type AttestPlugin, CONFUSED_USER, COOPERATIVE_USER, ContinuousEvalRunner, ConversationMessage, DriftReport, ENGINE_VERSION, EngineManager, EvaluateBatchResult, ExpectChain, FRIENDLY_USER, GeminiAdapter, InitializeResult, LangChainAdapter, ManualAdapter, OTelAdapter, OllamaAdapter, OpenAIAdapter, PluginRegistry, type PluginResult, Sampler, SimulateFaultConfig, SimulatePersona, Step, TIER_1, TIER_2, TIER_3, Trace, type TraceAdapter, TraceBuilder, TraceTree, VERSION, activeBuilder, agent, attestExpect, config, delegate, executePluginAssertion, getSampleRate, isSimulationMode, resetConfig, simulationEvaluateBatch, tier };