@ax-llm/ax 19.0.28 → 19.0.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "19.0.28",
+  "version": "19.0.30",
   "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.28"
+version: "19.0.30"
 ---
 
 # 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.28"
+version: "19.0.30"
 ---
 
 # 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:
 
@@ -621,7 +623,7 @@ Use it for:
 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.
+- `result` is the raw runtime result before Ax applies type-aware serialization and budget-proportional truncation.
 - `thought` is optional and only appears when the underlying `AxGen` call had `showThoughts` enabled and the provider actually returned a thought field.
 
 Good pattern:
@@ -654,7 +656,7 @@ 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
+- `maxRuntimeChars`: runtime/output truncation ceiling for console logs, tool results, and interpreter output replay. The actual limit is computed dynamically each turn based on remaining context budget (see **Dynamic Output Truncation** below)
 - `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
@@ -700,7 +702,7 @@ 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`.
+- `maxRuntimeChars` sets the truncation ceiling and is separate from `contextPolicy.budget`. The effective limit per turn is computed dynamically (see below).
 - `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`.
@@ -716,6 +718,23 @@ When choosing these options for a user:
 - Keep `actorOptions` focused on actor-only forward concerns such as `description`, `model`, `modelConfig`, `thinkingTokenBudget`, and `showThoughts`.
 - Use `actorModelPolicy` when the actor is the bottleneck and you want the responder to stay fixed.
 
+## Dynamic Output Truncation
+
+Runtime output truncation is **budget-proportional** and **type-aware**:
+
+**Budget-proportional sizing**: The effective truncation limit scales with remaining context budget. Early turns (empty action log) use the full `maxRuntimeChars` ceiling. As the action log fills toward `targetPromptChars`, the limit decays linearly down to 15% of the ceiling, hard-floored at 400 chars. This means early turns preserve more output detail while later turns conserve context for reasoning.
+
+**Type-aware serialization**: Non-string runtime output is serialized with structural awareness before the char-budget truncation pass:
+
+- **Large arrays** (>10 items): first 3 + last 2 items are kept; middle items replaced with `... [N hidden items]`.
+- **Deep objects** (>3 levels): nested values beyond depth 3 replaced with `[Object]` or `[Array(N)]`.
+- **Error stack traces**: first 3 + last 1 stack frames kept; middle frames replaced with `... [N frames hidden]`.
+- **Simple values**: standard `JSON.stringify` passthrough.
+
+This means the actor sees structurally informative output even when the char budget is tight, rather than a blindly head-truncated string.
+
+Users do not need to configure this behavior — it is automatic. `maxRuntimeChars` sets the upper bound; the dynamic system only ever reduces, never exceeds it.
+
 ## Actor Prompt Controls
 
 Use `actorOptions` for actor-only forward options and `responderOptions` for responder-only tuning.

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