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

package/dist/esm/index.d.ts

@@ -1,38 +1,18 @@
-import { InitializeResult, ProtocolLogger, ProtocolDiagnostic, Trace, Assertion, BatchBudget, BatchContext, EvaluateBatchResult, DriftReport, SimulatePersona, ConversationMessage, SimulateFaultConfig, Step, AssertionResult, Usage, Outcome } from './proto/index.js';
-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.js';
+import { ProtocolLogger, ProtocolDiagnostic, Trace, Assertion, BatchBudget, BatchContext, EvaluateBatchResult, DriftReport, SimulatePersona, ConversationMessage, SimulateFaultConfig, InitializeResult, Usage, Step, AssertionResult, Outcome } from './proto/index.js';
+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_JUDGE_MALFORMED, REASON_MISSING_EVIDENCE, REASON_PROVIDER_AUTH, 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.js';
 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";
-declare const ENGINE_VERSION = "1.0.0";
+declare const VERSION = "1.1.0-rc.1";
+declare const ENGINE_VERSION = "1.1.0-rc.1";
 
-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>;
-    /** Send initialize and check the engine's version and capabilities. */
-    private initialize;
-    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;
+/** Budget a timed-out request may have consumed; null means the whole remaining budget. */
+interface BudgetReservation {
+    readonly judgeCalls: number | null;
+    readonly usd: number | null;
 }
-
 interface AttestClientOptions {
     /** Logger override. When omitted, warnings only emit if ATTEST_DEBUG_PROTOCOL=1. */
     logger?: ProtocolLogger;
@@ -62,6 +42,7 @@ declare class AttestClient {
     private writeChain;
     private readerActive;
     private lineHandler;
+    private attachedReader;
     private readonly logger;
     private readonly diagnosticBuffer;
     private readonly diagnosticListeners;
@@ -73,24 +54,46 @@ declare class AttestClient {
     onProtocolDiagnostic(listener: (diagnostic: ProtocolDiagnostic) => void): () => void;
     /** Snapshot of the diagnostic ring buffer (most recent last). */
     protocolDiagnostics(): readonly ProtocolDiagnostic[];
+    /**
+     * Attach the id-routed reader to the engine's stdout. Idempotent; `sendRequest` starts it
+     * on first use, so calling it is optional.
+     */
     startReader(): void;
     stopReader(): void;
     private recordDiagnostic;
     private maybeTriggerDesync;
     private handleLine;
     private handleDecodeFailure;
+    /** Reject every request still waiting for a response. */
+    rejectPending(err: Error): void;
     private failAll;
+    /**
+     * Send one request and resolve with the result of the response that carries its id.
+     *
+     * After a timeout the engine is restarted (its late response can no longer be matched),
+     * every other pending request is rejected, and the new engine gets the remaining session
+     * budget.
+     */
     sendRequest(method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    /** `sendRequest` without the restart-on-timeout step, for the engine's own handshake. */
+    sendWithoutRestart(method: string, params: Record<string, unknown>, timeoutMs: number): Promise<unknown>;
+    private send;
+    /** A failed pipe write names the engine's stderr tail; the original error stays as `cause` and `code`. */
+    private describeWriteError;
+    private recoverFromTimeout;
     evaluateBatch(trace: Trace, assertions: readonly Assertion[], options?: {
         timeout?: number;
         budget?: BatchBudget;
         context?: BatchContext;
     }): Promise<EvaluateBatchResult>;
+    /** Reject a response whose assertion ids differ from the ids that were sent. */
+    private requireSentAssertionIds;
     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;
+        staticThreshold?: number;
     }): Promise<DriftReport>;
     generateUserMessage(persona: SimulatePersona, conversationHistory: readonly ConversationMessage[], faultConfig?: SimulateFaultConfig, options?: {
         timeout?: number;
@@ -103,6 +106,70 @@ declare class AttestClient {
  */
 declare function requireSimulationCapability(init: InitializeResult | null | undefined): void;
 
+declare class EngineManager {
+    private enginePath;
+    private readonly logLevel;
+    private readonly initializeTimeoutMs;
+    private process;
+    private reader;
+    private initialized;
+    private initResult;
+    private routedClient;
+    /** The running engine's stderr tail; each launch owns a fresh one so a killed engine cannot write into it. */
+    private stderr;
+    private restarting;
+    private configuredBudget;
+    private usedJudgeCalls;
+    private usedUsd;
+    private heldJudgeCalls;
+    private heldUsd;
+    /** Spend the SDK cannot observe may have happened; a restart then leaves no budget. */
+    private unknownSpend;
+    constructor(options?: {
+        enginePath?: string;
+        logLevel?: string;
+        initializeTimeoutMs?: number;
+    });
+    /**
+     * Start the engine and complete the `initialize` handshake. Rejects when the engine exits,
+     * closes its pipes or fails to answer within the initialize timeout; the error carries the
+     * tail of the engine's stderr.
+     */
+    start(): Promise<InitializeResult>;
+    /** Spawn the engine and run `initialize` on it; the engine is stopped when that fails. */
+    private launch;
+    /** Send initialize and check the engine's version and capabilities. */
+    private initialize;
+    stop(): Promise<void>;
+    /** Close the pipes, reject pending requests and stop the engine process (SIGKILL when `force`). */
+    private terminate;
+    /**
+     * Replace the engine after a request timed out: its late response can no longer be told
+     * apart from a new one. The new engine gets the remaining session budget: the configured
+     * limit minus the usage already returned, minus what the abandoned requests may still have
+     * reserved. A restart that leaves no budget makes later model calls
+     * `not_evaluated(budget_exhausted)`.
+     */
+    restartAfterTimeout(abandoned: readonly BudgetReservation[]): Promise<void>;
+    /** An engine reply the SDK cannot account for (no usage, an RPC error, a dropped reply) may have spent budget. */
+    markUnknownSpend(): void;
+    private restart;
+    /** Count the usage an evaluate_batch result reported against the session budget. */
+    recordUsage(usage: Usage): void;
+    /** Resolves once an engine restart in progress has finished. */
+    whenReady(): Promise<void>;
+    /** Tail of the engine's stderr: the reason an engine died. */
+    get stderrTail(): string;
+    /** The client that routes this engine's responses by id; replaced when the engine restarts. */
+    get client(): AttestClient | undefined;
+    sendRequest(method: string, params: Record<string, unknown>): Promise<unknown>;
+    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 TraceBuilder {
     private traceId;
     private agentId;
@@ -291,11 +358,23 @@ declare class WorldChecks<C> {
         where?: Where;
     }): C;
 }
+type ChainObserver = (chain: ExpectChain) => void;
+/**
+ * Register the function called with every new {@link ExpectChain}. The Vitest integration uses
+ * it to fail a test that builds a chain it never evaluates. One observer at a time; pass
+ * `undefined` to remove it.
+ */
+declare function setChainObserver(observer: ChainObserver | undefined): void;
 declare class ExpectChain {
     private readonly _result;
     private readonly _assertions;
     private _worldBytes;
+    private _evaluated;
     constructor(result: AgentResult);
+    /** True once the chain was handed to an evaluation. */
+    get evaluated(): boolean;
+    /** Record that the chain was handed to an evaluation. */
+    markEvaluated(): void;
     get assertions(): Assertion[];
     get trace(): Trace;
     private add;
@@ -1005,6 +1084,35 @@ declare class ExpectChain {
  */
 declare function attestExpect(result: AgentResult | Trace): ExpectChain;
 
+/**
+ * Assertion ids, id scheme 2 (contract C3). Normative text:
+ * proto/attest/v1/protocol-spec.md, "Assertion ids (id scheme 2)"; executable form:
+ * protocol-tests/ids/assertion-ids.json.
+ */
+declare const ID_SCHEME = 2;
+/** What an id is computed for; names the assertion in rejection errors. */
+interface AssertionIdentity {
+    readonly scopeId: string;
+    readonly type: string;
+    readonly spec: unknown;
+}
+/** RFC 8785 (JCS) serialization of an assertion spec; no spec is `{}`. */
+declare function canonicalSpec(spec: unknown, identity?: AssertionIdentity): string;
+/** The exact bytes (as text) that are hashed: the JCS array `[scope_id, type, spec, occurrence_index]`. */
+declare function canonicalIdInput(scopeId: string, type: string, spec: unknown, occurrenceIndex: number): string;
+/** `a2_` plus the first 32 hex characters of SHA-256 over the UTF-8 bytes of the id input. */
+declare function assertionIdOf(scopeId: string, type: string, spec: unknown, occurrenceIndex: number): string;
+/**
+ * Assigns ids inside one scope. The occurrence index of an assertion is the number of earlier
+ * assertions given an id here with the same (type, canonical spec), in call order.
+ */
+declare class AssertionIdAssigner {
+    readonly scopeId: string;
+    private readonly seen;
+    constructor(scopeId: string);
+    next(type: string, spec: unknown): string;
+}
+
 /**
  * Capture: turn a run into a verified fixture, and fixtures into tests.
  *
@@ -1015,7 +1123,9 @@ declare function attestExpect(result: AgentResult | Trace): ExpectChain;
  * - `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.
+ *   `attestExpect()` DSL. `attest capture` and `record()` call it. For a fixture captured
+ *   from a command, the test re-runs that command under strict replay (`replayRun()`) and
+ *   evaluates the contracts on the new run's trace.
  */
 
 /** A capture did not produce a fixture, or produced one that is not verified. */
@@ -1067,6 +1177,15 @@ interface Fixture {
 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 a drafted replay test re-runs the fixture's source command: `cwd` is the directory
+ * the capture ran in (the command's relative paths resolve there), `world` the world file
+ * the capture hosted, if any.
+ */
+interface Rerun {
+    cwd: string;
+    world?: string;
+}
 /**
  * Where the drafted test for a fixture goes: `tests/attest/<name>.test.ts` for
  * `tests/attest/fixtures/<name>.attest.json`.
@@ -1075,18 +1194,56 @@ 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.
+ * With `rerun` and a fixture captured from a command, the test re-runs that command under
+ * strict replay and evaluates every contract on the new run's trace (an incident
+ * reproduction included: it passes once the agent no longer reproduces the incident).
+ * Otherwise a verified fixture becomes a test that enforces every contract on the recorded
+ * trace with `evaluate`, and an incident reproduction (`expect_fail`) 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;
+declare function renderVitest(fixture: Fixture, fixturePath: string, testPath: string, rerun?: Rerun): 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).
+ * edited test). `rerun` makes the test of a command fixture re-run the command under strict
+ * replay (see `renderVitest`).
  */
-declare function emitVitest(fixturePath: string): string | null;
+declare function emitVitest(fixturePath: string, rerun?: Rerun): string | null;
+interface ReplayRunOptions {
+    /** The argv to run, written in the reviewed test; must equal the fixture's `source.command`. */
+    command: readonly string[];
+    /** Directory to run the command in (the one the capture ran in). */
+    cwd?: string | URL;
+    /** World file the capture hosted, when the fixture has a `world` section. */
+    world?: string | URL;
+    /** Engine binary; default is the SDK's discovery order. */
+    enginePath?: string;
+    /** Milliseconds before the run is abandoned (default 300000). */
+    timeoutMs?: number;
+}
+/**
+ * Re-run a fixture's source command under strict replay and return the new run's trace.
+ *
+ * Runs `attest-engine replay --mode strict --no-live --trace-out ... -- <command>`: the
+ * OpenAI- and Anthropic-compatible calls the command makes are answered from the fixture's
+ * recorded exchanges, and a call that matches no recording fails. Other providers are not
+ * blocked: the replay proxy redirects only `OPENAI_BASE_URL` and `ANTHROPIC_BASE_URL`, and
+ * `ATTEST_EGRESS=block` only affects processes that install attest's guard.
+ * `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY` and `GEMINI_API_KEY` are removed from the
+ * environment and `OPENAI_API_KEY` is a placeholder; run without other providers'
+ * credentials. The new run's trace is written unredacted to a private temporary directory
+ * removed afterwards.
+ *
+ * The fixture file can be changed by a pull request, so its `source.command` is never run:
+ * `options.command` is, and the call rejects when the fixture's differs, or when it has
+ * redacted or templated (`{{id_N}}`) arguments.
+ *
+ * Rejects with `CaptureError` when the fixture has no replayable source command, a request
+ * matched no recording, the command exited differently than when recorded, or no trace came
+ * out.
+ */
+declare function replayRun(fixture: string | URL, options: ReplayRunOptions): Promise<Trace>;
 /** A running in-process capture. */
 interface Capture {
     name: string;
@@ -1345,6 +1502,17 @@ declare class PluginRegistry {
     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>;
+/**
+ * Run the registered plugin of every `plugin` assertion and submit its result to the engine
+ * (`submit_plugin_result`) so the following `evaluate_batch` finds it. Order matters: submit
+ * before evaluate. A plugin assertion whose plugin is not registered is left without a
+ * submission, so the engine reports it `not_evaluated` (`missing_evidence`) instead of a failure.
+ */
+declare function submitPluginResults(registry: PluginRegistry, client: AttestClient, trace: Trace, assertions: readonly {
+    assertion_id: string;
+    type: string;
+    spec: Record<string, unknown>;
+}[]): Promise<void>;
 /** Explicitly register a plugin instance into the registry. */
 declare function registerPlugin(registry: PluginRegistry, name: string, plugin: AttestPlugin): void;
 /**
@@ -1365,16 +1533,26 @@ declare class Sampler {
     constructor(rate: number);
     shouldSample(): boolean;
 }
+type AlertStatus = "drift_detected" | "hard_fail";
+/** Webhook JSON body shared by both SDK runners. Every key is always present. */
 interface AlertPayload {
-    drift_type: string;
-    score: number | string;
-    trace_id: string;
-    [key: string]: unknown;
+    runner: string;
+    assertion_id: string;
+    /** Alert trigger: `hard_fail` wins over `drift_detected` when both hold. */
+    status: AlertStatus;
+    /** Status of the evaluated assertion result. */
+    result_status: "pass" | "soft_fail" | "hard_fail";
+    score: number | null;
+    baseline_mean: number | null;
+    baseline_count: number | null;
+    static_threshold: number;
+    trace_id: string | null;
 }
 declare class AlertDispatcher extends EventEmitter {
     private readonly webhookUrl;
     private readonly slackUrl;
-    constructor(webhookUrl?: string, slackUrl?: string);
+    private readonly timeoutMs;
+    constructor(webhookUrl?: string, slackUrl?: string, timeoutMs?: number);
     dispatch(alert: AlertPayload): Promise<void>;
     private postJson;
 }
@@ -1385,22 +1563,53 @@ declare class ContinuousEvalRunner {
     private readonly dispatcher;
     private readonly queue;
     private readonly maxSize;
+    private readonly name;
+    private readonly drainTimeoutMs;
+    private readonly onError;
+    private readonly inFlight;
+    private chain;
     private running;
     private loopTimer;
-    constructor(client: AttestClient, assertions: readonly Assertion[], options?: {
+    constructor(client: AttestClient, assertions: readonly Assertion[], options: {
+        /** Id scope of the assertions (C3): their ids derive from this name, so keep it stable. */
+        name: string;
         sampleRate?: number;
         alertWebhook?: string;
         alertSlackUrl?: string;
         maxSize?: number;
+        /** Called with every evaluation, drift-read and dispatch error (also logged and emitted as `alertError`). */
+        onError?: (error: unknown) => void;
+        /** Bound on one alert POST (default 10000). */
+        dispatchTimeoutMs?: number;
+        /** Bound on how long `stop()` waits for in-flight work (default 15000). */
+        drainTimeoutMs?: number;
     });
     get alertEmitter(): AlertDispatcher;
+    /** Runs `fn` after every previously queued evaluation, so evaluate → query_drift pairs never interleave. */
+    private serialize;
+    /** Surfaces an error to the log and `onError` without ever throwing or leaving a rejected promise. */
+    private reportError;
+    private logObserverFailure;
+    private emitError;
     evaluateTrace(trace: Trace): Promise<EvaluateBatchResult | null>;
+    private evaluateAndAlert;
+    private staticThresholdFor;
+    private alertIfNeeded;
     submit(trace: Trace): boolean;
     start(): void;
-    stop(): void;
+    /**
+     * Stops the loop, then processes the traces already queued and waits for in-flight evaluations
+     * and dispatches, all bounded by `drainTimeoutMs`. At the bound the whole remaining queue is
+     * discarded (nothing is evaluated after the timeout and nothing is left for a restart), the
+     * evaluation already in flight is left to finish, and the timeout with the number of discarded
+     * traces is reported through `onError`.
+     */
+    stop(): Promise<void>;
+    private drainQueue;
     get queueLength(): number;
     get isRunning(): boolean;
     private scheduleNext;
+    private tick;
 }
 
 /**
@@ -1594,34 +1803,81 @@ declare class ManualAdapter {
     createBuilder(): TraceBuilder;
 }
 
-interface OpenAIUsage {
+/** Options every single-call provider adapter accepts. */
+interface ProviderCallOptions {
+    inputMessages?: Record<string, unknown>[];
+    costUsd?: number;
+    /** Explicit latency; wins over the span between `startedAtMs` and `endedAtMs`. */
+    latencyMs?: number;
+    /** Wall-clock ms when the request was sent. */
+    startedAtMs?: number;
+    /** Wall-clock ms when the response was received. */
+    endedAtMs?: number;
+}
+
+interface ChatUsage {
+    prompt_tokens?: number;
+    completion_tokens?: number;
     total_tokens?: number;
 }
-interface OpenAIToolCall {
+interface ChatToolCall {
     function: {
         name: string;
         arguments: string;
     };
 }
-interface OpenAIMessage {
+interface ChatMessage {
     content: string | null;
-    tool_calls?: OpenAIToolCall[];
-}
-interface OpenAIChoice {
-    message: OpenAIMessage;
+    refusal?: string | null;
+    tool_calls?: ChatToolCall[];
 }
+/** An OpenAI Chat Completions response. */
 interface OpenAIChatCompletion {
+    object?: string;
+    model?: string;
+    usage?: ChatUsage;
+    choices: {
+        message: ChatMessage;
+    }[];
+}
+type ResponsesContentPart = {
+    type: "output_text";
+    text: string;
+} | {
+    type: "refusal";
+    refusal: string;
+};
+type ResponsesOutputItem = {
+    type: "message";
+    content: ResponsesContentPart[];
+} | {
+    type: "function_call";
+    name: string;
+    arguments: string;
+} | {
+    type: string;
+};
+/** An OpenAI Responses API response. */
+interface OpenAIResponse {
+    object: "response";
     model?: string;
-    usage?: OpenAIUsage;
-    choices: OpenAIChoice[];
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+        total_tokens?: number;
+    };
+    output: ResponsesOutputItem[];
 }
+/**
+ * Captures OpenAI Chat Completions and Responses API calls into Attest traces.
+ *
+ * A model refusal is the response's message: it becomes the completion and the trace
+ * output, and is also recorded as `refusal` on the llm_call step.
+ */
 declare class OpenAIAdapter {
     private readonly agentId;
     constructor(agentId?: string);
-    traceFromResponse(response: OpenAIChatCompletion, options?: {
-        inputMessages?: Record<string, unknown>[];
-        costUsd?: number;
-        latencyMs?: number;
+    traceFromResponse(response: OpenAIChatCompletion | OpenAIResponse, options?: ProviderCallOptions & {
         structuredOutput?: Record<string, unknown>;
     }): Trace;
 }
@@ -1630,29 +1886,29 @@ interface AnthropicTextBlock {
     type: "text";
     text: string;
 }
+/** A client-executed (`tool_use`) or Anthropic-executed (`server_tool_use`) tool call. */
 interface AnthropicToolUseBlock {
-    type: "tool_use";
+    type: "tool_use" | "server_tool_use";
     name: string;
     input: Record<string, unknown>;
 }
-type AnthropicContentBlock = AnthropicTextBlock | AnthropicToolUseBlock;
-interface AnthropicUsage {
-    input_tokens: number;
-    output_tokens: number;
+/** Any other block (tool results, thinking, ...): carries no text or call of its own. */
+interface AnthropicOtherBlock {
+    type: string;
 }
+type AnthropicContentBlock = AnthropicTextBlock | AnthropicToolUseBlock | AnthropicOtherBlock;
 interface AnthropicMessage {
     model?: string;
-    usage?: AnthropicUsage;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+    };
     content: AnthropicContentBlock[];
 }
 declare class AnthropicAdapter {
     private readonly agentId;
     constructor(agentId?: string);
-    traceFromResponse(response: AnthropicMessage, options?: {
-        inputMessages?: Record<string, unknown>[];
-        costUsd?: number;
-        latencyMs?: number;
-    }): Trace;
+    traceFromResponse(response: AnthropicMessage, options?: ProviderCallOptions): Trace;
 }
 
 interface GeminiFunctionCall {
@@ -1661,6 +1917,8 @@ interface GeminiFunctionCall {
 }
 interface GeminiPart {
     text?: string;
+    /** Thought-summary parts are the model's reasoning, not the answer. */
+    thought?: boolean;
     functionCall?: GeminiFunctionCall;
 }
 interface GeminiCandidate {
@@ -1668,25 +1926,39 @@ interface GeminiCandidate {
         parts: GeminiPart[];
     };
 }
+interface GeminiUsage {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    totalTokenCount?: number;
+}
 interface GeminiResponse {
     text?: string;
+    modelVersion?: string;
+    usageMetadata?: GeminiUsage;
     candidates?: GeminiCandidate[];
 }
+interface GeminiOptions extends ProviderCallOptions {
+    /** A plain-text prompt; `inputMessages` is the standard way to pass the input. */
+    inputText?: string;
+    /** Overrides the response's `modelVersion`. */
+    model?: string;
+}
 declare class GeminiAdapter {
     private readonly agentId;
     constructor(agentId?: string);
-    traceFromResponse(response: GeminiResponse, options?: {
-        inputText?: string;
-        costUsd?: number;
-        latencyMs?: number;
-        model?: string;
-    }): Trace;
+    traceFromResponse(response: GeminiResponse, options?: GeminiOptions): Trace;
 }
 
 interface OllamaResponse {
     model?: string;
     message?: {
         content?: string;
+        tool_calls?: {
+            function?: {
+                name?: string;
+                arguments?: Record<string, unknown>;
+            };
+        }[];
     };
     eval_count?: number;
     prompt_eval_count?: number;
@@ -1694,10 +1966,7 @@ interface OllamaResponse {
 declare class OllamaAdapter {
     private readonly agentId;
     constructor(agentId?: string);
-    traceFromResponse(response: OllamaResponse, options?: {
-        inputMessages?: Record<string, unknown>[];
-        latencyMs?: number;
-    }): Trace;
+    traceFromResponse(response: OllamaResponse, options?: Omit<ProviderCallOptions, "costUsd">): Trace;
 }
 
 type AttributeValue = string | number | boolean | readonly (string | number | boolean | null | undefined)[];
@@ -1748,58 +2017,78 @@ declare class OTelAdapter {
 }
 
 /**
- * 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.
+ * The part of `@langchain/core`'s `BaseCallbackHandler` this adapter relies on. It is
+ * declared locally so the published typings do not import an optional peer dependency.
  */
-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 {
+interface CallbackHandlerBase {
+    name: string;
+    awaitHandlers: boolean;
+    raiseError: boolean;
+}
+type CallbackHandlerConstructor = new () => CallbackHandlerBase;
+declare const BaseCallbackHandler: CallbackHandlerConstructor;
+type Values = Record<string, unknown>;
+interface Message {
+    content?: unknown;
+    usage_metadata?: {
+        input_tokens?: number;
+        output_tokens?: number;
+        total_tokens?: number;
+    };
+}
+interface LLMResult {
+    generations: {
+        text?: string;
+        message?: Message;
+    }[][];
+    llmOutput?: Values;
+}
+/**
+ * Captures a LangChain.js run into an Attest trace.
+ *
+ * A `BaseCallbackHandler` from `@langchain/core`: pass it in `callbacks` and call
+ * `buildTrace()` once the run resolves. Model and tool runs are keyed by `runId`, so
+ * interleaved runs are attributed correctly; steps are recorded in completion order.
+ *
+ * ```ts
+ * const adapter = new LangChainAdapter("my-agent");
+ * await agent.invoke(input, { callbacks: [adapter] });
+ * const trace = adapter.buildTrace();
+ * ```
+ */
+declare class LangChainAdapter extends BaseCallbackHandler {
+    name: string;
     private readonly agentId;
-    private readonly llmCalls;
-    private readonly toolCalls;
-    private chainOutput;
-    private startTime;
+    private input;
+    private output;
+    private steps;
+    private llmStarts;
+    private toolStarts;
+    private totalTokens;
+    private model;
+    private startedAtMs;
+    private endedAtMs;
     constructor(agentId?: string);
-    /**
-     * Reset accumulated state for a new trace capture session.
-     */
+    /** Handlers are shared by the callback manager, never cloned: a clone would lose the capture. */
+    copy(): this;
+    /** Reset accumulated state for a new capture session. */
     reset(): void;
+    private now;
+    handleChainStart(_chain: unknown, inputs: Values, _runId: string, parentRunId?: string): void;
+    handleChainEnd(outputs: Values, _runId: string, parentRunId?: string): void;
+    handleChatModelStart(_llm: unknown, _messages: unknown[][], runId: string, _parentRunId?: string, extraParams?: Values): void;
+    handleLLMStart(_llm: unknown, _prompts: string[], runId: string, _parentRunId?: string, extraParams?: Values): void;
+    handleLLMEnd(output: LLMResult, runId: string): void;
+    handleToolStart(tool: unknown, input: string, runId: string, _parentRunId?: string, _tags?: string[], _metadata?: Values, runName?: string): void;
+    handleToolEnd(output: unknown, runId: string): void;
+    handleToolError(error: unknown, runId: string): void;
+    private finishTool;
+    private step;
     /**
-     * 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.
+     * Build a Trace from the captured callback events.
      *
-     * @param options.costUsd - Total cost override.
+     * @param options.costUsd - Total cost.
      * @param options.model - Model name override.
-     * @returns A finalized Trace object.
      */
     buildTrace(options?: {
         costUsd?: number;
@@ -1811,5 +2100,5 @@ interface TraceAdapter {
     traceFromResponse(response: unknown, options?: Record<string, unknown>): Trace;
 }
 
-export { ADVERSARIAL_USER, Agent, AgentResult, AlertDispatcher, AnthropicAdapter, Assertion, AssertionResult, AttestClient, BatchBudget, BatchContext, CONFUSED_USER, COOPERATIVE_USER, CaptureError, ContinuousEvalRunner, ConversationMessage, DriftReport, ENGINE_VERSION, EgressBlockedError, EngineManager, EvaluateBatchResult, ExpectChain, FRIENDLY_USER, GeminiAdapter, InitializeResult, LangChainAdapter, ManualAdapter, MockToolRegistry, OTelAdapter, OllamaAdapter, OpenAIAdapter, Outcome, PluginRegistry, ProtocolDiagnostic, ProtocolLogger, RepeatResult, ReplayError, ReplayMissError, ReplayNotEvaluatedError, Sampler, ScenarioResult, 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, faultInject, firstMiss, formatUsage, getSampleRate, installEgressGuard, isProviderHost, isSimulationMode, liveLine, loadFixture, loadLabelsCSV, loadLabelsJSONL, loadPackagePlugins, mockTool, parseUsage, promptHash, record, registerPlugin, renderAssertionFailure, renderDiagnostics, renderSummary, renderVerdictDiagnostics, renderVitest, repeat, requireSimulationCapability, resetConfig, resolveMode, scenario, simulationEnvEnabled, startReplay, startWorld, sumUsage, testPathFor, tier, uninstallEgressGuard, usageSummaryLine, zeroUsage };
-export type { AgreementResult, AlertPayload, AttestClientOptions, AttestPlugin, Capture, Contract, ContractResult, FaultInjectOptions, Fixture, LabelPair, LabeledRecord, MockTool, MockToolFn, PluginResult, RecordOptions, RecordResult, RenderOptions, ReplayMode, ReplayModeSetting, ReplayOptions, ReplayRecord, ReplaySession, ReplaySummary, ScenarioConfig, ScenarioContext, ScenarioOptions, TraceAdapter, Verdict, WorldOptions, WorldSession, WorldSnapshot };
+export { ADVERSARIAL_USER, Agent, AgentResult, AlertDispatcher, AnthropicAdapter, Assertion, AssertionIdAssigner, AssertionResult, AttestClient, BatchBudget, BatchContext, CONFUSED_USER, COOPERATIVE_USER, CaptureError, ContinuousEvalRunner, ConversationMessage, DriftReport, ENGINE_VERSION, EgressBlockedError, EngineManager, EvaluateBatchResult, ExpectChain, FRIENDLY_USER, GeminiAdapter, ID_SCHEME, InitializeResult, LangChainAdapter, ManualAdapter, MockToolRegistry, OTelAdapter, OllamaAdapter, OpenAIAdapter, Outcome, PluginRegistry, ProtocolDiagnostic, ProtocolLogger, RepeatResult, ReplayError, ReplayMissError, ReplayNotEvaluatedError, Sampler, ScenarioResult, SimulateFaultConfig, SimulatePersona, Step, TIER_1, TIER_2, TIER_3, Trace, TraceBuilder, TraceTree, Usage, VERSION, WorldChecks, WorldError, activeBuilder, addUsage, agent, assertionIdOf, attestExpect, canonicalIdInput, canonicalSpec, computeAgreement, config, delegate, dslCall, egressBlockRequested, emitVitest, executePluginAssertion, faultInject, firstMiss, formatUsage, getSampleRate, installEgressGuard, isProviderHost, isSimulationMode, liveLine, loadFixture, loadLabelsCSV, loadLabelsJSONL, loadPackagePlugins, mockTool, parseUsage, promptHash, record, registerPlugin, renderAssertionFailure, renderDiagnostics, renderSummary, renderVerdictDiagnostics, renderVitest, repeat, replayRun, requireSimulationCapability, resetConfig, resolveMode, scenario, setChainObserver, simulationEnvEnabled, startReplay, startWorld, submitPluginResults, sumUsage, testPathFor, tier, uninstallEgressGuard, usageSummaryLine, zeroUsage };
+export type { AgreementResult, AlertPayload, AttestClientOptions, AttestPlugin, Capture, Contract, ContractResult, FaultInjectOptions, Fixture, LabelPair, LabeledRecord, MockTool, MockToolFn, PluginResult, RecordOptions, RecordResult, RenderOptions, ReplayMode, ReplayModeSetting, ReplayOptions, ReplayRecord, ReplayRunOptions, ReplaySession, ReplaySummary, Rerun, ScenarioConfig, ScenarioContext, ScenarioOptions, TraceAdapter, Verdict, WorldOptions, WorldSession, WorldSnapshot };