@ax-llm/ax 19.0.19 → 19.0.21

package/package.json

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

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, or offline tuning with agent.optimize(...).
-version: "19.0.19"
+version: "19.0.21"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
@@ -18,6 +18,8 @@ Use this skill to generate `AxAgent` code. Prefer short, modern, copyable patter
 - If `functions.discovery` is `true`, discover callables from modules before using them.
 - In stdout-mode RLM, use one observable `console.log(...)` step per non-final actor turn.
 - For long RLM tasks, prefer `contextPolicy: { preset: 'adaptive' }` so older successful turns collapse into checkpoint summaries while live runtime state stays visible.
+- Default `actorOptions.promptLevel` to `'detailed'` and opt down to `'basic'` only when the user wants a shorter actor prompt.
+- Use `actorTurnCallback` when the user needs per-turn observability into generated code, raw runtime result, formatted output, or provider thoughts.
 
 ## Mental Model
 
@@ -46,9 +48,51 @@ Important:
 
 - `contextPolicy` controls prompt replay and compression, not runtime persistence.
 - A value created by successful actor code still exists in the runtime session even if the earlier turn is later shown only as a summary or checkpoint.
-- Used discovery docs are replay artifacts too: `adaptive` and `lean` can hide old `listModuleFunctions(...)` / `getFunctionDefinitions(...)` output after the actor successfully uses the discovered callable.
+- Used discovery docs are replay artifacts too: `lean` hides old `listModuleFunctions(...)` / `getFunctionDefinitions(...)` output by default after the actor successfully uses the discovered callable, while `adaptive` keeps them unless you opt into pruning.
 - Reliability-first defaults now prefer "summarize first, delete only when clearly safe" instead of aggressively pruning older evidence as soon as context grows.
 
+## Choosing Presets, Prompt Level, And Model Size
+
+Treat these three knobs as a bundle:
+
+- `contextPolicy.preset` decides how much raw history the actor keeps seeing.
+- `actorOptions.promptLevel` decides how prescriptive the actor prompt is.
+- Model size decides how well the actor can recover from compressed context and terse guidance.
+
+Recommended combinations:
+
+- Short task, debugging, or weaker/cheaper model: `preset: 'full'` with `promptLevel: 'detailed'`.
+- Long multi-turn task, general default, medium-to-strong model: `preset: 'adaptive'` with `promptLevel: 'detailed'`.
+- Long task where the actor keeps making avoidable exploration mistakes: `preset: 'adaptive'` with `promptLevel: 'detailed'`.
+- Very long task under token pressure, stronger model only: `preset: 'lean'` with `promptLevel: 'basic'`.
+- Discovery-heavy or schema-uncertain work with a capable model: `preset: 'adaptive'` with `promptLevel: 'detailed'`.
+
+Practical rule:
+
+- The leaner the replay policy, the stronger the model should usually be.
+- `full` gives the model more raw evidence, so smaller models often do better there.
+- `adaptive` is the default middle ground for real agent work.
+- `lean` should be reserved for models that can reason well from runtime state plus summaries instead of exact old code/output.
+- `detailed` is not automatically "better"; it is more controlling. Use it when the actor needs tighter exploration rhythm, not just because the task is hard.
+
+Prompt-level guidance:
+
+- `basic`: opt-down mode. Gives the actor concise exploration guidance and works best when the model is already reliable.
+- `detailed`: adds explicit exploration recipes, truncation recovery guidance, error-avoidance tips, and stronger one-step-per-turn discipline.
+
+Use `promptLevel: 'detailed'` when:
+
+- the actor is probing unfamiliar or messy data shapes
+- discovery mode is central to the task
+- the model keeps over-logging, combining too many steps, or guessing field/function names
+- you are optimizing for reliability over prompt compactness
+
+Use `promptLevel: 'basic'` when:
+
+- the model is already following the one-step rhythm well
+- you want a shorter actor prompt
+- the task is straightforward and the runtime/state carries most of the complexity
+
 ## Critical Rules
 
 - Use `agent(...)` factory syntax for new code.
@@ -527,9 +571,11 @@ Rules:
 - Use `preset: 'full'` when the actor should keep seeing raw prior code and outputs with minimal compression.
 - Use `preset: 'adaptive'` when the task needs runtime state across many turns but older successful work should collapse into checkpoint summaries while important recent steps can still stay fully replayed.
 - Use `preset: 'lean'` when you want more aggressive compression and can rely mostly on current runtime state plus checkpoint summaries and compact action summaries.
+- `adaptive` now keeps used discovery docs by default and uses slightly richer live-state/checkpoint settings than `lean`; it should be the first choice unless you have a strong reason to prefer `full` or `lean`.
 - Use `state.summary` to inject a compact `Live Runtime State` block into the actor prompt. The block is structured and provenance-aware: variables are rendered with compact type/size/preview metadata, and when Ax can infer it, a short source suffix like `from t3 via db.search` is included. Combine `maxEntries` with `maxChars` so large runtime objects do not dominate the prompt.
 - Use `state.inspect` with `inspectThresholdChars` so the actor is reminded to call `inspect_runtime()` when replayed action history starts getting large.
-- `adaptive` and `lean` hide used discovery docs by default; set `contextPolicy.pruneUsedDocs: false` if you want to keep replaying them.
+- `adaptive` keeps used discovery docs by default; set `contextPolicy.pruneUsedDocs: true` only when you want more aggressive cleanup.
+- `lean` hides used discovery docs by default; set `contextPolicy.pruneUsedDocs: false` if you want to keep replaying them.
 - `full` keeps used discovery docs by default; set `contextPolicy.pruneUsedDocs: true` if you want the same cleanup there.
 - Use `summarizerOptions` to tune the internal checkpoint-summary AxGen program.
 - If you configure `expert.tombstones`, treat the object form as options for the internal tombstone-summary AxGen program.
@@ -559,6 +605,88 @@ Turn 3:
 final({ answer: '...' });
 ```
 
+## Actor Turn Observability
+
+Use `actorTurnCallback` when the caller needs structured telemetry for each actor turn.
+
+What it gives you:
+
+- `code`: the normalized JavaScript code the actor produced
+- `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
+- `actorResult`: the full actor payload, including actor-owned output fields when `actorFields` are configured
+- `isError`: whether the execution path for that turn was treated as an error
+
+Use it for:
+
+- debug UIs that want to show code plus raw runtime results
+- tracing and analytics
+- capturing `thought` for internal diagnostics when supported by the provider
+- storing per-turn execution artifacts without scraping the prompt/action log
+
+Important:
+
+- `output` is not raw stdout; it is the formatted replay string used in the action log.
+- `result` is the raw runtime result before Ax formats/truncates it.
+- `thought` is optional and only appears when the underlying `AxGen` call had `showThoughts` enabled and the provider actually returned a thought field.
+
+Good pattern:
+
+```typescript
+const supportAgent = agent('query:string -> answer:string', {
+  contextFields: ['query'],
+  runtime,
+  actorTurnCallback: ({ turn, code, result, output, thought, isError }) => {
+    console.log({
+      turn,
+      isError,
+      code,
+      rawResult: result,
+      replayOutput: output,
+      thought,
+    });
+  },
+  actorOptions: {
+    model: 'gpt-5.4-mini',
+    showThoughts: true,
+  },
+});
+```
+
+## Actor Prompt Controls
+
+Use `actorOptions` for actor-only model/prompt tuning and `responderOptions` for responder-only tuning.
+
+Key fields:
+
+- `actorOptions.description`: append extra actor-specific instructions without changing the responder prompt
+- `actorOptions.promptLevel`: choose `'basic'` or `'detailed'` guidance for the actor template
+- `actorOptions.model` / `responderOptions.model`: split model choice across actor and responder when needed
+
+Good split-model pattern:
+
+```typescript
+const researchAgent = agent('query:string -> answer:string', {
+  contextFields: ['query'],
+  runtime,
+  contextPolicy: { preset: 'adaptive' },
+  actorOptions: {
+    model: 'gpt-5.4',
+    promptLevel: 'detailed',
+  },
+  responderOptions: {
+    model: 'gpt-5.4-mini',
+  },
+});
+```
+
+Model guidance:
+
+- Put the stronger model on the actor when the task depends on multi-turn exploration, discovery, runtime state reuse, or compressed replay.
+- Put the stronger model on the responder only when the hard part is final synthesis/formatting rather than exploration.
+- For cost-sensitive setups, a common pattern is stronger actor + cheaper responder, not the other way around.
+
 Invalid pattern:
 
 ```javascript
@@ -752,11 +880,25 @@ Rules:
 
 - `llmQuery(...)` forwards only the explicit `context` argument.
 - Parent inputs are not automatically available to `llmQuery(...)` children.
+- In `mode: 'simple'`, `llmQuery(...)` is a direct semantic helper.
+- In `mode: 'advanced'`, `llmQuery(...)` delegates a focused subtask to a child `AxAgent` with its own runtime and action log while recursion depth remains.
+- In advanced mode, no parent `contextFields` are auto-inserted into recursive children. Only explicit `llmQuery(..., context)` payload is available there.
+- If `context` is a plain object, safe keys are exposed as child runtime globals and the full payload is also available as `context`.
+- In advanced mode, use `llmQuery(...)` to offload discovery-heavy, tool-heavy, or multi-turn semantic branches so the parent action log stays smaller and more focused.
+- In advanced mode, use batched `llmQuery([...])` only for independent subtasks. Use serial calls when later work depends on earlier results.
+- In advanced mode, a good pattern is: parent does coarse discovery and JS narrowing, child `llmQuery(...)` calls handle focused branch analysis, then parent merges child outputs and finishes.
+- In advanced mode with `functions.discovery: true`, prefer putting noisy tool discovery, `getFunctionDefinitions(...)`, and branch-specific tool chatter inside delegated child calls when those branches are independent or semantically distinct.
+- In advanced mode, pass compact named object context to children instead of huge raw parent payloads. This makes the delegated prompt easier to follow and gives the child useful top-level globals.
+- In advanced mode, do not assume child-created variables, discovered docs, or action-log history come back to the parent. Only the child return value comes back.
+- In advanced mode, if a child calls `ask_clarification(...)`, that clarification bubbles up and ends the top-level run.
+- In advanced mode, recursion is depth-limited: `maxDepth: 0` makes top-level `llmQuery(...)` simple, `maxDepth: 1` makes top-level `llmQuery(...)` advanced and child `llmQuery(...)` simple.
+- In advanced mode, batched delegated children are cancelled when a sibling child asks for clarification or aborts, so use batched form only when those branches are truly independent.
+- `maxSubAgentCalls` is a shared budget across the whole top-level run, including recursive children.
 - Single-call `llmQuery(...)` may return `[ERROR] ...` on non-abort failures.
 - Batched `llmQuery([...])` returns per-item `[ERROR] ...`.
 - If a result starts with `[ERROR]`, inspect or branch on it instead of assuming success.
 
-Example:
+Minimal example:
 
 ```javascript
 const summary = await llmQuery('Summarize this incident', inputs.context);
@@ -767,6 +909,70 @@ if (summary.startsWith('[ERROR]')) {
 }
 ```
 
+Advanced recursive discovery example:
+
+```javascript
+const narrowedIncidents = incidents.map((incident) => ({
+  id: incident.id,
+  timeline: incident.timeline,
+  notes: incident.notes.slice(0, 1200),
+}));
+
+const [severityReview, followupReview] = await llmQuery([
+  {
+    query:
+      'Use discovery and available tools to review severity policy alignment. Return compact findings.',
+    context: {
+      incidents: narrowedIncidents,
+      rubric: 'severity-policy',
+    },
+  },
+  {
+    query:
+      'Use discovery and available tools to review postmortem and follow-up obligations. Return compact findings.',
+    context: {
+      incidents: narrowedIncidents,
+      rubric: 'postmortem-followup',
+    },
+  },
+]);
+
+const merged = await llmQuery(
+  'Merge these delegated reviews into one manager-ready summary with next steps.',
+  {
+    severityReview,
+    followupReview,
+    audience: inputs.audience,
+  }
+);
+```
+
+Delegation decision guide:
+
+- **JS-only** — deterministic logic (filter, sort, count, regex, date math) → do it inline, don't delegate.
+- **Single-shot semantic** — needs LLM reasoning but no tools or multi-step exploration → single `llmQuery` with narrow context.
+- **Full delegation** — needs its own discovery, tool calls, or >2 turns of exploratory work → `llmQuery` as child agent.
+- **Parallel fan-out** — 2+ independent subtasks each qualifying for delegation → batched `llmQuery([...])`.
+
+Context handling:
+
+- In advanced mode, the `context` object is injected into the child's JS runtime as named globals — it does NOT go into the child's LLM prompt. The child's prompt sees only a compact metadata summary (types, sizes, element keys) of the delegated context.
+- The child actor explores the delegated context with code, the same way the parent explores `inputs.*`.
+- Always narrow with JS before delegating — never pass raw `inputs.*`. Name context keys semantically (e.g. `{ emails: filtered, rubric: 'classify-urgency' }`).
+- Estimate total sub-agent calls before fanning out. `maxSubAgentCalls` is a shared budget across all recursion levels.
+
+Divide-and-conquer patterns:
+
+- **Fan-Out / Fan-In**: JS narrows into categories → `llmQuery([...])` fans out per category → JS or one more `llmQuery` merges results.
+- **Pipeline**: serial `llmQuery` calls where each depends on the prior result.
+- **Scout-then-Execute**: first child explores (e.g. check availability) → parent processes with JS → second child acts (e.g. draft invite).
+
+Notes:
+
+- Use these patterns when one task naturally splits into focused semantic branches with their own discovery or tool usage.
+- Keep the parent responsible for orchestration, cheap JS narrowing, and final assembly.
+- See `src/examples/rlm-discovery.ts` for the full recursive discovery demo.
+
 ## Short API Reference
 
 ### `agentIdentity`
@@ -817,18 +1023,29 @@ agentIdentity?: {
   maxTurns?: number;
   contextPolicy?: AxContextPolicyConfig;
   actorFields?: string[];
-  actorCallback?: (result: Record<string, unknown>) => void | Promise<void>;
+  actorTurnCallback?: (turn: {
+    turn: number;
+    actorResult: Record<string, unknown>;
+    code: string;
+    result: unknown;
+    output: string;
+    isError: boolean;
+    thought?: string;
+  }) => void | Promise<void>;
   inputUpdateCallback?: (currentInputs: Record<string, unknown>) => Promise<Record<string, unknown> | undefined> | Record<string, unknown> | undefined;
   mode?: 'simple' | 'advanced';
   recursionOptions?: Partial<Omit<AxProgramForwardOptions, 'functions'>> & {
     maxDepth?: number;
+    promptLevel?: 'detailed' | 'basic';
   };
-  actorOptions?: Partial<AxProgramForwardOptions & { description?: string }>;
+  actorOptions?: Partial<AxProgramForwardOptions & { description?: string; promptLevel?: 'detailed' | 'basic' }>;
   responderOptions?: Partial<AxProgramForwardOptions & { description?: string }>;
   judgeOptions?: Partial<AxJudgeOptions>;
 }
 ```
 
+- `actorTurnCallback` fires for the root agent and for recursive child agents that run actor turns.
+
 ## Examples
 
 Fetch these for full working code:
@@ -839,7 +1056,7 @@ Fetch these for full working code:
 - [Smart Home](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/smart-home.ts) — state management
 - [RLM](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm.ts) — RLM basic
 - [RLM Long Task](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-long-task.ts) — RLM context policy
-- [RLM Discovery](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-discovery.ts) — discovery mode
+- [RLM Discovery](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-discovery.ts) — advanced recursive `llmQuery` plus discovery-heavy delegated subtasks
 - [RLM Shared Fields](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-shared-fields.ts) — shared fields
 - [RLM Adaptive Replay](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-adaptive-replay.ts) — adaptive replay
 - [RLM Live Runtime State](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-live-runtime-state.ts) — structured runtime-state rendering

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.19"
+version: "19.0.21"
 ---
 
 # 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.19"
+version: "19.0.21"
 ---
 
 # 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.19"
+version: "19.0.21"
 ---
 
 # 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: "19.0.19"
+version: "19.0.21"
 ---
 
 # 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.19"
+version: "19.0.21"
 ---
 
 # 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.19"
+version: "19.0.21"
 ---
 
 # 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: "19.0.19"
+version: "19.0.21"
 ---
 
 # Ax Signature Reference