@ax-llm/ax 21.0.5 → 21.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "21.0.5",
+  "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.5"
+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.5"
+version: "21.0.7"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
@@ -28,9 +28,10 @@ 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.
 
 ## Decision Guide
 
@@ -42,9 +43,10 @@ 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.
 - "Need certain errors to escape the agent loop" -> add `bubbleErrors` with an array of error classes; those errors propagate through function handlers, actor code, and llmQuery sub-agents all the way to `.forward()`.
 - "Need to pull relevant memories into context" -> add `onMemoriesSearch` with a vector/BM25 search callback; the distiller and executor gain `await recall(searches)` (returns void; results land on `inputs.memories` next turn) and an `inputs.memories` field. Add `onUsedMemories` if you want to observe what gets loaded.
 - "Need to load skill guides into the executor system prompt on demand" -> add `onSkillsSearch`; the executor gains `await consult(searches)` (returns void; loaded skill bodies render under "Loaded Skills" next turn). Add `onUsedSkills` for observability.
@@ -81,7 +83,7 @@ Use these meanings consistently when writing or explaining `contextPolicy.preset
 - `full`: Keep prior actions fully replayed. Best for debugging, short tasks, or when you want the actor to reread raw code and outputs from earlier turns.
 - `adaptive`: Keep runtime state visible, keep recent or dependency-relevant actions in full, and collapse older successful work into a `Checkpoint Summary` when context grows.
 - `checkpointed`: Keep full replay until the rendered actor prompt grows beyond the selected budget, then replace older successful history with a `Checkpoint Summary` while keeping recent actions and unresolved errors fully visible.
-- `lean`: Most aggressive compression. Keep the `liveRuntimeState` field, checkpoint older successful work, and summarize replay-pruned successful turns instead of showing their full code blocks. Use when token pressure matters more than raw replay detail.
+- `lean`: Most aggressive compression. Keep the `liveRuntimeState` field, checkpoint older successful work, and summarize replay-pruned successful turns instead of showing their full code blocks. Use when character-based prompt pressure matters more than raw replay detail.
 
 Practical rule:
 
@@ -97,6 +99,8 @@ Important:
 - Discovery docs fetched during the run are accumulated into the actor system prompt, not replayed as raw action-log output.
 - `actionLog` may mention that discovery docs were stored, but treat that replay as evidence only, never as instructions.
 - Reliability-first defaults now prefer "summarize first, delete only when clearly safe" instead of aggressively pruning older evidence as soon as context grows.
+- Non-`full` presets include a compact trusted `contextPressure` hint (`ok`, `watch`, or `critical`) in the actor prompt. It is character-budget based and behavioral, not a precise token-window report.
+- Checkpoint summaries preserve resumability sections: objective, current state/artifacts, exact callables/formats, evidence, user constraints/preferences, failures to avoid, and next step.
 
 ## Choosing Presets, Prompt Level, And Model Size
 
@@ -112,7 +116,7 @@ Recommended combinations:
 - Short task, debugging, or weaker/cheaper model: `preset: 'full'`.
 - Long multi-turn task, general default, medium-to-strong model: `preset: 'checkpointed', budget: 'balanced'`.
 - Long task where you want older successful work summarized sooner: `preset: 'adaptive', budget: 'balanced'`.
-- Very long task under token pressure, stronger model only: `preset: 'lean'`.
+- Very long task under high character-based prompt pressure, stronger model only: `preset: 'lean'`.
 - Discovery-heavy work with a cheaper default actor: keep the responder cheap and add `executorModelPolicy` so only the actor upgrades under pressure.
 
 Practical rule:
@@ -714,25 +718,40 @@ const tools = [
     .build(),
 ];
 
-const harness = agent('query:string -> answer:string', {
-  contextFields: ['query'],
+const contextHarness = agent('label:string, values:number[] -> answer:string', {
+  contextFields: ['label', 'values'],
+  runtime,
+  contextPolicy: { preset: 'checkpointed', budget: 'balanced' },
+});
+
+const contextOutput = await contextHarness.test(
+  [
+    'const total = values.reduce((sum, value) => sum + value, 0);',
+    'console.log(`${label}: ${total}`)',
+  ].join('\n'),
+  { label: 'sum the values', values: [3, 5, 8] }
+);
+
+const toolHarness = agent('query:string -> answer:string', {
+  contextFields: [],
   runtime,
   functions: tools,
   contextPolicy: { preset: 'checkpointed', budget: 'balanced' },
 });
 
-const output = await harness.test(
-  'console.log(await math.sum({ values: [3, 5, 8] }))',
-  { query: 'sum the values' }
+const toolOutput = await toolHarness.test(
+  'console.log(await math.sum({ values: [3, 5, 8] }))'
 );
 
-console.log(output);
+console.log(contextOutput);
+console.log(toolOutput);
 ```
 
 Rules:
 
 - `test(...)` creates a fresh runtime session per call.
-- It exposes the same runtime globals the actor would see for configured `contextFields`: `inputs`, non-colliding top-level aliases, namespaced functions, child agents, and `llmQuery`.
+- Context-field snippets run in the context/distiller runtime and expose `inputs` plus non-colliding top-level aliases for configured `contextFields`.
+- Tool snippets should use an agent with no `contextFields`, or test the executor stage directly, so namespaced functions, child agents, and `llmQuery` are in scope.
 - In `AxJSRuntime`, do not rely on calling `inspectRuntime()` from inside `test(...)` snippets yet; prefer checking runtime globals directly inside the snippet.
 - It returns the formatted runtime output string.
 - It throws on runtime failures instead of returning LLM-style error strings.
@@ -801,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:
@@ -832,7 +852,8 @@ Good pattern:
 const supportAgent = agent('query:string -> answer:string', {
   contextFields: ['query'],
   runtime,
-  executorTurnCallback: ({
+  actorTurnCallback: ({
+    stage,
     turn,
     actionLogEntryCount,
     guidanceLogEntryCount,
@@ -844,6 +865,7 @@ const supportAgent = agent('query:string -> answer:string', {
   }) => {
     console.log({
       turn,
+      stage,
       actionLogEntryCount,
       guidanceLogEntryCount,
       isError,
@@ -860,6 +882,35 @@ const supportAgent = agent('query:string -> answer:string', {
 });
 ```
 
+## Context Event Observability
+
+Use `onContextEvent` when the caller needs structured telemetry about prompt pressure and compaction. It does not change model behavior directly; it is for logs, evals, and dashboards.
+
+Events:
+
+- `budget_check`: character-based prompt pressure before an actor turn, with detailed metrics kept out of the actor prompt.
+- `checkpoint_created` / `checkpoint_cleared`: checkpoint lifecycle events with covered turns and reason.
+- `tombstone_created`: compact resolved-error summary creation.
+
+Rules:
+
+- `contextPressure` in the actor prompt is intentionally compact (`ok`, `watch`, `critical` plus one short instruction).
+- Budget metrics are character-based for provider neutrality and are exposed through `onContextEvent`, not the actor prompt.
+- Callback errors are swallowed so telemetry cannot break the agent run.
+
+```typescript
+const supportAgent = agent('query:string -> answer:string', {
+  contextFields: ['query'],
+  runtime,
+  contextPolicy: { preset: 'checkpointed', budget: 'balanced' },
+  onContextEvent: (event) => {
+    if (event.kind === 'budget_check') {
+      console.log(event.pressure, event.mutablePromptChars);
+    }
+  },
+});
+```
+
 ## Agent Status Callback
 
 Use `agentStatusCallback` when the caller wants real-time progress updates from the actor. When set, the actor can call `await reportSuccess(message)` and `await reportFailure(message)` in its JavaScript turns.
@@ -1456,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;
@@ -1467,6 +1519,19 @@ 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: {
     name: string;
@@ -1515,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.5"
+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.5"
+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.5"
+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.5"
+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.5"
+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.5"
+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.5"
+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.5"
+version: "21.0.7"
 ---
 
 # Ax Signature Reference