@cognipeer/agent-sdk 0.6.3 → 0.6.5

package/dist/index.d.cts

@@ -206,6 +206,24 @@ type AgentLimits = {
     maxToolCalls?: number;
     maxParallelTools?: number;
     maxContextTokens?: number;
+    /**
+     * Cap on cumulative model output tokens across the whole invoke. Once
+     * exceeded the loop terminates after the current iteration with a
+     * `metadata` event explaining the reason and emits `finalAnswer` so callers
+     * can still recover the partial result.
+     */
+    maxTotalOutputTokens?: number;
+    /**
+     * Cap on cumulative cost in USD. Requires `costEstimator` on the agent
+     * options to be a no-op-free check; otherwise this limit is ignored.
+     */
+    maxCostUsd?: number;
+    /**
+     * Cap on total wall-clock time for the invoke in milliseconds. Identical
+     * semantics to `InvokeConfig.timeoutMs` but lives on the agent definition
+     * so server-side defaults can be enforced without per-call wiring.
+     */
+    maxWallClockMs?: number;
 };
 type SmartAgentLimits = AgentLimits;
 type TraceSinkFileConfig = {
@@ -262,6 +280,25 @@ type AgentOptions = {
      * When omitted or `enabled=false` the agent behaves exactly as before.
      */
     reasoning?: ReasoningConfig;
+    /**
+     * Optional drop-in token counter. When provided, all internal token
+     * estimates (summarization trigger, hard caps, context budget) use this
+     * function instead of the built-in character heuristic. Recommended:
+     * tiktoken / @anthropic-ai/tokenizer for production accuracy.
+     */
+    tokenCounter?: (text: string) => number;
+    /**
+     * Pluggable cost estimator: returns USD cost for a single model call's
+     * usage. Used by the `maxCostUsd` budget limit. When omitted the SDK has
+     * no built-in pricing table and the cost limit is a no-op.
+     */
+    costEstimator?: (args: {
+        modelName?: string;
+        inputTokens: number;
+        outputTokens: number;
+        cachedInputTokens?: number;
+        reasoningTokens?: number;
+    }) => number;
 };
 type ReasoningLevel = "low" | "medium" | "high";
 type ReflectionCadence = "off" | "every_turn" | "after_tool" | "on_branch";
@@ -282,6 +319,18 @@ type ReflectionConfig = {
     promptTemplate?: string;
     /** When true emits `reflection` SmartAgent events. Default true. */
     emitEvents?: boolean;
+    /**
+     * Hard cap on the number of reflection calls within a single invoke. Once
+     * the cap is hit subsequent qualifying turns no longer trigger reflection.
+     * Default: unlimited.
+     */
+    maxPerRun?: number;
+    /**
+     * Minimum number of tool-bearing turns between reflections. Defaults to 1
+     * (reflect on every qualifying turn). Set to 2 to reflect every other tool
+     * turn, etc. Independent of `cadence`.
+     */
+    everyNTurns?: number;
 };
 type NativeReasoningConfig = {
     effort?: "minimal" | "low" | "medium" | "high";
@@ -418,7 +467,7 @@ type SmartAgentToolResponseConfig = {
     /**
      * Retention policy applied to all non-critical tool responses by the summarizer
      * when it fires (context limit reached). Has no effect at execution time.
-     * Defaults to "summarize_archive".
+      * Defaults to context.toolResponsePolicy, or the active runtime profile default.
      */
     defaultPolicy?: ToolResponseRetentionPolicy;
     /**
@@ -485,6 +534,10 @@ type SmartAgentOptions = {
      * Unified reasoning configuration. Same shape as on `AgentOptions`. See `ReasoningConfig`.
      */
     reasoning?: ReasoningConfig;
+    /** See AgentOptions.tokenCounter. */
+    tokenCounter?: (text: string) => number;
+    /** See AgentOptions.costEstimator. */
+    costEstimator?: AgentOptions["costEstimator"];
 };
 type AgentRuntimeConfig = {
     name?: string;
@@ -1098,7 +1151,29 @@ type AgentInstance<TOutput = unknown> = {
 type SmartAgentInstance<TOutput = unknown> = AgentInstance<TOutput>;
 
 type SmartToolFn = (args: any) => Promise<any> | any;
-declare function createTool({ name, description, schema, func, needsApproval, approvalPrompt, approvalDefaults, maxExecutionsPerRun, }: {
+type ToolCachePolicy = {
+    /** Cache scope. "run" persists for the current invoke only. */
+    scope?: "run";
+    /** Override the cache key (default: stable JSON of args). */
+    keyFn?: (args: any) => string;
+    /** Time-to-live for the cached value, in ms. Default: full invoke. */
+    ttlMs?: number;
+};
+type ToolRetryPolicy = {
+    /** Max retry attempts after the initial failure. Default: 0. */
+    maxRetries?: number;
+    /** Initial backoff in ms (doubled on each retry). Default: 250. */
+    backoffMs?: number;
+    /** Decide whether an error is worth retrying. Default: every error. */
+    shouldRetry?: (err: unknown, attempt: number) => boolean;
+    /**
+     * Open a circuit-breaker after this many consecutive failures across the
+     * invoke; once tripped the tool short-circuits with the breaker error
+     * until the loop ends. Default: never trip.
+     */
+    circuitBreakerThreshold?: number;
+};
+declare function createTool({ name, description, schema, func, needsApproval, approvalPrompt, approvalDefaults, maxExecutionsPerRun, cache, retry, }: {
     name: string;
     description?: string;
     schema: ZodSchema;
@@ -1107,6 +1182,10 @@ declare function createTool({ name, description, schema, func, needsApproval, ap
     approvalPrompt?: string;
     approvalDefaults?: any;
     maxExecutionsPerRun?: number | null;
+    /** When set, identical args within the same invoke short-circuit to the cached result. */
+    cache?: boolean | ToolCachePolicy;
+    /** Per-tool retry + circuit-breaker policy. */
+    retry?: ToolRetryPolicy;
 }): ToolInterface;
 
 declare function buildSystemPrompt(extra?: string, planning?: boolean | PlanningMode, name?: string, todoListPrompt?: string): string;
@@ -1137,15 +1216,30 @@ declare function createToolLimitFinalizeNode(_opts: SmartAgentOptions): (state:
  */
 declare function createContextSummarizeNode(opts: SmartAgentOptions): (state: SmartState) => Promise<Partial<SmartState>>;
 
+/**
+ * Token counter contract used across the SDK. The default is a
+ * character-based heuristic; users can swap in a real tokenizer (tiktoken,
+ * @anthropic-ai/tokenizer, …) via SmartAgentOptions.tokenCounter.
+ */
+type TokenCounter = (text: string) => number;
 /**
  * Estimates token count from text using a character-based heuristic.
  *
- * This is a rough approximation:
+ * Approximation:
  * - For Latin/ASCII text: ~4 characters per token (GPT-family models)
  * - For CJK/Unicode text: ~1.5 characters per token
  *
- * For production accuracy, consider using a proper tokenizer like tiktoken.
+ * For production accuracy, pass a `tokenCounter` option backed by tiktoken.
+ */
+declare function defaultTokenCounter(text: string): number;
+/**
+ * Installs a custom token counter used by every callable in this module
+ * (countApproxTokens, countMessagesTokens). Pass `undefined` or
+ * `defaultTokenCounter` to restore the heuristic.
  */
+declare function setTokenCounter(counter?: TokenCounter | null): void;
+declare function getTokenCounter(): TokenCounter;
+/** Backwards-compatible alias that delegates to the active counter. */
 declare function countApproxTokens(text: string): number;
 /**
  * Estimates the total token count for an array of messages.
@@ -1624,6 +1718,16 @@ type ChatCompletionChunk = {
     usage?: TokenUsage;
     finishReason?: FinishReason;
 };
+type ProviderRetryConfig = {
+    /** Maximum retries on 429/5xx (default 3). */
+    maxRetries?: number;
+    /** Initial delay between retries in ms (default 500, doubled each attempt). */
+    baseDelayMs?: number;
+    /** Hard cap on a single retry delay in ms (default 8000). */
+    maxDelayMs?: number;
+    /** Custom predicate to opt in/out of a specific retry. */
+    shouldRetry?: (error: any, attempt: number) => boolean;
+};
 type OpenAIProviderConfig = {
     provider: "openai";
     apiKey: string;
@@ -1631,6 +1735,7 @@ type OpenAIProviderConfig = {
     organization?: string;
     defaultModel?: string;
     defaultHeaders?: Record<string, string>;
+    retry?: ProviderRetryConfig;
 };
 type AnthropicProviderConfig = {
     provider: "anthropic";
@@ -1639,6 +1744,15 @@ type AnthropicProviderConfig = {
     defaultModel?: string;
     defaultHeaders?: Record<string, string>;
     anthropicVersion?: string;
+    retry?: ProviderRetryConfig;
+    /**
+     * Prompt caching configuration. When enabled, places cache_control:
+     * ephemeral breakpoints on the system prompt and the final tool definition,
+     * which is the recommended Anthropic recipe for static system + tools.
+     */
+    prompt_caching?: {
+        enabled: boolean;
+    };
 };
 type AzureProviderConfig = {
     provider: "azure";
@@ -1664,6 +1778,15 @@ type BedrockProviderConfig = {
     sessionToken?: string;
     defaultModel?: string;
     defaultHeaders?: Record<string, string>;
+    retry?: ProviderRetryConfig;
+    /**
+     * Insert Bedrock Converse `cachePoint` blocks at the end of the system
+     * prompt and tools list. Only supported by models that implement Converse
+     * prompt caching (most Anthropic Claude variants on Bedrock).
+     */
+    prompt_caching?: {
+        enabled: boolean;
+    };
 };
 type VertexProviderConfig = {
     provider: "vertex";
@@ -1683,12 +1806,32 @@ declare class ProviderError extends Error {
     constructor(message: string, provider: string, statusCode?: number | undefined, responseBody?: any | undefined);
 }
 
+type ProviderRetryPolicy = {
+    /** Maximum number of retries on 429/5xx responses. Default: 3. */
+    maxRetries?: number;
+    /** Initial backoff in ms (doubled on each retry). Default: 500. */
+    baseDelayMs?: number;
+    /** Hard cap on individual delay between retries. Default: 8000. */
+    maxDelayMs?: number;
+    /**
+     * Custom predicate to decide whether to retry. By default we retry 429
+     * and 5xx responses; pass a function to broaden/narrow that set.
+     */
+    shouldRetry?: (error: any, attempt: number) => boolean;
+};
 declare abstract class BaseProvider {
     abstract readonly providerName: ProviderType;
+    protected retryPolicy: ProviderRetryPolicy;
     /** Non-streaming completion */
     abstract complete(request: ChatCompletionRequest): Promise<ChatCompletionResponse>;
     /** Streaming completion – yields incremental chunks */
     abstract completeStream(request: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown>;
+    /**
+     * Helper concrete providers can wrap their fetch with. Retries 429/5xx
+     * with exponential backoff and respects Retry-After if the response
+     * carries one.
+     */
+    protected doFetchWithRetry(execute: () => Promise<Response>): Promise<Response>;
 }
 
 declare class OpenAIProvider extends BaseProvider {
@@ -1715,6 +1858,7 @@ declare class AnthropicProvider extends BaseProvider {
     private readonly defaultModel;
     private readonly defaultHeaders;
     private readonly anthropicVersion;
+    private readonly promptCachingEnabled;
     constructor(config: AnthropicProviderConfig);
     complete(request: ChatCompletionRequest): Promise<ChatCompletionResponse>;
     completeStream(request: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown>;
@@ -1747,6 +1891,7 @@ declare class BedrockProvider extends BaseProvider {
     private readonly credentials;
     private readonly defaultModel;
     private readonly defaultHeaders;
+    private readonly promptCachingEnabled;
     constructor(config: BedrockProviderConfig);
     complete(request: ChatCompletionRequest): Promise<ChatCompletionResponse>;
     completeStream(request: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown>;
@@ -1830,4 +1975,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
  */
 declare function createProvider(config: ProviderConfig): BaseProvider;
 
-export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, type PendingToolApproval, type PlanEvent, type PlanStepRecord, type PlanningMode, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, type SerializableSmartState, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCallEvent, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, VertexProvider, type VertexProviderConfig, agentVerdictRule, buildSystemPrompt, captureSnapshot, codePresenceRule, cognipeerSink, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createProvider, createRegexGuardrail, createResolverNode, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveMemoryStore, resolveStrategy, resolveToolApprovalState, restoreSnapshot, runSmartAgentEvalHarness, startStreamingSession, traceSessionToOtlp, withTools, writeSummaryFactsToMemory };
+export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, type PendingToolApproval, type PlanEvent, type PlanStepRecord, type PlanningMode, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, type SerializableSmartState, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, VertexProvider, type VertexProviderConfig, agentVerdictRule, buildSystemPrompt, captureSnapshot, codePresenceRule, cognipeerSink, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createProvider, createRegexGuardrail, createResolverNode, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, defaultTokenCounter, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveMemoryStore, resolveStrategy, resolveToolApprovalState, restoreSnapshot, runSmartAgentEvalHarness, setTokenCounter, startStreamingSession, traceSessionToOtlp, withTools, writeSummaryFactsToMemory };

package/dist/index.d.ts

@@ -206,6 +206,24 @@ type AgentLimits = {
     maxToolCalls?: number;
     maxParallelTools?: number;
     maxContextTokens?: number;
+    /**
+     * Cap on cumulative model output tokens across the whole invoke. Once
+     * exceeded the loop terminates after the current iteration with a
+     * `metadata` event explaining the reason and emits `finalAnswer` so callers
+     * can still recover the partial result.
+     */
+    maxTotalOutputTokens?: number;
+    /**
+     * Cap on cumulative cost in USD. Requires `costEstimator` on the agent
+     * options to be a no-op-free check; otherwise this limit is ignored.
+     */
+    maxCostUsd?: number;
+    /**
+     * Cap on total wall-clock time for the invoke in milliseconds. Identical
+     * semantics to `InvokeConfig.timeoutMs` but lives on the agent definition
+     * so server-side defaults can be enforced without per-call wiring.
+     */
+    maxWallClockMs?: number;
 };
 type SmartAgentLimits = AgentLimits;
 type TraceSinkFileConfig = {
@@ -262,6 +280,25 @@ type AgentOptions = {
      * When omitted or `enabled=false` the agent behaves exactly as before.
      */
     reasoning?: ReasoningConfig;
+    /**
+     * Optional drop-in token counter. When provided, all internal token
+     * estimates (summarization trigger, hard caps, context budget) use this
+     * function instead of the built-in character heuristic. Recommended:
+     * tiktoken / @anthropic-ai/tokenizer for production accuracy.
+     */
+    tokenCounter?: (text: string) => number;
+    /**
+     * Pluggable cost estimator: returns USD cost for a single model call's
+     * usage. Used by the `maxCostUsd` budget limit. When omitted the SDK has
+     * no built-in pricing table and the cost limit is a no-op.
+     */
+    costEstimator?: (args: {
+        modelName?: string;
+        inputTokens: number;
+        outputTokens: number;
+        cachedInputTokens?: number;
+        reasoningTokens?: number;
+    }) => number;
 };
 type ReasoningLevel = "low" | "medium" | "high";
 type ReflectionCadence = "off" | "every_turn" | "after_tool" | "on_branch";
@@ -282,6 +319,18 @@ type ReflectionConfig = {
     promptTemplate?: string;
     /** When true emits `reflection` SmartAgent events. Default true. */
     emitEvents?: boolean;
+    /**
+     * Hard cap on the number of reflection calls within a single invoke. Once
+     * the cap is hit subsequent qualifying turns no longer trigger reflection.
+     * Default: unlimited.
+     */
+    maxPerRun?: number;
+    /**
+     * Minimum number of tool-bearing turns between reflections. Defaults to 1
+     * (reflect on every qualifying turn). Set to 2 to reflect every other tool
+     * turn, etc. Independent of `cadence`.
+     */
+    everyNTurns?: number;
 };
 type NativeReasoningConfig = {
     effort?: "minimal" | "low" | "medium" | "high";
@@ -418,7 +467,7 @@ type SmartAgentToolResponseConfig = {
     /**
      * Retention policy applied to all non-critical tool responses by the summarizer
      * when it fires (context limit reached). Has no effect at execution time.
-     * Defaults to "summarize_archive".
+      * Defaults to context.toolResponsePolicy, or the active runtime profile default.
      */
     defaultPolicy?: ToolResponseRetentionPolicy;
     /**
@@ -485,6 +534,10 @@ type SmartAgentOptions = {
      * Unified reasoning configuration. Same shape as on `AgentOptions`. See `ReasoningConfig`.
      */
     reasoning?: ReasoningConfig;
+    /** See AgentOptions.tokenCounter. */
+    tokenCounter?: (text: string) => number;
+    /** See AgentOptions.costEstimator. */
+    costEstimator?: AgentOptions["costEstimator"];
 };
 type AgentRuntimeConfig = {
     name?: string;
@@ -1098,7 +1151,29 @@ type AgentInstance<TOutput = unknown> = {
 type SmartAgentInstance<TOutput = unknown> = AgentInstance<TOutput>;
 
 type SmartToolFn = (args: any) => Promise<any> | any;
-declare function createTool({ name, description, schema, func, needsApproval, approvalPrompt, approvalDefaults, maxExecutionsPerRun, }: {
+type ToolCachePolicy = {
+    /** Cache scope. "run" persists for the current invoke only. */
+    scope?: "run";
+    /** Override the cache key (default: stable JSON of args). */
+    keyFn?: (args: any) => string;
+    /** Time-to-live for the cached value, in ms. Default: full invoke. */
+    ttlMs?: number;
+};
+type ToolRetryPolicy = {
+    /** Max retry attempts after the initial failure. Default: 0. */
+    maxRetries?: number;
+    /** Initial backoff in ms (doubled on each retry). Default: 250. */
+    backoffMs?: number;
+    /** Decide whether an error is worth retrying. Default: every error. */
+    shouldRetry?: (err: unknown, attempt: number) => boolean;
+    /**
+     * Open a circuit-breaker after this many consecutive failures across the
+     * invoke; once tripped the tool short-circuits with the breaker error
+     * until the loop ends. Default: never trip.
+     */
+    circuitBreakerThreshold?: number;
+};
+declare function createTool({ name, description, schema, func, needsApproval, approvalPrompt, approvalDefaults, maxExecutionsPerRun, cache, retry, }: {
     name: string;
     description?: string;
     schema: ZodSchema;
@@ -1107,6 +1182,10 @@ declare function createTool({ name, description, schema, func, needsApproval, ap
     approvalPrompt?: string;
     approvalDefaults?: any;
     maxExecutionsPerRun?: number | null;
+    /** When set, identical args within the same invoke short-circuit to the cached result. */
+    cache?: boolean | ToolCachePolicy;
+    /** Per-tool retry + circuit-breaker policy. */
+    retry?: ToolRetryPolicy;
 }): ToolInterface;
 
 declare function buildSystemPrompt(extra?: string, planning?: boolean | PlanningMode, name?: string, todoListPrompt?: string): string;
@@ -1137,15 +1216,30 @@ declare function createToolLimitFinalizeNode(_opts: SmartAgentOptions): (state:
  */
 declare function createContextSummarizeNode(opts: SmartAgentOptions): (state: SmartState) => Promise<Partial<SmartState>>;
 
+/**
+ * Token counter contract used across the SDK. The default is a
+ * character-based heuristic; users can swap in a real tokenizer (tiktoken,
+ * @anthropic-ai/tokenizer, …) via SmartAgentOptions.tokenCounter.
+ */
+type TokenCounter = (text: string) => number;
 /**
  * Estimates token count from text using a character-based heuristic.
  *
- * This is a rough approximation:
+ * Approximation:
  * - For Latin/ASCII text: ~4 characters per token (GPT-family models)
  * - For CJK/Unicode text: ~1.5 characters per token
  *
- * For production accuracy, consider using a proper tokenizer like tiktoken.
+ * For production accuracy, pass a `tokenCounter` option backed by tiktoken.
+ */
+declare function defaultTokenCounter(text: string): number;
+/**
+ * Installs a custom token counter used by every callable in this module
+ * (countApproxTokens, countMessagesTokens). Pass `undefined` or
+ * `defaultTokenCounter` to restore the heuristic.
  */
+declare function setTokenCounter(counter?: TokenCounter | null): void;
+declare function getTokenCounter(): TokenCounter;
+/** Backwards-compatible alias that delegates to the active counter. */
 declare function countApproxTokens(text: string): number;
 /**
  * Estimates the total token count for an array of messages.
@@ -1624,6 +1718,16 @@ type ChatCompletionChunk = {
     usage?: TokenUsage;
     finishReason?: FinishReason;
 };
+type ProviderRetryConfig = {
+    /** Maximum retries on 429/5xx (default 3). */
+    maxRetries?: number;
+    /** Initial delay between retries in ms (default 500, doubled each attempt). */
+    baseDelayMs?: number;
+    /** Hard cap on a single retry delay in ms (default 8000). */
+    maxDelayMs?: number;
+    /** Custom predicate to opt in/out of a specific retry. */
+    shouldRetry?: (error: any, attempt: number) => boolean;
+};
 type OpenAIProviderConfig = {
     provider: "openai";
     apiKey: string;
@@ -1631,6 +1735,7 @@ type OpenAIProviderConfig = {
     organization?: string;
     defaultModel?: string;
     defaultHeaders?: Record<string, string>;
+    retry?: ProviderRetryConfig;
 };
 type AnthropicProviderConfig = {
     provider: "anthropic";
@@ -1639,6 +1744,15 @@ type AnthropicProviderConfig = {
     defaultModel?: string;
     defaultHeaders?: Record<string, string>;
     anthropicVersion?: string;
+    retry?: ProviderRetryConfig;
+    /**
+     * Prompt caching configuration. When enabled, places cache_control:
+     * ephemeral breakpoints on the system prompt and the final tool definition,
+     * which is the recommended Anthropic recipe for static system + tools.
+     */
+    prompt_caching?: {
+        enabled: boolean;
+    };
 };
 type AzureProviderConfig = {
     provider: "azure";
@@ -1664,6 +1778,15 @@ type BedrockProviderConfig = {
     sessionToken?: string;
     defaultModel?: string;
     defaultHeaders?: Record<string, string>;
+    retry?: ProviderRetryConfig;
+    /**
+     * Insert Bedrock Converse `cachePoint` blocks at the end of the system
+     * prompt and tools list. Only supported by models that implement Converse
+     * prompt caching (most Anthropic Claude variants on Bedrock).
+     */
+    prompt_caching?: {
+        enabled: boolean;
+    };
 };
 type VertexProviderConfig = {
     provider: "vertex";
@@ -1683,12 +1806,32 @@ declare class ProviderError extends Error {
     constructor(message: string, provider: string, statusCode?: number | undefined, responseBody?: any | undefined);
 }
 
+type ProviderRetryPolicy = {
+    /** Maximum number of retries on 429/5xx responses. Default: 3. */
+    maxRetries?: number;
+    /** Initial backoff in ms (doubled on each retry). Default: 500. */
+    baseDelayMs?: number;
+    /** Hard cap on individual delay between retries. Default: 8000. */
+    maxDelayMs?: number;
+    /**
+     * Custom predicate to decide whether to retry. By default we retry 429
+     * and 5xx responses; pass a function to broaden/narrow that set.
+     */
+    shouldRetry?: (error: any, attempt: number) => boolean;
+};
 declare abstract class BaseProvider {
     abstract readonly providerName: ProviderType;
+    protected retryPolicy: ProviderRetryPolicy;
     /** Non-streaming completion */
     abstract complete(request: ChatCompletionRequest): Promise<ChatCompletionResponse>;
     /** Streaming completion – yields incremental chunks */
     abstract completeStream(request: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown>;
+    /**
+     * Helper concrete providers can wrap their fetch with. Retries 429/5xx
+     * with exponential backoff and respects Retry-After if the response
+     * carries one.
+     */
+    protected doFetchWithRetry(execute: () => Promise<Response>): Promise<Response>;
 }
 
 declare class OpenAIProvider extends BaseProvider {
@@ -1715,6 +1858,7 @@ declare class AnthropicProvider extends BaseProvider {
     private readonly defaultModel;
     private readonly defaultHeaders;
     private readonly anthropicVersion;
+    private readonly promptCachingEnabled;
     constructor(config: AnthropicProviderConfig);
     complete(request: ChatCompletionRequest): Promise<ChatCompletionResponse>;
     completeStream(request: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown>;
@@ -1747,6 +1891,7 @@ declare class BedrockProvider extends BaseProvider {
     private readonly credentials;
     private readonly defaultModel;
     private readonly defaultHeaders;
+    private readonly promptCachingEnabled;
     constructor(config: BedrockProviderConfig);
     complete(request: ChatCompletionRequest): Promise<ChatCompletionResponse>;
     completeStream(request: ChatCompletionRequest): AsyncGenerator<ChatCompletionChunk, void, unknown>;
@@ -1830,4 +1975,4 @@ declare function fromNativeProvider(provider: BaseProvider, options?: NativeMode
  */
 declare function createProvider(config: ProviderConfig): BaseProvider;
 
-export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, type PendingToolApproval, type PlanEvent, type PlanStepRecord, type PlanningMode, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, type SerializableSmartState, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCallEvent, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, VertexProvider, type VertexProviderConfig, agentVerdictRule, buildSystemPrompt, captureSnapshot, codePresenceRule, cognipeerSink, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createProvider, createRegexGuardrail, createResolverNode, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveMemoryStore, resolveStrategy, resolveToolApprovalState, restoreSnapshot, runSmartAgentEvalHarness, startStreamingSession, traceSessionToOtlp, withTools, writeSummaryFactsToMemory };
+export { type AIMessage, type AgentInstance, type AgentInvokeResult, type AgentLimits, type AgentOptions, type AgentRuleOptions, type AgentRuntimeConfig, type AgentSnapshot, type AgentSnapshotMetadata, type AgentState, AnthropicProvider, type AnthropicProviderConfig, AzureProvider, type AzureProviderConfig, type BaseChatMessage, type BaseChatMessagePart, type BaseChatModel, type BaseMessage, BaseProvider, BedrockProvider, type BedrockProviderConfig, type BuiltInRuntimeProfile, type CancellationTokenLike, type CancelledEvent, type ChatCompletionChunk, type ChatCompletionRequest, type ChatCompletionResponse, type ChildContextPolicy, type CodeDetectionRuleOptions, type CodeGuardrailOptions, type ContextPolicy, type ContextToolsStateRef, type ConversationGuardrail, type CustomRuleCallback, type CustomRuleOptions, DEFAULT_PROFILE_CONFIGS, type DelegationMode, type EvalCase, type EvalCaseResult, type EvalFamily, type EvalHarnessMetrics, type EvalHarnessParams, type EvalHarnessResult, type EvalProfileDescriptor, type EvalProfileTarget, type FinalAnswerEvent, type FinishReason, type GuardrailContext, type GuardrailDisposition, type GuardrailEvent, type GuardrailIncident, type GuardrailOutcome, GuardrailPhase, type GuardrailRule, type HandoffDescriptor, type HandoffEvent, InMemoryMemoryStore, type InvokeConfig, type JsonGuardrailOptions, type JsonSchemaRuleOptions, type MemoryFact, type MemoryProviderKind, type MemoryReadPolicy, type MemoryScope, type MemoryStore, type MemoryWritePolicy, type Message, type MetadataEvent, type ModelCapabilities, NativeJsonSchemaStrategy, type NativeModelOptions, type NativeReasoningConfig, OpenAICompatibleProvider, type OpenAICompatibleProviderConfig, OpenAIProvider, type OpenAIProviderConfig, type PendingToolApproval, type PlanEvent, type PlanStepRecord, type PlanningMode, type ProfileConfig, type ProgressEvent, type ProgressUpdate, type ProviderConfig, ProviderError, type ToolCall as ProviderToolCall, type ToolDefinition as ProviderToolDefinition, type ProviderType, type ReasoningConfig, type ReasoningLevel, type ReflectionCadence, type ReflectionConfig, type ReflectionEvent, type ReflectionRecord, type RegexGuardrailOptions, type RegexRuleOptions, type ReplanPolicy, type ResolvedSmartAgentConfig, type ResolvedTraceConfig, type ResolvedTraceSink, type RestoreSnapshotOptions, type RuntimeProfile, type SerializableSmartState, type SmartAgentBudgetConfig, type SmartAgentContextConfig, type SmartAgentCustomProfileConfig, type SmartAgentDelegationConfig, type SmartAgentEvent, type SmartAgentInstance, type SmartAgentLimits, type SmartAgentMemoryConfig, type SmartAgentOptions, type SmartAgentPlanningConfig, type SmartAgentSummarizationConfig, type SmartAgentToolResponseConfig, type SmartAgentTracingConfig, type SmartModel, type SmartState, type SmartToolFn, type SnapshotOptions, type SnapshotRuntimeHint, type StreamChunk, type StreamEvent, type StructuredOutputError, type StructuredOutputFieldError, StructuredOutputManager, type StructuredOutputManagerConfig, type StructuredOutputResult, type StructuredOutputStrategy, type StructuredSummary, type SummarizationEvent, type SummarizationMode, type SummaryFactItem, type SummaryIntegrityCheck, type TokenCounter, type TokenUsage, type ToolApprovalEvent, type ToolApprovalResolution, type ToolApprovalStatus, ToolBasedStrategy, type ToolCachePolicy, type ToolCallEvent, type ToolInterface, type ToolResponseClassification, type ToolResponseRetentionPolicy, type ToolRetryPolicy, type TraceDataSection, type TraceErrorRecord, type TraceEventRecord, type TraceMessageSection, type TraceMetadataSection, type TraceSessionConfigSnapshot, type TraceSessionFile, type TraceSessionStatus, type TraceSessionSummary, type TraceSinkCognipeerConfig, type TraceSinkConfig, type TraceSinkCustomConfig, type TraceSinkFileConfig, type TraceSinkHttpConfig, type TraceSinkOtlpConfig, type TraceSinkSnapshot, type TraceSummarySection, type TraceToolCallSection, type TraceToolResultSection, type TracingConfig, type TracingMode, type UnifiedMessage, VertexProvider, type VertexProviderConfig, agentVerdictRule, buildSystemPrompt, captureSnapshot, codePresenceRule, cognipeerSink, countApproxTokens, countMessagesTokens, createAgent, createAgentNode, createCodeGuardrail, createContextSummarizeNode, createContextTools, createGetToolResponseTool, createGuardrail, createJsonGuardrail, createManageTodoTool, createProvider, createRegexGuardrail, createResolverNode, createSmartAgent, createTool, createToolLimitFinalizeNode, createToolsNode, customCallbackRule, customSink, defaultTokenCounter, emptyUsage, evaluateGuardrails, fileSink, formatZodError, fromLangchainModel, fromLangchainTools, fromNativeProvider, generateSpanId, generateTraceId, getModelCapabilities, getNestedValue, getResolvedSmartConfig, getTokenCounter, hasToolResponseRecoveryReference, httpSink, isSmartModel, jsonSchemaRule, normalizeSmartAgentOptions, otlpSink, readMemoryFacts, regexRule, resolveMemoryStore, resolveStrategy, resolveToolApprovalState, restoreSnapshot, runSmartAgentEvalHarness, setTokenCounter, startStreamingSession, traceSessionToOtlp, withTools, writeSummaryFactsToMemory };