@amitdeshmukh/ax-crew 8.7.3 → 9.0.1

package/src/skills/axcrew-functions.md

@@ -192,7 +192,7 @@ async function main() {
   const crew = new AxCrew(config, customFunctions);
 
   // Set state for class-based functions
-  crew.state.set("env", { API_BASE_URL: "https://api.example.com" });
+  crew.crewState.set("env", { API_BASE_URL: "https://api.example.com" });
 
   await crew.addAllAgents();
   const assistant = crew.agents?.get("assistant");
@@ -210,7 +210,7 @@ main().catch(console.error);
 ## Do Not Generate
 
 - Do NOT define functions inline in AgentConfig; always use a `FunctionRegistryType` registry passed to the `AxCrew` constructor.
-- Do NOT forget that class-based function constructors receive `state: Record<string, any>`, not `StateInstance`. Access values directly (e.g. `this.state.env`), since the state object is a plain record populated via `crew.state.set()`.
+- Do NOT forget that class-based function constructors receive `state: Record<string, any>`, not `StateInstance`. Access values directly (e.g. `this.state.env`), since the state object is a plain record populated via `crew.crewState.set()`.
 - Do NOT use a registry key that differs from the function name used in `AgentConfig.functions[]` -- they must match.
 - Do NOT import `AxCrewFunctions` from `@ax-llm/ax`; import from `@amitdeshmukh/ax-crew`.
 

package/src/skills/axcrew-mcp.md

@@ -1,6 +1,6 @@
 ---
 name: axcrew-mcp
-version: "8.7.3"
+version: "9.0.0"
 description: "ax-crew MCP integration: MCP, Model Context Protocol, STDIO, HTTP SSE, Streamable HTTP, mcpServers, tools, tool filtering, multiple servers"
 argument-hint: [topic]
 allowed-tools: Read, Grep, Glob
@@ -205,6 +205,46 @@ async function main() {
 main().catch(console.error);
 ```
 
+## Deferred Tool Loading
+
+When an agent has many MCP tools (20+), use the `deferredTools` config to reduce token usage. Only core tools + a `search_tools` meta-function are sent to the LLM. The LLM discovers additional tools on demand. Discovered tools persist across `forward()` calls. Tool results that mention deferred tool names (e.g., error responses suggesting `fix_query_error`) auto-activate those tools.
+
+```typescript
+{
+  name: "BigMCPAgent",
+  description: "Agent with many MCP tools",
+  signature: 'query:string -> answer:string',
+  provider: "anthropic",
+  providerKeyName: "ANTHROPIC_API_KEY",
+  ai: { model: "claude-sonnet-4-6", temperature: 0 },
+  mcpServers: {
+    "large-server": {
+      command: "npx",
+      args: ["-y", "some-large-mcp-server"],
+    },
+  },
+  deferredTools: {
+    enabled: true,       // default: auto (true when tool count > threshold)
+    threshold: 20,       // tool count to activate deferred mode
+    maxSearchResults: 10, // max tools returned per search
+    coreTools: ["execute_graphql", "list_tables"],  // always keep active
+  },
+}
+```
+
+### What is "core" vs "deferred"
+
+- **Core** (always visible): custom functions, sub-agent functions, `resource_*` functions, explicitly listed `coreTools`
+- **Deferred** (discoverable via search): MCP tool functions (except `resource_*`)
+
+### Resource Caching
+
+MCP `resource_*` functions (reference docs like query syntax guides) are automatically cached in-memory. Repeated calls return the cached result without re-fetching from the MCP server.
+
+## Prompt Caching
+
+Prompt caching is enabled by default for all agents. System prompts and tool definitions are cached across multi-step interactions via Anthropic's implicit caching or Gemini's context caching. This reduces token costs by up to 6x for agents with many tools — the system prompt (~13K tokens of tool schemas) is processed once and reused on subsequent steps.
+
 ## Supporting files
 - See [examples/mcp-agent.ts](examples/mcp-agent.ts) for a complete runnable example.
 - See [examples/graphjin-database-agent.ts](examples/graphjin-database-agent.ts) for Streamable HTTP transport.

package/src/skills/axcrew-patterns.md

@@ -1,6 +1,6 @@
 ---
 name: axcrew-patterns
-version: 8.7.3
+version: 9.0.0
 description: "AxCrew multi-agent patterns: pipeline, delegation, fan-out, orchestrator, sequential workflows, and agent coordination."
 tags: [patterns, workflow, pipeline, multi-agent, orchestrator, delegation, sequential, fan-out]
 ---
@@ -251,8 +251,8 @@ Target audience: intermediate developers familiar with TypeScript.`,
 All agents in a crew share a mutable `state` object for out-of-band data passing:
 
 ```ts
-crew.state.set("env", { WORDPRESS_URL: "http://...", WORDPRESS_USERNAME: "..." });
-crew.state.set("context", { userId: "abc-123" });
+crew.crewState.set("env", { WORDPRESS_URL: "http://...", WORDPRESS_USERNAME: "..." });
+crew.crewState.set("context", { userId: "abc-123" });
 
 // Inside a custom function, state is accessible via the constructor:
 class MyTool {
@@ -271,17 +271,61 @@ class MyTool {
 }
 ```
 
+## Cost Optimization Pattern (Single-Delegation Manager)
+
+When a manager orchestrates sub-agents, use a **single-delegation** pattern: send the full question to the sub-agent in one call. Do NOT break questions into sub-queries — the sub-agent handles multi-step work internally.
+
+This pattern reduced costs from $128 to $1 on the same query in testing.
+
+```ts
+{
+  name: "ManagerAgent",
+  description: "Orchestrates database queries and analysis tasks",
+  definition: `You are an orchestrator that routes questions to specialized agents.
+Delegate each question to the most relevant agent in a SINGLE call — do not break questions into sub-queries.
+The sub-agent will handle all the steps internally. Your job is to route and synthesize, not to decompose.
+If multiple agents are needed, call them and combine their answers.`,
+  signature: 'question:string -> answer:string',
+  provider: "anthropic" as Provider,
+  providerKeyName: "ANTHROPIC_API_KEY",
+  ai: { model: "claude-sonnet-4-6", maxTokens: 2000, temperature: 0 },
+  agents: ["DatabaseAgent", "AnalyticsAgent"],
+}
+```
+
+## Workflow Reuse Pattern (MCP Agents)
+
+For agents connected to MCP servers, use a strategy-driven definition that checks for saved workflows before building new ones. This ensures repeat questions reuse cached workflows ($0.17) instead of rebuilding from scratch ($0.55).
+
+```ts
+{
+  name: "DatabaseAgent",
+  definition: `You answer questions by querying databases via an MCP server.
+
+STRATEGY:
+1. Check first — call list_workflows and list_saved_queries. If a match exists, execute it directly.
+2. Learn — read resource docs, list tables, describe schema.
+3. Build — author a JS workflow with server-side computation, validate with a test query.
+4. Save and run — save the workflow for reuse, then execute it.
+5. If a query fails, call fix_query_error to diagnose. Do not retry the same query.
+6. Synthesize the answer from results.`,
+  // ...
+}
+```
+
 ## Supporting files
 - See [examples/write-post-and-publish-to-wordpress.ts](examples/write-post-and-publish-to-wordpress.ts) for a complete pipeline example.
 - See [examples/solve-math-problem.ts](examples/solve-math-problem.ts) for a delegation example.
+- See [examples/graphjin-database-agent.ts](examples/graphjin-database-agent.ts) for single-delegation + workflow reuse pattern.
 
 ## Do Not Generate
 
 - Do NOT add a parent agent before its sub-agents -- `addAgentsToCrew` resolves dependencies but `addAgent` does not.
 - Do NOT use `agents: ["SelfName"]` -- an agent cannot be its own sub-agent (circular dependency error).
-- Do NOT assume agents share conversation context -- they share `state` but each `forward()` call is independent. Pass data explicitly via signatures.
+- Do NOT assume agents share conversation context -- they share `crewState` but each `forward()` call is independent. Pass data explicitly via signatures.
 - Do NOT use `definition` shorter than 100 characters -- Ax requires minimum length for program definitions.
 - Do NOT confuse `description` (used as the tool description when this agent is a sub-agent) with `definition` (the system prompt).
+- Do NOT have the manager decompose questions into sub-queries -- send the full question to the sub-agent in one call.
 
 ## References
 

package/src/skills/axcrew-state.md

@@ -1,12 +1,12 @@
 ---
 name: axcrew-state
-version: 8.7.3
+version: 9.0.0
 description: "State management: shared state, StateInstance, set, get, getAll, reset, accessing state from class-based functions"
 ---
 
 # State
 
-Every `AxCrew` instance has a shared `StateInstance` at `crew.state`. All agents and class-based functions in the crew can access the same state.
+Every `AxCrew` instance has a shared `StateInstance` at `crew.crewState`. All agents and class-based functions in the crew can access the same state.
 
 ## StateInstance API
 
@@ -21,9 +21,9 @@ interface StateInstance {
 
 ## Core Behavior
 
-- `crew.state` is created automatically when `new AxCrew(config)` is called.
+- `crew.crewState` is created automatically when `new AxCrew(config)` is called.
 - State is keyed by `crewId` (auto-generated UUID). Each crew instance has its own isolated state.
-- State persists for the lifetime of the crew. Calling `crew.destroy()` calls `state.reset()`.
+- State persists for the lifetime of the crew. Calling `crew.destroy()` calls `crewState.reset()`.
 - Values can be any type: strings, objects, arrays, etc.
 
 ## Canonical Pattern
@@ -53,7 +53,7 @@ class SendEmail {
         required: ['to', 'subject', 'body']
       },
       func: async ({ to, subject, body }: { to: string; subject: string; body: string }) => {
-        // Access env credentials set via crew.state.set("env", {...})
+        // Access env credentials set via crew.crewState.set("env", {...})
         const env = this.state.env || {};
         const smtpHost = env.SMTP_HOST;
         const smtpUser = env.SMTP_USER;
@@ -84,15 +84,15 @@ async function main() {
   const crew = new AxCrew(config, functions);
 
   // Set environment variables in shared state BEFORE adding agents
-  crew.state.set("env", {
+  crew.crewState.set("env", {
     SMTP_HOST: "smtp.example.com",
     SMTP_USER: "user@example.com",
     SMTP_PASS: "secret",
   });
 
   // You can also set arbitrary data
-  crew.state.set("company", "Acme Corp");
-  crew.state.set("maxRetries", 3);
+  crew.crewState.set("company", "Acme Corp");
+  crew.crewState.set("maxRetries", 3);
 
   await crew.addAllAgents();
   const notifier = crew.agents?.get("notifier");
@@ -101,11 +101,11 @@ async function main() {
   console.log(result?.result);
 
   // Read state back
-  console.log("All state:", crew.state.getAll());
-  console.log("Company:", crew.state.get("company"));
+  console.log("All state:", crew.crewState.getAll());
+  console.log("Company:", crew.crewState.get("company"));
 
   // Reset state (clear all)
-  crew.state.reset();
+  crew.crewState.reset();
 
   crew.destroy();
 }
@@ -118,7 +118,7 @@ main().catch(console.error);
 The common pattern for passing credentials to class-based functions:
 
 ```ts
-crew.state.set("env", {
+crew.crewState.set("env", {
   WORDPRESS_URL: "http://my-wordpress-site.com",
   WORDPRESS_USERNAME: "my-username",
   WORDPRESS_PASSWORD: "my-password",
@@ -147,11 +147,11 @@ class MyFunction {
 
 ## Accessing State from Agents
 
-Each `StatefulAxAgent` has a `state` property that references the crew's shared state:
+Each `StatefulAxAgent` has a `crewState` property that references the crew's shared state:
 
 ```ts
 const agent = crew.agents?.get("myAgent");
-// agent.state is the same StateInstance as crew.state
+// agent.crewState is the same StateInstance as crew.crewState
 ```
 
 ## Supporting files
@@ -160,8 +160,8 @@ const agent = crew.agents?.get("myAgent");
 ## Do Not Generate
 
 - Do NOT assume state values exist without checking; always use optional chaining (e.g. `this.state.env?.KEY`).
-- Do NOT call `crew.state.set("env", ...)` after `addAllAgents()` if class-based functions read state during construction -- set state first.
-- Do NOT confuse `crew.state` (StateInstance with `set`/`get`/`getAll`/`reset`) with plain objects. The state object passed to class-based function constructors is a plain record, not the `StateInstance` interface.
+- Do NOT call `crew.crewState.set("env", ...)` after `addAllAgents()` if class-based functions read state during construction -- set state first.
+- Do NOT confuse `crew.crewState` (StateInstance with `set`/`get`/`getAll`/`reset`) with plain objects. The state object passed to class-based function constructors is a plain record, not the `StateInstance` interface.
 - Do NOT store sensitive credentials in state if the state object might be logged or serialized. The `getAll()` method returns all stored values.
 
 ## References

package/src/skills/axcrew.md

@@ -98,11 +98,24 @@ new AxCrew(crewConfig: AxCrewConfig, functionsRegistry?: FunctionRegistryType, o
 | `crew.agents?.get("A")` | Retrieve a `StatefulAxAgent` |
 | `await agent.forward({ key: "value" })` | Run the agent |
 | `agent.streamingForward({ key: "value" })` | Stream output chunks |
-| `crew.state` | Shared `StateInstance` across all agents |
+| `crew.crewState` | Shared `StateInstance` across all agents |
 | `crew.resetCosts()` | Reset usage/metrics for all agents |
 | `crew.getCrewMetrics()` | Aggregate metrics snapshot |
 | `crew.destroy()` | Clean up agents, state, execution history |
 
+## Deferred Tool Loading
+
+Agents with many MCP tools can use `deferredTools` in their agent config to avoid overwhelming the LLM context. When the total tool count exceeds a threshold (default 20), only core tools plus a `search_tools` meta-tool are visible to the agent. The LLM discovers additional tools by calling `search_tools`, which uses local multi-signal search (no API calls). Discovered tools persist across `forward()` calls, and related tools are proactively activated alongside the requested tool.
+
+```ts
+{
+  name: "BigToolAgent",
+  // ...
+  mcpServers: { /* ... */ },
+  deferredTools: { maxTools: 20 },  // optional, 20 is the default threshold
+}
+```
+
 ## Related Skills
 
 - `ax-crew-agent-config` -- AgentConfig fields, provider setup, executionMode

package/src/types.ts

@@ -202,6 +202,22 @@ interface ACEConfig {
   compileOnStart?: boolean;
 }
 
+/**
+ * Configuration for deferred tool loading.
+ * When an agent has many tools, only core tools are visible by default.
+ * A search_tools meta-function lets the LLM discover and activate deferred tools on demand.
+ */
+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[];
+}
+
 /**
  * The configuration for an agent.
  * 
@@ -261,6 +277,8 @@ interface AgentConfig {
   mcpServers?: Record<string, MCPTransportConfig>;
   /** Optional AxACE configuration to enable optimization for this agent */
   ace?: ACEConfig;
+  /** Deferred tool loading — reduces token usage when an agent has many tools */
+  deferredTools?: DeferredToolsConfig;
 }
 
 /**
@@ -335,6 +353,7 @@ export {
   type ModelInfo,
   type UsageCost,
   type AggregatedCosts,
+  type DeferredToolsConfig,
   // ACE exports
   type ACEConfig,
   type ACEMetricConfig,

package/.claude/settings.local.json

@@ -1,13 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm test:*)",
-      "Bash(git push:*)",
-      "Bash(git status:*)",
-      "Bash(node:*)",
-      "Bash(npm version:*)",
-      "WebFetch(domain:github.com)",
-      "WebFetch(domain:tanstack.com)"
-    ]
-  }
-}