@ax-llm/ax 19.0.15 → 19.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "19.0.15",
+  "version": "19.0.16",
   "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.15"
+version: "19.0.16"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
@@ -11,11 +11,26 @@ Use this skill to generate `AxAgent` code. Prefer short, modern, copyable patter
 ## Use These Defaults
 
 - Use `agent(...)`, not `new AxAgent(...)`.
+- Prefer `fn(...)` for host-side function definitions instead of hand-writing JSON Schema objects.
 - Prefer namespaced functions such as `utils.search(...)` or `kb.find(...)`.
 - 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.
+- For long RLM tasks, prefer `contextPolicy: { preset: 'adaptive' }` so older successful turns collapse into checkpoint summaries while live runtime state stays visible.
+
+## Context Policy Presets
+
+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. This is the default recommendation for long multi-turn tasks.
+- `lean`: Most aggressive compression. Keep `Live Runtime State`, 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.
+
+Practical rule:
+
+- Start with `adaptive` for most long RLM tasks.
+- Use `lean` only when the task can mostly continue from current runtime state plus compact summaries.
+- Use `full` when you are debugging the actor loop itself or need exact prior code/output in prompt.
 
 ## Critical Rules
 
@@ -24,10 +39,11 @@ Use this skill to generate `AxAgent` code. Prefer short, modern, copyable patter
 - 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 `ask_clarification(...)` in the same actor turn.
+- 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.
-- 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.
+- If `contextPolicy.state.summary` is on, rely on the `Live Runtime State` block for current variables instead of re-reading old action log code.
+- If `contextPolicy.preset` is `'adaptive'` or `'lean'`, assume older successful turns may be replaced by a `Checkpoint Summary` and that replay-pruned successful turns may appear as compact summaries instead of full code blocks.
 
 ## Canonical Pattern
 
@@ -119,43 +135,34 @@ Rules:
 ## Tool Functions And Namespaces
 
 ```typescript
-import type { AxAgentFunction } from '@ax-llm/ax';
+import { f, fn } from '@ax-llm/ax';
+
+const tools = [
+  fn('findSnippets')
+    .description('Find handbook snippets by topic')
+    .namespace('kb')
+    .arg('topic', f.string('Topic keyword'))
+    .returns(f.string('Matching snippet').array())
+    .example({
+      title: 'Find severity guidance',
+      code: 'await kb.findSnippets({ topic: "severity" });',
+    })
+    .handler(async ({ topic }) => [])
+    .build(),
+];
 
-const tools: AxAgentFunction[] = [
-  {
-    name: 'findSnippets',
-    namespace: 'kb',
-    description: 'Find handbook snippets by topic',
-    parameters: {
-      type: 'object',
-      properties: {
-        topic: { type: 'string', description: 'Topic keyword' },
-      },
-      required: ['topic'],
-    },
-    returns: {
-      type: 'array',
-      items: { type: 'string' },
-    },
-    examples: [
+const analyst = agent('query:string -> answer:string', {
+  functions: {
+    local: [
       {
-        title: 'Find severity guidance',
-        code: 'await kb.findSnippets({ topic: "severity" });',
+        namespace: 'kb',
+        title: 'Knowledge Base',
+        selectionCriteria: 'Use for handbook and documentation lookups.',
+        description: 'Handbook and documentation search helpers.',
+        functions: tools.map(({ namespace: _namespace, ...tool }) => tool),
       },
     ],
-    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: [],
 });
 ```
@@ -172,6 +179,44 @@ Rules:
 - Default function namespace is `utils` when no namespace is set.
 - Use the runtime call shape `await <namespace>.<name>({...})`.
 
+## Host-Side Completion From Functions
+
+Use this pattern when the actor should call a namespaced function, but the host-side function implementation should decide to end the turn:
+
+```typescript
+import { f, fn } from '@ax-llm/ax';
+
+const workflowTools = [
+  fn('finishReply')
+    .description('Complete the actor turn with the final reply text')
+    .namespace('workflow')
+    .arg('reply', f.string('Final reply text'))
+    .returns(f.string('Final reply text'))
+    .handler(async ({ reply }, extra) => {
+      extra?.protocol?.final(reply);
+      return reply;
+    })
+    .build(),
+  fn('askForOrderId')
+    .description('Complete the actor turn by requesting clarification')
+    .namespace('workflow')
+    .arg('question', f.string('Clarification question'))
+    .returns(f.string('Clarification question'))
+    .handler(async ({ question }, extra) => {
+      extra?.protocol?.askClarification(question);
+      return question;
+    })
+    .build(),
+];
+```
+
+Rules:
+
+- `extra.protocol` is only available when the function call comes from an active AxAgent actor runtime session.
+- Use `extra.protocol.final(...)` or `extra.protocol.askClarification(...)` only inside host-side function handlers.
+- Inside actor-authored JavaScript, keep using the runtime globals `final(...)` and `ask_clarification(...)`.
+- Do not model these protocol completions as normal registered tool functions or discovery entries.
+
 ## Discovery Mode
 
 Enable discovery mode when you want the actor to discover modules and fetch callable definitions on demand:
@@ -199,7 +244,8 @@ Discovery APIs:
 
 Both return Markdown.
 
-- `listModuleFunctions(...)` only lists modules that actually have callable entries. Namespace metadata from `namespaces` only enriches those callable-backed modules.
+- `listModuleFunctions(...)` only lists modules that actually have callable entries.
+- Grouped modules render in the Actor prompt as `<namespace> - <selection criteria>` when criteria is provided.
 - 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`.
 
@@ -247,7 +293,54 @@ Use these rules when generating actor JavaScript for RLM in stdout mode:
 - 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]: ...`.
+- Do not assume older successful turns remain fully replayed; adaptive or lean policies may collapse them into a `Checkpoint Summary` block or compact action summaries.
+
+## RLM Test Harness
+
+Use `agent.test(code, contextFieldValues?, options?)` when the user wants to validate JavaScript snippets against the actual AxAgent runtime environment without running the full Actor/Responder loop.
+
+```typescript
+import { AxJSRuntime, agent, f, fn } from '@ax-llm/ax';
+
+const runtime = new AxJSRuntime();
+
+const tools = [
+  fn('sum')
+    .description('Return the sum of the provided numeric values')
+    .namespace('math')
+    .arg('values', f.number('Value to add').array())
+    .returns(f.number('Sum of all values'))
+    .handler(async ({ values }) =>
+      values.reduce((total, value) => total + value, 0)
+    )
+    .build(),
+];
+
+const harness = agent('query:string -> answer:string', {
+  contextFields: ['query'],
+  runtime,
+  functions: { local: tools },
+  contextPolicy: { preset: 'adaptive' },
+});
+
+const output = await harness.test(
+  'console.log(await math.sum({ values: [3, 5, 8] }))',
+  { query: 'sum the values' }
+);
+
+console.log(output);
+```
+
+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`.
+- In `AxJSRuntime`, do not rely on calling `inspect_runtime()` 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.
+- Do not call `final(...)` or `ask_clarification(...)` inside `test(...)` snippets.
+- Pass only `contextFields` values to `test(...)`; it is not a general way to inject arbitrary non-context inputs.
+- If the snippet uses `llmQuery(...)`, provide an AI service through the agent config or `options.ai`.
 
 ## RLM Adaptive Replay
 
@@ -260,15 +353,22 @@ const analyst = agent(
     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,
+    contextPolicy: {
+      preset: 'adaptive',
+      state: {
+        summary: true,
+        inspect: true,
+        inspectThresholdChars: 2_000,
+        maxEntries: 6,
+      },
+      checkpoints: {
+        enabled: true,
+        triggerChars: 2_000,
+      },
+      expert: {
+        pruneErrors: true,
+        rankPruning: { enabled: true, minRank: 2 },
+      },
     },
   }
 );
@@ -276,12 +376,11 @@ const analyst = agent(
 
 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.
+- 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.
+- Use `state.summary` to inject a compact `Live Runtime State` block into the actor prompt.
+- Use `state.inspect` with `inspectThresholdChars` so the actor is reminded to call `inspect_runtime()` when context grows.
 
 Good pattern:
 
@@ -455,7 +554,7 @@ agentIdentity?: {
   maxRuntimeChars?: number;
   maxBatchedLlmQueryConcurrency?: number;
   maxTurns?: number;
-  contextManagement?: AxContextManagementConfig;
+  contextPolicy?: AxContextPolicyConfig;
   actorFields?: string[];
   actorCallback?: (result: Record<string, unknown>) => void | Promise<void>;
   inputUpdateCallback?: (currentInputs: Record<string, unknown>) => Promise<Record<string, unknown> | undefined> | Record<string, unknown> | undefined;

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