@ax-llm/ax 21.0.6 → 21.0.7

package/package.json

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

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: "21.0.6"
+version: "21.0.7"
 ---
 
 # 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: "21.0.6"
+version: "21.0.7"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
@@ -28,7 +28,7 @@ Your job is not just to write valid code. Your job is to choose the smallest cor
 - Default to `contextPolicy: { preset: 'checkpointed', budget: 'balanced' }` for most RLM tasks.
 - Prefer `contextPolicy: { preset: 'adaptive', budget: 'balanced' }` when older successful turns should collapse sooner while live runtime state stays visible.
 - Prefer `executorModelPolicy` when the actor may need to upgrade after repeated error turns or discovery in specific namespaces without also upgrading the responder.
-- Use `executorTurnCallback` when the user needs per-turn observability into generated code, raw runtime result, formatted output, or provider thoughts.
+- Use `actorTurnCallback` when the user needs per-turn observability into generated code, raw runtime result, formatted output, provider thoughts, or the actor stage (`distiller` vs `executor`). `executorTurnCallback` is the deprecated alias.
 - Use `agentStatusCallback` when the user wants real-time task progress updates from the actor via `await reportSuccess(message)` and `await reportFailure(message)` calls.
 - Use `onFunctionCall` when the user wants to observe every function the actor invokes from the JS runtime (their own registered functions plus internal globals like child agents, `discoverModules`, `discoverFunctions`, `consult`).
 - Use `onContextEvent` when the caller needs context-pressure and compaction telemetry (`budget_check`, `checkpoint_created`, `checkpoint_cleared`, `tombstone_created`); callback failures are ignored.
@@ -43,7 +43,7 @@ Map user intent to agent shape before writing code:
 - "Need child agents with distinct responsibilities" -> add the child agents to the parent's `functions: [...]` list. Set `agentIdentity.namespace` on each child to control where it lands in the JS runtime (e.g. `team.writer(...)`); otherwise it lands under `utils.<name>` like any other tool.
 - "Need tool discovery because names/schemas are not stable" -> use `functions.discovery: true` and generate discovery-first code.
 - "Need a stronger actor only when the run gets noisy or large" -> use `executorModelPolicy` and keep the responder model separate.
-- "Need debugging or traceability" -> start with `debug: true` or `executorTurnCallback`; do not add both unless the user clearly wants both prompt/runtime visibility and structured telemetry.
+- "Need debugging or traceability" -> start with `debug: true` or `actorTurnCallback`; do not add both unless the user clearly wants both prompt/runtime visibility and structured telemetry.
 - "Need real-time progress updates" -> add `agentStatusCallback` so the actor can call `await reportSuccess(message)` and `await reportFailure(message)` to report sub-task progress.
 - "Need to log/trace every tool call" -> add `onFunctionCall` to receive `{ name, qualifiedName, args, kind }` for each function invoked by the runtime; `kind` is `'external'` for caller-registered functions and `'internal'` for agent-injected ones (child agents, discovery, skills loader).
 - "Need to observe compaction or prompt pressure" -> add `onContextEvent`; do not scrape actor prompts for pressure metrics.
@@ -820,15 +820,16 @@ await final("Summarize the severity-related snippets found", { snippets });
 
 ## Actor Turn Observability
 
-Use `executorTurnCallback` when the caller needs structured telemetry for each actor turn.
+Use `actorTurnCallback` when the caller needs structured telemetry for each actor turn. `executorTurnCallback` is still accepted as a deprecated alias for older code.
 
 What it gives you:
 
 - `code`: the normalized JavaScript code the actor produced
+- `stage`: which actor produced the turn (`distiller` or `executor`)
 - `result`: the raw untruncated runtime return value from executing that code
 - `output`: the formatted action-log output string after Ax normalizes and truncates it for prompt replay
 - `thought`: the actor model's `thought` field when `showThoughts` is enabled and the provider returns one
-- `executorResult`: the full actor payload returned by the executor stage
+- `executorResult`: the full actor payload returned by the current actor stage (kept under this historical field name for compatibility)
 - `isError`: whether the execution path for that turn was treated as an error
 
 Use it for:
@@ -851,7 +852,8 @@ Good pattern:
 const supportAgent = agent('query:string -> answer:string', {
   contextFields: ['query'],
   runtime,
-  executorTurnCallback: ({
+  actorTurnCallback: ({
+    stage,
     turn,
     actionLogEntryCount,
     guidanceLogEntryCount,
@@ -863,6 +865,7 @@ const supportAgent = agent('query:string -> answer:string', {
   }) => {
     console.log({
       turn,
+      stage,
       actionLogEntryCount,
       guidanceLogEntryCount,
       isError,
@@ -1504,7 +1507,8 @@ Use `promptMaxChars` when partial data is worse than no data (e.g. JSON objects)
   maxRuntimeChars?: number;
   contextPolicy?: AxContextPolicyConfig;
   summarizerOptions?: Omit<AxProgramForwardOptions<string>, 'functions'>;
-  executorTurnCallback?: (turn: {
+  actorTurnCallback?: (turn: {
+    stage: 'distiller' | 'executor';
     turn: number;
     actionLogEntryCount: number;
     guidanceLogEntryCount: number;
@@ -1515,6 +1519,18 @@ Use `promptMaxChars` when partial data is worse than no data (e.g. JSON objects)
     isError: boolean;
     thought?: string;
   }) => void | Promise<void>;
+  executorTurnCallback?: (turn: {
+    stage: 'distiller' | 'executor';
+    turn: number;
+    actionLogEntryCount: number;
+    guidanceLogEntryCount: number;
+    executorResult: Record<string, unknown>;
+    code: string;
+    result: unknown;
+    output: string;
+    isError: boolean;
+    thought?: string;
+  }) => void | Promise<void>; // deprecated alias; use actorTurnCallback
   onContextEvent?: (event: AxAgentContextEvent) => void | Promise<void>;
   inputUpdateCallback?: (currentInputs: Record<string, unknown>) => Promise<Record<string, unknown> | undefined> | Record<string, unknown> | undefined;
   onFunctionCall?: (call: {
@@ -1564,7 +1580,7 @@ Use `promptMaxChars` when partial data is worse than no data (e.g. JSON objects)
 }
 ```
 
-- `executorTurnCallback` fires for the root agent and for recursive child agents that run actor turns.
+- `actorTurnCallback` fires for the root agent and for recursive child agents that run actor turns.
 - `executorModelPolicy` applies to the actor loop and can be inherited by recursive child agents unless you override it there.
 - `namespaces` matches exact discovery namespaces from successful `discoverFunctions(...)` lookups and starts affecting model choice on the next actor turn.
 - Consecutive error turns reset after a successful non-error turn and when checkpoint summarization refreshes to a new fingerprint.

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: "21.0.6"
+version: "21.0.7"
 ---
 
 # AI Provider Codegen Rules (@ax-llm/ax)

package/skills/ax-audio.md

@@ -1,7 +1,7 @@
 ---
 name: ax-audio
 description: This skill helps an LLM generate correct conversational audio I/O code with @ax-llm/ax. Use when the user asks about .chat() audio input, audio output, OpenAI gpt-audio or realtime models, Gemini Live native audio, Grok Voice Agent models, voices, formats, transcripts, or how audio fits with signatures and structured outputs.
-version: "21.0.6"
+version: "21.0.7"
 ---
 
 # 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.6"
+version: "21.0.7"
 ---
 
 # 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: "21.0.6"
+version: "21.0.7"
 ---
 
 # AxGen Codegen Rules (@ax-llm/ax)

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.6"
+version: "21.0.7"
 ---
 
 # 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: "21.0.6"
+version: "21.0.7"
 ---
 
 # AxLearn Codegen Rules (@ax-llm/ax)

package/skills/ax-llm.md

@@ -1,7 +1,7 @@
 ---
 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.6"
+version: "21.0.7"
 ---
 
 # Ax Library (@ax-llm/ax) Quick Reference

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: "21.0.6"
+version: "21.0.7"
 ---
 
 # Ax Signature Reference