anyclaude-sdk 0.3.0 → 0.4.1

package/README.md

@@ -1,9 +1,19 @@
 # anyclaude-sdk
 
-Claude Code agent capabilities — tools, the tool loop, multi-turn conversations —
-running **entirely in the browser** via [WebContainer](https://webcontainers.io),
-against **any OpenAI- or Anthropic-compatible LLM endpoint**. No backend, no OAuth,
-no native binaries.
+[![npm version](https://img.shields.io/npm/v/anyclaude-sdk.svg)](https://www.npmjs.com/package/anyclaude-sdk)
+[![anyclaude-react](https://img.shields.io/npm/v/anyclaude-react.svg?label=anyclaude-react)](https://www.npmjs.com/package/anyclaude-react)
+[![license](https://img.shields.io/npm/l/anyclaude-sdk.svg)](LICENSE)
+[![docs](https://img.shields.io/badge/docs-anyclaude--docs.puter.site-4dd0e1.svg)](https://anyclaude-docs.puter.site)
+[![live demo](https://img.shields.io/badge/live%20demo-browser%20IDE-4dd0e1.svg)](https://anyclaude-docs.puter.site/demo/)
+
+Claude Code agent capabilities — tools, the tool loop, multi-turn conversations,
+MCP, sub-agents, sessions — against **any OpenAI- or Anthropic-compatible LLM
+endpoint**, running in the **browser** ([WebContainer](https://webcontainers.io)),
+**Node**, and **Bun**. No backend required, no OAuth, no native binaries.
+
+> **Live demo:** [a full IDE running in your browser](https://anyclaude-docs.puter.site/demo/) ·
+> **Docs:** [anyclaude-docs.puter.site](https://anyclaude-docs.puter.site) ·
+> **React UI kit:** [`anyclaude-react`](anyclaude-react/)
 
 It exposes the same `query()` async-generator interface and the same `SDKMessage`
 envelope as `@anthropic-ai/claude-agent-sdk`, so code written against the official
@@ -267,18 +277,75 @@ await fs.writeFile('/app/index.ts', 'export const x = 1')
 const workspace = composeWorkspace(fs, new NoopCommandExecutor())
 ```
 
+## Serverless & the "survivor"
+
+Run `query()` in a serverless function and stream `SDKMessage`s to the browser. For runs longer than the platform's time cap, checkpoint at a turn boundary and continue transparently in a fresh invocation:
+
+```ts
+// pause near the deadline, persist to the store, emit a `paused` message
+query({ prompt, workspace, llm, sessionStore, maxDurationMs: 20_000 })
+// later — resume + continue the tool loop with NO new user message
+query({ workspace, llm, sessionStore, resume: true, continueRun: true })
+```
+
+Pluggable `SessionStore` adapters (all implement `SessionStoreLike`): `SessionStore` (IndexedDB), `MemorySessionStore`, `KVSessionStore` (Vercel KV / Upstash), `RedisSessionStore`, `PostgresSessionStore` (Neon / pg / postgres.js), `SupabaseSessionStore`.
+
+## Client-side tools — server brain, browser hands
+
+Declare tools the **host** executes — e.g. run `bash` in the user's browser WebContainer while the agent loop runs on your server. The run pauses with a `client_tool_request`; the client executes it and you resume with the result:
+
+```ts
+query({ prompt, llm, workspace, sessionId, clientTools: ['bash'] })   // → emits client_tool_request + pauses
+query({ llm, workspace, sessionId, resume: true, continueRun: true, clientToolResults })  // → continues
+```
+
+## Interactive — `ask_user_question`
+
+Provide `onAskUser` and the agent gains an `ask_user_question` tool to put a multiple-choice decision to the user:
+
+```ts
+query({ prompt, workspace, llm, onAskUser: async ({ question, options }) => pickOne(question, options) })
+```
+
+## Hiding your prompt from the browser (projection)
+
+The agent loop runs server-side, so your system prompt, tool instructions, and retrieved context live in the server→LLM request and **never reach the browser**. To also strip sensitive artifacts (reasoning, raw tool output / RAG, model identity) from the streamed messages, wrap the stream — a pure, opt-in output transform:
+
+```ts
+import { projectMessages } from 'anyclaude-sdk'
+for await (const m of projectMessages(query({ /* ... */ }), { preset: 'public' }))
+  res.write(JSON.stringify(m) + '\n')
+```
+
+`paused` and `client_tool_request` control messages are always preserved. (Note: anything that *runs in the browser* — `createAgentClient` mode — necessarily exposes its request; use the server/endpoint path when the prompt is proprietary.)
+
+## React UI kit — `anyclaude-react`
+
+```bash
+npm install anyclaude-react
+```
+
+`useAgent()` plus restylable components — chat (`AgentChat`, `ChatPanel`, `Transcript`, `MarkdownMessage`, `Composer`, `Working`, `ToolCall`) and an IDE set (`Terminal`, `FileExplorer`, `CodeEditor`, `AskUser`). `createAgentClient` / `createEndpointClient` auto-stitch `paused` continuations and run `clientTools` in the browser.
+
+## Examples & live demo
+
+Runnable Vite projects in [`examples/`](examples/): **`browser-ide`** (WebContainer IDE — real shell + Node in the tab), `browser-chat`, `vercel-kv-survivor`, `vercel-supabase-survivor`, `vercel-indexeddb-survivor`, **`vercel-clienttools`** (server brain / browser hands). Try the **[live demo](https://anyclaude-docs.puter.site/demo/)**.
+
 ## API
 
 - `query(options): AsyncGenerator<SDKMessage>` — main entry.
   - `prompt: string | AsyncIterable<SDKUserMessage>`
   - `workspace: FileSystem & CommandExecutor`
   - `llm: LLMClient`
-  - `tools?`, `model?`, `systemPrompt?`, `maxTurns?` (default 50), `cwd?`, `abortController?`
-- `createOpenAIClient(options): LLMClient`
-- `createAnthropicClient(options): LLMClient`
-- `WebContainerWorkspace`, `MemoryFileSystem`, `NoopCommandExecutor`
+  - `tools?`, `extraTools?`, `allowedTools?`/`disallowedTools?`, `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?`
+- `createOpenAIClient` / `createAnthropicClient` / `createResponsesClient`
+- `WebContainerWorkspace`, `MemoryFileSystem`, `NoopCommandExecutor`, `LocalSandbox`, `composeWorkspace`
+- `defineTool` (custom tools), `projectMessages` (server-side stream redaction)
 - `ALL_CLAUDE_CODE_TOOLS`, individual tools, `toolDefs`, `toolByName`
-- All `SDK*` message types, `ContentBlockParam`, `LLMClient`, `ToolDef`, etc.
+- All `SDK*` message types, `ContentBlockParam`, `LLMClient`, `ToolDef`, `SessionStoreLike`, etc.
 
 ## Differences from the official SDK
 
@@ -286,9 +353,11 @@ const workspace = composeWorkspace(fs, new NoopCommandExecutor())
 |---------|-------------|--------------------|
 | Auth | OAuth token | None required |
 | Backend | claude.ai API | Any OpenAI/Anthropic endpoint |
-| File ops | Native filesystem | WebContainer fs (pluggable) |
-| Commands | Native shell | jsh (WebContainer) |
-| MCP / slash commands / background tasks | Built-in | Not included |
+| Runtime | Node only | Browser, Node, Bun |
+| File ops | Native filesystem | Pluggable (WebContainer / Memory / IndexedDB / local) |
+| Commands | Native shell | jsh (WebContainer) / local / client-side tools |
+| MCP / slash commands / background tasks / sub-agents | Built-in | Built-in |
+| Serverless survivor + prompt projection | — | Built-in |
 
 ## License
 

package/dist/agent.js

@@ -797,7 +797,19 @@ export async function* runAgent(options) {
                                 isError = !!r.isError;
                             }
                             catch (err) {
-                                content = `Error executing ${name}: ${err instanceof Error ? err.message : String(err)}`;
+                                const detail = err instanceof Error
+                                    ? err.message
+                                    : typeof err === 'string'
+                                        ? err
+                                        : (() => {
+                                            try {
+                                                return JSON.stringify(err);
+                                            }
+                                            catch {
+                                                return String(err);
+                                            }
+                                        })();
+                                content = `Error executing ${name}: ${detail}`;
                                 isError = true;
                             }
                             if (isError) {

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from './mcp/index.js';
 export * from './commands/index.js';
 export * from './background/index.js';
 export * from './queue.js';
+export { projectMessages, projectMessage, type ProjectionOptions, type ProjectionPreset, } from './projection.js';
 export * from './team/index.js';
 export * from './session/index.js';
 export * from './memory/index.js';

package/dist/index.js

@@ -15,6 +15,7 @@ export * from './mcp/index.js';
 export * from './commands/index.js';
 export * from './background/index.js';
 export * from './queue.js';
+export { projectMessages, projectMessage, } from './projection.js';
 export * from './team/index.js';
 export * from './session/index.js';
 export * from './memory/index.js';

package/dist/projection.d.ts

@@ -0,0 +1,29 @@
+import type { SDKMessage } from './types/index.js';
+export type ProjectionPreset = 'public' | 'raw';
+export interface ProjectionOptions {
+    /** 'public' (browser-safe defaults) or 'raw' (passthrough; only explicit opts apply). Default 'public'. */
+    preset?: ProjectionPreset;
+    /** Replace tool_result block content with a placeholder — hides raw tool output + RAG context. */
+    redactToolResults?: boolean;
+    /** Drop synthetic tool_result messages entirely instead of redacting their content. */
+    dropToolResults?: boolean;
+    /** Remove thinking/reasoning blocks and deltas. */
+    stripReasoning?: boolean;
+    /** Remove tool_use input args (tool NAMES still appear via usage). */
+    stripToolInput?: boolean;
+    /** Remove model/provider-identifying fields (model name, tool list, mcp servers, modelUsage). */
+    stripModelInfo?: boolean;
+    /** Placeholder substituted for redacted content. Default '[redacted]'. */
+    placeholder?: string;
+    /** Drop any message whose `type` or `subtype` is in this list. */
+    drop?: string[];
+    /** Custom transform applied last; return null to drop the message. */
+    redact?: (m: SDKMessage) => SDKMessage | null;
+}
+/** Project one message. Returns null to drop it. */
+export declare function projectMessage(msg: SDKMessage, options?: ProjectionOptions): SDKMessage | null;
+/**
+ * Wrap an SDKMessage stream, projecting each message for browser delivery.
+ * Pure output transform — does NOT affect the agent loop. Opt-in.
+ */
+export declare function projectMessages(source: AsyncIterable<SDKMessage>, options?: ProjectionOptions): AsyncGenerator<SDKMessage>;

package/dist/projection.js

@@ -0,0 +1,99 @@
+function resolve(o) {
+    const pub = (o.preset ?? 'public') === 'public';
+    return {
+        redactToolResults: o.redactToolResults ?? pub,
+        dropToolResults: o.dropToolResults ?? false,
+        stripReasoning: o.stripReasoning ?? pub,
+        stripToolInput: o.stripToolInput ?? false,
+        stripModelInfo: o.stripModelInfo ?? pub,
+        placeholder: o.placeholder ?? '[redacted]',
+        drop: o.drop ?? [],
+        redact: o.redact,
+    };
+}
+/** Project one message. Returns null to drop it. */
+export function projectMessage(msg, options = {}) {
+    const o = resolve(options);
+    const m = msg;
+    const type = m.type;
+    const subtype = m.subtype;
+    if (o.drop.includes(type) || (subtype && o.drop.includes(subtype)))
+        return null;
+    // Control messages the client must act on — never alter (survivor + client tools).
+    if (type === 'system' && (subtype === 'paused' || subtype === 'client_tool_request')) {
+        return o.redact ? o.redact(msg) : msg;
+    }
+    let out = msg;
+    if (type === 'user') {
+        // Synthetic tool_result messages carry raw tool output + retrieved context.
+        const message = m.message;
+        const content = message?.content;
+        if (Array.isArray(content) && content.some((b) => b.type === 'tool_result')) {
+            if (o.dropToolResults)
+                return o.redact ? o.redact(msg) ?? null : null;
+            if (o.redactToolResults) {
+                const newContent = content.map((b) => b.type === 'tool_result' ? { ...b, content: o.placeholder } : b);
+                out = { ...m, message: { ...message, content: newContent } };
+            }
+        }
+    }
+    else if (type === 'assistant') {
+        const message = m.message;
+        let content = message.content;
+        if (o.stripReasoning)
+            content = content.filter((b) => b.type !== 'thinking');
+        if (o.stripToolInput)
+            content = content.map((b) => (b.type === 'tool_use' ? { ...b, input: {} } : b));
+        const newMessage = { ...message, content };
+        if (o.stripModelInfo)
+            newMessage.model = '';
+        out = { ...m, message: newMessage };
+    }
+    else if (type === 'stream_event') {
+        const event = m.event;
+        const et = event?.type;
+        if (o.stripReasoning) {
+            if (et === 'content_block_delta' && event.delta?.type === 'thinking_delta')
+                return null;
+            if (et === 'content_block_start' && event.content_block?.type === 'thinking')
+                return null;
+        }
+        if (o.stripModelInfo && et === 'message_start') {
+            const sm = { ...event.message };
+            delete sm.model;
+            out = { ...m, event: { ...event, message: sm } };
+        }
+    }
+    else if (type === 'system' && subtype === 'init') {
+        if (o.stripModelInfo) {
+            out = {
+                ...m,
+                model: '',
+                tools: [],
+                mcp_servers: [],
+                slash_commands: [],
+                skills: [],
+                agents: [],
+                apiKeySource: 'none',
+                cwd: '',
+            };
+        }
+    }
+    else if (type === 'result') {
+        if (o.stripModelInfo) {
+            out = { ...m, modelUsage: {} };
+        }
+    }
+    return o.redact ? o.redact(out) : out;
+}
+/**
+ * Wrap an SDKMessage stream, projecting each message for browser delivery.
+ * Pure output transform — does NOT affect the agent loop. Opt-in.
+ */
+export async function* projectMessages(source, options = {}) {
+    for await (const m of source) {
+        const out = projectMessage(m, options);
+        if (out)
+            yield out;
+    }
+}

package/dist/tools/bash.js

@@ -32,7 +32,15 @@ export const bash = {
             return { content: 'Error: `command` is required.', isError: true };
         }
         const timeout = typeof input.timeout_ms === 'number' ? input.timeout_ms : undefined;
-        const { output, exitCode } = await ctx.exec.exec(command, timeout);
+        let result;
+        try {
+            result = await ctx.exec.exec(command, timeout);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : typeof e === 'string' ? e : JSON.stringify(e);
+            return { content: `Failed to run command: ${msg}`, isError: true };
+        }
+        const { output, exitCode } = result;
         if (exitCode !== 0) {
             const body = output || '(no output)';
             return {

package/dist/workspace/webcontainer.d.ts

@@ -39,7 +39,11 @@ export interface WebContainerProcess {
 export declare class WebContainerWorkspace implements FileSystem, CommandExecutor {
     readonly wc: WebContainerLike;
     readonly cwd: string;
+    private cwdReady;
     constructor(wc: WebContainerLike, cwd?: string);
+    /** Ensure the working directory exists before spawning into it (memoized).
+     *  A fresh WebContainer has only `/`, so spawning with a missing cwd rejects. */
+    private ensureCwd;
     /** Resolve a possibly-relative path against the workspace cwd. */
     resolve(path: string): string;
     readFile(path: string): Promise<string | null>;

package/dist/workspace/webcontainer.js

@@ -8,9 +8,20 @@ const textDecoder = new TextDecoder();
  */
 export class WebContainerWorkspace {
     constructor(wc, cwd) {
+        this.cwdReady = null;
         this.wc = wc;
         this.cwd = cwd ?? wc.workdir ?? '/home/projects';
     }
+    /** Ensure the working directory exists before spawning into it (memoized).
+     *  A fresh WebContainer has only `/`, so spawning with a missing cwd rejects. */
+    ensureCwd() {
+        if (!this.cwdReady) {
+            this.cwdReady = Promise.resolve(this.wc.fs.mkdir(this.cwd, { recursive: true }))
+                .then(() => undefined)
+                .catch(() => undefined);
+        }
+        return this.cwdReady;
+    }
     /** Resolve a possibly-relative path against the workspace cwd. */
     resolve(path) {
         if (path.startsWith('/'))
@@ -80,10 +91,21 @@ export class WebContainerWorkspace {
     // ---- CommandExecutor ----
     async exec(command, timeoutMs = 120_000, env) {
         const sanitized = sanitizeCommand(command);
-        const proc = await this.wc.spawn('jsh', ['-c', sanitized], {
-            env,
-            cwd: this.cwd,
-        });
+        await this.ensureCwd();
+        let proc;
+        try {
+            proc = await this.wc.spawn('jsh', ['-c', sanitized], { env, cwd: this.cwd });
+        }
+        catch (e) {
+            // Last-resort: spawn without an explicit cwd (defaults to /) so a bad cwd
+            // never hard-fails the tool; surface a real message if even that fails.
+            try {
+                proc = await this.wc.spawn('jsh', ['-c', sanitized], { env });
+            }
+            catch {
+                throw new Error(`failed to start shell (jsh): ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
         let output = '';
         const reader = proc.output.getReader();
         const collect = (async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anyclaude-sdk",
-  "version": "0.3.0",
+  "version": "0.4.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",