@axlsdk/axl 0.7.6 → 0.8.0

package/dist/index.d.cts

@@ -196,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 = {
@@ -211,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. */
@@ -240,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';
@@ -252,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;
@@ -287,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;
@@ -1002,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(): {
@@ -1408,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;
@@ -1800,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

@@ -196,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 = {
@@ -211,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. */
@@ -240,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';
@@ -252,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;
@@ -287,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;
@@ -1002,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(): {
@@ -1408,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;
@@ -1800,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.js

@@ -1998,6 +1998,18 @@ var GuardrailError = class extends AxlError {
     this.reason = reason;
   }
 };
+var ValidationError = class extends AxlError {
+  lastOutput;
+  reason;
+  retries;
+  constructor(lastOutput, reason, retries) {
+    super("VALIDATION_ERROR", `Validation failed after ${retries} retries: ${reason}`);
+    this.name = "ValidationError";
+    this.lastOutput = lastOutput;
+    this.reason = reason;
+    this.retries = retries;
+  }
+};
 var ToolDenied = class extends AxlError {
   toolName;
   agentName;
@@ -2262,9 +2274,6 @@ var WorkflowContext = class _WorkflowContext {
           agent2,
           prompt,
           options,
-          0,
-          void 0,
-          void 0,
           void 0,
           usageCapture
         );
@@ -2314,7 +2323,7 @@ var WorkflowContext = class _WorkflowContext {
       return result;
     });
   }
-  async executeAgentCall(agent2, prompt, options, retryCount = 0, previousOutput, previousError, handoffMessages, usageCapture) {
+  async executeAgentCall(agent2, prompt, options, handoffMessages, usageCapture) {
     if (this.budgetContext?.exceeded) {
       const { limit, totalCost: spent, policy } = this.budgetContext;
       if (policy === "warn") {
@@ -2386,16 +2395,6 @@ var WorkflowContext = class _WorkflowContext {
 
 Respond with valid JSON matching this schema:
 ${JSON.stringify(jsonSchema, null, 2)}`;
-    }
-    if (previousOutput && previousError) {
-      userContent += `
-
-Your previous response was invalid:
-${previousOutput}
-
-Error: ${previousError}
-
-Please fix and try again.`;
     }
     messages.push({ role: "user", content: userContent });
     if (handoffMessages && handoffMessages.length > 0) {
@@ -2440,9 +2439,17 @@ Please fix and try again.`;
     const maxTurns = agent2._config.maxTurns ?? 25;
     const timeoutMs = parseDuration(agent2._config.timeout ?? "60s");
     const startTime = Date.now();
+    if (this.onToken && options?.validate) {
+      throw new AxlError(
+        "INVALID_CONFIG",
+        "Cannot use validate with streaming. Validate requires schema (JSON output) which does not benefit from token streaming. Use a non-streaming call instead."
+      );
+    }
     const currentMessages = [...messages];
     let turns = 0;
     let guardrailOutputRetries = 0;
+    let schemaRetries = 0;
+    let validateRetries = 0;
     while (turns < maxTurns) {
       if (Date.now() - startTime > timeoutMs) {
         throw new TimeoutError("ctx.ask()", timeoutMs);
@@ -2570,14 +2577,17 @@ Please fix and try again.`;
                 }
               }
               const handoffStart = Date.now();
-              const handoffOptions = options ? { schema: options.schema, retries: options.retries, metadata: options.metadata } : void 0;
+              const handoffOptions = options ? {
+                schema: options.schema,
+                retries: options.retries,
+                metadata: options.metadata,
+                validate: options.validate,
+                validateRetries: options.validateRetries
+              } : void 0;
               const handoffFn = () => this.executeAgentCall(
                 descriptor.agent,
                 handoffPrompt,
                 handoffOptions,
-                0,
-                void 0,
-                void 0,
                 currentMessages,
                 usageCapture
               );
@@ -2911,26 +2921,26 @@ Please fix and try again.`;
           throw new GuardrailError("output", outputResult.reason ?? "Output blocked by guardrail");
         }
       }
+      let validated = void 0;
       if (options?.schema) {
         try {
           const parsed = JSON.parse(stripMarkdownFences(content));
-          const validated = options.schema.parse(parsed);
-          this.pushAssistantToSessionHistory(content, response.providerMetadata);
-          return validated;
+          validated = options.schema.parse(parsed);
         } catch (err) {
-          const maxRetries = options.retries ?? 3;
-          if (retryCount < maxRetries) {
+          const maxSchemaRetries = options.retries ?? 3;
+          if (schemaRetries < maxSchemaRetries) {
+            schemaRetries++;
             const errorMsg = err instanceof Error ? err.message : String(err);
-            return this.executeAgentCall(
-              agent2,
-              prompt,
-              options,
-              retryCount + 1,
+            currentMessages.push({
+              role: "assistant",
               content,
-              errorMsg,
-              void 0,
-              usageCapture
-            );
+              ...response.providerMetadata ? { providerMetadata: response.providerMetadata } : {}
+            });
+            currentMessages.push({
+              role: "system",
+              content: `Your response was not valid JSON or did not match the required schema: ${errorMsg}. Please fix and try again.`
+            });
+            continue;
           }
           const zodErr = err instanceof ZodError ? err : new ZodError([
             {
@@ -2939,11 +2949,55 @@ Please fix and try again.`;
               message: err instanceof Error ? err.message : String(err)
             }
           ]);
-          throw new VerifyError(content, zodErr, maxRetries);
+          throw new VerifyError(content, zodErr, maxSchemaRetries);
+        }
+      }
+      if (options?.schema && options.validate) {
+        let validateResult;
+        try {
+          validateResult = await options.validate(validated, {
+            metadata: this.metadata
+          });
+        } catch (err) {
+          const reason = err instanceof Error ? err.message : String(err);
+          validateResult = { valid: false, reason: `Validator error: ${reason}` };
+        }
+        this.emitTrace({
+          type: "validate",
+          agent: agent2._name,
+          data: {
+            valid: validateResult.valid,
+            ...validateResult.reason ? { reason: validateResult.reason } : {}
+          }
+        });
+        this.spanManager?.addEventToActiveSpan("axl.validate.check", {
+          "axl.validate.valid": validateResult.valid,
+          ...validateResult.reason ? { "axl.validate.reason": validateResult.reason } : {}
+        });
+        if (!validateResult.valid) {
+          const maxValidateRetries = options.validateRetries ?? 2;
+          if (validateRetries < maxValidateRetries) {
+            validateRetries++;
+            currentMessages.push({
+              role: "assistant",
+              content,
+              ...response.providerMetadata ? { providerMetadata: response.providerMetadata } : {}
+            });
+            currentMessages.push({
+              role: "system",
+              content: `Your response parsed correctly but failed validation: ${validateResult.reason ?? "Validation failed"}. Previous attempts are visible above. Please fix and try again.`
+            });
+            continue;
+          }
+          throw new ValidationError(
+            validated,
+            validateResult.reason ?? "Validation failed",
+            maxValidateRetries
+          );
         }
       }
       this.pushAssistantToSessionHistory(content, response.providerMetadata);
-      return content;
+      return validated ?? content;
     }
     throw new MaxTurnsError("ctx.ask()", maxTurns);
   }
@@ -3300,32 +3354,57 @@ ${summaryResponse.content}`
   // ── ctx.verify() ──────────────────────────────────────────────────────
   async verify(fn, schema, options) {
     const maxRetries = options?.retries ?? 3;
-    let lastOutput = void 0;
-    let lastErrorMessage = void 0;
+    let lastRetry = void 0;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
-      let result;
+      let rawOutput;
       try {
-        result = await fn(lastOutput, lastErrorMessage);
-        lastOutput = result;
-        return schema.parse(result);
+        const result = await fn(lastRetry);
+        rawOutput = result;
+        const parsed = schema.parse(result);
+        if (options?.validate) {
+          let validateResult;
+          try {
+            validateResult = await options.validate(parsed, { metadata: this.metadata });
+          } catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            validateResult = { valid: false, reason: `Validator error: ${reason}` };
+          }
+          if (!validateResult.valid) {
+            const errorMsg = validateResult.reason ?? "Validation failed";
+            lastRetry = { error: errorMsg, output: rawOutput, parsed };
+            if (attempt === maxRetries) {
+              if (options?.fallback !== void 0) return options.fallback;
+              throw new ValidationError(parsed, errorMsg, maxRetries);
+            }
+            continue;
+          }
+        }
+        return parsed;
       } catch (err) {
-        if (err instanceof ZodError) {
-          lastErrorMessage = err.message;
-        } else if (err instanceof Error) {
-          lastErrorMessage = err.message;
-        } else {
-          lastErrorMessage = String(err);
+        if (err instanceof ValidationError) {
+          lastRetry = {
+            error: err.reason,
+            output: rawOutput,
+            parsed: err.lastOutput
+          };
+          if (attempt === maxRetries) {
+            if (options?.fallback !== void 0) return options.fallback;
+            throw err;
+          }
+          continue;
         }
+        const errorMsg = err instanceof ZodError ? err.message : err instanceof Error ? err.message : String(err);
+        lastRetry = { error: errorMsg, output: rawOutput };
         if (attempt === maxRetries) {
           if (options?.fallback !== void 0) return options.fallback;
-          const zodErr = err instanceof ZodError ? err : new ZodError([{ code: "custom", path: [], message: lastErrorMessage }]);
-          throw new VerifyError(lastOutput, zodErr, maxRetries);
+          const zodErr = err instanceof ZodError ? err : new ZodError([{ code: "custom", path: [], message: errorMsg }]);
+          throw new VerifyError(rawOutput, zodErr, maxRetries);
         }
       }
     }
     if (options?.fallback !== void 0) return options.fallback;
     throw new VerifyError(
-      lastOutput,
+      lastRetry?.output,
       new ZodError([{ code: "custom", path: [], message: "Verify failed" }]),
       maxRetries
     );
@@ -3427,7 +3506,7 @@ ${summaryResponse.content}`
       let remaining = fns.length;
       for (const fn of fns) {
         const p = signalStorage.run(composedSignal, fn);
-        p.then((value) => {
+        p.then(async (value) => {
           if (settled) return;
           if (schema) {
             const parsed = schema.safeParse(value);
@@ -3440,6 +3519,33 @@ ${summaryResponse.content}`
               }
               return;
             }
+            if (options?.validate) {
+              try {
+                const validateResult = await options.validate(parsed.data, {
+                  metadata: this.metadata
+                });
+                if (!validateResult.valid) {
+                  remaining--;
+                  lastError = new Error(
+                    `Validation failed: ${validateResult.reason ?? "Validation failed"}`
+                  );
+                  if (remaining === 0 && !settled) {
+                    settled = true;
+                    reject(lastError);
+                  }
+                  return;
+                }
+              } catch (err) {
+                remaining--;
+                lastError = err instanceof Error ? err : new Error(`Validator error: ${String(err)}`);
+                if (remaining === 0 && !settled) {
+                  settled = true;
+                  reject(lastError);
+                }
+                return;
+              }
+            }
+            if (settled) return;
             settled = true;
             controller.abort();
             resolve(parsed.data);
@@ -3691,7 +3797,9 @@ ${summaryResponse.content}`
       return this.ask(agents[0], prompt, {
         schema: options?.schema,
         retries: options?.retries,
-        metadata: options?.metadata
+        metadata: options?.metadata,
+        validate: options?.validate,
+        validateRetries: options?.validateRetries
       });
     }
     const resolveCtx = options?.metadata ? { metadata: { ...this.metadata, ...options.metadata } } : { metadata: this.metadata };
@@ -3732,7 +3840,9 @@ ${summaryResponse.content}`
     return this.ask(routerAgent, prompt, {
       schema: options?.schema,
       retries: options?.retries,
-      metadata: options?.metadata
+      metadata: options?.metadata,
+      validate: options?.validate,
+      validateRetries: options?.validateRetries
     });
   }
   // ── Private ───────────────────────────────────────────────────────────
@@ -6012,6 +6122,7 @@ export {
   SqliteVectorStore,
   TimeoutError,
   ToolDenied,
+  ValidationError,
   VerifyError,
   WorkflowContext,
   agent,