@ax-llm/ax 18.0.12 → 19.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "18.0.12",
+  "version": "19.0.1",
   "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 with building AxAgent-based agents using @ax-llm/ax. Use when the user asks about agent(), AxAgent, child agents, tool functions, RLM mode, stopping agents, or composing multi-agent hierarchies.
-version: "18.0.12"
+description: This skill helps with building AxAgent-based agents using @ax-llm/ax. Use when the user asks about agent(), AxAgent, child agents, tool functions, RLM mode, stopping agents, composing multi-agent hierarchies, shared fields, shared agents, or global shared fields/agents.
+version: "19.0.1"
 ---
 
 # AxAgent Guide (@ax-llm/ax)
@@ -84,15 +84,10 @@ const myAgent = agent(
 
     // Optional
     ai: llm,                            // Bind a specific AI service
-    functions: [searchTool, calcTool],   // Tool functions
-    agents: [childAgent1, childAgent2],  // Child agents
-    maxSteps: 25,                        // Max reasoning steps (default: 25)
-    maxRetries: 3,                       // Retries on assertion failures
-    temperature: 0.7,                    // Sampling temperature
+    contextFields: ['...'],             // Fields removed from LLM; available in JS runtime
+    functions: { local: [searchTool, calcTool] },   // Agent functions (AxAgentFunction)
+    agents: { local: [childAgent1, childAgent2] },  // Child agents
     debug: false,                        // Debug logging
-
-    // RLM mode (see RLM section below)
-    contextFields: ['...'],          // Fields to load into runtime session
     // ... other RLM options (see RLM section below)
   }
 );
@@ -102,14 +97,6 @@ const myAgent = agent(
 
 Required when the agent is used as a child agent. Contains `name` (converted to camelCase for the function name, e.g. `'Physics Researcher'` becomes `physicsResearcher`) and `description` (shown to parent agents when they decide which child to call).
 
-### `functions`
-
-An array of tool functions the agent can call. Each function has a name, description, JSON Schema parameters, and an implementation.
-
-### `agents`
-
-An array of child agents. When provided, the agent can delegate subtasks to these children. See [Child Agents](#child-agents).
-
 ## Running Agents
 
 ### `forward()`
@@ -293,7 +280,7 @@ const weatherAgent = agent(
       name: 'weatherAssistant',
       description: 'An assistant that helps with weather queries',
     },
-    functions: [getCurrentWeather]
+    functions: { local: [getCurrentWeather] }
   }
 );
 
@@ -330,11 +317,12 @@ const summarizer = agent(
       name: 'Science Summarizer',
       description: 'Summarizer can write short summaries of advanced science topics',
     },
+    actorOptions: {
+      description: 'You are a science summarizer. You can write short summaries of advanced science topics. Use numbered bullet points to summarize the answer in order of importance.',
+    },
   }
 );
 
-summarizer.setActorDescription('You are a science summarizer. You can write short summaries of advanced science topics. Use numbered bullet points to summarize the answer in order of importance.');
-
 const scientist = agent(
   f()
     .input('question', f.string())
@@ -345,7 +333,7 @@ const scientist = agent(
       name: 'Scientist',
       description: 'An agent that can answer advanced science questions',
     },
-    agents: [researcher, summarizer],
+    agents: { local: [researcher, summarizer] },
   }
 );
 
@@ -354,6 +342,67 @@ const result = await scientist.forward(llm, {
 });
 ```
 
+## Shared Fields and Agents
+
+When composing agent hierarchies, you often need to pass data or utility agents to child agents without requiring the parent's LLM to explicitly route them.
+
+### `fields.shared` — Pass fields to direct children (one level)
+
+Fields listed in `fields.shared` are automatically injected into direct child agents at runtime. They bypass the parent's LLM entirely.
+
+```typescript
+const parentAgent = agent('query:string, userId:string, knowledgeBase:string -> answer:string', {
+  agents: { local: [childAgent] },
+  contextFields: ['knowledgeBase'],
+  fields: { shared: ['userId'] },  // userId is injected into child agents automatically
+});
+```
+
+- `userId` is removed from the parent's Actor/Responder prompts
+- Children can opt out via `fields: { excluded: ['userId'] }`
+
+### `fields.globallyShared` — Pass fields to ALL descendants (recursive)
+
+Like `fields.shared`, but propagates through the entire agent tree — children, grandchildren, and beyond.
+
+```typescript
+const parent = agent('query:string, sessionId:string -> answer:string', {
+  agents: { local: [child] },
+  fields: { globallyShared: ['sessionId'] },  // sessionId reaches child AND grandchild
+});
+```
+
+### `agents.shared` — Add agents to direct children (one level)
+
+Utility agents listed in `agents.shared` are added to every direct child agent's available agents list.
+
+```typescript
+const parent = agent('query:string -> answer:string', {
+  agents: { local: [worker], shared: [logger] },  // worker can now call agents.logger(...)
+});
+```
+
+### `agents.globallyShared` — Add agents to ALL descendants (recursive)
+
+Like `agents.shared`, but propagates through the entire agent tree.
+
+```typescript
+const parent = agent('query:string -> answer:string', {
+  agents: { local: [child], globallyShared: [logger] },  // both child AND grandchild can call agents.logger(...)
+});
+```
+
+### `fields.excluded`
+
+Any child agent can opt out of receiving specific shared fields:
+
+```typescript
+const sentiment = agent('text:string -> sentiment:string', {
+  agentIdentity: { name: 'Sentiment', description: 'Analyzes sentiment' },
+  fields: { excluded: ['userId'] },
+});
+```
+
 ## RLM Mode
 
 RLM (Recursive Language Model) mode lets agents process arbitrarily long documents without hitting context window limits. Instead of stuffing the entire document into the LLM prompt, RLM loads it into a code interpreter session and gives the LLM tools to analyze it programmatically.
@@ -372,7 +421,7 @@ When you pass a long document to an LLM, you face:
    - **Actor** — A code generation agent that writes JavaScript to analyze context data. It NEVER generates final answers directly.
    - **Responder** — An answer synthesis agent that produces the final answer from the Actor's `actorResult` payload. It NEVER generates code.
 3. **Recursive queries** — Inside code, `llmQuery(...)` delegates semantic work to a sub-query (plain AxGen in simple mode, full AxAgent in advanced mode).
-4. **Completion** — The Actor signals completion by calling `submit(...args)` or asks for more user input with `ask_clarification(...args)`, then the Responder synthesizes the final answer.
+4. **Completion** — The Actor signals completion by calling `final(...args)` or asks for more user input with `ask_clarification(...args)`, then the Responder synthesizes the final answer.
 
 The Actor writes JavaScript code to inspect, filter, and iterate over the document. It uses `llmQuery` for semantic analysis and can chunk data in code before querying.
 
@@ -529,7 +578,7 @@ The Actor generates JavaScript code in a `javascriptCode` output field. Each tur
 2. The runtime executes the code and returns the result
 3. The result is appended to the action log
 4. The Actor sees the updated action log and decides what to do next
-5. When the Actor calls `submit(...args)` or `ask_clarification(...args)`, the loop ends and the Responder takes over
+5. When the Actor calls `final(...args)` or `ask_clarification(...args)`, the loop ends and the Responder takes over
 
 The Actor's typical workflow:
 
@@ -538,7 +587,7 @@ The Actor's typical workflow:
 3. Use code for structural work (filter, map, regex, property access)
 4. Use llmQuery for semantic work (summarization, interpretation)
 5. Build up answers in variables across turns
-6. Signal completion by calling `submit(...args)` (or `ask_clarification(...args)` to request user input)
+6. Signal completion by calling `final(...args)` (or `ask_clarification(...args)` to request user input)
 
 ### Actor Fields
 
@@ -565,7 +614,7 @@ const analyzer = agent(
 
 ### Actor Callback
 
-Use `actorCallback` to observe each Actor turn. It receives the full Actor result (including `javascriptCode` and any `actorFields`) and fires every turn, including the `submit(...)`/`ask_clarification(...)` turn.
+Use `actorCallback` to observe each Actor turn. It receives the full Actor result (including `javascriptCode` and any `actorFields`) and fires every turn, including the `final(...)`/`ask_clarification(...)` turn.
 
 ```typescript
 const analyzer = agent(
@@ -637,7 +686,7 @@ Each `llmQuery` call runs a sub-query with a fresh session and the same register
 
 ### Actor/Responder Descriptions
 
-Use `setActorDescription()` and `setResponderDescription()` to append additional instructions to the Actor or Responder system prompts. The base RLM prompts are preserved; your text is appended after them.
+Use `actorOptions.description` and `responderOptions.description` to append additional instructions to the Actor or Responder system prompts. The base RLM prompts are preserved; your text is appended after them.
 
 ```typescript
 const analyzer = agent(
@@ -652,18 +701,16 @@ const analyzer = agent(
       description: 'Analyzes context with custom actor and responder instructions',
     },
     contextFields: ['context'],
+    actorOptions: {
+      description: 'Focus on numerical data. Use precise calculations.',
+    },
+    responderOptions: {
+      description: 'Format answers as bullet points. Cite evidence.',
+    },
   }
 );
-
-// Add domain-specific instructions to the Actor (code generation agent)
-analyzer.setActorDescription('Focus on numerical data. Use precise calculations.');
-
-// Add domain-specific instructions to the Responder (answer synthesis agent)
-analyzer.setResponderDescription('Format answers as bullet points. Cite evidence.');
 ```
 
-> **Note:** Signature-level descriptions (via `.description()` on the signature) are not supported on `AxAgent`. Use these methods instead to customize each sub-program independently.
-
 ### Few-Shot Demos
 
 Use `setDemos()` to provide few-shot examples that guide the Actor and Responder. Demos are keyed by program ID — use `namedPrograms()` to discover available IDs.
@@ -681,7 +728,7 @@ analyzer.setDemos([
       },
       {
         actionLog: 'Step 1 | console.log(context.slice(0, 200))\n→ Chapter 1: ...',
-        javascriptCode: 'submit("analysis complete")',
+        javascriptCode: 'final("analysis complete")',
       },
     ],
   },
@@ -706,10 +753,10 @@ Demo values are validated against the target program's signature. Invalid values
 |-----|-------------|
 | `await llmQuery(query, context)` | Ask a sub-LM a question with a context value. Returns a string. Oversized context is truncated to `maxRuntimeChars` |
 | `await llmQuery([{ query, context }, ...])` | Run multiple sub-LM queries in parallel. Returns string[]. Failed items return `[ERROR] ...` |
-| `submit(...args)` | Stop Actor execution and pass payload args to Responder. Requires at least one argument |
+| `final(...args)` | Stop Actor execution and pass payload args to Responder. Requires at least one argument |
 | `ask_clarification(...args)` | Stop Actor execution and pass clarification payload args to Responder. Requires at least one argument |
 | `await agents.<name>({...})` | Call a child agent by name. Parameters match the agent's JSON schema. Returns a string |
-| `await <toolName>({...})` | Call a tool function by name. Parameters match the tool's JSON schema |
+| `await <namespace>.<name>({...})` | Call an agent function. Registered under `namespace.name` (default namespace: `utils`) |
 | `print(...args)` | Available in `AxJSRuntime` when `outputMode: 'stdout'`; captured output appears in the function result |
 | Context variables | All fields listed in `contextFields` are available by name |
 
@@ -803,9 +850,9 @@ class MyBrowserInterpreter implements AxCodeRuntime {
 The `globals` object passed to `createSession` includes:
 - All context field values (by field name)
 - `llmQuery` function (supports both single and batched queries)
-- `submit(...args)` and `ask_clarification(...args)` completion functions
+- `final(...args)` and `ask_clarification(...args)` completion functions
 - `agents` namespace object with child agent functions (e.g., `agents.summarize(...)`)
-- Tool functions as flat globals
+- `<namespace>` objects containing agent functions (e.g., `globals.utils.search(...)`)
 - `print` function when supported by the runtime (for `AxJSRuntime`, set `outputMode: 'stdout'`)
 
 If provided, `getUsageInstructions()` is appended to the RLM system prompt as runtime-specific guidance. Use it for semantics that differ by runtime (for example state persistence or async execution behavior).
@@ -887,11 +934,22 @@ interface AxCodeSession {
 interface AxAgentConfig<IN, OUT> extends AxAgentOptions {
   ai?: AxAIService;
   agentIdentity?: { name: string; description: string };
-  agents?: AxAgentic<IN, OUT>[];
-  functions?: AxInputFunctionType;
 }
 ```
 
+### `AxAgentFunction`
+
+```typescript
+type AxAgentFunction = {
+  name: string;
+  description: string;
+  parameters: AxFunctionJSONSchema;  // required
+  returns?: AxFunctionJSONSchema;
+  namespace?: string;                // default: 'utils'
+  func: AxFunctionHandler;
+};
+```
+
 ### `AxAgentOptions`
 
 Extends `AxProgramForwardOptions` (without `functions`) with:
@@ -900,12 +958,33 @@ Extends `AxProgramForwardOptions` (without `functions`) with:
 {
   debug?: boolean;
   contextFields: string[];
+
+  agents?: {
+    local?: AxAnyAgentic[];        // Agents callable under the agents.* namespace
+    shared?: AxAnyAgentic[];       // Added to all direct child agents (one level)
+    globallyShared?: AxAnyAgentic[]; // Added to ALL descendants recursively
+    excluded?: string[];           // Agent names this agent should NOT receive from parents
+  };
+
+  fields?: {
+    shared?: string[];             // Fields passed to direct child agents (one level)
+    globallyShared?: string[];     // Fields passed to ALL descendants recursively
+    excluded?: string[];           // Fields this agent should NOT receive from parents
+  };
+
+  functions?: {
+    local?: AxAgentFunction[];         // Registered as namespace.name globals in the JS runtime
+    shared?: AxAgentFunction[];        // Shared with direct child agents (one level)
+    globallyShared?: AxAgentFunction[]; // Shared with ALL descendants recursively
+    excluded?: string[];               // Function names this agent should NOT receive from parents
+  };
+
   runtime?: AxCodeRuntime;
   maxLlmCalls?: number;
   maxRuntimeChars?: number;
   maxBatchedLlmQueryConcurrency?: number;
   maxTurns?: number;
-  trajectoryPruning?: boolean;               // @deprecated Use contextManagement.errorPruning
+  trajectoryPruning?: boolean;           // @deprecated Use contextManagement.errorPruning
   contextManagement?: AxContextManagementConfig;
   actorFields?: string[];
   actorCallback?: (result: Record<string, unknown>) => void | Promise<void>;
@@ -913,27 +992,11 @@ Extends `AxProgramForwardOptions` (without `functions`) with:
   recursionOptions?: Partial<Omit<AxProgramForwardOptions, 'functions'>> & {
     maxDepth?: number;  // Maximum recursion depth for llmQuery sub-agent calls (default: 2)
   };
-  actorOptions?: Partial<AxProgramForwardOptions>;   // Default forward options for Actor
-  responderOptions?: Partial<AxProgramForwardOptions>; // Default forward options for Responder
+  actorOptions?: Partial<AxProgramForwardOptions & { description?: string }>;    // Default forward options for Actor
+  responderOptions?: Partial<AxProgramForwardOptions & { description?: string }>; // Default forward options for Responder
 }
 ```
 
-### `setActorDescription()`
-
-```typescript
-public setActorDescription(additionalText: string): void
-```
-
-Appends additional text to the Actor's RLM system prompt. The base prompt is preserved; the additional text is appended after it.
-
-### `setResponderDescription()`
-
-```typescript
-public setResponderDescription(additionalText: string): void
-```
-
-Appends additional text to the Responder's RLM system prompt. The base prompt is preserved; the additional text is appended after it.
-
 ### `stop()`
 
 ```typescript

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