anyclaude-sdk 0.4.6 → 0.4.8

package/dist/agent.d.ts

@@ -38,6 +38,11 @@ export interface AgentOptions {
      *  one, the loop emits a `client_tool_request` + pauses; the client runs it and
      *  resumes (continueRun) with `clientToolResults`. (e.g. bash on a browser WebContainer.) */
     clientTools?: string[];
+    /** One switch to delegate ALL built-in workspace tools (bash + file ops) to the
+     *  host: the server emits client_tool_request for them and NEVER runs them
+     *  against its own (in-memory) workspace — execution happens client-side
+     *  (e.g. a browser WebContainer / IndexedDB via createWorkspaceClientTools). */
+    clientWorkspaceTools?: boolean;
     /** Results for client-tool calls, injected into the transcript before continuing. */
     clientToolResults?: Array<{
         tool_use_id: string;

package/dist/agent.js

@@ -8,7 +8,7 @@
 //   5. Execute each tool against the workspace
 //   6. Run PostToolUse hooks; append results to the message history
 //   7. Repeat until no tool calls or max turns reached
-import { ALL_CLAUDE_CODE_TOOLS, toolByName, toolDefs } from './tools/index.js';
+import { ALL_CLAUDE_CODE_TOOLS, toolByName, toolDefs, WORKSPACE_TOOL_NAMES } from './tools/index.js';
 import { task as taskTool } from './tools/task.js';
 import { askUserQuestion } from './tools/ask_user.js';
 import { loadMcpServers } from './mcp/index.js';
@@ -250,6 +250,16 @@ export async function* runAgent(options) {
         tools = [...localTools, ...loaded.tools];
         mcpStatuses = loaded.statuses.map((s) => ({ name: s.name, status: s.status }));
     }
+    // Delegation set: explicit clientTools, plus (one switch) every built-in
+    // workspace tool when clientWorkspaceTools is on, plus any tool with no `run`
+    // (Vercel-style "no execute = client"). These emit client_tool_request and are
+    // never executed on the server.
+    if (options.clientWorkspaceTools)
+        for (const n of WORKSPACE_TOOL_NAMES)
+            clientTools.add(n);
+    for (const t of tools)
+        if (!t.run)
+            clientTools.add(t.def.function.name);
     const defs = toolDefs(tools);
     const byName = toolByName(tools);
     let system = options.systemPrompt != null ? options.systemPrompt : defaultSystemPrompt(cwd);
@@ -707,8 +717,11 @@ export async function* runAgent(options) {
                 let content = '';
                 let isError = false;
                 let extraContext = '';
-                if (!tool) {
-                    content = `Error: unknown tool "${name}"`;
+                if (!tool || !tool.run) {
+                    // Unknown, or a run-less (client-delegated) tool that somehow reached
+                    // server execution — both are errors here (delegated tools are handled
+                    // above via clientTools).
+                    content = `Error: ${tool ? `tool "${name}" has no server executor (it is client-delegated)` : `unknown tool "${name}"`}`;
                     isError = true;
                 }
                 else {

package/dist/index.d.ts

@@ -25,3 +25,4 @@ export { uuid } from './util/ids.js';
 export * as paths from './util/paths.js';
 export { priceFor, computeCostUSD, contextWindowFor, type Pricing } from './util/pricing.js';
 export { estimateTokens, summarizeHistory, compactWithWindow } from './compact.js';
+export { runToolLoop, type RunToolLoopOptions } from './loop.js';

package/dist/index.js

@@ -27,4 +27,5 @@ export { uuid } from './util/ids.js';
 export * as paths from './util/paths.js';
 export { priceFor, computeCostUSD, contextWindowFor } from './util/pricing.js';
 export { estimateTokens, summarizeHistory, compactWithWindow } from './compact.js';
+export { runToolLoop } from './loop.js';
 // (createResponsesClient is exported via ./llm/index.js)

package/dist/loop.d.ts

@@ -0,0 +1,45 @@
+import type { CanUseTool, ChatMsg, LLMClient, SDKMessage } from './types/index.js';
+import type { Tool, ToolContext } from './tools/types.js';
+export interface RunToolLoopOptions {
+    /** Conversation so far: `[systemMsg, ...]`. Mutated in place as the loop appends turns. */
+    history: ChatMsg[];
+    /** Tools the model may call (executed via `ctx`). */
+    tools: Tool[];
+    /** Any OpenAI/Anthropic-compatible client. */
+    llm: LLMClient;
+    model?: string;
+    /** Tool-execution context (fs / exec / cwd / readFiles / limits …). */
+    ctx: ToolContext;
+    /** Max LLM turns before stopping with `error_max_turns`. Default 50. */
+    maxTurns?: number;
+    signal?: AbortSignal;
+    /** Optional permission gate; a `deny` result turns into an error tool_result. */
+    canUseTool?: CanUseTool;
+    /** Tool names to DELEGATE to the host instead of running via `ctx` (inline). A
+     *  tool with no `run` is auto-delegated too (Vercel-style "no execute = client"). */
+    clientTools?: string[];
+    /** Executor for delegated tools — runs the call (e.g. on a browser WebContainer)
+     *  and returns the result inline. Required if any tool is delegated. */
+    onClientTool?: (req: {
+        tool_use_id: string;
+        name: string;
+        input: Record<string, unknown>;
+    }) => Promise<{
+        content: unknown;
+        is_error?: boolean;
+    }> | {
+        content: unknown;
+        is_error?: boolean;
+    };
+    /** Emit `stream_event` text deltas as the assistant streams. */
+    includePartialMessages?: boolean;
+    /** Correlation id stamped on every emitted SDKMessage. */
+    sessionId?: string;
+}
+/**
+ * Run the bare tool loop, yielding SDKMessages until the model stops or maxTurns.
+ *
+ *   const ctx = { fs, exec, cwd: '/work', readFiles: new Set() } as ToolContext
+ *   for await (const m of runToolLoop({ history, tools, llm, model, ctx })) render(m)
+ */
+export declare function runToolLoop(opts: RunToolLoopOptions): AsyncGenerator<SDKMessage>;

package/dist/loop.js

@@ -0,0 +1,305 @@
+import { toolByName, toolDefs } from './tools/index.js';
+import { uuid } from './util/ids.js';
+const emptyUsage = () => ({ input_tokens: 0, output_tokens: 0 });
+function addUsage(t, b) {
+    if (!b)
+        return;
+    t.input_tokens += b.input_tokens || 0;
+    t.output_tokens += b.output_tokens || 0;
+    t.cache_read_input_tokens = (t.cache_read_input_tokens || 0) + (b.cache_read_input_tokens || 0);
+    t.cache_creation_input_tokens = (t.cache_creation_input_tokens || 0) + (b.cache_creation_input_tokens || 0);
+}
+function safeParse(json) {
+    if (!json || !json.trim())
+        return {};
+    try {
+        const v = JSON.parse(json);
+        return v && typeof v === 'object' ? v : { value: v };
+    }
+    catch {
+        return { _raw: json };
+    }
+}
+function toolUseBlocks(calls) {
+    return calls.map((c) => ({ type: 'tool_use', id: c.id, name: c.function.name, input: safeParse(c.function.arguments) }));
+}
+function resultToText(content) {
+    if (typeof content === 'string')
+        return content;
+    return content
+        .map((b) => (b.type === 'text' ? b.text : b.type === 'image' ? '[image]' : b.type === 'document' ? '[document]' : `[${b.type}]`))
+        .join('\n');
+}
+function toToolResultContent(content) {
+    if (typeof content === 'string')
+        return content;
+    return content.filter((b) => b.type === 'text' || b.type === 'image' || b.type === 'document');
+}
+function createPushQueue() {
+    const items = [];
+    let resolveNext = null;
+    let closed = false;
+    return {
+        push(v) {
+            if (resolveNext) {
+                resolveNext({ value: v, done: false });
+                resolveNext = null;
+            }
+            else
+                items.push(v);
+        },
+        close() {
+            closed = true;
+            if (resolveNext) {
+                resolveNext({ value: undefined, done: true });
+                resolveNext = null;
+            }
+        },
+        [Symbol.asyncIterator]() {
+            return {
+                next: () => {
+                    if (items.length)
+                        return Promise.resolve({ value: items.shift(), done: false });
+                    if (closed)
+                        return Promise.resolve({ value: undefined, done: true });
+                    return new Promise((res) => (resolveNext = res));
+                },
+            };
+        },
+    };
+}
+/**
+ * Run the bare tool loop, yielding SDKMessages until the model stops or maxTurns.
+ *
+ *   const ctx = { fs, exec, cwd: '/work', readFiles: new Set() } as ToolContext
+ *   for await (const m of runToolLoop({ history, tools, llm, model, ctx })) render(m)
+ */
+export async function* runToolLoop(opts) {
+    const { history, llm, model, ctx, signal, canUseTool, onClientTool } = opts;
+    const tools = opts.tools;
+    const clientTools = new Set(opts.clientTools ?? []);
+    const maxTurns = opts.maxTurns ?? 50;
+    const sessionId = opts.sessionId ?? uuid();
+    const emitPartial = !!opts.includePartialMessages;
+    const byName = toolByName(tools);
+    const defs = toolDefs(tools);
+    const startedAt = Date.now();
+    let apiMs = 0;
+    let turns = 0;
+    let lastText = '';
+    let resultModel = model ?? 'unknown';
+    let hitMaxTurns = false;
+    let errored = null;
+    const usageTotal = emptyUsage();
+    while (true) {
+        if (signal?.aborted)
+            break;
+        if (turns >= maxTurns) {
+            hitMaxTurns = true;
+            break;
+        }
+        turns++;
+        let streamedText = '';
+        let captured = [];
+        const apiStart = Date.now();
+        let result;
+        try {
+            if (emitPartial) {
+                const q = createPushQueue();
+                let inToolMarkup = false;
+                const sp = llm.streamChat(history, {
+                    model,
+                    tools: defs,
+                    signal,
+                    onToken: (delta) => {
+                        streamedText += delta;
+                        if (!inToolMarkup && /<tool_call|<function\s*=/.test(streamedText))
+                            inToolMarkup = true;
+                        if (inToolMarkup)
+                            return;
+                        q.push({
+                            type: 'stream_event',
+                            event: { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: delta } },
+                            parent_tool_use_id: null,
+                            uuid: uuid(),
+                            session_id: sessionId,
+                        });
+                    },
+                    onTool: (calls) => {
+                        captured = calls;
+                    },
+                });
+                sp.then(() => { }, () => { }).finally(() => q.close());
+                for await (const ev of q)
+                    yield ev;
+                result = await sp;
+            }
+            else {
+                result = await llm.streamChat(history, {
+                    model,
+                    tools: defs,
+                    signal,
+                    onToken: (delta) => {
+                        streamedText += delta;
+                    },
+                    onTool: (calls) => {
+                        captured = calls;
+                    },
+                });
+            }
+        }
+        catch (err) {
+            errored = err instanceof Error ? err.message : String(err);
+            break;
+        }
+        apiMs += Date.now() - apiStart;
+        const text = result.text || streamedText;
+        const calls = result.toolCalls.length ? result.toolCalls : captured;
+        lastText = text || lastText;
+        resultModel = result.model || resultModel;
+        addUsage(usageTotal, result.usage);
+        const stopReason = calls.length ? 'tool_use' : result.stopReason ?? 'end_turn';
+        const assistantContent = [];
+        if (text)
+            assistantContent.push({ type: 'text', text });
+        assistantContent.push(...toolUseBlocks(calls));
+        const apiAssistant = {
+            id: 'msg_' + uuid().replace(/-/g, '').slice(0, 24),
+            type: 'message',
+            role: 'assistant',
+            model: resultModel,
+            content: assistantContent,
+            stop_reason: stopReason,
+            stop_sequence: null,
+            usage: result.usage ?? emptyUsage(),
+        };
+        yield { type: 'assistant', message: apiAssistant, parent_tool_use_id: null, uuid: uuid(), session_id: sessionId };
+        history.push({ role: 'assistant', content: text, tool_calls: calls.length ? calls : undefined });
+        if (!calls.length)
+            break;
+        const toolResultBlocks = [];
+        const turnMedia = [];
+        for (const call of calls) {
+            if (signal?.aborted)
+                break;
+            const name = call.function.name;
+            let input = safeParse(call.function.arguments);
+            const tool = byName.get(name);
+            let content = '';
+            let isError = false;
+            // Delegated tool (listed in clientTools, or has no `run`): execute on the
+            // host via onClientTool instead of `ctx` — never touches the server FS.
+            const delegated = clientTools.has(name) || (tool != null && !tool.run);
+            if (delegated) {
+                if (!onClientTool) {
+                    content = `No client executor for "${name}" (delegated tool; pass onClientTool).`;
+                    isError = true;
+                }
+                else {
+                    try {
+                        const r = await onClientTool({ tool_use_id: call.id, name, input });
+                        content = (typeof r.content === 'string' ? r.content : JSON.stringify(r.content ?? ''));
+                        isError = !!r.is_error;
+                    }
+                    catch (err) {
+                        content = `Error (client) ${name}: ${err instanceof Error ? err.message : String(err)}`;
+                        isError = true;
+                    }
+                }
+            }
+            else if (!tool) {
+                content = `Error: unknown tool "${name}"`;
+                isError = true;
+            }
+            else {
+                const decision = canUseTool
+                    ? await canUseTool(name, input, { signal, toolUseId: call.id })
+                    : { behavior: 'allow' };
+                if (decision.behavior === 'deny') {
+                    content = `Permission denied: ${decision.message}`;
+                    isError = true;
+                }
+                else {
+                    if ('updatedInput' in decision && decision.updatedInput)
+                        input = decision.updatedInput;
+                    try {
+                        const r = await tool.run(input, ctx);
+                        content = r.content;
+                        isError = !!r.isError;
+                    }
+                    catch (err) {
+                        content = `Error executing ${name}: ${err instanceof Error ? err.message : String(err)}`;
+                        isError = true;
+                    }
+                }
+            }
+            const textOut = resultToText(content);
+            history.push({ role: 'tool', tool_call_id: call.id, content: textOut });
+            if (Array.isArray(content)) {
+                for (const b of content)
+                    if (b.type === 'image' || b.type === 'document')
+                        turnMedia.push(b);
+            }
+            toolResultBlocks.push({
+                type: 'tool_result',
+                tool_use_id: call.id,
+                content: typeof content === 'string' ? textOut : toToolResultContent(content),
+                is_error: isError || undefined,
+            });
+        }
+        if (turnMedia.length) {
+            history.push({
+                role: 'user',
+                content: [{ type: 'text', text: 'Attached file content from the tools above:' }, ...turnMedia],
+            });
+        }
+        if (toolResultBlocks.length) {
+            yield {
+                type: 'user',
+                message: { role: 'user', content: toolResultBlocks },
+                parent_tool_use_id: null,
+                isSynthetic: true,
+                timestamp: new Date().toISOString(),
+                uuid: uuid(),
+                session_id: sessionId,
+            };
+        }
+    }
+    const durationMs = Date.now() - startedAt;
+    if (errored || hitMaxTurns) {
+        yield {
+            type: 'result',
+            subtype: hitMaxTurns ? 'error_max_turns' : 'error_during_execution',
+            duration_ms: durationMs,
+            duration_api_ms: apiMs,
+            is_error: true,
+            num_turns: turns,
+            stop_reason: hitMaxTurns ? 'max_turns' : 'error',
+            total_cost_usd: 0,
+            usage: usageTotal,
+            modelUsage: {},
+            permission_denials: [],
+            errors: errored ? [errored] : [`Reached max turns (${maxTurns})`],
+            uuid: uuid(),
+            session_id: sessionId,
+        };
+    }
+    else {
+        yield {
+            type: 'result',
+            subtype: 'success',
+            duration_ms: durationMs,
+            duration_api_ms: apiMs,
+            is_error: false,
+            num_turns: turns,
+            result: lastText,
+            stop_reason: 'end_turn',
+            total_cost_usd: 0,
+            usage: usageTotal,
+            modelUsage: {},
+            permission_denials: [],
+            uuid: uuid(),
+            session_id: sessionId,
+        };
+    }
+}

package/dist/query.d.ts

@@ -29,6 +29,10 @@ export interface QueryOptions {
     /** Tool names the HOST/client executes (e.g. bash on a browser WebContainer). The agent
      *  emits a `client_tool_request` + pauses; the client runs it and resumes with results. */
     clientTools?: string[];
+    /** One switch: delegate ALL built-in workspace tools (bash + file ops) to the host
+     *  so the server never runs them against its in-memory workspace — execution happens
+     *  client-side (pair with anyclaude-react `createWorkspaceClientTools`). */
+    clientWorkspaceTools?: boolean;
     /** Results for client-tool calls, injected before continuing (with continueRun). */
     clientToolResults?: Array<{
         tool_use_id: string;

package/dist/query.js

@@ -23,6 +23,7 @@ export function query(options) {
         maxDurationMs: options.maxDurationMs,
         continueRun: options.continueRun,
         clientTools: options.clientTools,
+        clientWorkspaceTools: options.clientWorkspaceTools,
         clientToolResults: options.clientToolResults,
         cwd: options.cwd,
         sessionId: options.sessionId,

package/dist/tools/define.d.ts

@@ -9,8 +9,10 @@ export interface DefineToolSpec {
         properties: Record<string, unknown>;
         required?: string[];
     };
-    /** Execution method. Receives the parsed input + the tool context (fs/exec/cwd/signal/…). */
-    run: (input: Record<string, unknown>, ctx: ToolContext) => Promise<ToolResult> | ToolResult;
+    /** Execution method. Receives the parsed input + the tool context (fs/exec/cwd/signal/…).
+     *  OMIT it to make this a CLIENT/delegated tool — the agent loop emits a
+     *  client_tool_request and the host executes it (resume with clientToolResults). */
+    run?: (input: Record<string, unknown>, ctx: ToolContext) => Promise<ToolResult> | ToolResult;
     /** Optional: spill threshold for large outputs (see Tool.maxResultChars). */
     maxResultChars?: number;
 }

package/dist/tools/define.js

@@ -13,8 +13,10 @@ export function defineTool(spec) {
                 },
             },
         },
-        run: async (input, ctx) => spec.run(input, ctx),
     };
+    // With a run → server-executed. Without → client-delegated (no run on the Tool).
+    if (spec.run)
+        tool.run = async (input, ctx) => spec.run(input, ctx);
     if (spec.maxResultChars !== undefined)
         tool.maxResultChars = spec.maxResultChars;
     return tool;

package/dist/tools/types.d.ts

@@ -81,7 +81,10 @@ export interface ToolResult {
 /** A tool pairs an OpenAI-shape function definition with its implementation. */
 export interface Tool {
     def: ToolDef;
-    run(input: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult>;
+    /** Server-side executor. OMIT to make the tool client-delegated (Vercel-style
+     *  "no execute = client"): the loop emits a client_tool_request instead of
+     *  running it, and the host supplies the result. */
+    run?(input: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult>;
     /**
      * Max result size in characters before the agent loop spills the full output
      * to a file and replaces it with a preview + path (see large-output handling).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anyclaude-sdk",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "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",
@@ -63,6 +63,10 @@
     "./prompt": {
       "types": "./dist/prompt.d.ts",
       "import": "./dist/prompt.js"
+    },
+    "./loop": {
+      "types": "./dist/loop.d.ts",
+      "import": "./dist/loop.js"
     }
   },
   "sideEffects": false,