@agentfield/sdk 0.1.111-rc.1 → 0.1.111-rc.3

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,7 +999,10 @@ 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;
 }>;
@@ -968,6 +1132,13 @@ declare class ReasonerContext<TInput = any> {
     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
@@ -1005,6 +1176,7 @@ declare class ReasonerContext<TInput = any> {
         workflow: WorkflowReporter;
         did: DidInterface;
         signal?: AbortSignal;
+        costTracker?: CostTracker;
         trigger?: TriggerContext;
     });
     ai<T>(prompt: string, options: AIRequestOptions & {
@@ -1143,6 +1315,11 @@ interface SkillOptions {
 interface HarnessConfig {
     provider: 'claude-code' | 'codex' | 'gemini' | 'opencode';
     model?: string;
+    /**
+     * Provider-specific reasoning-effort variant (e.g. `high`, `minimal`).
+     * Wins over a `#variant` suffix on `model`.
+     */
+    variant?: string;
     maxTurns?: number;
     maxBudgetUsd?: number;
     maxRetries?: number;
@@ -1161,6 +1338,11 @@ interface HarnessConfig {
 interface HarnessOptions {
     provider?: string;
     model?: string;
+    /**
+     * Provider-specific reasoning-effort variant (e.g. `high`, `minimal`).
+     * Wins over a `#variant` suffix on `model`.
+     */
+    variant?: string;
     maxTurns?: number;
     maxBudgetUsd?: number;
     maxRetries?: number;
@@ -1184,6 +1366,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;
@@ -1202,6 +1392,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;
@@ -1600,6 +1798,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;
@@ -2430,6 +2637,33 @@ declare class OpenRouterMediaProvider implements MediaProvider {
     private get;
 }
 
+/**
+ * Separator for the `provider/model#variant` model-string syntax. `#` is
+ * safe because provider model ids never contain it (`:` is taken by
+ * OpenRouter suffixes like `:free`, `@` by Vertex-style ids).
+ */
+declare const MODEL_VARIANT_SEP = "#";
+interface ModelVariant {
+    model?: string;
+    variant?: string;
+}
+/**
+ * Split a `provider/model#variant` string into `{ model, variant }`.
+ *
+ * The `#variant` suffix carries a provider-specific reasoning-effort
+ * variant (e.g. `high`, `minimal`) through config surfaces that only
+ * hold a model string. A bare model string passes through as
+ * `{ model }`; non-string or empty input yields `{}`.
+ */
+declare function splitModelVariant(model: unknown): ModelVariant;
+/**
+ * Resolve `{ model, variant }` from harness options.
+ *
+ * An explicit `options.variant` wins over a `#variant` suffix on
+ * `options.model`; the returned model never carries the suffix.
+ */
+declare function resolveModelAndVariant(options: Record<string, unknown>): ModelVariant;
+
 declare const SUPPORTED_PROVIDERS: Set<string>;
 declare function buildProvider(config: HarnessConfig): Promise<HarnessProvider>;
 
@@ -2769,4 +3003,4 @@ declare function simulateSchedule<R>(handler: (ctx: SimulatedContext) => R | Pro
  */
 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, 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, type UnwrapResult, type VectorSearchOptions, type VectorSearchResult, Video, type VideoFrameImage, type VideoInputReference, type VideoRequest, type WaitForApprovalOptions, type WorkflowCredential, type WorkflowMetadata, type WorkflowProgressOptions, WorkflowReporter, type ZodSchema, applyTriggerTransform, 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, isTriggerEnvelope, loadFixture, normalizeExecutionLogEntry, normalizeSessionTransportValue, normalizeStatus, scheduleTrigger, serializeExecutionLogEntry, simulateSchedule, simulateTrigger, text, triggerToPayload, unwrapEnvelope, validateSessionTransport, videoFromBase64, videoFromBuffer, videoFromFile, videoFromUrl };
+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, MODEL_VARIANT_SEP, 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 ModelVariant, 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, resolveModelAndVariant, scheduleTrigger, serializeExecutionLogEntry, simulateSchedule, simulateTrigger, splitModelVariant, text, triggerToPayload, unwrapEnvelope, usageSummaryOrNull, validateSessionTransport, videoFromBase64, videoFromBuffer, videoFromFile, videoFromUrl };