anyclaude-sdk 0.7.4 → 0.8.1

package/README.md

@@ -386,6 +386,20 @@ npm create anyclaude-app@latest my-app   # template: bolt — WebContainer + cha
 
 The `bolt` template wires `useWebContainerPreview({ wc })` (boot a dev server → live preview URL) + a browser-side `query()` + the IDE components. See [`anyclaude-react`](#react-ui-kit--anyclaude-react).
 
+## Token efficiency — deferred tools
+
+Keep a large pool of rarely-used tools **out of the per-turn payload** (big savings on weak/uncached models) while staying discoverable + callable. Mark them deferred; `tool_search` indexes them and the loop **arms** a tool (sends its schema on subsequent turns) once search surfaces it — then it executes normally.
+
+```ts
+query({ prompt, workspace, llm,
+  extraTools: [deploy, ...integrationTools],   // e.g. 35 integration tools
+  deferredTools: ['stripe_charge', 'supabase_query', /* … the niche ones */],
+})
+// or per-tool: defineTool({ name, description, parameters, run, defer: true })
+```
+
+Only the lean core + `tool_search` are sent each turn; the model searches when it needs a niche tool, the SDK arms it, and the call goes through. Register 35, send ~10.
+
 ## Other niceties
 
 - **Live compaction marker** — `autoCompact` emits a `compact_boundary` with `status: 'start'` *before* summarizing (for a live "compacting…" shimmer) and `status: 'end'` after with `post_tokens`.
@@ -402,7 +416,7 @@ Runnable Vite projects in [`examples/`](examples/): **`browser-ide`** (WebContai
   - `prompt: string | AsyncIterable<SDKUserMessage>`
   - `workspace: FileSystem & CommandExecutor`
   - `llm: LLMClient`
-  - `tools?`, `extraTools?`, `allowedTools?`/`disallowedTools?`, `model?`, `systemPrompt?`/`appendSystemPrompt?`, `maxTurns?` (default 50), `cwd?`, `abortController?`
+  - `tools?`, `extraTools?`, `allowedTools?`/`disallowedTools?`, `deferredTools?` (lazy-load), `model?`, `systemPrompt?`/`appendSystemPrompt?`, `maxTurns?` (default 50), `cwd?`, `abortController?`
   - serverless: `sessionStore?`, `resume?`, `maxDurationMs?`, `continueRun?`
   - client tools: `clientTools?`, `clientToolResults?`; interactive: `onAskUser?`
   - also: `mcpServers?`, `agents?`, `commands?`, `hooks?`, `background?`, `team?`, `memory?`, `permissionMode?`/`canUseTool?`, `messageQueue?`

package/dist/agent.d.ts

@@ -26,6 +26,11 @@ export interface AgentOptions {
     allowedTools?: string[];
     /** Denylist of tool names, applied after allowedTools. */
     disallowedTools?: string[];
+    /** Tool names to DEFER out of the per-turn payload — still discoverable via
+     *  `tool_search` and executable, but their schema isn't sent (saving tokens)
+     *  until the model searches and the loop arms them. For large pools of
+     *  rarely-used integration tools. (Per-tool `defer: true` works too.) */
+    deferredTools?: string[];
     maxTurns?: number;
     /** Wall-clock budget (ms). At a turn boundary past this, the loop pauses: it
      *  persists to sessionStore and emits a `paused` system message instead of

package/dist/agent.js

@@ -263,8 +263,17 @@ export async function* runAgent(options) {
     for (const t of tools)
         if (!t.run)
             clientTools.add(t.def.function.name);
-    const defs = toolDefs(tools);
+    const defs = toolDefs(tools); // FULL set — for the search index, suppression, and call recovery
     const byName = toolByName(tools);
+    // Deferred tools: kept OUT of the per-turn payload (token savings) but still
+    // discoverable via tool_search and executable. `tool_search` surfaces them and
+    // arms them (adds their schema to subsequent turns). tool_search itself is
+    // never deferred, or discovery breaks.
+    const deferredSet = new Set([...(options.deferredTools ?? []), ...tools.filter((t) => t.defer).map((t) => t.def.function.name)].filter((n) => n !== 'tool_search'));
+    const armed = new Set();
+    const sentDefs = () => deferredSet.size
+        ? toolDefs(tools.filter((t) => !deferredSet.has(t.def.function.name) || armed.has(t.def.function.name)))
+        : defs;
     // Stop streaming visible deltas once tool-call / reasoning markup begins (native
     // dialects, <thinking>, or named-tag tools like <finish>); final text is cleaned.
     const streamSuppressRe = (() => {
@@ -302,6 +311,13 @@ export async function* runAgent(options) {
         memory,
         skills,
         planMode,
+        armTools: deferredSet.size
+            ? (names) => {
+                for (const n of names)
+                    if (deferredSet.has(n))
+                        armed.add(n);
+            }
+            : undefined,
     };
     const skillCommands = skillsToCommands(skills);
     const allCommands = [...(options.commands ?? []), ...skillCommands];
@@ -412,7 +428,7 @@ export async function* runAgent(options) {
         subtype: 'init',
         apiKeySource: 'none',
         cwd,
-        tools: defs.map((d) => d.function.name),
+        tools: sentDefs().map((d) => d.function.name),
         mcp_servers: mcpStatuses,
         model: model ?? 'unknown',
         permissionMode,
@@ -641,7 +657,7 @@ export async function* runAgent(options) {
                     let inToolMarkup = false;
                     const sp = llm.streamChat(history, {
                         model,
-                        tools: defs,
+                        tools: sentDefs(),
                         signal,
                         onToken: (delta) => {
                             streamedText += delta;
@@ -673,7 +689,7 @@ export async function* runAgent(options) {
                 else {
                     result = await llm.streamChat(history, {
                         model,
-                        tools: defs,
+                        tools: sentDefs(),
                         signal,
                         onToken: (delta) => {
                             streamedText += delta;

package/dist/query.d.ts

@@ -22,6 +22,9 @@ export interface QueryOptions {
     appendSystemPrompt?: string;
     allowedTools?: string[];
     disallowedTools?: string[];
+    /** Tool names to defer out of the per-turn payload — discoverable via `tool_search`
+     *  and armed on demand. Saves tokens on large tool pools (also per-tool `defer: true`). */
+    deferredTools?: string[];
     maxTurns?: number;
     /** Wall-clock budget (ms): pause at a turn boundary past this + emit `paused` (survivor). */
     maxDurationMs?: number;

package/dist/query.js

@@ -21,6 +21,7 @@ export function query(options) {
         appendSystemPrompt: options.appendSystemPrompt,
         allowedTools: options.allowedTools,
         disallowedTools: options.disallowedTools,
+        deferredTools: options.deferredTools,
         maxTurns: options.maxTurns,
         maxDurationMs: options.maxDurationMs,
         continueRun: options.continueRun,

package/dist/tools/define.d.ts

@@ -15,6 +15,9 @@ export interface DefineToolSpec {
     run?: (input: Record<string, unknown>, ctx: ToolContext) => Promise<ToolResult> | ToolResult;
     /** Optional: spill threshold for large outputs (see Tool.maxResultChars). */
     maxResultChars?: number;
+    /** Defer out of the per-turn payload — discoverable via `tool_search`, armed on
+     *  demand. For large pools of rarely-used tools (see Tool.defer). */
+    defer?: boolean;
 }
 /** Build a `Tool` from a friendly spec. */
 export declare function defineTool(spec: DefineToolSpec): Tool;

package/dist/tools/define.js

@@ -19,5 +19,7 @@ export function defineTool(spec) {
         tool.run = async (input, ctx) => spec.run(input, ctx);
     if (spec.maxResultChars !== undefined)
         tool.maxResultChars = spec.maxResultChars;
+    if (spec.defer)
+        tool.defer = true;
     return tool;
 }

package/dist/tools/tool_search.js

@@ -41,8 +41,11 @@ export const toolSearch = {
             .slice(0, limit);
         if (!scored.length)
             return { content: `No tools matched "${q}".` };
+        // Arm any deferred tools we surfaced so their full schema is sent next turn
+        // and the model can call them directly.
+        ctx.armTools?.(scored.map(({ t }) => t.name));
         return {
-            content: `Matching tools for "${q}":\n` +
+            content: `Matching tools for "${q}" (now available to call):\n` +
                 scored.map(({ t }) => `  ${t.name} — ${t.description.split('\n')[0]}`).join('\n'),
         };
     },

package/dist/tools/types.d.ts

@@ -72,6 +72,9 @@ export interface ToolContext {
     planMode?: {
         active: boolean;
     };
+    /** Arm deferred tools by name so their full schema is sent on subsequent turns.
+     *  Provided by the loop; `tool_search` calls it for the deferred tools it surfaces. */
+    armTools?: (names: string[]) => void;
 }
 /** Result returned by a tool run. */
 export interface ToolResult {
@@ -92,4 +95,12 @@ export interface Tool {
      * When omitted, the loop uses its global default threshold.
      */
     maxResultChars?: number;
+    /**
+     * DEFER this tool out of the per-turn payload sent to the LLM. It stays
+     * discoverable via `tool_search` and executable when called, but its schema
+     * isn't sent (saving tokens every turn) until `tool_search` surfaces it — at
+     * which point the loop "arms" it for subsequent turns. Use for large pools of
+     * rarely-used integration tools. (Also settable via `query({ deferredTools })`.)
+     */
+    defer?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anyclaude-sdk",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "description": "Standalone, browser-compatible SDK providing Claude Code agent capabilities (tools, tool loop, multi-turn, MCP, sub-agents, sessions) against any OpenAI/Anthropic-compatible LLM endpoint. Runs in the browser (WebContainer), Node, and Bun — no backend required.",
   "type": "module",
   "main": "./dist/index.js",