@ax-llm/ax 19.0.27 → 19.0.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "19.0.27",
+  "version": "19.0.29",
   "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: "19.0.27"
+version: "19.0.29"
 ---
 
 # 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.27"
+version: "19.0.29"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
@@ -114,6 +114,7 @@ Practical rule:
 - If `functions.discovery` is `true`, call `listModuleFunctions(...)` first, then `getFunctionDefinitions(...)`, then call only discovered functions.
 - In stdout-mode RLM, non-final turns must emit exactly one `console.log(...)` and stop immediately after it.
 - Never combine `console.log(...)` with `final(...)` or `askClarification(...)` in the same actor turn.
+- Inside actor-authored JavaScript, `final(...)` and `askClarification(...)` end the current turn immediately; code after them is dead code.
 - If a host-side `AxAgentFunction` needs to end the current actor turn, use `extra.protocol.final(...)` or `extra.protocol.askClarification(...)`.
 - If a child agent needs parent inputs such as `audience`, use `fields.shared` or `fields.globallyShared`.
 - `llmQuery(...)` failures may come back as `[ERROR] ...`; do not assume success.
@@ -368,9 +369,10 @@ askClarification({
 ```
 
 - Supported `type` values are `text`, `number`, `date`, `single_choice`, and `multiple_choice`.
-- Choice payloads require a non-empty `choices` array.
+- `single_choice` payloads with missing, empty, or malformed `choices` are downgraded to a plain clarification question instead of failing the turn.
+- `multiple_choice` payloads must include at least two valid choices; otherwise the actor turn fails with a corrective runtime error that tells the model how to fix the call.
 - Choice entries may be strings or `{ label, value? }` objects.
-- Invalid clarification payloads are treated as actor-turn runtime errors, not as successful clarification completions.
+- Invalid clarification payloads such as a missing `question` are still treated as actor-turn runtime errors, not as successful clarification completions.
 
 What `AxAgentState` contains:
 
@@ -564,7 +566,7 @@ Rules:
 - 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: 'checkpointed'` when you want full replay first, then only older successful history checkpointed after budget pressure becomes real.
 - Use `preset: 'lean'` when you want more aggressive compression and can rely mostly on current runtime state plus checkpoint summaries and compact action summaries.
-- Use `budget: 'compact'` when you want earlier summarization and tighter runtime/output truncation, `budget: 'balanced'` for the default, and `budget: 'expanded'` when you want the actor prompt to grow more before compression starts.
+- Use `budget: 'compact'` when you want earlier summarization and tighter prompt-pressure thresholds, `budget: 'balanced'` for the default, and `budget: 'expanded'` when you want the actor prompt to grow more before compression starts.
 - `checkpointed + balanced` is the default. `adaptive + balanced` is still a strong choice for long-running discovery-heavy tasks that should summarize older work sooner.
 - `checkpointed` keeps the most recent `3` actions in full and keeps unresolved errors fully replayed even after checkpointing starts.
 - Non-`full` presets 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.
@@ -654,6 +656,8 @@ Use these top-level controls consistently:
 - `mode`: controls whether `llmQuery(...)` stays simple or delegates to recursive child agents in advanced mode
 - `recursionOptions.maxDepth`: limits recursive `llmQuery(...)` depth
 - `maxSubAgentCalls`: shared delegated-call budget across the whole run, including recursive children
+- `maxRuntimeChars`: runtime/output truncation cap for console logs, tool results, and interpreter output replay
+- `summarizerOptions`: default model/options for the internal checkpoint summarizer
 - `actorOptions`: actor-only forward options such as `description`, `model`, `modelConfig`, `thinkingTokenBudget`, and `showThoughts`
 - `actorModelPolicy`: actor-only model override rules based on consecutive error turns or discovery fetches from listed namespaces
 - `responderOptions`: responder-only forward options
@@ -669,6 +673,11 @@ const researchAgent = agent('query:string -> answer:string', {
   recursionOptions: {
     maxDepth: 2,
   },
+  maxRuntimeChars: 3000,
+  summarizerOptions: {
+    model: 'gpt-5.4-mini',
+    modelConfig: { temperature: 0.1, maxTokens: 180 },
+  },
   contextPolicy: {
     preset: 'checkpointed',
     budget: 'balanced',
@@ -693,6 +702,8 @@ const researchAgent = agent('query:string -> answer:string', {
 Semantics:
 
 - `mode` stays top-level; there is no `recursionOptions.mode`.
+- `maxRuntimeChars` controls runtime/output truncation only. It is separate from `contextPolicy.budget`.
+- `summarizerOptions` tunes only the internal checkpoint summarizer. It does not change actor or responder model selection.
 - The current merged actor model stays the default base model. `actorModelPolicy` only overrides it when a rule matches.
 - `actorModelPolicy` only switches the actor model. It does not change `responderOptions.model`.
 - Recursive child agents can inherit `actorModelPolicy`; use a child override only when that child needs different routing behavior.
@@ -980,7 +991,9 @@ agentIdentity?: {
   maxSubAgentCalls?: number;
   maxBatchedLlmQueryConcurrency?: number;
   maxTurns?: number;
+  maxRuntimeChars?: number;
   contextPolicy?: AxContextPolicyConfig;
+  summarizerOptions?: Omit<AxProgramForwardOptions<string>, 'functions'>;
   actorFields?: string[];
   actorTurnCallback?: (turn: {
     turn: number;

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.27"
+version: "19.0.29"
 ---
 
 # 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.27"
+version: "19.0.29"
 ---
 
 # 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.27"
+version: "19.0.29"
 ---
 
 # 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.27"
+version: "19.0.29"
 ---
 
 # 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.27"
+version: "19.0.29"
 ---
 
 # 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.27"
+version: "19.0.29"
 ---
 
 # 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.27"
+version: "19.0.29"
 ---
 
 # Ax Signature Reference