@ax-llm/ax 19.0.13 → 19.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "19.0.13",
+  "version": "19.0.15",
   "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(...), or RLM code execution.
-version: "19.0.13"
+version: "19.0.15"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
@@ -15,6 +15,7 @@ Use this skill to generate `AxAgent` code. Prefer short, modern, copyable patter
 - Assume the child-agent module is `agents` unless `agentIdentity.namespace` is set.
 - 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 `contextManagement.actionReplay: 'adaptive'` plus `stateSummary` so prior exploratory turns are summarized and live runtime state stays visible.
 
 ## Critical Rules
 
@@ -25,6 +26,8 @@ Use this skill to generate `AxAgent` code. Prefer short, modern, copyable patter
 - Never combine `console.log(...)` with `final(...)` or `ask_clarification(...)` in the same actor turn.
 - 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.
+- If `contextManagement.stateSummary.enabled` is on, rely on the `Live Runtime State` block for current variables instead of re-reading old action log code.
+- If `contextManagement.actionReplay` is `'adaptive'` or `'minimal'`, assume older successful turns may be summarized or omitted.
 
 ## Canonical Pattern
 
@@ -116,9 +119,9 @@ Rules:
 ## Tool Functions And Namespaces
 
 ```typescript
-import type { AxFunction } from '@ax-llm/ax';
+import type { AxAgentFunction } from '@ax-llm/ax';
 
-const tools: AxFunction[] = [
+const tools: AxAgentFunction[] = [
   {
     name: 'findSnippets',
     namespace: 'kb',
@@ -134,11 +137,24 @@ const tools: AxFunction[] = [
       type: 'array',
       items: { type: 'string' },
     },
+    examples: [
+      {
+        title: 'Find severity guidance',
+        code: 'await kb.findSnippets({ topic: "severity" });',
+      },
+    ],
     func: async ({ topic }) => [],
   },
 ];
 
 const analyst = agent('query:string -> answer:string', {
+  namespaces: [
+    {
+      name: 'kb',
+      title: 'Knowledge Base',
+      description: 'Handbook and documentation search helpers.',
+    },
+  ],
   functions: { local: tools },
   contextFields: [],
 });
@@ -183,13 +199,21 @@ Discovery APIs:
 
 Both return Markdown.
 
+- `listModuleFunctions(...)` only lists modules that actually have callable entries. Namespace metadata from `namespaces` only enriches those callable-backed modules.
+- If a requested module does not exist, `listModuleFunctions(...)` returns a per-module markdown error without failing the whole call.
+- `getFunctionDefinitions(...)` may include argument comments from schema descriptions and fenced code examples from `AxAgentFunction.examples`.
+
 Rules:
 
 1. Call `listModuleFunctions(...)`.
-2. Inspect the logged result.
-3. Call `getFunctionDefinitions(...)` for only the callables you plan to use.
-4. Inspect the logged result.
-5. Call discovered functions and child agents.
+2. If you need multiple modules, use one batched array call such as `listModuleFunctions(['timeRange', 'schedulingOrganizer'])`.
+3. Log or inspect the returned markdown directly. Do not wrap it in JSON or custom objects.
+4. If you need multiple callable definitions, prefer one batched `getFunctionDefinitions([...])` call.
+5. Do not split discovery into separate calls with `Promise.all(...)`.
+6. Inspect the logged result.
+7. Call `getFunctionDefinitions(...)` for only the callables you plan to use.
+8. Inspect the logged result.
+9. Call discovered functions and child agents.
 
 Examples:
 
@@ -208,6 +232,8 @@ Do not:
 - Do not guess callable names when discovery mode is on.
 - Do not assume sub-agents live under `agents` if `agentIdentity.namespace` is configured.
 - Do not dump large pre-known tool definitions into actor code when discovery mode is enabled.
+- Do not use `Promise.all(...)` to fan out discovery calls across modules or definitions.
+- Do not convert discovery markdown into JSON before logging or using it.
 
 ## RLM Actor Code Rules
 
@@ -216,10 +242,46 @@ Use these rules when generating actor JavaScript for RLM in stdout mode:
 - Treat each actor turn as exactly one observable step.
 - If you need to inspect a value, compute it, `console.log(...)` it, and stop immediately after that `console.log(...)`.
 - On the next turn, read the logged result from `Action Log` before writing more code that depends on it.
+- If the prompt contains `Live Runtime State`, treat it as the canonical view of current variables.
 - Errors from child-agent or tool calls appear in `Action Log`; inspect them and fix the code on the next turn.
 - Non-final turns should contain exactly one `console.log(...)`.
 - Final turns should call `final(...)` or `ask_clarification(...)` without `console.log(...)`.
 - Do not write a complete multi-step program in one actor turn.
+- Do not assume older successful turns remain fully replayed; adaptive replay may compress them to `[SUMMARY]: ...`.
+
+## RLM Adaptive Replay
+
+Prefer this configuration for long, multi-turn runtime analysis:
+
+```typescript
+const analyst = agent(
+  'context:string, question:string -> answer:string, findings:string[]',
+  {
+    contextFields: ['context'],
+    runtime: new AxJSRuntime(),
+    maxTurns: 10,
+    contextManagement: {
+      actionReplay: 'adaptive',
+      recentFullActions: 1,
+      successSummarization: true,
+      stateSummary: { enabled: true, maxEntries: 6 },
+      stateInspection: { contextThreshold: 2_000 },
+      errorPruning: true,
+      hindsightEvaluation: true,
+      pruneRank: 2,
+    },
+  }
+);
+```
+
+Rules:
+
+- Use `actionReplay: 'adaptive'` when the task needs runtime state across many turns but old exploratory code should not keep bloating the prompt.
+- Use `recentFullActions` to keep the newest one or two turns verbatim while older successful turns collapse to summaries.
+- Use `successSummarization: true` for explicit, compact summaries of older successful turns.
+- Use `stateSummary.enabled` to inject a compact `Live Runtime State` block into the actor prompt.
+- Use `actionReplay: 'minimal'` only when you want aggressively compressed history and can rely mostly on current runtime state.
+- Keep `stateInspection.contextThreshold` on so the actor is reminded to call `inspect_runtime()` when context grows.
 
 Good pattern:
 

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.13"
+version: "19.0.15"
 ---
 
 # Ax Library (@ax-llm/ax) Usage Guide