@axlsdk/axl 0.7.5 → 0.8.0

package/dist/index.d.cts

@@ -108,6 +108,8 @@ type StreamChunk = {
         reasoning_tokens?: number;
         cached_tokens?: number;
     };
+    /** Estimated cost in USD for this call, computed the same way as ProviderResponse.cost. */
+    cost?: number;
     /** Provider-specific opaque metadata (e.g. raw Gemini parts with thought signatures). */
     providerMetadata?: Record<string, unknown>;
 };
@@ -194,10 +196,22 @@ type VoteOptions<T> = {
     scorer?: (value: T) => number | Promise<number>;
     reducer?: (values: T[]) => T | Promise<T>;
 };
+/** Context passed to the verify function on retry (undefined on first call). */
+type VerifyRetry<T> = {
+    /** Error message from the failed attempt (schema or validate). */
+    error: string;
+    /** Raw return value from the previous fn call. */
+    output: unknown;
+    /** Schema-parsed object — only present when schema passed but validate failed.
+     *  Safe to modify and return as the next attempt. */
+    parsed?: T;
+};
 /** Verify options */
 type VerifyOptions<T> = {
     retries?: number;
     fallback?: T;
+    /** Post-schema business rule validation on the parsed object. */
+    validate?: OutputValidator<T>;
 };
 /** AwaitHuman options */
 type AwaitHumanOptions = {
@@ -209,6 +223,12 @@ type AwaitHumanOptions = {
 type AskOptions<T = unknown> = {
     schema?: z.ZodType<T>;
     retries?: number;
+    /** Post-schema business rule validation. Receives the parsed typed object after schema
+     *  validation succeeds. Only runs when `schema` is set. Retries with accumulating context
+     *  on failure (LLM sees all previous failed attempts). Throws `ValidationError` on exhaustion. */
+    validate?: OutputValidator<T>;
+    /** Maximum retries for validate failures (default: 2). */
+    validateRetries?: number;
     /** Per-call metadata passed to dynamic model/system selector functions. */
     metadata?: Record<string, unknown>;
     /** Override temperature for this call. */
@@ -238,11 +258,17 @@ type DelegateOptions<T = unknown> = {
     metadata?: Record<string, unknown>;
     /** Number of retries for structured output validation (passed to the final ask). */
     retries?: number;
+    /** Post-schema business rule validation. Passed through to the final `ctx.ask()` call. */
+    validate?: OutputValidator<T>;
+    /** Maximum retries for validate failures (default: 2). Passed through to the final `ctx.ask()` call. */
+    validateRetries?: number;
 };
 /** Race options */
 type RaceOptions<T = unknown> = {
     /** Schema to validate each result. Invalid results are discarded and the race continues. */
     schema?: z.ZodType<T>;
+    /** Post-schema business rule validation. Results that fail are discarded (same as schema failures). */
+    validate?: OutputValidator<T>;
 };
 /** Execution status */
 type ExecutionStatus = 'running' | 'completed' | 'failed' | 'waiting';
@@ -250,7 +276,7 @@ type ExecutionStatus = 'running' | 'completed' | 'failed' | 'waiting';
 type TraceEvent = {
     executionId: string;
     step: number;
-    type: 'agent_call' | 'tool_call' | 'verify' | 'handoff' | 'delegate' | 'tool_denied' | 'log' | 'workflow_start' | 'workflow_end' | 'guardrail';
+    type: 'agent_call' | 'tool_call' | 'verify' | 'handoff' | 'delegate' | 'tool_denied' | 'log' | 'workflow_start' | 'workflow_end' | 'guardrail' | 'validate';
     workflow?: string;
     agent?: string;
     tool?: string;
@@ -285,6 +311,18 @@ type GuardrailsConfig = {
     onBlock?: GuardrailBlockHandler;
     maxRetries?: number;
 };
+/** Result of a validate check (post-schema business rule validation).
+ *  Note: uses `valid: true` = pass, unlike `GuardrailResult` which uses `block: true` = fail. */
+type ValidateResult = {
+    valid: boolean;
+    reason?: string;
+};
+/** Output validator function. Runs after schema parsing on the typed object.
+ *  Only invoked when a schema is provided on the `ctx.ask()` call — without a schema,
+ *  use output guardrails for raw text validation instead. */
+type OutputValidator<T = unknown> = (output: T, ctx: {
+    metadata: Record<string, unknown>;
+}) => ValidateResult | Promise<ValidateResult>;
 /** Execution info */
 type ExecutionInfo = {
     executionId: string;
@@ -1000,7 +1038,7 @@ declare class WorkflowContext<TInput = unknown> {
     private numericVote;
     private meanVote;
     private medianVote;
-    verify<T>(fn: (lastOutput?: unknown, errorMessage?: string) => Promise<unknown>, schema: z.ZodType<T>, options?: VerifyOptions<T>): Promise<T>;
+    verify<T>(fn: (retry?: VerifyRetry<T>) => Promise<unknown>, schema: z.ZodType<T>, options?: VerifyOptions<T>): Promise<T>;
     budget<T>(options: BudgetOptions, fn: () => Promise<T>): Promise<BudgetResult<T>>;
     /** Get the current budget status, or null if not inside a budget block. */
     getBudgetStatus(): {
@@ -1406,6 +1444,13 @@ declare class GuardrailError extends AxlError {
     readonly reason: string;
     constructor(guardrailType: 'input' | 'output', reason: string);
 }
+/** Thrown when post-schema business rule validation fails after all retries exhausted */
+declare class ValidationError extends AxlError {
+    readonly lastOutput: unknown;
+    readonly reason: string;
+    readonly retries: number;
+    constructor(lastOutput: unknown, reason: string, retries: number);
+}
 /** Internal: thrown when an agent tries to call a tool not in its ACL */
 declare class ToolDenied extends AxlError {
     readonly toolName: string;
@@ -1798,4 +1843,4 @@ declare class NoopSpanManager implements SpanManager {
  */
 declare function createSpanManager(config?: TelemetryConfig): Promise<SpanManager>;
 
-export { type Agent, type AgentCallInfo, type AgentConfig, AnthropicProvider, type AskOptions, type AwaitHumanOptions, type AxlConfig, AxlError, AxlRuntime, AxlStream, BudgetExceededError, type BudgetOptions, type BudgetResult, type ChatMessage, type ChatOptions, type DelegateOptions, type Effort, type Embedder, type ExecutionInfo, type ExecutionState, GeminiProvider, type GuardrailBlockHandler, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HumanDecision, InMemoryVectorStore, type InputGuardrail, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type PendingDecision, type Provider, type ProviderAdapter, ProviderRegistry, type ProviderResponse, QuorumNotMet, type RaceOptions, type RecallOptions, RedisStore, type RememberOptions, type ResolvedThinkingOptions, type Result, type RetryPolicy, SQLiteStore, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type StreamEvent, type TelemetryConfig, TimeoutError, type Tool, type ToolCallMessage, type ToolChoice, type ToolConfig, ToolDenied, type ToolHooks, type TraceEvent, type VectorEntry, type VectorResult, type VectorStore, VerifyError, type VerifyOptions, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, agent, createSpanManager, defineConfig, resolveThinkingOptions, tool, workflow, zodToJsonSchema };
+export { type Agent, type AgentCallInfo, type AgentConfig, AnthropicProvider, type AskOptions, type AwaitHumanOptions, type AxlConfig, AxlError, AxlRuntime, AxlStream, BudgetExceededError, type BudgetOptions, type BudgetResult, type ChatMessage, type ChatOptions, type DelegateOptions, type Effort, type Embedder, type ExecutionInfo, type ExecutionState, GeminiProvider, type GuardrailBlockHandler, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HumanDecision, InMemoryVectorStore, type InputGuardrail, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type OutputValidator, type PendingDecision, type Provider, type ProviderAdapter, ProviderRegistry, type ProviderResponse, QuorumNotMet, type RaceOptions, type RecallOptions, RedisStore, type RememberOptions, type ResolvedThinkingOptions, type Result, type RetryPolicy, SQLiteStore, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type StreamEvent, type TelemetryConfig, TimeoutError, type Tool, type ToolCallMessage, type ToolChoice, type ToolConfig, ToolDenied, type ToolHooks, type TraceEvent, type ValidateResult, ValidationError, type VectorEntry, type VectorResult, type VectorStore, VerifyError, type VerifyOptions, type VerifyRetry, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, agent, createSpanManager, defineConfig, resolveThinkingOptions, tool, workflow, zodToJsonSchema };

package/dist/index.d.ts

@@ -108,6 +108,8 @@ type StreamChunk = {
         reasoning_tokens?: number;
         cached_tokens?: number;
     };
+    /** Estimated cost in USD for this call, computed the same way as ProviderResponse.cost. */
+    cost?: number;
     /** Provider-specific opaque metadata (e.g. raw Gemini parts with thought signatures). */
     providerMetadata?: Record<string, unknown>;
 };
@@ -194,10 +196,22 @@ type VoteOptions<T> = {
     scorer?: (value: T) => number | Promise<number>;
     reducer?: (values: T[]) => T | Promise<T>;
 };
+/** Context passed to the verify function on retry (undefined on first call). */
+type VerifyRetry<T> = {
+    /** Error message from the failed attempt (schema or validate). */
+    error: string;
+    /** Raw return value from the previous fn call. */
+    output: unknown;
+    /** Schema-parsed object — only present when schema passed but validate failed.
+     *  Safe to modify and return as the next attempt. */
+    parsed?: T;
+};
 /** Verify options */
 type VerifyOptions<T> = {
     retries?: number;
     fallback?: T;
+    /** Post-schema business rule validation on the parsed object. */
+    validate?: OutputValidator<T>;
 };
 /** AwaitHuman options */
 type AwaitHumanOptions = {
@@ -209,6 +223,12 @@ type AwaitHumanOptions = {
 type AskOptions<T = unknown> = {
     schema?: z.ZodType<T>;
     retries?: number;
+    /** Post-schema business rule validation. Receives the parsed typed object after schema
+     *  validation succeeds. Only runs when `schema` is set. Retries with accumulating context
+     *  on failure (LLM sees all previous failed attempts). Throws `ValidationError` on exhaustion. */
+    validate?: OutputValidator<T>;
+    /** Maximum retries for validate failures (default: 2). */
+    validateRetries?: number;
     /** Per-call metadata passed to dynamic model/system selector functions. */
     metadata?: Record<string, unknown>;
     /** Override temperature for this call. */
@@ -238,11 +258,17 @@ type DelegateOptions<T = unknown> = {
     metadata?: Record<string, unknown>;
     /** Number of retries for structured output validation (passed to the final ask). */
     retries?: number;
+    /** Post-schema business rule validation. Passed through to the final `ctx.ask()` call. */
+    validate?: OutputValidator<T>;
+    /** Maximum retries for validate failures (default: 2). Passed through to the final `ctx.ask()` call. */
+    validateRetries?: number;
 };
 /** Race options */
 type RaceOptions<T = unknown> = {
     /** Schema to validate each result. Invalid results are discarded and the race continues. */
     schema?: z.ZodType<T>;
+    /** Post-schema business rule validation. Results that fail are discarded (same as schema failures). */
+    validate?: OutputValidator<T>;
 };
 /** Execution status */
 type ExecutionStatus = 'running' | 'completed' | 'failed' | 'waiting';
@@ -250,7 +276,7 @@ type ExecutionStatus = 'running' | 'completed' | 'failed' | 'waiting';
 type TraceEvent = {
     executionId: string;
     step: number;
-    type: 'agent_call' | 'tool_call' | 'verify' | 'handoff' | 'delegate' | 'tool_denied' | 'log' | 'workflow_start' | 'workflow_end' | 'guardrail';
+    type: 'agent_call' | 'tool_call' | 'verify' | 'handoff' | 'delegate' | 'tool_denied' | 'log' | 'workflow_start' | 'workflow_end' | 'guardrail' | 'validate';
     workflow?: string;
     agent?: string;
     tool?: string;
@@ -285,6 +311,18 @@ type GuardrailsConfig = {
     onBlock?: GuardrailBlockHandler;
     maxRetries?: number;
 };
+/** Result of a validate check (post-schema business rule validation).
+ *  Note: uses `valid: true` = pass, unlike `GuardrailResult` which uses `block: true` = fail. */
+type ValidateResult = {
+    valid: boolean;
+    reason?: string;
+};
+/** Output validator function. Runs after schema parsing on the typed object.
+ *  Only invoked when a schema is provided on the `ctx.ask()` call — without a schema,
+ *  use output guardrails for raw text validation instead. */
+type OutputValidator<T = unknown> = (output: T, ctx: {
+    metadata: Record<string, unknown>;
+}) => ValidateResult | Promise<ValidateResult>;
 /** Execution info */
 type ExecutionInfo = {
     executionId: string;
@@ -1000,7 +1038,7 @@ declare class WorkflowContext<TInput = unknown> {
     private numericVote;
     private meanVote;
     private medianVote;
-    verify<T>(fn: (lastOutput?: unknown, errorMessage?: string) => Promise<unknown>, schema: z.ZodType<T>, options?: VerifyOptions<T>): Promise<T>;
+    verify<T>(fn: (retry?: VerifyRetry<T>) => Promise<unknown>, schema: z.ZodType<T>, options?: VerifyOptions<T>): Promise<T>;
     budget<T>(options: BudgetOptions, fn: () => Promise<T>): Promise<BudgetResult<T>>;
     /** Get the current budget status, or null if not inside a budget block. */
     getBudgetStatus(): {
@@ -1406,6 +1444,13 @@ declare class GuardrailError extends AxlError {
     readonly reason: string;
     constructor(guardrailType: 'input' | 'output', reason: string);
 }
+/** Thrown when post-schema business rule validation fails after all retries exhausted */
+declare class ValidationError extends AxlError {
+    readonly lastOutput: unknown;
+    readonly reason: string;
+    readonly retries: number;
+    constructor(lastOutput: unknown, reason: string, retries: number);
+}
 /** Internal: thrown when an agent tries to call a tool not in its ACL */
 declare class ToolDenied extends AxlError {
     readonly toolName: string;
@@ -1798,4 +1843,4 @@ declare class NoopSpanManager implements SpanManager {
  */
 declare function createSpanManager(config?: TelemetryConfig): Promise<SpanManager>;
 
-export { type Agent, type AgentCallInfo, type AgentConfig, AnthropicProvider, type AskOptions, type AwaitHumanOptions, type AxlConfig, AxlError, AxlRuntime, AxlStream, BudgetExceededError, type BudgetOptions, type BudgetResult, type ChatMessage, type ChatOptions, type DelegateOptions, type Effort, type Embedder, type ExecutionInfo, type ExecutionState, GeminiProvider, type GuardrailBlockHandler, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HumanDecision, InMemoryVectorStore, type InputGuardrail, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type PendingDecision, type Provider, type ProviderAdapter, ProviderRegistry, type ProviderResponse, QuorumNotMet, type RaceOptions, type RecallOptions, RedisStore, type RememberOptions, type ResolvedThinkingOptions, type Result, type RetryPolicy, SQLiteStore, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type StreamEvent, type TelemetryConfig, TimeoutError, type Tool, type ToolCallMessage, type ToolChoice, type ToolConfig, ToolDenied, type ToolHooks, type TraceEvent, type VectorEntry, type VectorResult, type VectorStore, VerifyError, type VerifyOptions, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, agent, createSpanManager, defineConfig, resolveThinkingOptions, tool, workflow, zodToJsonSchema };
+export { type Agent, type AgentCallInfo, type AgentConfig, AnthropicProvider, type AskOptions, type AwaitHumanOptions, type AxlConfig, AxlError, AxlRuntime, AxlStream, BudgetExceededError, type BudgetOptions, type BudgetResult, type ChatMessage, type ChatOptions, type DelegateOptions, type Effort, type Embedder, type ExecutionInfo, type ExecutionState, GeminiProvider, type GuardrailBlockHandler, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HumanDecision, InMemoryVectorStore, type InputGuardrail, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type OutputValidator, type PendingDecision, type Provider, type ProviderAdapter, ProviderRegistry, type ProviderResponse, QuorumNotMet, type RaceOptions, type RecallOptions, RedisStore, type RememberOptions, type ResolvedThinkingOptions, type Result, type RetryPolicy, SQLiteStore, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type StreamEvent, type TelemetryConfig, TimeoutError, type Tool, type ToolCallMessage, type ToolChoice, type ToolConfig, ToolDenied, type ToolHooks, type TraceEvent, type ValidateResult, ValidationError, type VectorEntry, type VectorResult, type VectorStore, VerifyError, type VerifyOptions, type VerifyRetry, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, agent, createSpanManager, defineConfig, resolveThinkingOptions, tool, workflow, zodToJsonSchema };