@ax-llm/ax 21.0.14 → 22.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "21.0.14",
+  "version": "22.0.0",
   "type": "module",
   "description": "The best library to work with LLMs",
   "repository": {

package/skills/ax-agent-memory-skills.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-memory-skills
 description: This skill helps an LLM generate correct AxAgent memory retrieval, context-map, and dynamic skill-loading code using @ax-llm/ax. Use when the user asks about contextMap, AxAgentContextMap, onMemoriesSearch, recall(...), inputs.memories, onLoadedMemories, onUsedMemories, onSkillsSearch, discover({ skills }), onLoadedSkills, onUsedSkills, preloaded skills, loaded memory/skill IDs, or carrying memories across forward() calls.
-version: "21.0.14"
+version: "22.0.0"
 ---
 
 # AxAgent Memory And Skills Rules (@ax-llm/ax)

package/skills/ax-agent-observability.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-observability
-description: This skill helps an LLM generate correct AxAgent observability code using @ax-llm/ax. Use when the user asks about actorTurnCallback, executorTurnCallback, onContextEvent, agentStatusCallback, onFunctionCall, reportSuccess, reportFailure, getChatLog(), getUsage(), resetUsage(), debug traces, progress updates, or telemetry for AxAgent runs.
-version: "21.0.14"
+description: This skill helps an LLM generate correct AxAgent observability code using @ax-llm/ax. Use when the user asks about actorTurnCallback, onContextEvent, agentStatusCallback, onFunctionCall, reportSuccess, reportFailure, getChatLog(), getUsage(), resetUsage(), debug traces, progress updates, or telemetry for AxAgent runs.
+version: "22.0.0"
 ---
 
 # AxAgent Observability Rules (@ax-llm/ax)
@@ -38,7 +38,7 @@ These globals are live defaults for future AI, AxGen, AxFlow, and agent-internal
 
 ## Actor Turn Callback
 
-Use `actorTurnCallback` when the caller needs structured telemetry for each actor turn. `executorTurnCallback` is still accepted as a deprecated alias for older code.
+Use `actorTurnCallback` when the caller needs structured telemetry for each actor turn.
 
 What it gives you:
 
@@ -127,7 +127,7 @@ actorTurnCallback?: (turn: {
   chatLogMessages?: ReadonlyArray<{ role: string; content: string }>;
 }) => void | Promise<void>;
 
-executorTurnCallback?: (turn: {
+actorTurnCallback?: (turn: {
   stage: 'distiller' | 'executor';
   turn: number;
   actionLogEntryCount: number;

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 agent optimization guidance.
-version: "21.0.14"
+version: "22.0.0"
 ---
 
 # AxAgent Optimize Codegen Rules (@ax-llm/ax)

package/skills/ax-agent-rlm.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-rlm
 description: This skill helps an LLM generate correct AxAgent RLM/runtime code using @ax-llm/ax. Use when the user asks about RLM code execution, AxJSRuntime, contextFields, contextPolicy, liveRuntimeState, promptLevel, stage prompt controls, executorModelPolicy, maxRuntimeChars, agent.test(...), llmQuery(...), recursionOptions, or long-running agent runtime behavior.
-version: "21.0.14"
+version: "22.0.0"
 ---
 
 # AxAgent RLM Runtime Rules (@ax-llm/ax)
@@ -30,11 +30,11 @@ Use this skill for code-runtime agents and `llmQuery(...)` semantic-helper behav
 distiller (RLM actor) -> executor (RLM actor) -> responder (synthesizer)
 ```
 
-- **distiller** always runs first. It sees all original inputs so it can understand and normalize the task; declared `contextFields` stay runtime-only when present. It distils relevant evidence by writing JS code in a multi-turn loop, then calls `final(request, evidence)`. The request becomes the executor's `inputs.executorRequest`; it must be self-contained and restate the concrete action, target, and constraints, not vague wording like "do it". The distiller should expand the original user task with facts found in context, including follow-ups like "yes, do it". When no `contextFields` are configured, it still performs request normalization over the original inputs with `contextFields: []`. **The distiller has no tools and is not a capability gate.**
+- **distiller** always runs first. It sees all original inputs so it can understand and normalize the task; declared `contextFields` stay runtime-only when present. It distils relevant evidence by writing runtime-language code in a multi-turn loop, then calls the runtime-exposed `final(request, evidence)` primitive. The request becomes the executor's `inputs.executorRequest`; it must be self-contained and restate the concrete action, target, and constraints, not vague wording like "do it". The distiller should expand the original user task with facts found in context, including follow-ups like "yes, do it". When no `contextFields` are configured, it still performs request normalization over the original inputs with `contextFields: []`. **The distiller has no tools and is not a capability gate.**
 - **executor** always runs. It receives non-context inputs plus `inputs.executorRequest` and `inputs.distilledContext` from the distiller's `final(request, evidence)` payload. Raw context fields are not present in the executor stage. The executor owns tool use, decides whether to call its available functions or finish directly from distilled evidence, and reports actual tool results or failures.
 - **responder** always runs last. It synthesizes the user's output signature from whichever upstream actor finished the run and must not contradict tool evidence gathered upstream.
 
-Treat both actor stages as long-running JavaScript REPLs that the actor steers over multiple turns, not as fresh script generators on every turn.
+Treat both actor stages as long-running code runtime sessions that the actor steers over multiple turns, not as fresh script generators on every turn. `AxJSRuntime` is the default; custom runtimes set `language` so the actor code field becomes `<language>Code` such as `pythonCode` while JavaScript keeps the legacy `javascriptCode`.
 
 - Successful code leaves variables, functions, imports, and computed values available in the runtime session.
 - The actor should continue from existing runtime state instead of recreating prior work.
@@ -43,7 +43,7 @@ Treat both actor stages as long-running JavaScript REPLs that the actor steers o
 
 ## RLM Actor Code Rules
 
-Use these rules when generating actor JavaScript for RLM in stdout mode:
+Use these rules when generating actor JavaScript for RLM in `AxJSRuntime` stdout mode. For custom runtimes, follow the runtime's `getUsageInstructions()`, primitive overrides, and callable formatter instead.
 
 - Treat each actor turn as exactly one observable step.
 - Inspect what already exists before recomputing it. If a prior turn successfully created a value, prefer reusing that runtime value.
@@ -246,6 +246,14 @@ Model guidance:
 - For cost-sensitive setups, a common pattern is stronger actor plus cheaper responder.
 - Prefer `executorModelPolicy` over globally upgrading the whole agent when the actor only needs help after context grows or the run starts thrashing.
 
+Prompt/cache shape:
+
+- Actor turns are compact observable turns, not replayed chat transcripts.
+- Stable system prompt: role/stage rules, primitive descriptions, static module list, always-included callable signatures, output contract, and field definitions.
+- Cached working inputs: task inputs, inline context, `contextMetadata`, `contextMap`, `memories`, `executorRequest`, `distilledContext`, `discoveredToolDocs`, `loadedSkills`, and `summarizedActorLog`.
+- Dynamic turn tail: `guidanceLog`, `actionLog`, `liveRuntimeState`, and `contextPressure`.
+- Prefer one compact inspection per non-final turn. Never combine inspection output with `final(...)` or `askClarification(...)`.
+
 Invalid actor turn:
 
 ```javascript
@@ -260,6 +268,8 @@ Reason: this mixes observation and follow-up work in one turn. `discover(...)` r
 
 Default `new AxJSRuntime()` is hardened: no network, no filesystem, no child process, dynamic `import()` blocked, intrinsics frozen, `ShadowRealm` locked to `undefined`, worker IPC locked in browser/Deno/Bun, Bun workers use `smol: true`, and on Node 20+ the OS Permission Model auto-engages where available.
 
+Threat model: this is defense-in-depth for LLM-authored code, not a container or VM boundary. Host callbacks and granted runtime permissions remain the authority boundary; keep durable secrets and privileged effects in host-side functions.
+
 Permission enum (`AxJSRuntimePermission`):
 `NETWORK`, `STORAGE`, `CODE_LOADING`, `COMMUNICATION`, `TIMING`, `WORKERS`, `FILESYSTEM`, `CHILD_PROCESS`.
 
@@ -267,7 +277,7 @@ Options quick reference:
 
 - `permissions?: readonly AxJSRuntimePermission[]`: default `[]`; opt in capabilities.
 - `blockDynamicImport?: boolean`: default `true`.
-- `allowedModules?: readonly string[]`: default `[]`.
+- `allowedModules?: readonly string[]`: default `[]`; narrow dynamic-import allowlist gate. Allowlisted specifiers are attempted, but full Node module namespace passthrough depends on Node vm semantics.
 - `freezeIntrinsics?: boolean`: default `true`.
 - `blockShadowRealm?: boolean`: default `true`.
 - `lockWorkerIPC?: boolean`: default `true`.
@@ -300,15 +310,25 @@ 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]`.
-- When the user asks for filesystem access, add both `permissions: [AxJSRuntimePermission.FILESYSTEM]` and `allowedModules: ['node:fs', 'node:fs/promises', 'node:path']`. Scope with `nodePermissionAllowlist` when the user names a directory.
+- When the user asks for filesystem access, prefer host-side tool functions. If direct runtime filesystem access is required, add `permissions: [AxJSRuntimePermission.FILESYSTEM]`, scope with `nodePermissionAllowlist` when the user names a directory, and treat `allowedModules` as an import allowlist gate rather than a portability guarantee.
 - Do not disable `freezeIntrinsics`, `blockShadowRealm`, or `lockWorkerIPC` unless the user explicitly asks.
 - 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.
 - On Deno, `blockDynamicImport` is a no-op; the defense is the worker permission sandbox. Pass `allowDenoRemoteImport: true` only if remote module loading is genuinely required.
 
+## Custom Code Runtimes
+
+Implement `AxCodeRuntime` when the actor should write a language other than JavaScript.
+
+- Set `language` to the model-facing language name. JavaScript aliases (`JavaScript`, `js`, `ecmascript`) keep `javascriptCode`; other values derive lower-camel code fields such as `pythonCode` or `cSharpCode`.
+- Keep execution inside `createSession(globals, options)`. AxAgent passes `inputs`, `llmQuery`, `final`, `askClarification`, progress callbacks, memory/discovery primitives, and namespaced tools as host globals; the runtime decides how those globals appear in the target language.
+- Put language syntax, output behavior, persistence semantics, and completion-call examples in `getUsageInstructions()`.
+- Use `getPrimitiveOverrides()` to describe language-native calls for built-in primitives, and `formatCallable()` to describe language-native calls for tools and child agents.
+- Implement `inspectGlobals()` on sessions when `contextPolicy` should show live runtime state for non-JavaScript runtimes; otherwise AxAgent will not run JavaScript fallback inspection snippets.
+
 ## 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.
+Use `agent.test(code, contextFieldValues?, options?)` when the user wants to validate runtime snippets against the actual AxAgent runtime environment without running the full actor/responder loop. With `AxJSRuntime`, those snippets are JavaScript.
 
 ```typescript
 import { AxJSRuntime, agent, f, fn } from '@ax-llm/ax';
@@ -365,7 +385,7 @@ Rules:
 
 - `llmQuery(...)` forwards only the explicit `context` argument.
 - Parent inputs, runtime variables, tool results, and discovered docs are not automatically available to `llmQuery(...)`; include any needed facts in `context`.
-- `llmQuery(...)` is a direct semantic helper backed by an AxGen sub-query. It does not create a child AxAgent, does not run a JS runtime, and does not have access to tools or discovery.
+- `llmQuery(...)` is a direct semantic helper backed by an AxGen sub-query. It does not create a child AxAgent, does not run an actor runtime session, and does not have access to tools or discovery.
 - Use batched `llmQuery([...])` only for independent semantic questions. Use serial calls when later work depends on earlier results.
 - Pass compact named object context instead of huge raw parent payloads.
 - Do not assume anything other than the returned string comes back from `llmQuery(...)`.

package/skills/ax-agent.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent
 description: This skill helps an LLM generate correct core AxAgent code using @ax-llm/ax. Use when the user asks about agent(), child agents, namespaced functions, discovery mode, clarification, bubbleErrors, host-side final/clarification protocol, or ordinary agent runtime behavior. For RLM/code-runtime work use ax-agent-rlm; for callbacks and telemetry use ax-agent-observability; for recall/memory/skill loading use ax-agent-memory-skills; for agent.optimize(...) use ax-agent-optimize.
-version: "21.0.14"
+version: "22.0.0"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
@@ -118,7 +118,7 @@ Use direct `ax(...)` or `.chat()` if the model should receive native audio inste
 
 ## Child Agents As Tools
 
-Child agents are passed in the parent's `functions` list. There is no separate `agents` option for new code. Each child agent's `agentIdentity.namespace` (or `utils`, the default) determines where it lands in the JS runtime:
+Child agents are passed in the parent's `functions` list. There is no separate `agents` option for new code. Each child agent's `agentIdentity.namespace` (or `utils`, the default) determines where it lands in the actor runtime. With `AxJSRuntime`, that produces JavaScript call sites such as `team.writer(...)`:
 
 ```typescript
 const writer = agent('draft:string -> revision:string', {
@@ -156,7 +156,7 @@ Rules:
 
 ### Reserved namespace names
 
-The agent runtime injects a fixed set of globals into the JS REPL. These names cannot be used as `agentIdentity.namespace` values or as agent-function namespaces.
+The agent runtime injects a fixed set of globals into the runtime session. These names cannot be used as `agentIdentity.namespace` values or as agent-function namespaces.
 
 ```text
 inputs
@@ -205,7 +205,7 @@ Rules:
 
 - Prefer namespaced functions.
 - Default function namespace is `utils` when no namespace is set.
-- Use the runtime call shape `await <namespace>.<name>({...})`.
+- With `AxJSRuntime`, use the runtime call shape `await <namespace>.<name>({...})`. Custom runtimes should expose equivalent namespaced calls through their own `formatCallable()` guidance.
 - `.arg()` and `.returns()` can use Ax field helpers or any Standard Schema v1 validator directly.
 
 ## Grouped Function Modules
@@ -235,6 +235,26 @@ const parent = agent('query:string -> answer:string', {
 });
 ```
 
+MCP clients and other `toFunction()` providers can be placed directly inside a group after initialization:
+
+```typescript
+await mcpClient.init();
+
+const parent = agent('query:string -> answer:string', {
+  functions: [
+    {
+      namespace: 'memory',
+      title: 'Memory MCP',
+      description: 'Memory server tools',
+      selectionCriteria: 'Use for persistent memory lookup and updates.',
+      functions: [mcpClient],
+    },
+  ],
+  functionDiscovery: true,
+  contextFields: [],
+});
+```
+
 Rules:
 
 - A group is `{ namespace, title, description, functions: [...] }`.
@@ -242,8 +262,8 @@ Rules:
 - The group's `namespace`, `title`, `selectionCriteria`, and `description` show up in `discover(...)` module docs.
 - Add `alwaysInclude: true` to a group when discovery mode is on but the actor should always see that group's full callable definitions inline in the prompt.
 - Keep `functions: [...]` either flat or grouped. Runtime validation rejects mixed plain function entries and group objects.
-- In flat mode, pass `fn(...)` tools and child agents directly.
-- In grouped mode, put callable entries inside groups. To expose a child agent inside a group, use `childAgent.getFunction()`.
+- In flat mode, pass `fn(...)` tools, child agents, and `toFunction()` providers directly.
+- In grouped mode, put callable entries and `toFunction()` providers inside groups. To expose a child agent inside a group, use `childAgent.getFunction()`.
 
 ## Host-Side Completion From Functions
 
@@ -279,7 +299,7 @@ Rules:
 
 - `extra.protocol` is only available when the function call comes from an active AxAgent actor runtime session.
 - Use `extra.protocol.final(...)`, `extra.protocol.askClarification(...)`, or `extra.protocol.guideAgent(...)` only inside host-side function handlers.
-- Inside actor-authored JavaScript, use the runtime globals `final(...)` and `askClarification(...)`.
+- Inside actor-authored runtime code, use the runtime globals `final(...)` and `askClarification(...)` with the syntax documented by the active runtime.
 - `extra.protocol.guideAgent(...)` is handler-only internal control flow. It stops the current actor turn and appends trusted guidance to `guidanceLog` for the next iteration.
 - `askClarification(...)` accepts either a simple string or a structured object with `question` plus optional UI hints such as `type: 'date' | 'number' | 'single_choice' | 'multiple_choice'` and `choices`.
 

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, batch audio with ai.transcribe() or ai.speak(), extended thinking, context caching, or mentions OpenAI/Anthropic/Google/Azure/Groq/DeepSeek/Mistral/Cohere/Together/Ollama/HuggingFace/Reka/OpenRouter with @ax-llm/ax.
-version: "21.0.14"
+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, batch audio with ai.transcribe() or ai.speak(), extended thinking, context caching, or mentions OpenAI/Anthropic/Google/Azure/DeepSeek/Mistral/Cohere/HuggingFace/Reka/Grok with @ax-llm/ax.
+version: "22.0.0"
 ---
 
 # AI Provider Codegen Rules (@ax-llm/ax)
@@ -17,16 +17,13 @@ const openai = ai({ name: 'openai', apiKey: 'sk-...' });
 const claude = ai({ name: 'anthropic', apiKey: 'sk-ant-...' });
 const gemini = ai({ name: 'google-gemini', apiKey: 'AIza...' });
 const azure = ai({ name: 'azure-openai', apiKey: 'your-key', resourceName: 'your-resource', deploymentName: 'gpt-4' });
-const groq = ai({ name: 'groq', apiKey: 'gsk_...' });
 const deepseek = ai({ name: 'deepseek', apiKey: 'sk-...' });
 const mistral = ai({ name: 'mistral', apiKey: 'your-key' });
 const cohere = ai({ name: 'cohere', apiKey: 'your-key' });
-const together = ai({ name: 'together', apiKey: 'your-key' });
-const openrouter = ai({ name: 'openrouter', apiKey: 'your-key' });
-const ollama = ai({ name: 'ollama', url: 'http://localhost:11434' });
 const hf = ai({ name: 'huggingface', apiKey: 'hf_...' });
 const reka = ai({ name: 'reka', apiKey: 'your-key' });
 const grok = ai({ name: 'grok', apiKey: 'your-key' });
+const compatible = ai({ name: 'openai', apiKey: 'key', apiURL: 'https://api.example.com/v1', config: { model: 'provider/model' } });
 ```
 
 ## Model Presets
@@ -64,7 +61,7 @@ Use `axGetSupportedAIModels()` to build provider/model selectors before creating
 
 Filter with `{ type: 'all' | 'text' | 'embeddings' | 'code' | 'audio' }` or an array of those values. The `'text'` filter includes code-capable models; use `'code'` to show only code-first models.
 
-Dynamic providers such as Azure OpenAI deployments, OpenRouter, Ollama, and Hugging Face are marked with `isDynamic: true` and may have an empty or static-limited model list.
+Dynamic providers such as Azure OpenAI deployments and Hugging Face are marked with `isDynamic: true` and may have an empty or static-limited model list.
 
 ## Chat
 
@@ -165,7 +162,7 @@ import { ai, AxAIAnthropicModel } from '@ax-llm/ax';
 const claude = ai({
   name: 'anthropic',
   apiKey: process.env.ANTHROPIC_APIKEY!,
-  config: { model: AxAIAnthropicModel.Claude46Opus },
+  config: { model: AxAIAnthropicModel.Claude48Opus },
 });
 
 const res = await claude.chat(
@@ -189,10 +186,27 @@ console.log(res.results[0]?.content);
 
 ### Anthropic Model-Specific Behavior
 
+- Opus 4.8 and 4.7: adaptive thinking, effort levels including `'xhigh'`,
+  no manual `budget_tokens`, and no `temperature` / `topP` / `topK`.
 - Opus 4.6: adaptive thinking, effort levels
 - Opus 4.5: budget_tokens + effort levels (capped at `'high'`)
 - Other thinking models: budget tokens only
 
+Anthropic `modelConfig.effort` can be set directly on a request. Fast mode and
+task budgets are Anthropic-only opt-ins; `taskBudget.total` must be at least
+20,000 tokens.
+
+```typescript
+const res = await claude.chat({
+  chatPrompt: [{ role: 'user', content: 'Review this migration plan.' }],
+  modelConfig: {
+    effort: 'xhigh',
+    speed: 'fast',
+    taskBudget: { type: 'tokens', total: 64_000 },
+  },
+});
+```
+
 ### Custom Thinking Levels
 
 ```typescript
@@ -200,7 +214,7 @@ const claude = ai({
   name: 'anthropic',
   apiKey: '...',
   config: {
-    model: AxAIAnthropicModel.Claude46Opus,
+    model: AxAIAnthropicModel.Claude48Opus,
     thinkingTokenBudgetLevels: {
       minimal: 2048,
       low: 8000,
@@ -300,8 +314,10 @@ const client = new AxMCPClient(transport);
 ## Critical Rules
 
 - Use `ai()` factory for all providers.
-- Provider names: `'openai'`, `'anthropic'`, `'google-gemini'`, `'azure-openai'`, `'mistral'`, `'groq'`, `'cohere'`, `'together'`, `'deepseek'`, `'ollama'`, `'huggingface'`, `'openrouter'`, `'reka'`, `'grok'`
-- Thinking constraints on Anthropic: `temperature` and `topK` are ignored; `topP` only sent if >= 0.95.
+- Provider names: `'openai'`, `'openai-responses'`, `'anthropic'`, `'google-gemini'`, `'azure-openai'`, `'mistral'`, `'cohere'`, `'deepseek'`, `'huggingface'`, `'reka'`, `'grok'`
+- Thinking constraints on Anthropic: Opus 4.8/4.7 omit `temperature`, `topP`,
+  and `topK`; older thinking models ignore `temperature` and `topK`, with
+  `topP` only sent if >= 0.95.
 - Bedrock uses `new AxAIBedrock()`, not `ai()`.
 - Vercel AI SDK uses `AxAIProvider` wrapper.
 
@@ -319,7 +335,7 @@ Fetch these for full working code:
 - [Gemini Context Cache](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/gemini-context-cache.ts) — Gemini context caching
 - [Gemini Files](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/gemini-file-support.ts) — Gemini file handling
 - [Grok Live Search](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/grok-live-search.ts) — Grok live search
-- [OpenRouter](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/openrouter.ts) — OpenRouter provider
+- [OpenAI-Compatible](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/openai-compatible.ts) — custom OpenAI-compatible base URL
 - [Vertex AI Auth](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/vertex-auth-example.ts) — Vertex AI authentication
 - [MCP Stdio](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/mcp-client-memory.ts) — MCP stdio transport
 - [MCP HTTP](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/mcp-client-pipedream.ts) — MCP HTTP transport

package/skills/ax-audio.md

@@ -1,7 +1,7 @@
 ---
 name: ax-audio
 description: This skill helps an LLM generate correct audio code with @ax-llm/ax. Use when the user asks about ai.transcribe(), ai.speak(), signature audio inputs or outputs, agent audio behavior, .chat() conversational audio, OpenAI audio or realtime models, Gemini Live native audio, Grok Voice Agent models, voices, formats, transcripts, or how audio fits with structured outputs.
-version: "21.0.14"
+version: "22.0.0"
 ---
 
 # Audio I/O 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: "21.0.14"
+version: "22.0.0"
 ---
 
 # AxFlow Codegen Rules (@ax-llm/ax)
@@ -12,7 +12,7 @@ Use this skill to generate `AxFlow` workflow code. Prefer short, modern, copyabl
 
 - Use `flow()` factory, not `new AxFlow()`.
 - Import: `import { ai, flow, f } from '@ax-llm/ax';`
-- `autoParallel: true` is the default; independent executes run in parallel automatically.
+- `autoParallel: true` is the default; independent executes and derives run in parallel when their metadata reads/writes are known and non-conflicting.
 - Node results are stored as `${nodeName}Result` in state.
 - Always define `.node()` before `.execute()` for that node.
 - Use `.returns()` (or `.r()`) as the last step to lock the output type.
@@ -28,7 +28,7 @@ Use this skill to generate `AxFlow` workflow code. Prefer short, modern, copyabl
 - Always define nodes before executing them; reversed order throws at runtime.
 - Keep state flat; avoid deep nesting in `.map()`.
 - Ensure loop conditions can change to avoid infinite loops.
-- Structure independent executes to maximize auto-parallelization.
+- Structure independent executes to maximize safe auto-parallelization.
 - Use `flow<InputType, OutputType>()` for typed flows.
 - Aliases: `.n()` = `.node()`, `.nx()` = `.nodeExtended()`, `.m()` = `.map()`, `.r()` = `.returns()`.
 
@@ -174,7 +174,7 @@ const wf = flow<{ input: string }, { finalResult: string }>()
 
 ## Auto-Parallel Execution
 
-Independent executes run in parallel automatically (`autoParallel: true` by default):
+Independent execute steps run in parallel automatically (`autoParallel: true` by default) when their metadata reads/writes are known and non-conflicting:
 
 ```typescript
 const wf = flow<{ text: string }, { combined: string }>()
@@ -199,6 +199,12 @@ const plan = wf.getExecutionPlan();
 console.log(plan.parallelGroups, plan.maxParallelism);
 ```
 
+Planner rules:
+- Independent `.execute()` and `.derive()` steps may parallelize.
+- `.map()`, `.returns()`, `.branch()`, `.while()`, `.feedback()`, and explicit `.parallel()` are barriers.
+- Branch, while, and feedback bodies still use the same planner internally.
+- Use `autoParallel: false` when you need strict sequential execution.
+
 Disable auto-parallel:
 
 ```typescript
@@ -299,7 +305,7 @@ const wf = flow<{ items: string[] }, { processed: string[] }>({ batchSize: 3 })
 Route nodes to different AI providers:
 
 ```typescript
-const fast = ai({ name: 'groq', apiKey: '...' });
+const fast = ai({ name: 'openai', apiKey: '...', config: { model: 'gpt-5-mini' } });
 const smart = ai({ name: 'anthropic', apiKey: '...' });
 
 const wf = flow<{ text: string }, { out: string }>()
@@ -425,6 +431,8 @@ Fetch these for full working code:
 
 - Do not use `new AxFlow(...)` for new code.
 - Do not execute a node before defining it with `.node()`.
+- Do not use removed terminal shapers like `.mapOutput()` or `.mo()`.
+- Do not rely on broad signature inference from arbitrary transform source. Use explicit input/output generics and `.returns()` for the final output contract.
 - Do not use generic field names like `text`, `result`, `data`, `input`, `output`.
 - Do not create deep-nested state objects in `.map()`.
 - Do not create loop conditions that can never change.

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: "21.0.14"
+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(), validation, streaming guards, field processors, step hooks, self-tuning, or structured outputs.
+version: "22.0.0"
 ---
 
 # AxGen Codegen Rules (@ax-llm/ax)
@@ -13,7 +13,9 @@ Use this skill to generate `AxGen` code. Prefer short, modern, copyable patterns
 - Use `ax(...)` factory, not `new AxGen(...)`.
 - Always pass an AI instance from `ai(...)` as the first argument to `forward()`.
 - Streaming uses `streamingForward()`, not `forward()` with a stream option.
-- Assertions auto-retry with error feedback on failure.
+- Use schema validation for field shape and constraints.
+- Use `bestOfN(...)` / `refine(...)` for reward-scored complete outputs.
+- Streaming guards abort unsafe partial output; they do not retry or refine.
 - Step hook mutations are applied at the next step boundary (pending pattern).
 - `stopFunction` accepts a string or string[] for multiple stop functions.
 - Multi-step continues until: all outputs filled, stop function called, or `maxSteps` reached.
@@ -173,18 +175,29 @@ Rules:
 - `abortSignal` cancels the underlying AI service call immediately.
 - Catch `AxAIServiceAbortedError` when using either mechanism.
 
-## Assertions And Validation
+## Validation, Selection, And Guards
 
 ```typescript
-// Standard assertion (checked after forward completes)
-gen.addAssert(
-  (args) => args.output.length > 50,
-  'Output must be at least 50 characters'
+import { ax, bestOfN, f } from '@ax-llm/ax';
+import { z } from 'zod';
+
+// Schema validation: output shape and field validity.
+const gen = ax(
+  f()
+    .input('topic', z.string().min(1))
+    .output('summary', z.string().min(50))
+    .build()
 );
 
-// Streaming assertion (checked during streaming)
-gen.addStreamingAssert(
-  'output',
+// bestOfN: choose the best complete candidate.
+const selected = bestOfN(gen, {
+  n: 4,
+  rewardFn: ({ prediction }) => prediction.summary.length,
+});
+
+// Streaming guards: fail fast on unsafe partial output.
+gen.addStreamingGuard(
+  'summary',
   (text) => !text.includes('forbidden'),
   'Output contains forbidden text'
 );
@@ -192,9 +205,12 @@ gen.addStreamingAssert(
 
 Rules:
 
-- Failed assertions cause an automatic retry with the error message fed back to the LLM.
-- `addAssert` receives the full output object.
-- `addStreamingAssert` targets a specific field and receives the partial text so far.
+- Schema validation retries with parser/constraint feedback.
+- `bestOfN(...)` scores complete candidates and returns the highest reward or first threshold hit.
+- `refine(...)` runs rounds and can feed reward-derived advice into instruction components between rounds.
+- `addStreamingGuard(...)` targets a string/code output field and receives partial text so far.
+- Streaming guards only abort the stream by throwing `AxStreamingGuardError`.
+- Breaking migration: do not generate removed `addAssert(...)` or `addStreamingAssert(...)` APIs.
 
 ## Field Processors
 
@@ -452,9 +468,10 @@ gen.resetUsage();
 
 Fetch these for full working code:
 
-- [Streaming](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/streaming.ts) — streaming with assertions
-- [Assertions](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/asserts.ts) — output validation
-- [Streaming Assertions](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/streaming-asserts.ts) — streaming with assertion checks
+- [Streaming](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/streaming.ts) — field-by-field streaming
+- [Best Of N](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/best-of-n.ts) — reward-scored sample selection
+- [Refine](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/refine.ts) — retry rounds with generated feedback
+- [Streaming Guard](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/streaming-guard.ts) — fail-fast partial-output safety
 - [Structured Output](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/structured_output.ts) — fluent API with validation
 - [Debug Logging](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/debug-logging.ts) — debug mode and step hooks
 - [Stop Function](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/stop-function.ts) — stop functions
@@ -467,6 +484,6 @@ Fetch these for full working code:
 - Do not use `new AxGen(...)` for new code unless explicitly required.
 - Do not pass raw API keys or config objects where an `ai(...)` instance is expected.
 - Do not use `forward()` for streaming; use `streamingForward()`.
-- Do not forget that assertions auto-retry; avoid manual retry loops around assertion logic.
+- Do not use streaming guards as retry/refine mechanisms; they only abort unsafe partial output.
 - Do not mutate step hook context expecting immediate effect; mutations are pending until the next step.
 - Do not assume multi-step stops after one LLM call; it continues until outputs are filled, a stop function fires, or `maxSteps` is reached.

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: "21.0.14"
+version: "22.0.0"
 ---
 
 # AxGEPA Codegen Rules (@ax-llm/ax)

package/skills/ax-llm.md

@@ -1,20 +1,20 @@
 ---
 name: ax-llm
 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: "21.0.14"
+version: "22.0.0"
 ---
 
 # Ax Library (@ax-llm/ax) Quick Reference
 
 Ax is a TypeScript library for building LLM-powered applications with type-safe signatures, streaming support, and multi-provider compatibility.
 
-> **Detailed skills available:** ax-ai (providers), ax-signature (signatures/types), ax-gen (generators), ax-agent (core agents/tools), ax-agent-rlm (agent runtime/RLM/delegation), ax-agent-observability (callbacks/logs/usage), ax-agent-memory-skills (recall and dynamic skill loading), ax-agent-optimize (agent tuning/eval), ax-flow (workflows), ax-gepa (Pareto optimization), ax-learn (self-improving agents).
+> **Detailed skills available:** ax-ai (providers), ax-signature (signatures/types), ax-gen (generators), ax-agent (core agents/tools), ax-agent-rlm (agent runtime/RLM/delegation), ax-agent-observability (callbacks/logs/usage), ax-agent-memory-skills (recall and dynamic skill loading), ax-agent-optimize (agent tuning/eval), ax-flow (workflows), ax-gepa (Pareto optimization).
 
 ## Imports & Factories
 
 ```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 { ax, ai, f, s, fn, agent, flow, AxMemory, AxMCPClient } from '@ax-llm/ax';
 import { z } from 'zod'; // optional — any Standard Schema v1 library works
 
 // AI provider
@@ -239,7 +239,7 @@ axGlobals.meter = openTelemetryMeter;
 ## MCP Integration
 
 ```typescript
-import { AxMCPClient } from '@ax-llm/ax';
+import { AxMCPClient, agent } from '@ax-llm/ax';
 import { AxMCPStdioTransport } from '@ax-llm/ax-tools';
 
 // Stdio transport (local MCP server)
@@ -251,11 +251,19 @@ const transport = new AxMCPStdioTransport({
 const mcpClient = new AxMCPClient(transport, { debug: false });
 await mcpClient.init();
 
-// Use with agent
+// Use with agent under a namespace
 const myAgent = agent('userMessage:string -> response:string', {
-  name: 'assistant',
-  description: 'An assistant with MCP tools',
-  functions: [mcpClient],
+  functions: [
+    {
+      namespace: 'memory',
+      title: 'Memory MCP',
+      description: 'Memory server tools',
+      selectionCriteria: 'Use for persistent memory lookup and updates.',
+      functions: [mcpClient],
+    },
+  ],
+  functionDiscovery: true,
+  contextFields: [],
 });
 ```
 
@@ -300,7 +308,7 @@ class AxGen<IN, OUT> {
   forward(ai: AxAIService, values: IN, options?: AxProgramForwardOptions): Promise<OUT>;
   streamingForward(ai: AxAIService, values: IN, options?: AxProgramStreamingForwardOptions): AsyncGenerator<{ delta: Partial<OUT> }>;
   setExamples(examples: Array<Partial<IN & OUT>>): void;
-  addAssert(fn: (output: OUT) => boolean, message?: string): void;
+  addStreamingGuard(field: keyof OUT, fn: (chunk: string, done?: boolean) => boolean | string | undefined, message?: string): void;
   addFieldProcessor(field: keyof OUT, fn: (value: any) => any): void;
   addStreamingFieldProcessor(field: keyof OUT, fn: (chunk: string, ctx: any) => void): void;
   stop(): void;