anyclaude-sdk 0.4.7 → 0.4.9

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/llm/index.d.ts

@@ -2,3 +2,4 @@ export * from './openai.js';
 export * from './anthropic.js';
 export * from './responses.js';
 export { hasInlineToolCalls, parseInlineToolCalls } from './inlineTools.js';
+export type { LLMClient, ChatMsg, StreamResult, ToolCall, ToolDef, StopReason, Usage, ContentBlockParam, } from '../types/index.js';

package/dist/llm/openai.d.ts

@@ -1,4 +1,4 @@
-import type { LLMClient } from '../types/index.js';
+import type { ChatMsg, ContentBlockParam, LLMClient } from '../types/index.js';
 export interface OpenAIClientOptions {
     /** API key, or a function returning one per request (for round-robin key pools). */
     apiKey?: string | (() => string | undefined);
@@ -25,5 +25,28 @@ export interface OpenAIClientOptions {
  * from streamed deltas) via the returned StreamResult and the `onTool` hook.
  */
 export declare function createOpenAIClient(options?: OpenAIClientOptions): LLMClient;
+/** A single message in OpenAI `/chat/completions` wire shape. */
+export type OpenAIChatMessage = Record<string, unknown>;
+/**
+ * Convert the SDK's provider-neutral `ChatMsg[]` into OpenAI `/chat/completions`
+ * `messages`. Exported so custom `LLMClient` authors who bring their own
+ * transport (proxy, encryption, alternate URL) can reuse the SDK's canonical
+ * wire conversion instead of forking it — keeping content-block mapping
+ * (text / image / PDF `document` / `tool_result`) in lockstep with the
+ * built-in `createOpenAIClient`.
+ */
+export declare function toOpenAIMessages(messages: ChatMsg[]): OpenAIChatMessage[];
+/** Convert our provider-neutral ChatMsg into an OpenAI chat message. */
+export declare function toOpenAIMessage(msg: ChatMsg): OpenAIChatMessage;
+/**
+ * Map content blocks to OpenAI multimodal `content` parts
+ * (`text` / `image_url` / `file`). Exported for custom `LLMClient` authors.
+ */
+export declare function blocksToOpenAIContent(blocks: ContentBlockParam[]): unknown;
+/**
+ * Flatten `text` + nested `tool_result` content blocks to a plain string
+ * (used for `assistant`/`tool` roles). Exported for custom `LLMClient` authors.
+ */
+export declare function blocksToText(blocks: ContentBlockParam[]): string;
 /** Read an SSE response body, invoking `onData` for each `data:` payload. */
 export declare function consumeSSE(body: ReadableStream<Uint8Array>, onData: (data: string) => void): Promise<void>;

package/dist/llm/openai.js

@@ -131,8 +131,19 @@ function mapFinishReason(reason) {
             return reason ? 'end_turn' : null;
     }
 }
+/**
+ * Convert the SDK's provider-neutral `ChatMsg[]` into OpenAI `/chat/completions`
+ * `messages`. Exported so custom `LLMClient` authors who bring their own
+ * transport (proxy, encryption, alternate URL) can reuse the SDK's canonical
+ * wire conversion instead of forking it — keeping content-block mapping
+ * (text / image / PDF `document` / `tool_result`) in lockstep with the
+ * built-in `createOpenAIClient`.
+ */
+export function toOpenAIMessages(messages) {
+    return messages.map(toOpenAIMessage);
+}
 /** Convert our provider-neutral ChatMsg into an OpenAI chat message. */
-function toOpenAIMessage(msg) {
+export function toOpenAIMessage(msg) {
     if (msg.role === 'tool') {
         return {
             role: 'tool',
@@ -155,7 +166,11 @@ function toOpenAIMessage(msg) {
     }
     return { role: msg.role, content: blocksToOpenAIContent(msg.content) };
 }
-function blocksToOpenAIContent(blocks) {
+/**
+ * Map content blocks to OpenAI multimodal `content` parts
+ * (`text` / `image_url` / `file`). Exported for custom `LLMClient` authors.
+ */
+export function blocksToOpenAIContent(blocks) {
     const parts = [];
     for (const b of blocks) {
         if (b.type === 'text')
@@ -186,7 +201,11 @@ function blocksToOpenAIContent(blocks) {
     }
     return parts.length ? parts : '';
 }
-function blocksToText(blocks) {
+/**
+ * Flatten `text` + nested `tool_result` content blocks to a plain string
+ * (used for `assistant`/`tool` roles). Exported for custom `LLMClient` authors.
+ */
+export function blocksToText(blocks) {
     return blocks
         .map((b) => {
         if (b.type === 'text')

package/dist/loop.d.ts

@@ -15,6 +15,22 @@ export interface RunToolLoopOptions {
     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. */

package/dist/loop.js

@@ -75,8 +75,9 @@ function createPushQueue() {
  *   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 } = 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;
@@ -186,7 +187,27 @@ export async function* runToolLoop(opts) {
             const tool = byName.get(name);
             let content = '';
             let isError = false;
-            if (!tool) {
+            // 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;
             }

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.7",
+  "version": "0.4.9",
   "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",