@axlsdk/axl 0.7.6 → 0.9.0

package/README.md

@@ -7,9 +7,11 @@ Core SDK for orchestrating agentic systems in TypeScript. Part of the [Axl](http
 ## Installation
 
 ```bash
-npm install @axlsdk/axl zod
+npm install @axlsdk/axl zod@^4
 ```
 
+> **Note:** `zod` is a peer dependency — your application and Axl share a single Zod instance. Zod v4 (`^4.0.0`) is required.
+
 ## Project Structure
 
 The recommended pattern separates config, tools, agents, workflows, and runtime into their own modules. Dependencies flow one direction: tools → agents → workflows → runtime.
@@ -320,7 +322,7 @@ for await (const event of sessionStream) {
 All available on `ctx` inside workflow handlers. See the [API Reference](../../docs/api-reference.md) for complete option types, valid values, and defaults.
 
 ```typescript
-// Invoke an agent (schema retries rebuild the call with the failed output + error in the prompt)
+// Invoke an agent (schema/validate retries accumulate — LLM sees all previous failed attempts)
 const answer = await ctx.ask(agent, 'prompt', { schema, retries });
 
 // Run 3 agents in parallel — each gets the same question independently
@@ -329,11 +331,11 @@ const results = await ctx.spawn(3, async (i) => ctx.ask(agent, prompts[i]));
 // Pick the answer that appeared most often — also supports LLM-as-judge via scorer
 const winner = await ctx.vote(results, { strategy: 'majority', key: 'answer' });
 
-// Generic retry-until-valid loop (not conversation-aware — you decide how to use the error)
+// Retry-until-valid loop — for APIs, pipelines, or as a repair fallback for ctx.ask()
 const valid = await ctx.verify(
-  async (lastOutput, error) => ctx.ask(agent, error ? `Fix: ${error}` : prompt),
-  schema,
-  { retries: 3, fallback: defaultValue },
+  async () => fetchRouteFromAPI(origin, destination),
+  RouteSchema,
+  { retries: 3, fallback: defaultRoute },
 );
 
 // Cost control — returns { value, budgetExceeded, totalCost }
@@ -477,7 +479,29 @@ const safe = agent({
 });
 ```
 
-When `onBlock` is `'retry'`, the LLM's blocked output is appended to the conversation (as an assistant message) along with a system message containing the block reason, then the LLM is re-called so it can self-correct. These messages **accumulate** across retries — if the guardrail blocks multiple times, the LLM sees all prior failed attempts and corrections before its next try. All retry messages are ephemeral — they are **not** persisted to session history, so subsequent session turns never see the blocked attempts. Note: `ctx.ask()` schema retries work differently — each retry rebuilds the call from scratch and only includes the most recent failed output and error (previous failures do not accumulate). Input guardrails always throw since the prompt is user-supplied. Throws `GuardrailError` if retries are exhausted or `onBlock` is `'throw'`.
+When `onBlock` is `'retry'`, the LLM's blocked output is appended to the conversation (as an assistant message) along with a system message containing the block reason, then the LLM is re-called so it can self-correct. These messages **accumulate** across retries — if the guardrail blocks multiple times, the LLM sees all prior failed attempts and corrections before its next try. All retry messages are ephemeral — they are **not** persisted to session history, so subsequent session turns never see the blocked attempts. Schema retries and validate retries use the same accumulating pattern. Input guardrails always throw since the prompt is user-supplied. Throws `GuardrailError` if retries are exhausted or `onBlock` is `'throw'`.
+
+For **business rule validation** on the parsed typed object (not raw text), use `validate` on `ctx.ask()`:
+
+```typescript
+const UserSchema = z.object({
+  name: z.string(),
+  email: z.string(),
+  role: z.enum(['admin', 'editor', 'viewer']),
+});
+
+const result = await ctx.ask(extractAgent, 'Extract user from this text', {
+  schema: UserSchema,
+  validate: (user) => {
+    if (user.role === 'admin' && !user.email.endsWith('@company.com')) {
+      return { valid: false, reason: 'Admin users must have a company email' };
+    }
+    return { valid: true };
+  },
+});
+```
+
+`validate` is per-call, co-located with the `schema` it validates. It runs **after** schema parsing succeeds, receiving the fully typed object. On failure, the LLM sees all previous attempts (accumulating context) and the validation reason. Requires `schema` — without it, validate is skipped (use guardrails for raw text). Throws `ValidationError` after retries are exhausted. Also supported on `ctx.delegate()`, `ctx.race()`, and `ctx.verify()`.
 
 ### State Stores
 
@@ -556,6 +580,7 @@ import {
   MaxTurnsError, // Agent exceeded max tool-calling turns
   BudgetExceededError, // Budget limit exceeded
   GuardrailError, // Guardrail blocked input or output
+  ValidationError, // Post-schema business rule validation failed after retries
   ToolDenied, // Agent tried to call unauthorized tool
 } from '@axlsdk/axl';
 ```

package/dist/index.cjs

@@ -135,6 +135,7 @@ __export(index_exports, {
   SqliteVectorStore: () => SqliteVectorStore,
   TimeoutError: () => TimeoutError,
   ToolDenied: () => ToolDenied,
+  ValidationError: () => ValidationError,
   VerifyError: () => VerifyError,
   WorkflowContext: () => WorkflowContext,
   agent: () => agent,
@@ -2143,6 +2144,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;
@@ -2235,48 +2248,9 @@ function resolveConfig(config) {
 // src/context.ts
 var signalStorage = new import_node_async_hooks.AsyncLocalStorage();
 function zodToJsonSchema(schema) {
-  const def = schema._def;
-  if (!def || !def.typeName) return {};
-  switch (def.typeName) {
-    case "ZodString":
-      return { type: "string" };
-    case "ZodNumber":
-      return { type: "number" };
-    case "ZodBoolean":
-      return { type: "boolean" };
-    case "ZodArray":
-      return { type: "array", items: zodToJsonSchema(def.type) };
-    case "ZodObject": {
-      const shape = def.shape?.() ?? {};
-      const properties = {};
-      const required = [];
-      for (const [key, value] of Object.entries(shape)) {
-        properties[key] = zodToJsonSchema(value);
-        const innerDef = value._def;
-        if (innerDef?.typeName !== "ZodOptional" && innerDef?.typeName !== "ZodDefault") {
-          required.push(key);
-        }
-      }
-      return { type: "object", properties, required: required.length > 0 ? required : void 0 };
-    }
-    case "ZodOptional":
-      return zodToJsonSchema(def.innerType);
-    case "ZodDefault":
-      return zodToJsonSchema(def.innerType);
-    case "ZodEnum":
-      return { type: "string", enum: def.values };
-    case "ZodLiteral": {
-      const v = def.value;
-      const t = v === null ? "null" : typeof v;
-      return { type: t, const: v };
-    }
-    case "ZodUnion":
-      return { oneOf: def.options.map((o) => zodToJsonSchema(o)) };
-    case "ZodNullable":
-      return { ...zodToJsonSchema(def.innerType), nullable: true };
-    default:
-      return {};
-  }
+  const result = import_zod.z.toJSONSchema(schema, { unrepresentable: "any" });
+  delete result.$schema;
+  return result;
 }
 function estimateTokens(text) {
   return Math.ceil(text.length / 4);
@@ -2407,9 +2381,6 @@ var WorkflowContext = class _WorkflowContext {
           agent2,
           prompt,
           options,
-          0,
-          void 0,
-          void 0,
           void 0,
           usageCapture
         );
@@ -2459,7 +2430,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") {
@@ -2531,16 +2502,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) {
@@ -2585,9 +2546,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);
@@ -2715,14 +2684,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
               );
@@ -3056,26 +3028,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 import_zod.ZodError ? err : new import_zod.ZodError([
             {
@@ -3084,11 +3056,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);
   }
@@ -3445,32 +3461,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 import_zod.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 import_zod.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 import_zod.ZodError ? err : new import_zod.ZodError([{ code: "custom", path: [], message: lastErrorMessage }]);
-          throw new VerifyError(lastOutput, zodErr, maxRetries);
+          const zodErr = err instanceof import_zod.ZodError ? err : new import_zod.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 import_zod.ZodError([{ code: "custom", path: [], message: "Verify failed" }]),
       maxRetries
     );
@@ -3572,7 +3613,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);
@@ -3585,6 +3626,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);
@@ -3836,7 +3904,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 };
@@ -3877,7 +3947,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 ───────────────────────────────────────────────────────────
@@ -6159,6 +6231,7 @@ function cosineSimilarity2(a, b) {
   SqliteVectorStore,
   TimeoutError,
   ToolDenied,
+  ValidationError,
   VerifyError,
   WorkflowContext,
   agent,