@amitdeshmukh/ax-crew 8.7.1 → 9.0.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## [9.0.0] - 2026-03-25
+
+### Breaking Changes
+- **`crew.state` renamed to `crew.crewState`**: The shared state property on `AxCrew` and `StatefulAxAgent` is now `crewState` instead of `state`. This avoids a conflict with ax-llm's new `private state: AxAgentState` on `AxAgent`. Update all `crew.state.set/get/getAll/reset` calls to `crew.crewState.set/get/getAll/reset`. Class-based function constructors still receive `state: Record<string, any>` (unchanged).
+
+### Added
+- **Deferred tool loading**: When an agent has many MCP tools (20+), only core tools + a `search_tools` meta-function are sent to the LLM. The LLM discovers and activates deferred tools on demand. Configurable via `deferredTools` on agent config:
+  - `enabled`: force on/off (default: auto when tool count exceeds threshold)
+  - `threshold`: tool count to activate (default: 20)
+  - `maxSearchResults`: max tools per search (default: 10)
+  - `coreTools`: tool names to always keep active
+- **Tool persistence across forward() calls**: Activated tools are re-injected via `beforeStep` hook so the LLM doesn't need to re-discover tools on each delegation.
+- **Auto-activation from results**: When a tool result mentions a deferred tool name (e.g., error response suggests `fix_query_error`), that tool is automatically activated.
+- **Prompt caching**: `contextCache` is now enabled by default on AxGen programs. System prompts and tool definitions are cached across multi-step interactions, reducing token costs by up to 6x for agents with many tools. Works automatically with Anthropic (implicit caching) and Gemini (explicit context caching).
+- **MCP resource result caching**: `resource_*` function calls are cached in-memory so repeated reads of the same MCP resource doc return instantly without re-fetching from the server.
+
+### Changed
+- **Refactored `agents/index.ts`**: Split 1300+ line monolith into separate modules:
+  - `statefulAgent.ts` — `StatefulAxAgent` class
+  - `lazyAgent.ts` — `LazyStatefulAxAgent` class
+  - `crew.ts` — `AxCrew` class
+  - `deferredTools.ts` — `DeferredToolManager` class
+  - `index.ts` — barrel exports
+- **Improved GraphJin example** (`examples/graphjin-database-agent.ts`):
+  - Strategy-driven DatabaseAgent prompt: check saved workflows first, build JS workflows with `gj.tools.*` for server-side computation, save for reuse
+  - Single-delegation ManagerAgent pattern: route full questions to sub-agents in one call instead of decomposing into sub-queries (reduced costs from $128 to $0.17 on same query)
+  - Performance timers for setup/query/total wall-clock time
+  - Workflow reuse: saved workflows are checked and executed on repeat queries, ensuring reproducible results
+
+## [8.7.4] - 2026-03-24
+
+### Added
+- **Auto-include MCP resource tool functions**: `resource_*` functions generated by ax-llm from MCP server resources are now automatically included in an agent's tool list, even when a `tools` allowlist is specified. This ensures agents can always discover and read MCP reference docs (query syntax, guides, etc.) on demand without needing to explicitly allowlist each resource tool.
+
+## [8.7.3] - 2026-03-17
+
+### Added
+- **Supporting example files** bundled with each skill. The postinstall script now copies relevant example `.ts` files into each skill's `examples/` directory. Claude Code can load these on demand for complete runnable references.
+- SKILL.md files now reference local `examples/` paths instead of GitHub URLs, enabling Claude to read examples directly.
+
+### Changed
+- Renamed all skill files from `ax-crew-*` to `axcrew-*` (e.g., `axcrew-ace.md`, `axcrew-mcp.md`). Skill directory names in `.claude/skills/` updated accordingly.
+- Updated version in all skill frontmatter to `8.7.3`.
+
+## [8.7.2] - 2026-03-17
+
+### Fixed
+- Skill install now creates proper directory structure for Claude Code discovery. Each skill gets its own directory with a `SKILL.md` file (e.g., `.claude/skills/ax-crew/SKILL.md`, `.claude/skills/ax-crew-ace/SKILL.md`). Previously installed loose `.md` files in a single directory which Claude Code couldn't discover.
+
 ## [8.7.1] - 2026-03-17
 
 ### Fixed

package/README.md

@@ -1,4 +1,4 @@
-![image](axcrew.png)
+![AxCrew](axcrew.webp)
 
 [![npm version](https://img.shields.io/npm/v/@amitdeshmukh/ax-crew.svg)](https://www.npmjs.com/package/@amitdeshmukh/ax-crew) [![npm downloads](https://img.shields.io/npm/dm/@amitdeshmukh/ax-crew.svg)](https://www.npmjs.com/package/@amitdeshmukh/ax-crew)
 
@@ -92,8 +92,8 @@ const myFunctions: FunctionRegistryType = {
 const crew = new AxCrew(config, myFunctions);
 
 // Set and get state
-crew.state.set('key', 'value');
-const value: string = crew.state.get('key');
+crew.crewState.set('key', 'value');
+const value: string = crew.crewState.get('key');
 
 // Add agents to the crew
 await crew.addAgentsToCrew(['Planner']);
@@ -125,7 +125,7 @@ Key TypeScript features:
 - **Agent**: An LLM program with a `signature`, `provider`, `ai` model config, optional `examples`, and optional `mcpServers`.
 - **Sub‑agents**: List other agent names in `agents` to compose behaviors.
 - **Functions (tools)**: Register callable functions via a registry and reference by name in agent `functions`.
-- **State**: `crew.state.set/get/getAll()` shared across all agents.
+- **State**: `crew.crewState.set/get/getAll()` shared across all agents.
 - **Persona**: Use `definition` (preferred) or `prompt` to set the system program. If both are present, `definition` wins.
 - **Execution mode**: Set `executionMode` to `axgen` (default) or `axagent` per agent.
 - **Streaming**: Use `streamingForward()` for token streams.
@@ -443,19 +443,19 @@ The `StatefulAxAgent` class in `src/agents/index.js` allows for shared state fun
 
 ```javascript
 // Set some state (key/value) for this crew
-crew.state.set('name', 'Crew1');
-crew.state.set('location', 'Earth');
+crew.crewState.set('name', 'Crew1');
+crew.crewState.set('location', 'Earth');
 
 // Get the state for the crew
-crew.state.get('name'); // 'Crew1'
-crew.state.getAll(); // { name: 'Crew1', location: 'Earth' }
+crew.crewState.get('name'); // 'Crew1'
+crew.crewState.getAll(); // { name: 'Crew1', location: 'Earth' }
 ``` 
 
 State can also be set/get by individual agents in the crew. This state is shared with all agents. It is also passed to any functions expressed as a class in `FunctionsRegistry`.
 
 ```javascript
-Planner.state.set('plan', 'Fly to Mars'); 
-console.log(Manager.state.getAll()); // { name: 'Crew1', location: 'Earth', plan: 'Fly to Mars' }
+Planner.crewState.set('plan', 'Fly to Mars');
+console.log(Manager.crewState.getAll()); // { name: 'Crew1', location: 'Earth', plan: 'Fly to Mars' }
 ```
 
 ## Example Agent task

package/dist/agents/agentConfig.d.ts

@@ -34,9 +34,11 @@ declare const parseAgentConfig: (agentName: string, crewConfig: AxCrewConfig, fu
     definition: any;
     signature: string | import("@ax-llm/ax").AxSignature<Record<string, any>, Record<string, any>>;
     functions: AxFunction[];
+    mcpFunctionNames: Set<string>;
     subAgentNames: string[];
     examples: Record<string, any>[];
     tracker: AxDefaultCostTracker;
+    deferredTools: any;
     debug: any;
 }>;
 export { parseAgentConfig, parseCrewConfig };

package/dist/agents/agentConfig.js

@@ -56,16 +56,19 @@ const initializeMCPServers = async (agentConfigData) => {
             initializedClients.push(mcpClient);
             // Normalize MCP tool schemas: some MCP servers omit `parameters` for
             // zero-arg tools, but providers like Gemini require a valid schema.
-            let mcpFns = mcpClient.toFunction().map(fn => ({
+            const allFns = mcpClient.toFunction().map(fn => ({
                 ...fn,
                 parameters: fn.parameters ?? { type: 'object', properties: {} },
             }));
-            // Filter to allowlisted tools if specified
+            // Filter to allowlisted tools if specified, but always include resource_* functions
             if (mcpServerConfig.tools && mcpServerConfig.tools.length > 0) {
                 const allowed = new Set(mcpServerConfig.tools);
-                mcpFns = mcpFns.filter(fn => allowed.has(fn.name));
+                const filtered = allFns.filter(fn => allowed.has(fn.name) || fn.name.startsWith('resource_'));
+                functions.push(...filtered);
+            }
+            else {
+                functions.push(...allFns);
             }
-            functions.push(...mcpFns);
         }
         return functions;
     }
@@ -180,6 +183,8 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state, options
             ...mcpFunctions
         ];
         const executionMode = agentConfigData.executionMode === 'axagent' ? 'axagent' : 'axgen';
+        // Track MCP function names for deferred tool loading
+        const mcpFunctionNames = new Set(mcpFunctions.map(fn => fn.name));
         // Return AI instance and Agent parameters
         return {
             ai: aiInstance,
@@ -190,9 +195,11 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state, options
             definition: agentConfigData.definition ?? agentConfigData.prompt,
             signature: agentConfigData.signature,
             functions: agentFunctions,
+            mcpFunctionNames,
             subAgentNames: agentConfigData.agents || [],
             examples: agentConfigData.examples || [],
             tracker: costTracker,
+            deferredTools: agentConfigData.deferredTools,
             debug: agentConfigData.options?.debug ?? agentConfigData.debug ?? false,
         };
     }

package/dist/agents/crew.d.ts

@@ -0,0 +1,59 @@
+import type { StateInstance, FunctionRegistryType, AxCrewConfig, AxCrewOptions } from "../types.js";
+import { StatefulAxAgent } from "./statefulAgent.js";
+/**
+ * AxCrew orchestrates a set of Ax agents that share state,
+ * tools (functions), optional MCP servers, streaming, and a built-in metrics
+ * registry for tokens, requests, and estimated cost.
+ *
+ * Typical usage:
+ *  const crew = new AxCrew(config, AxCrewFunctions)
+ *  await crew.addAllAgents()
+ *  const planner = crew.agents?.get("Planner")
+ *  const res = await planner?.forward({ task: "Plan something" })
+ *
+ * Key behaviors:
+ * - Validates and instantiates agents from a config-first model
+ * - Shares a mutable state object across all agents in the crew
+ * - Supports sub-agents and a function registry per agent
+ * - Tracks per-agent and crew-level metrics via MetricsRegistry
+ * - Provides helpers to add agents (individually, a subset, or all) and
+ *   to reset metrics/costs when needed
+ */
+declare class AxCrew {
+    private crewConfig;
+    private options?;
+    functionsRegistry: FunctionRegistryType;
+    crewId: string;
+    agents: Map<string, StatefulAxAgent> | null;
+    crewState: StateInstance;
+    private executionHistory;
+    constructor(crewConfig: AxCrewConfig, functionsRegistry?: FunctionRegistryType, options?: AxCrewOptions, crewId?: string);
+    /**
+     * Factory function for creating an agent.
+     */
+    createAgent: (agentName: string) => Promise<StatefulAxAgent>;
+    addAgent(agentName: string): Promise<void>;
+    addLazyAgent(agentName: string): void;
+    addAgentsToCrew(agentNames: string[]): Promise<Map<string, StatefulAxAgent> | null>;
+    addAllAgents(): Promise<Map<string, StatefulAxAgent> | null>;
+    trackAgentExecution(taskId: string, agentName: string, input: any): void;
+    recordAgentResult(taskId: string, agentName: string, result: any): void;
+    getTaskAgentInvolvement(taskId: string): {
+        rootAgent: string;
+        involvedAgents: string[];
+        taskInput: any;
+        agentResults: Map<string, any>;
+        duration?: number;
+    } | null;
+    applyTaskFeedback(params: {
+        taskId: string;
+        feedback: string;
+        strategy?: 'all' | 'primary' | 'weighted';
+    }): Promise<void>;
+    cleanupOldExecutions(maxAgeMs?: number): void;
+    destroy(): void;
+    resetCosts(): void;
+    getCrewMetrics(): import("../metrics/types.js").MetricsSnapshot;
+    resetCrewMetrics(): void;
+}
+export { AxCrew };

package/dist/agents/crew.js

@@ -0,0 +1,355 @@
+import { v4 as uuidv4 } from "uuid";
+import { createState } from "../state/index.js";
+import { parseCrewConfig, parseAgentConfig } from "./agentConfig.js";
+import { DeferredToolManager } from "./deferredTools.js";
+import { MetricsRegistry } from "../metrics/index.js";
+import { StatefulAxAgent } from "./statefulAgent.js";
+import { LazyStatefulAxAgent } from "./lazyAgent.js";
+/**
+ * AxCrew orchestrates a set of Ax agents that share state,
+ * tools (functions), optional MCP servers, streaming, and a built-in metrics
+ * registry for tokens, requests, and estimated cost.
+ *
+ * Typical usage:
+ *  const crew = new AxCrew(config, AxCrewFunctions)
+ *  await crew.addAllAgents()
+ *  const planner = crew.agents?.get("Planner")
+ *  const res = await planner?.forward({ task: "Plan something" })
+ *
+ * Key behaviors:
+ * - Validates and instantiates agents from a config-first model
+ * - Shares a mutable state object across all agents in the crew
+ * - Supports sub-agents and a function registry per agent
+ * - Tracks per-agent and crew-level metrics via MetricsRegistry
+ * - Provides helpers to add agents (individually, a subset, or all) and
+ *   to reset metrics/costs when needed
+ */
+class AxCrew {
+    crewConfig;
+    options;
+    functionsRegistry = {};
+    crewId;
+    agents;
+    crewState;
+    // Execution history for ACE feedback routing
+    executionHistory = new Map();
+    constructor(crewConfig, functionsRegistry = {}, options, crewId = uuidv4()) {
+        if (!crewConfig || typeof crewConfig !== 'object' || !('crew' in crewConfig)) {
+            throw new Error('Invalid crew configuration');
+        }
+        crewConfig.crew.forEach((agent) => {
+            if (!agent.name || agent.name.trim() === '') {
+                throw new Error('Agent name cannot be empty');
+            }
+        });
+        this.crewConfig = crewConfig;
+        this.functionsRegistry = functionsRegistry;
+        this.crewId = crewId;
+        this.options = options;
+        this.agents = new Map();
+        this.crewState = createState(crewId);
+        this.crewState.set('crewId', crewId);
+    }
+    /**
+     * Factory function for creating an agent.
+     */
+    createAgent = async (agentName) => {
+        try {
+            const agentConfig = await parseAgentConfig(agentName, this.crewConfig, this.functionsRegistry, this.crewState, this.options);
+            const { ai, name, executionMode, axAgentOptions, description, signature, functions, subAgentNames, examples, tracker } = agentConfig;
+            // Get subagents for the AI agent
+            const subAgents = subAgentNames.map((subAgentName) => {
+                if (!this.agents?.get(subAgentName)) {
+                    throw new Error(`Sub-agent '${subAgentName}' does not exist in available agents.`);
+                }
+                return this.agents?.get(subAgentName);
+            });
+            // Dedupe sub-agents by name
+            const subAgentSet = new Map();
+            for (const sa of subAgents.filter((agent) => agent !== undefined)) {
+                const n = sa?.agentName ?? sa?.name ?? '';
+                if (!subAgentSet.has(n))
+                    subAgentSet.set(n, sa);
+            }
+            const uniqueSubAgents = Array.from(subAgentSet.values());
+            // Dedupe functions by name and avoid collision with sub-agent names
+            const subAgentNameSet = new Set(uniqueSubAgents.map((sa) => sa?.agentName ?? sa?.name).filter(Boolean));
+            const uniqueFunctions = [];
+            const seenFn = new Set();
+            for (const fn of functions.filter((fn) => fn !== undefined)) {
+                const fnName = fn.name;
+                if (subAgentNameSet.has(fnName))
+                    continue;
+                if (!seenFn.has(fnName)) {
+                    seenFn.add(fnName);
+                    uniqueFunctions.push(fn);
+                }
+            }
+            // Resolve factory functions into AxFunction objects
+            const resolvedFunctions = uniqueFunctions.map(fn => typeof fn === 'function' ? fn() : fn);
+            // Wrap each function handler to record call count and latency
+            const crewId = this.crewId;
+            const agentNameForMetrics = name;
+            const instrumentedFunctions = resolvedFunctions.map(fn => ({
+                ...fn,
+                func: async (args, extra) => {
+                    const fnStart = performance.now();
+                    try {
+                        return await fn.func(args, extra);
+                    }
+                    finally {
+                        const latencyMs = performance.now() - fnStart;
+                        MetricsRegistry.recordFunctionCall({ crewId, agent: agentNameForMetrics }, latencyMs, fn.name);
+                    }
+                },
+            }));
+            // Deferred tool loading
+            const mcpFnNames = agentConfig.mcpFunctionNames ?? new Set();
+            const deferredConfig = agentConfig.deferredTools;
+            const deferredManager = new DeferredToolManager(instrumentedFunctions, mcpFnNames, deferredConfig);
+            const effectiveFunctions = deferredManager.isActive
+                ? deferredManager.getInitialFunctions()
+                : instrumentedFunctions;
+            if (deferredManager.isActive) {
+                console.log(`[ax-crew] Deferred tool loading active for "${name}": ` +
+                    `${effectiveFunctions.length} core + search_tools, ` +
+                    `${instrumentedFunctions.length - effectiveFunctions.length + 1} deferred`);
+            }
+            // Create the agent
+            const agentState = { ...this.crewState, crew: this };
+            const agent = new StatefulAxAgent(ai, {
+                name,
+                executionMode,
+                axAgentOptions,
+                description,
+                definition: agentConfig.definition,
+                signature,
+                functions: effectiveFunctions,
+                agents: uniqueSubAgents,
+                examples,
+                debug: agentConfig.debug,
+            }, agentState);
+            agent.costTracker = tracker;
+            if (deferredManager.isActive) {
+                agent.deferredToolManager = deferredManager;
+            }
+            agent.__functionsRegistry = this.functionsRegistry;
+            // Initialize ACE if configured
+            try {
+                const crewAgent = parseCrewConfig(this.crewConfig).crew.find(a => a.name === name);
+                const ace = crewAgent?.ace;
+                if (ace) {
+                    await agent.initACE?.(ace);
+                    if (ace.compileOnStart) {
+                        const { resolveMetric } = await import('./ace.js');
+                        const metric = resolveMetric(ace.metric, this.functionsRegistry);
+                        await agent.optimizeOffline?.({ metric, examples });
+                    }
+                }
+            }
+            catch { }
+            return agent;
+        }
+        catch (error) {
+            throw error;
+        }
+    };
+    async addAgent(agentName) {
+        try {
+            if (!this.agents) {
+                this.agents = new Map();
+            }
+            if (!this.agents.has(agentName)) {
+                this.agents.set(agentName, await this.createAgent(agentName));
+            }
+            if (this.agents && !this.agents.has(agentName)) {
+                this.agents.set(agentName, await this.createAgent(agentName));
+            }
+        }
+        catch (error) {
+            console.error(`Failed to create agent '${agentName}':`);
+            throw new Error(`Failed to add agent ${agentName}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    addLazyAgent(agentName) {
+        if (!this.agents) {
+            this.agents = new Map();
+        }
+        if (!this.agents.has(agentName)) {
+            this.agents.set(agentName, new LazyStatefulAxAgent(this, agentName, this.crewConfig));
+        }
+    }
+    async addAgentsToCrew(agentNames) {
+        try {
+            const parsedConfig = parseCrewConfig(this.crewConfig);
+            const dependencyMap = new Map();
+            parsedConfig.crew.forEach(agent => {
+                dependencyMap.set(agent.name, agent.agents || []);
+            });
+            const areDependenciesInitialized = (agentName) => {
+                const dependencies = dependencyMap.get(agentName) || [];
+                return dependencies.every(dep => this.agents?.has(dep));
+            };
+            const initializedAgents = new Set();
+            while (initializedAgents.size < agentNames.length) {
+                let madeProgress = false;
+                for (const agentName of agentNames) {
+                    if (initializedAgents.has(agentName))
+                        continue;
+                    if (areDependenciesInitialized(agentName)) {
+                        await this.addAgent(agentName);
+                        initializedAgents.add(agentName);
+                        madeProgress = true;
+                    }
+                }
+                if (!madeProgress) {
+                    const remaining = agentNames.filter(agent => !initializedAgents.has(agent));
+                    throw new Error(`Failed to initialize agents due to missing dependencies: ${remaining.join(', ')}`);
+                }
+            }
+            return this.agents;
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    async addAllAgents() {
+        try {
+            const parsedConfig = parseCrewConfig(this.crewConfig);
+            const dependencyMap = new Map();
+            parsedConfig.crew.forEach(agent => {
+                dependencyMap.set(agent.name, agent.agents || []);
+            });
+            const areDependenciesInitialized = (agentName) => {
+                const dependencies = dependencyMap.get(agentName) || [];
+                return dependencies.every(dep => this.agents?.has(dep));
+            };
+            const allAgents = parsedConfig.crew.map(agent => agent.name);
+            const initializedAgents = new Set();
+            while (initializedAgents.size < allAgents.length) {
+                let madeProgress = false;
+                for (const agentName of allAgents) {
+                    if (initializedAgents.has(agentName))
+                        continue;
+                    if (areDependenciesInitialized(agentName)) {
+                        await this.addAgent(agentName);
+                        initializedAgents.add(agentName);
+                        madeProgress = true;
+                    }
+                }
+                if (!madeProgress) {
+                    const remaining = allAgents.filter(agent => !initializedAgents.has(agent));
+                    throw new Error(`Circular dependency detected or missing dependencies for agents: ${remaining.join(', ')}`);
+                }
+            }
+            return this.agents;
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    // === ACE execution tracking ===
+    trackAgentExecution(taskId, agentName, input) {
+        if (!this.executionHistory.has(taskId)) {
+            this.executionHistory.set(taskId, {
+                taskId,
+                rootAgent: agentName,
+                involvedAgents: new Set([agentName]),
+                taskInput: input,
+                agentResults: new Map(),
+                startTime: Date.now()
+            });
+        }
+        else {
+            const context = this.executionHistory.get(taskId);
+            context.involvedAgents.add(agentName);
+        }
+    }
+    recordAgentResult(taskId, agentName, result) {
+        const context = this.executionHistory.get(taskId);
+        if (context) {
+            context.agentResults.set(agentName, result);
+            context.endTime = Date.now();
+        }
+    }
+    getTaskAgentInvolvement(taskId) {
+        const context = this.executionHistory.get(taskId);
+        if (!context)
+            return null;
+        return {
+            rootAgent: context.rootAgent,
+            involvedAgents: Array.from(context.involvedAgents),
+            taskInput: context.taskInput,
+            agentResults: context.agentResults,
+            duration: context.endTime ? context.endTime - context.startTime : undefined
+        };
+    }
+    async applyTaskFeedback(params) {
+        const involvement = this.getTaskAgentInvolvement(params.taskId);
+        if (!involvement) {
+            console.warn(`No execution history found for task ${params.taskId}`);
+            return;
+        }
+        const { involvedAgents, taskInput, agentResults } = involvement;
+        const strategy = params.strategy || 'all';
+        let agentsToUpdate = [];
+        if (strategy === 'primary') {
+            agentsToUpdate = [involvement.rootAgent];
+        }
+        else if (strategy === 'all' || strategy === 'weighted') {
+            agentsToUpdate = involvedAgents;
+        }
+        for (const agentName of agentsToUpdate) {
+            const agent = this.agents?.get(agentName);
+            if (agent && typeof agent.applyOnlineUpdate === 'function') {
+                try {
+                    await agent.applyOnlineUpdate({
+                        example: taskInput,
+                        prediction: agentResults.get(agentName),
+                        feedback: params.feedback
+                    });
+                }
+                catch (error) {
+                    console.warn(`Failed to apply ACE feedback to agent ${agentName}:`, error);
+                }
+            }
+        }
+    }
+    cleanupOldExecutions(maxAgeMs = 3600000) {
+        const cutoffTime = Date.now() - maxAgeMs;
+        for (const [taskId, context] of this.executionHistory) {
+            if (context.startTime < cutoffTime) {
+                this.executionHistory.delete(taskId);
+            }
+        }
+    }
+    // === Lifecycle ===
+    destroy() {
+        this.agents = null;
+        this.executionHistory.clear();
+        this.crewState.reset();
+    }
+    // === Metrics ===
+    resetCosts() {
+        if (this.agents) {
+            for (const [, agent] of this.agents) {
+                try {
+                    agent.resetUsage?.();
+                }
+                catch { }
+                try {
+                    agent.resetMetrics?.();
+                }
+                catch { }
+            }
+        }
+        MetricsRegistry.reset({ crewId: this.crewId });
+    }
+    getCrewMetrics() {
+        return MetricsRegistry.snapshotCrew(this.crewId);
+    }
+    resetCrewMetrics() {
+        MetricsRegistry.reset({ crewId: this.crewId });
+    }
+}
+export { AxCrew };

package/dist/agents/deferredTools.d.ts

@@ -0,0 +1,49 @@
+import type { AxFunction, AxStepHooks } from '@ax-llm/ax';
+export interface DeferredToolsConfig {
+    /** Enable deferred tool loading. Default: auto (true when tool count > threshold) */
+    enabled?: boolean;
+    /** Tool count threshold to activate deferred mode. Default: 20 */
+    threshold?: number;
+    /** Max tools returned per search. Default: 10 */
+    maxSearchResults?: number;
+    /** Tool names to always keep active (bypasses deferral) */
+    coreTools?: string[];
+}
+/**
+ * Manages deferred tool loading for agents with many tools.
+ *
+ * When tool count exceeds a threshold, only core tools + a `search_tools`
+ * meta-function are visible to the LLM. The LLM calls `search_tools` to
+ * discover and activate deferred tools, which are injected via ax-llm
+ * step hooks for subsequent turns.
+ */
+export declare class DeferredToolManager {
+    private registry;
+    private deferredNames;
+    private activatedNames;
+    private coreNames;
+    private readonly maxSearchResults;
+    private readonly _isActive;
+    private resourceCache;
+    constructor(allFunctions: readonly AxFunction[], mcpFunctionNames: ReadonlySet<string>, config?: DeferredToolsConfig);
+    /** Whether deferred mode is active */
+    get isActive(): boolean;
+    /** Get the initial function set (core tools + search_tools) */
+    getInitialFunctions(): AxFunction[];
+    /** Wrap a resource function so repeated calls return cached results */
+    private wrapWithCache;
+    /**
+     * Get step hooks for dynamic tool activation.
+     * - beforeStep: re-injects previously activated tools at the start of each
+     *   forward() call so tools discovered in earlier calls persist.
+     * - afterFunctionExecution: injects newly discovered tools after search_tools
+     *   runs, and auto-activates tools mentioned in function results.
+     */
+    getStepHooks(): AxStepHooks;
+    /** Scan function results for mentions of deferred tool names and auto-activate them. */
+    private autoActivateFromResults;
+    /** Search deferred tools by keyword matching on name + description */
+    private search;
+    /** Create the search_tools meta-function */
+    private createSearchToolFunction;
+}