@agentfield/sdk 0.1.110 → 0.1.111-rc.2

package/dist/index.d.ts

@@ -150,6 +150,15 @@ declare class AIClient {
      * Exposed for use by the tool-calling loop.
      */
     getModel(options?: AIRequestOptions): _ai_sdk_provider.LanguageModelV3;
+    /**
+     * Resolve the effective provider/model pair for a request without building
+     * the model. Used by usage tracking to attribute token/cost entries to the
+     * model actually called.
+     */
+    resolveModelChoice(options?: AIRequestOptions): {
+        provider: NonNullable<AIConfig['provider']>;
+        modelName: string;
+    };
     private buildModel;
     private buildEmbeddingModel;
     private openRouterHeaders;
@@ -372,6 +381,142 @@ declare class ExecutionLogger {
 }
 declare function createExecutionLogger(options?: ExecutionLoggerOptions): ExecutionLogger;
 
+/**
+ * Per-execution LLM cost and token-usage tracking.
+ *
+ * Mirrors the Python SDK's `agentfield/cost_tracker.py`: a `CostTracker`
+ * accumulates one `CostEntry` per LLM (or coding-agent harness) call made
+ * during a single reasoner execution, and `serialize()` emits the
+ * cross-language wire contract consumed by the control plane's usage-ingest
+ * path (see the Go `parseUsageEntries`).
+ */
+/**
+ * Reserved envelope key used to attach the serialized usage summary to a
+ * synchronous 200 result body. Namespaced so it cannot collide with user data:
+ * a plain "usage" key in an agent's own result object is user payload and must
+ * never be touched. The control plane strips exactly this key back out (see
+ * the Go `extractUsageFromResult`). `__agentfield_`-prefixed keys are reserved
+ * for SDK<->control-plane transport.
+ */
+declare const USAGE_ENVELOPE_KEY = "__agentfield_usage__";
+/** A single LLM (or harness) call usage record. */
+interface CostEntry {
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    /**
+     * Cost may be unknown (provider gave no figure) — tokens are recorded
+     * regardless, so cost is nullable and never gates them.
+     */
+    costUsd: number | null;
+    reasonerName: string | null;
+    /** "llm" for direct model calls, "harness" for coding-agent runs. */
+    source: 'llm' | 'harness';
+    /** e.g. "anthropic", "openrouter" — derived from the model slug if unset. */
+    provider: string | null;
+    /** e.g. "claude_code" for harness-originated entries; null for plain LLM. */
+    harness: string | null;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    /** Where costUsd came from: "provider" | null. */
+    costSource: string | null;
+}
+/** Input accepted by {@link CostTracker.record}. */
+interface CostEntryInit {
+    model: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    costUsd?: number | null;
+    reasonerName?: string | null;
+    source?: 'llm' | 'harness';
+    provider?: string | null;
+    harness?: string | null;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    costSource?: string | null;
+}
+/** Wire form of a single usage entry (snake_case cross-language contract). */
+interface UsageEntryWire {
+    source: string;
+    provider: string | null;
+    model: string;
+    harness: string | null;
+    reasoner: string | null;
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_creation_tokens: number;
+    total_tokens: number;
+    cost_usd: number | null;
+    cost_source: string | null;
+}
+/** Wire form of the usage summary attached to execution envelopes. */
+interface UsageSummaryWire {
+    /** Null when no entry had a known cost; otherwise sum rounded to 6 decimals. */
+    total_cost_usd: number | null;
+    total_input_tokens: number;
+    total_output_tokens: number;
+    total_tokens: number;
+    entries: UsageEntryWire[];
+}
+/**
+ * Best-effort provider name from a model slug.
+ *
+ * `anthropic/claude-opus-4-8` -> `anthropic`,
+ * `openrouter/anthropic/claude` -> `openrouter`,
+ * a bare `gpt-4o` (no provider prefix) -> `null`.
+ */
+declare function deriveProvider(model: string | null | undefined): string | null;
+/** Accumulates LLM/harness usage for a single execution run. */
+declare class CostTracker {
+    private entries;
+    /**
+     * Record a single call's usage.
+     *
+     * Cost is optional: a call with known token counts but unknown price is
+     * still recorded (`costUsd: null`) so tokens are never discarded.
+     */
+    record(init: CostEntryInit): void;
+    /** Total accumulated cost in USD (unknown costs count as zero). */
+    get totalCostUsd(): number;
+    /** Total tokens used across all calls (per-entry total, no fallback). */
+    get totalTokens(): number;
+    /** Number of calls tracked. */
+    get callCount(): number;
+    get hasEntries(): boolean;
+    /**
+     * Return the transport contract form attached to execution envelopes.
+     *
+     * Matches the Python SDK's `CostTracker.serialize()` byte-for-byte in shape:
+     * unset string fields serialize as null, `total_cost_usd` is null when no
+     * entry had a known cost, and a per-entry `total_tokens` of zero falls back
+     * to input + output.
+     */
+    serialize(): UsageSummaryWire;
+    /** Clear all tracked entries. */
+    reset(): void;
+}
+/**
+ * Return the transport `usage` object, or null when there is nothing to
+ * report. Zero entries means no usage key at all per the contract, so callers
+ * must skip attaching `usage` on null.
+ */
+declare function usageSummaryOrNull(tracker: CostTracker | undefined | null): UsageSummaryWire | null;
+/**
+ * Attach usage to a synchronous 200 result body.
+ *
+ * The summary is merged as a sibling under the reserved
+ * {@link USAGE_ENVELOPE_KEY}; the control plane strips exactly that key back
+ * out, so a user result that legitimately contains its own "usage" key is
+ * never touched. Only plain-object results can carry usage this way —
+ * non-object results (arrays, scalars, class instances, null) are returned
+ * unchanged and their usage flows via the async status-callback path instead
+ * (the production path). No-usage trackers leave any result unchanged.
+ */
+declare function attachUsageToSyncResult(result: unknown, tracker: CostTracker | undefined | null): unknown;
+
 interface ExecutionStatusUpdate {
     status?: string;
     result?: Record<string, any>;
@@ -531,6 +676,13 @@ declare class AgentFieldClient {
         durationMs?: number;
         completedAt?: string;
         reasoner?: string;
+        /**
+         * Serialized token/cost usage summary for the execution (the
+         * CostTracker wire contract). Omitted entirely when the execution
+         * recorded no usage. Attached on failure/timeout/cancelled terminal
+         * reports too — a reasoner may have consumed tokens before ending.
+         */
+        usage?: UsageSummaryWire;
     }, maxRetries?: number): Promise<boolean>;
     discoverCapabilities(options?: DiscoveryOptions): Promise<DiscoveryResult>;
     private mapDiscoveryResponse;
@@ -598,12 +750,21 @@ declare class ExecutionContext {
     readonly req: express.Request;
     readonly res: express.Response;
     readonly agent: Agent;
+    /**
+     * Per-execution LLM/harness usage accumulator. Each top-level execution
+     * binds a fresh tracker (isolated across concurrent executions via the
+     * AsyncLocalStorage this context lives in); nested local `agent.call()`
+     * executions inherit the parent's tracker so their usage rolls up into the
+     * parent's report.
+     */
+    readonly costTracker: CostTracker;
     constructor(params: {
         input: any;
         metadata: ExecutionMetadata;
         req: express.Request;
         res: express.Response;
         agent: Agent;
+        costTracker?: CostTracker;
     });
     get logger(): ExecutionLogger;
     static run<T>(ctx: ExecutionContext, fn: () => T): T;
@@ -838,103 +999,14 @@ declare function buildToolConfig(toolsParam: ToolsOption, agent: Agent): Promise
     config: ToolCallConfig;
     needsLazyHydration: boolean;
 }>;
-declare function executeToolCallLoop(agent: Agent, prompt: string, toolMap: ToolSet, config: ToolCallConfig, needsLazyHydration: boolean, buildModel: () => any, options?: AIRequestOptions): Promise<{
+declare function executeToolCallLoop(agent: Agent, prompt: string, toolMap: ToolSet, config: ToolCallConfig, needsLazyHydration: boolean, buildModel: () => any, options?: AIRequestOptions, modelChoice?: {
+    provider?: string;
+    modelName?: string;
+}): Promise<{
     text: string;
     trace: ToolCallTrace;
 }>;
 
-declare class ReasonerContext<TInput = any> {
-    readonly input: TInput;
-    readonly executionId: string;
-    readonly runId?: string;
-    readonly sessionId?: string;
-    readonly actorId?: string;
-    readonly workflowId?: string;
-    readonly rootWorkflowId?: string;
-    readonly parentExecutionId?: string;
-    readonly reasonerId?: string;
-    readonly callerDid?: string;
-    readonly targetDid?: string;
-    readonly agentNodeDid?: string;
-    readonly req: express.Request;
-    readonly res: express.Response;
-    readonly agent: Agent;
-    readonly logger: ExecutionLogger;
-    readonly aiClient: AIClient;
-    readonly memory: MemoryInterface;
-    readonly workflow: WorkflowReporter;
-    readonly did: DidInterface;
-    /**
-     * AbortSignal that fires when the control plane cancels this execution
-     * (per-execution cancel, the bottom-up cancel-tree endpoint, or any
-     * future source that flips the bus). Pass it through to `fetch`, the
-     * @anthropic-ai/sdk, the openai SDK, or anywhere that accepts
-     * `{ signal }` to short-circuit in-flight work mid-call. For pure-JS
-     * CPU loops, check `ctx.signal.aborted` periodically and throw.
-     */
-    readonly signal: AbortSignal;
-    constructor(params: {
-        input: TInput;
-        executionId: string;
-        runId?: string;
-        sessionId?: string;
-        actorId?: string;
-        workflowId?: string;
-        rootWorkflowId?: string;
-        parentExecutionId?: string;
-        reasonerId?: string;
-        callerDid?: string;
-        targetDid?: string;
-        agentNodeDid?: string;
-        req: express.Request;
-        res: express.Response;
-        agent: Agent;
-        logger: ExecutionLogger;
-        aiClient: AIClient;
-        memory: MemoryInterface;
-        workflow: WorkflowReporter;
-        did: DidInterface;
-        signal?: AbortSignal;
-    });
-    ai<T>(prompt: string, options: AIRequestOptions & {
-        schema: ZodSchema<T>;
-    }): Promise<T>;
-    ai(prompt: string, options?: AIToolRequestOptions): Promise<string>;
-    /**
-     * AI call with automatic tool calling via discover -> ai -> call loop.
-     *
-     * Discovers available capabilities, presents them as tools to the LLM,
-     * dispatches tool calls via agent.call(), and iterates until a final response.
-     *
-     * @returns Object with `text` (final response) and `trace` (observability data).
-     */
-    aiWithTools(prompt: string, options?: AIToolRequestOptions): Promise<{
-        text: string;
-        trace: ToolCallTrace;
-    }>;
-    aiStream(prompt: string, options?: AIRequestOptions): Promise<AIStream>;
-    call(target: string, input: any): Promise<any>;
-    /**
-     * Pause this execution for external approval / resumption.
-     *
-     * Transitions the execution to `waiting` on the control plane and blocks
-     * until a decision arrives via the agent's approval webhook, or the timeout
-     * elapses (returning `{ decision: 'expired' }`). The caller creates the
-     * approval request on an external service first and passes its
-     * `approvalRequestId`. Delegates to {@link Agent.pause}. See its docs for the
-     * async-execution requirement that lets a pause outlive the dispatch ceiling.
-     */
-    pause(opts: {
-        approvalRequestId: string;
-        approvalRequestUrl?: string;
-        expiresInHours?: number;
-        timeoutMs?: number;
-    }): Promise<ApprovalResult>;
-    discover(options?: DiscoveryOptions): Promise<DiscoveryResult>;
-    note(message: string, tags?: string[]): void;
-}
-declare function getCurrentContext<TInput = any>(): ReasonerContext<TInput> | undefined;
-
 /**
  * Trigger binding types for AgentField TypeScript SDK.
  *
@@ -1039,6 +1111,113 @@ interface ScheduleTriggerBinding {
     spec: ScheduleTriggerSpec;
 }
 
+declare class ReasonerContext<TInput = any> {
+    readonly input: TInput;
+    readonly executionId: string;
+    readonly runId?: string;
+    readonly sessionId?: string;
+    readonly actorId?: string;
+    readonly workflowId?: string;
+    readonly rootWorkflowId?: string;
+    readonly parentExecutionId?: string;
+    readonly reasonerId?: string;
+    readonly callerDid?: string;
+    readonly targetDid?: string;
+    readonly agentNodeDid?: string;
+    readonly req: express.Request;
+    readonly res: express.Response;
+    readonly agent: Agent;
+    readonly logger: ExecutionLogger;
+    readonly aiClient: AIClient;
+    readonly memory: MemoryInterface;
+    readonly workflow: WorkflowReporter;
+    readonly did: DidInterface;
+    /**
+     * Per-execution token/cost usage accumulator. LLM calls made through
+     * `ctx.ai()` / `ctx.aiWithTools()` and harness runs record into it
+     * automatically; reasoner authors may also `record()` custom entries. Its
+     * serialized summary is attached to the execution's terminal report.
+     */
+    readonly costTracker: CostTracker;
+    /**
+     * AbortSignal that fires when the control plane cancels this execution
+     * (per-execution cancel, the bottom-up cancel-tree endpoint, or any
+     * future source that flips the bus). Pass it through to `fetch`, the
+     * @anthropic-ai/sdk, the openai SDK, or anywhere that accepts
+     * `{ signal }` to short-circuit in-flight work mid-call. For pure-JS
+     * CPU loops, check `ctx.signal.aborted` periodically and throw.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Trigger context populated when the reasoner was invoked by an inbound
+     * webhook event or cron schedule. `undefined` for direct calls via
+     * `app.call(...)` or HTTP POST without a dispatcher envelope.
+     */
+    readonly trigger?: TriggerContext;
+    constructor(params: {
+        input: TInput;
+        executionId: string;
+        runId?: string;
+        sessionId?: string;
+        actorId?: string;
+        workflowId?: string;
+        rootWorkflowId?: string;
+        parentExecutionId?: string;
+        reasonerId?: string;
+        callerDid?: string;
+        targetDid?: string;
+        agentNodeDid?: string;
+        req: express.Request;
+        res: express.Response;
+        agent: Agent;
+        logger: ExecutionLogger;
+        aiClient: AIClient;
+        memory: MemoryInterface;
+        workflow: WorkflowReporter;
+        did: DidInterface;
+        signal?: AbortSignal;
+        costTracker?: CostTracker;
+        trigger?: TriggerContext;
+    });
+    ai<T>(prompt: string, options: AIRequestOptions & {
+        schema: ZodSchema<T>;
+    }): Promise<T>;
+    ai(prompt: string, options?: AIToolRequestOptions): Promise<string>;
+    /**
+     * AI call with automatic tool calling via discover -> ai -> call loop.
+     *
+     * Discovers available capabilities, presents them as tools to the LLM,
+     * dispatches tool calls via agent.call(), and iterates until a final response.
+     *
+     * @returns Object with `text` (final response) and `trace` (observability data).
+     */
+    aiWithTools(prompt: string, options?: AIToolRequestOptions): Promise<{
+        text: string;
+        trace: ToolCallTrace;
+    }>;
+    aiStream(prompt: string, options?: AIRequestOptions): Promise<AIStream>;
+    call(target: string, input: any): Promise<any>;
+    /**
+     * Pause this execution for external approval / resumption.
+     *
+     * Transitions the execution to `waiting` on the control plane and blocks
+     * until a decision arrives via the agent's approval webhook, or the timeout
+     * elapses (returning `{ decision: 'expired' }`). The caller creates the
+     * approval request on an external service first and passes its
+     * `approvalRequestId`. Delegates to {@link Agent.pause}. See its docs for the
+     * async-execution requirement that lets a pause outlive the dispatch ceiling.
+     */
+    pause(opts: {
+        approvalRequestId: string;
+        approvalRequestUrl?: string;
+        expiresInHours?: number;
+        timeoutMs?: number;
+    }): Promise<ApprovalResult>;
+    discover(options?: DiscoveryOptions): Promise<DiscoveryResult>;
+    note(message: string, tags?: string[]): void;
+}
+declare function getCurrentContext<TInput = any>(): ReasonerContext<TInput> | undefined;
+
 interface ReasonerDefinition<TInput = any, TOutput = any> {
     name: string;
     handler: ReasonerHandler<TInput, TOutput>;
@@ -1177,6 +1356,14 @@ interface Metrics {
     totalCostUsd?: number;
     usage?: Record<string, unknown>;
     sessionId: string;
+    /** Token counts parsed from the provider's result payload (best effort). */
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    totalTokens?: number;
+    /** Model reported by the provider, when available. */
+    model?: string;
 }
 interface RawResult {
     result?: string;
@@ -1195,6 +1382,14 @@ interface HarnessResult {
     durationMs: number;
     sessionId: string;
     messages: Array<Record<string, unknown>>;
+    /** Token counts reported by the harness provider, when available. */
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    totalTokens?: number;
+    /** Model reported by the harness provider, when available. */
+    model?: string;
     readonly text: string;
 }
 declare function createHarnessResult(partial?: Partial<Omit<HarnessResult, 'text'>>): HarnessResult;
@@ -1552,6 +1747,33 @@ declare class Agent {
      */
     private resolvePublicUrl;
     reasoner<TInput = any, TOutput = any>(name: string, handler: ReasonerHandler<TInput, TOutput>, options?: ReasonerOptions): this;
+    /**
+     * Sugar for registering an event-triggered reasoner.
+     *
+     * Equivalent to:
+     * ```ts
+     * app.reasoner(name, handler, { triggers: [eventTrigger(spec)] });
+     * ```
+     *
+     * The reasoner name defaults to `handler.name` when not provided.
+     */
+    onEvent<TInput = any, TOutput = any>(spec: Omit<EventTriggerSpec, 'codeOrigin'> & {
+        name?: string;
+    }, handler: ReasonerHandler<TInput, TOutput>, options?: Omit<ReasonerOptions, 'triggers'>): this;
+    /**
+     * Sugar for registering a schedule-triggered (cron) reasoner.
+     *
+     * Equivalent to:
+     * ```ts
+     * app.reasoner(name, handler, { triggers: [scheduleTrigger({ cron })] });
+     * ```
+     *
+     * The reasoner name defaults to `handler.name` when not provided.
+     */
+    onSchedule<TInput = any, TOutput = any>(cron: string, handler: ReasonerHandler<TInput, TOutput>, options?: Omit<ReasonerOptions, 'triggers'> & {
+        name?: string;
+        timezone?: string;
+    }): this;
     skill<TInput = any, TOutput = any>(name: string, handler: SkillHandler<TInput, TOutput>, options?: SkillOptions): this;
     includeRouter(router: AgentRouter): void;
     session(name: string, options: SessionOptions, handler: (session: RealtimeSession) => Promise<unknown> | unknown): this;
@@ -1566,6 +1788,15 @@ declare class Agent {
     getExecutionLogger(): ExecutionLogger;
     getHarnessRunner(): Promise<HarnessRunner>;
     harness(prompt: string, options?: HarnessOptions): Promise<HarnessResult>;
+    /**
+     * Record a harness run's token/cost usage into the current execution's
+     * tracker. Mirrors the Python SDK's `_record_harness_usage`: a no-op when
+     * the harness reported neither tokens nor cost (the common case for
+     * providers that don't expose usage) so empty entries are never emitted;
+     * cost is threaded even when tokens are unknown, and vice versa. Never
+     * throws — usage capture is best-effort.
+     */
+    private recordHarnessUsage;
     getMemoryInterface(metadata?: ExecutionMetadata): MemoryInterface;
     getWorkflowReporter(metadata: ExecutionMetadata): WorkflowReporter;
     getDidInterface(metadata: ExecutionMetadata, defaultInput?: any, targetName?: string): DidInterface;
@@ -2574,4 +2805,165 @@ declare function scheduleTrigger(spec: ScheduleTriggerSpec): ScheduleTriggerBind
  */
 declare function triggerToPayload(trigger: TriggerBinding): Record<string, unknown>;
 
-export { ACTIVE_STATUSES, AIClient, type AIConfig, type AIEmbeddingOptions, type AIRequestOptions, type AIStream, type AIToolRequestOptions, Agent, type AgentCapability, type AgentConfig, type AgentHandler, AgentRouter, type AgentRouterOptions, type AgentState, ApprovalClient, type ApprovalDecision, type ApprovalRequestResponse, ApprovalResult, type ApprovalStatusResponse, Audio, type AudioOutput, type AudioRequest, type AuditTrailExport, type AuditTrailFilters, type Awaitable, CANONICAL_STATUSES, type CompactCapability, type CompactDiscoveryResponse, DIDAuthenticator, type DIDIdentity, type DIDIdentityPackage, type DIDRegistrationRequest, type DIDRegistrationResponse, type DeploymentType, DidClient, DidInterface, DidManager, type DidResolver, type DiscoveryFormat, type DiscoveryOptions, type DiscoveryPagination, type DiscoveryResponse, type DiscoveryResult, type EventTriggerBinding, type EventTriggerSpec, ExecutionContext, type ExecutionCredential, type ExecutionLogAttributes, type ExecutionLogBatchPayload, type ExecutionLogContext, type ExecutionLogEmitOptions, type ExecutionLogEntry, type ExecutionLogLevel, type ExecutionLogTransport, type ExecutionLogTransportPayload, type ExecutionLogWireEntry, ExecutionLogger, type ExecutionLoggerOptions, type ExecutionMetadata, ExecutionStatus, type ExecutionStatusValue, File, type FileOutput, type GenerateCredentialOptions, type GenerateCredentialParams, HEADER_CALLER_DID, HEADER_DID_NONCE, HEADER_DID_SIGNATURE, HEADER_DID_TIMESTAMP, type HarnessConfig, type HarnessOptions, type HarnessProvider, type HarnessResult, HarnessRunner, type HealthStatus, Image, type ImageOutput, type ImageRequest, JWE_ALG, JWE_ENC, KEY_AGREEMENT_TYPE, type MediaProvider, MediaProviderError, type MediaResponse, MediaRouter, type MemoryChangeEvent, MemoryClient, MemoryClientBase, type MemoryConfig, MemoryEventClient, type MemoryEventHandler, type MemoryEventHistoryOptions, MemoryInterface, type MemoryRequestMetadata, type MemoryRequestOptions, type MemoryScope, type MemoryWatchHandler, type Metrics, type MultimodalContent, MultimodalResponse, OpenRouterMediaProvider, type OpenRouterMediaProviderOptions, PauseClock, PauseManager, type Payload, PayloadEncryptionError, RateLimitError, type RateLimiterOptions, type RawExecutionContext, type RawResult, RealtimeSession, type ReasonerCapability, ReasonerContext, type ReasonerDefinition, type ReasonerHandler, type ReasonerOptions, type RequestApprovalPayload, SUPPORTED_PROVIDERS, SUPPORTED_SESSION_TRANSPORTS, type ScheduleTriggerBinding, type ScheduleTriggerSpec, type ServerlessAdapter, type ServerlessEvent, type ServerlessResponse, type SessionDefinition, type SessionOptions, type SessionProvider, type SessionTransport, type SessionTransportCapability, SessionTransportError, type SessionTurn, type SkillCapability, SkillContext, type SkillDefinition, type SkillHandler, type SkillOptions, StatelessRateLimiter, TERMINAL_STATUSES, Text, type ToolCallConfig, type ToolCallRecord, type ToolCallTrace, type ToolsOption, type TriggerBinding, type TriggerContext, type VectorSearchOptions, type VectorSearchResult, Video, type VideoFrameImage, type VideoInputReference, type VideoRequest, type WaitForApprovalOptions, type WorkflowCredential, type WorkflowMetadata, type WorkflowProgressOptions, WorkflowReporter, type ZodSchema, audioFromBase64, audioFromBuffer, audioFromFile, audioFromUrl, buildProvider, buildSessionDefinition, buildToolConfig, capabilitiesToTools, capabilityToMetadataTool, capabilityToTool, createExecutionLogger, createHarnessResult, createMetrics, createMultimodalResponse, createRawResult, decrypt, decryptToString, encryptForDid, encryptToJwk, eventTrigger, executeToolCallLoop, extractKeyAgreementJwk, fileFromBase64, fileFromBuffer, fileFromPath, fileFromUrl, generateX25519KeyPair, getCurrentContext, getCurrentSkillContext, imageFromBase64, imageFromBuffer, imageFromFile, imageFromUrl, installApprovalWebhookRoute, isActive, isExecutionLogBatchPayload, isTerminal, normalizeExecutionLogEntry, normalizeSessionTransportValue, normalizeStatus, scheduleTrigger, serializeExecutionLogEntry, text, triggerToPayload, validateSessionTransport, videoFromBase64, videoFromBuffer, videoFromFile, videoFromUrl };
+/**
+ * Trigger dispatch envelope detection and TriggerContext construction.
+ *
+ * When the control plane dispatches a webhook event to a reasoner, it wraps
+ * the payload in an envelope: `{ event: <payload>, _meta: <trigger metadata> }`.
+ * This module detects that shape, unwraps the event, constructs a TriggerContext,
+ * and applies the binding's `transform` if one is declared.
+ *
+ * Direct calls (no envelope) pass through unchanged — the handler receives
+ * its input as before.
+ *
+ * @module triggers/dispatch
+ */
+
+/**
+ * Shape of the dispatcher's envelope sent by the control plane for
+ * webhook-triggered executions.
+ */
+interface TriggerEnvelope {
+    event: Record<string, unknown>;
+    _meta: {
+        trigger_id: string;
+        source: string;
+        event_type: string;
+        event_id: string;
+        idempotency_key: string;
+        received_at: string;
+        vc_id?: string;
+    };
+}
+/**
+ * Result of envelope detection and unwrap.
+ */
+interface UnwrapResult {
+    /** The unwrapped input (event payload or original input for direct calls). */
+    input: unknown;
+    /** TriggerContext if this was a trigger dispatch; undefined for direct calls. */
+    triggerContext?: TriggerContext;
+}
+/**
+ * Detect whether a request body is a dispatcher trigger envelope.
+ *
+ * The envelope shape is `{ event: ..., _meta: { trigger_id, source, ... } }`.
+ * Only objects with both `event` and `_meta` keys (where `_meta` contains
+ * `trigger_id`) are considered envelopes.
+ */
+declare function isTriggerEnvelope(body: unknown): body is TriggerEnvelope;
+/**
+ * Unwrap a trigger envelope (if present) and construct TriggerContext.
+ *
+ * For trigger dispatches: extracts the event payload and builds a typed
+ * TriggerContext from `_meta`. For direct calls: returns the body unchanged
+ * with `triggerContext: undefined`.
+ */
+declare function unwrapEnvelope(body: unknown): UnwrapResult;
+/**
+ * Apply the matching binding's `transform` function to the unwrapped event.
+ *
+ * Matching logic (mirrors Python SDK's `_apply_trigger_transform`):
+ * 1. Find bindings where `binding.spec.source === triggerContext.source`
+ * 2. For event bindings with non-empty `types`, check prefix match against
+ *    `triggerContext.eventType`
+ * 3. Most specific match (non-empty types) wins over catch-all (empty types)
+ * 4. Apply `transform` if the matched binding declares one
+ *
+ * Returns the (possibly transformed) input.
+ */
+declare function applyTriggerTransform(triggerContext: TriggerContext, bindings: TriggerBinding[], input: unknown): unknown;
+
+/**
+ * Testing helpers for reasoners that handle webhook triggers.
+ *
+ * The standard SDK runtime delivers trigger events via the agent's HTTP
+ * endpoint — your reasoner sees `ctx.trigger` populated and (when `transform`
+ * is set) the unwrapped, transformed input. For unit tests you want the same
+ * shape without spinning up a control plane, an HTTP server, or a real
+ * provider. `simulateTrigger` gives you that: it crafts the `TriggerContext`
+ * the agent runtime would have produced, applies any matching `transform`
+ * from the reasoner's declared bindings, and invokes the handler directly
+ * with a minimal ReasonerContext-like object. No HTTP, no workflow
+ * registration, no VC mint.
+ *
+ * @module triggers/testing
+ */
+
+/**
+ * Options for `simulateTrigger`.
+ */
+interface SimulateTriggerOptions {
+    /** Provider source name (e.g. "stripe", "github", "cron"). */
+    source: string;
+    /** Inbound event body. Defaults to `{}`. */
+    body?: Record<string, unknown>;
+    /** Provider's event type (e.g. "payment_intent.succeeded"). Defaults to "". */
+    eventType?: string;
+    /** Override the generated event ID. */
+    eventId?: string;
+    /** Override the generated idempotency key. */
+    idempotencyKey?: string;
+    /** Override the generated trigger ID. */
+    triggerId?: string;
+    /** Override the received-at timestamp. Defaults to `new Date()`. */
+    receivedAt?: Date;
+    /** Optional VC ID. */
+    vcId?: string;
+    /**
+     * Trigger bindings for the handler. Used to find the matching binding's
+     * `transform`. If not provided, the body is passed through as-is.
+     */
+    bindings?: TriggerBinding[];
+}
+/**
+ * Options for `simulateSchedule`.
+ */
+interface SimulateScheduleOptions {
+    /** Cron expression (for test introspection). */
+    cron?: string;
+    /** Override the received-at timestamp. Defaults to `new Date()`. */
+    receivedAt?: Date;
+    /** Trigger bindings for the handler. */
+    bindings?: TriggerBinding[];
+}
+/**
+ * Minimal execution context surface exposed as `ctx` in simulate tests.
+ * Only carries the bits a webhook reasoner is likely to read.
+ */
+interface SimulatedContext<TInput = unknown> {
+    input: TInput;
+    trigger: TriggerContext;
+    executionId: string;
+}
+/**
+ * Simulate a trigger dispatch and invoke the handler.
+ *
+ * Builds a synthetic `TriggerContext`, optionally applies the matched
+ * binding's `transform`, and calls the handler with a minimal context
+ * object that mirrors what the real dispatch path produces.
+ *
+ * @param handler - Function accepting `(ctx: { input, trigger, executionId })`.
+ *   The same shape a `ReasonerHandler` receives, but trimmed to the fields
+ *   relevant for trigger-driven logic.
+ * @param options - Trigger simulation options.
+ * @returns Whatever the handler returns (awaits async handlers transparently).
+ */
+declare function simulateTrigger<R>(handler: (ctx: SimulatedContext) => R | Promise<R>, options: SimulateTriggerOptions): Promise<R>;
+/**
+ * Simulate a schedule (cron) trigger dispatch.
+ *
+ * Convenience wrapper around `simulateTrigger` for cron-triggered reasoners.
+ * Passes an empty body and `source: 'cron'`, `eventType: 'tick'`.
+ */
+declare function simulateSchedule<R>(handler: (ctx: SimulatedContext) => R | Promise<R>, options?: SimulateScheduleOptions): Promise<R>;
+/**
+ * Load a captured provider payload from the SDK fixture library.
+ *
+ * Fixtures live at `src/triggers/fixtures/<source>.json` relative to the
+ * package root. Returns a parsed object — each call re-reads from disk so
+ * tests can mutate freely.
+ */
+declare function loadFixture(source: string): Record<string, unknown>;
+
+export { ACTIVE_STATUSES, AIClient, type AIConfig, type AIEmbeddingOptions, type AIRequestOptions, type AIStream, type AIToolRequestOptions, Agent, type AgentCapability, type AgentConfig, type AgentHandler, AgentRouter, type AgentRouterOptions, type AgentState, ApprovalClient, type ApprovalDecision, type ApprovalRequestResponse, ApprovalResult, type ApprovalStatusResponse, Audio, type AudioOutput, type AudioRequest, type AuditTrailExport, type AuditTrailFilters, type Awaitable, CANONICAL_STATUSES, type CompactCapability, type CompactDiscoveryResponse, type CostEntry, type CostEntryInit, CostTracker, DIDAuthenticator, type DIDIdentity, type DIDIdentityPackage, type DIDRegistrationRequest, type DIDRegistrationResponse, type DeploymentType, DidClient, DidInterface, DidManager, type DidResolver, type DiscoveryFormat, type DiscoveryOptions, type DiscoveryPagination, type DiscoveryResponse, type DiscoveryResult, type EventTriggerBinding, type EventTriggerSpec, ExecutionContext, type ExecutionCredential, type ExecutionLogAttributes, type ExecutionLogBatchPayload, type ExecutionLogContext, type ExecutionLogEmitOptions, type ExecutionLogEntry, type ExecutionLogLevel, type ExecutionLogTransport, type ExecutionLogTransportPayload, type ExecutionLogWireEntry, ExecutionLogger, type ExecutionLoggerOptions, type ExecutionMetadata, ExecutionStatus, type ExecutionStatusValue, File, type FileOutput, type GenerateCredentialOptions, type GenerateCredentialParams, HEADER_CALLER_DID, HEADER_DID_NONCE, HEADER_DID_SIGNATURE, HEADER_DID_TIMESTAMP, type HarnessConfig, type HarnessOptions, type HarnessProvider, type HarnessResult, HarnessRunner, type HealthStatus, Image, type ImageOutput, type ImageRequest, JWE_ALG, JWE_ENC, KEY_AGREEMENT_TYPE, type MediaProvider, MediaProviderError, type MediaResponse, MediaRouter, type MemoryChangeEvent, MemoryClient, MemoryClientBase, type MemoryConfig, MemoryEventClient, type MemoryEventHandler, type MemoryEventHistoryOptions, MemoryInterface, type MemoryRequestMetadata, type MemoryRequestOptions, type MemoryScope, type MemoryWatchHandler, type Metrics, type MultimodalContent, MultimodalResponse, OpenRouterMediaProvider, type OpenRouterMediaProviderOptions, PauseClock, PauseManager, type Payload, PayloadEncryptionError, RateLimitError, type RateLimiterOptions, type RawExecutionContext, type RawResult, RealtimeSession, type ReasonerCapability, ReasonerContext, type ReasonerDefinition, type ReasonerHandler, type ReasonerOptions, type RequestApprovalPayload, SUPPORTED_PROVIDERS, SUPPORTED_SESSION_TRANSPORTS, type ScheduleTriggerBinding, type ScheduleTriggerSpec, type ServerlessAdapter, type ServerlessEvent, type ServerlessResponse, type SessionDefinition, type SessionOptions, type SessionProvider, type SessionTransport, type SessionTransportCapability, SessionTransportError, type SessionTurn, type SimulateScheduleOptions, type SimulateTriggerOptions, type SimulatedContext, type SkillCapability, SkillContext, type SkillDefinition, type SkillHandler, type SkillOptions, StatelessRateLimiter, TERMINAL_STATUSES, Text, type ToolCallConfig, type ToolCallRecord, type ToolCallTrace, type ToolsOption, type TriggerBinding, type TriggerContext, type TriggerEnvelope, USAGE_ENVELOPE_KEY, type UnwrapResult, type UsageEntryWire, type UsageSummaryWire, type VectorSearchOptions, type VectorSearchResult, Video, type VideoFrameImage, type VideoInputReference, type VideoRequest, type WaitForApprovalOptions, type WorkflowCredential, type WorkflowMetadata, type WorkflowProgressOptions, WorkflowReporter, type ZodSchema, applyTriggerTransform, attachUsageToSyncResult, audioFromBase64, audioFromBuffer, audioFromFile, audioFromUrl, buildProvider, buildSessionDefinition, buildToolConfig, capabilitiesToTools, capabilityToMetadataTool, capabilityToTool, createExecutionLogger, createHarnessResult, createMetrics, createMultimodalResponse, createRawResult, decrypt, decryptToString, deriveProvider, encryptForDid, encryptToJwk, eventTrigger, executeToolCallLoop, extractKeyAgreementJwk, fileFromBase64, fileFromBuffer, fileFromPath, fileFromUrl, generateX25519KeyPair, getCurrentContext, getCurrentSkillContext, imageFromBase64, imageFromBuffer, imageFromFile, imageFromUrl, installApprovalWebhookRoute, isActive, isExecutionLogBatchPayload, isTerminal, isTriggerEnvelope, loadFixture, normalizeExecutionLogEntry, normalizeSessionTransportValue, normalizeStatus, scheduleTrigger, serializeExecutionLogEntry, simulateSchedule, simulateTrigger, text, triggerToPayload, unwrapEnvelope, usageSummaryOrNull, validateSessionTransport, videoFromBase64, videoFromBuffer, videoFromFile, videoFromUrl };