anyclaude-sdk 0.1.0

package/dist/background/index.d.ts

@@ -0,0 +1,3 @@
+export { BackgroundTaskManager, type BgTask, type BgStatus, type BgTaskFn, } from './manager.js';
+export { exposeBackgroundWorker, wrapWorker, type WorkerRunner, } from './worker.js';
+export { taskList, taskOutput, taskStop, BACKGROUND_TOOLS } from './tools.js';

package/dist/background/index.js

@@ -0,0 +1,9 @@
+// Background task system for browser-claude-sdk.
+//
+// - BackgroundTaskManager: run detached, pollable async work on the main thread
+//   (background sub-agents, long shell commands) — no worker required.
+// - worker helpers: optional Comlink-based off-main-thread execution.
+// - tools: task_list / task_output / task_stop for the agent to manage tasks.
+export { BackgroundTaskManager, } from './manager.js';
+export { exposeBackgroundWorker, wrapWorker, } from './worker.js';
+export { taskList, taskOutput, taskStop, BACKGROUND_TOOLS } from './tools.js';

package/dist/background/manager.d.ts

@@ -0,0 +1,32 @@
+export type BgStatus = 'running' | 'completed' | 'failed' | 'stopped';
+export interface BgTask {
+    id: string;
+    description: string;
+    status: BgStatus;
+    output: string;
+    error?: string;
+    startedAt: number;
+    endedAt?: number;
+}
+/** Work performed by a background task. */
+export type BgTaskFn = (signal: AbortSignal, append: (chunk: string) => void) => Promise<string>;
+export declare class BackgroundTaskManager {
+    private entries;
+    private counter;
+    /**
+     * Launch `fn` detached and return a task id immediately. The task runs in the
+     * background; poll it with get()/output()/list(). Never throws synchronously.
+     */
+    start(description: string, fn: BgTaskFn): string;
+    get(id: string): BgTask | undefined;
+    list(): BgTask[];
+    /** Return a task's output, optionally sliced from a char offset. */
+    output(id: string, opts?: {
+        since?: number;
+    }): string | null;
+    /** Abort a running task. Returns false if there is no such running task. */
+    stop(id: string): boolean;
+    stopAll(): void;
+    /** Await settlement of a task (resolves regardless of outcome). */
+    wait(id: string): Promise<BgTask | undefined>;
+}

package/dist/background/manager.js

@@ -0,0 +1,108 @@
+// In-thread background task manager. Runs detached async work (background
+// sub-agents, long shell commands) without blocking the main agent loop. Tasks
+// are pollable by id; output can stream in via the `append` callback.
+//
+// This is the core — it requires no worker. For true off-main-thread execution,
+// see ./worker.ts (optional, Comlink-based).
+function now() {
+    // Read Date.now lazily at runtime (never at module top-level).
+    return Date.now();
+}
+export class BackgroundTaskManager {
+    constructor() {
+        this.entries = new Map();
+        this.counter = 0;
+    }
+    /**
+     * Launch `fn` detached and return a task id immediately. The task runs in the
+     * background; poll it with get()/output()/list(). Never throws synchronously.
+     */
+    start(description, fn) {
+        const id = `bg_${++this.counter}`;
+        const controller = new AbortController();
+        const task = {
+            id,
+            description,
+            status: 'running',
+            output: '',
+            startedAt: now(),
+        };
+        const append = (chunk) => {
+            // Ignore writes after the task has settled.
+            if (task.status === 'running')
+                task.output += chunk;
+        };
+        const promise = (async () => {
+            try {
+                const final = await fn(controller.signal, append);
+                if (task.status !== 'running')
+                    return; // already stopped
+                // Append the final result unless it was already streamed via `append`.
+                if (final && !task.output.trimEnd().endsWith(final.trimEnd())) {
+                    task.output += (task.output ? '\n' : '') + final;
+                }
+                task.status = 'completed';
+            }
+            catch (err) {
+                if (task.status === 'stopped')
+                    return;
+                if (controller.signal.aborted) {
+                    task.status = 'stopped';
+                }
+                else {
+                    task.status = 'failed';
+                    task.error = err instanceof Error ? err.message : String(err);
+                }
+            }
+            finally {
+                task.endedAt = now();
+            }
+        })();
+        this.entries.set(id, { task, controller, promise });
+        return id;
+    }
+    get(id) {
+        return this.entries.get(id)?.task;
+    }
+    list() {
+        return [...this.entries.values()].map((e) => e.task);
+    }
+    /** Return a task's output, optionally sliced from a char offset. */
+    output(id, opts) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return null;
+        const out = entry.task.output;
+        return opts?.since ? out.slice(opts.since) : out;
+    }
+    /** Abort a running task. Returns false if there is no such running task. */
+    stop(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return false;
+        if (entry.task.status === 'running') {
+            entry.task.status = 'stopped';
+            entry.task.endedAt = now();
+            try {
+                entry.controller.abort();
+            }
+            catch {
+                /* ignore */
+            }
+            return true;
+        }
+        return false;
+    }
+    stopAll() {
+        for (const id of this.entries.keys())
+            this.stop(id);
+    }
+    /** Await settlement of a task (resolves regardless of outcome). */
+    async wait(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return undefined;
+        await entry.promise;
+        return entry.task;
+    }
+}

package/dist/background/tools.d.ts

@@ -0,0 +1,5 @@
+import type { Tool } from '../tools/types.js';
+export declare const taskList: Tool;
+export declare const taskOutput: Tool;
+export declare const taskStop: Tool;
+export declare const BACKGROUND_TOOLS: Tool[];

package/dist/background/tools.js

@@ -0,0 +1,98 @@
+// Tools for inspecting and controlling background tasks. They read
+// `ctx.background` (a BackgroundTaskManager) which the agent loop injects into
+// ToolContext when background tasks are enabled.
+/** Read the (optional) background manager off the tool context. */
+function mgr(ctx) {
+    return ctx.background;
+}
+function ageMs(task) {
+    const end = task.endedAt ?? Date.now();
+    return end - task.startedAt;
+}
+const NOT_ENABLED = {
+    content: 'Background tasks are not enabled for this session.',
+    isError: true,
+};
+export const taskList = {
+    def: {
+        type: 'function',
+        function: {
+            name: 'task_list',
+            description: 'List background tasks with their id, status, description, and age. Use to see what background work is running or finished.',
+            parameters: { type: 'object', properties: {} },
+        },
+    },
+    async run(_input, ctx) {
+        const m = mgr(ctx);
+        if (!m)
+            return { ...NOT_ENABLED };
+        const tasks = m.list();
+        if (!tasks.length)
+            return { content: 'No background tasks.' };
+        const rows = tasks
+            .map((t) => `${t.id}  [${t.status}]  ${t.description}  (${Math.round(ageMs(t) / 1000)}s${t.error ? `, error: ${t.error}` : ''})`)
+            .join('\n');
+        return { content: rows };
+    },
+};
+export const taskOutput = {
+    // Background output can be large; let the loop persist it if needed.
+    def: {
+        type: 'function',
+        function: {
+            name: 'task_output',
+            description: "Read a background task's accumulated output. Optionally pass `since` (a character offset) to fetch only new output since a previous read.",
+            parameters: {
+                type: 'object',
+                properties: {
+                    task_id: { type: 'string', description: 'The background task id (e.g. bg_1).' },
+                    since: {
+                        type: 'number',
+                        description: 'Character offset to read from (for incremental polling).',
+                    },
+                },
+                required: ['task_id'],
+            },
+        },
+    },
+    async run(input, ctx) {
+        const m = mgr(ctx);
+        if (!m)
+            return { ...NOT_ENABLED };
+        const id = String(input.task_id ?? '');
+        const task = m.get(id);
+        if (!task)
+            return { content: `No background task with id "${id}".`, isError: true };
+        const since = typeof input.since === 'number' ? input.since : undefined;
+        const out = m.output(id, since !== undefined ? { since } : undefined) ?? '';
+        const header = `[${task.id}] status=${task.status}${task.error ? ` error=${task.error}` : ''}`;
+        return { content: out ? `${header}\n${out}` : `${header}\n(no output yet)` };
+    },
+};
+export const taskStop = {
+    def: {
+        type: 'function',
+        function: {
+            name: 'task_stop',
+            description: 'Stop (abort) a running background task by id.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    task_id: { type: 'string', description: 'The background task id to stop.' },
+                },
+                required: ['task_id'],
+            },
+        },
+    },
+    async run(input, ctx) {
+        const m = mgr(ctx);
+        if (!m)
+            return { ...NOT_ENABLED };
+        const id = String(input.task_id ?? '');
+        const stopped = m.stop(id);
+        return stopped
+            ? { content: `Stopped background task ${id}.` }
+            : { content: `Task ${id} was not running (no such task or already finished).`, isError: true };
+    },
+};
+export const BACKGROUND_TOOLS = [taskList, taskOutput, taskStop];

package/dist/background/worker.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A generic "run this serializable job" surface a worker can expose. `code`
+ * identifies the job (e.g. a registered handler name or a stringified task);
+ * `input` is structured-clone-serializable data. Keep it serializable —
+ * functions, class instances, and live handles do not cross the worker boundary.
+ */
+export interface WorkerRunner {
+    run(code: string, input: unknown): Promise<unknown>;
+}
+/**
+ * Call inside a Web Worker / Service Worker to expose a WorkerRunner to the main
+ * thread via Comlink. No-op (with a console warning) if not in a worker scope.
+ */
+export declare function exposeBackgroundWorker(api: WorkerRunner): Promise<void>;
+/**
+ * Main-thread side: wrap a Worker into a WorkerRunner proxy via Comlink. The
+ * returned object's `run` calls execute inside the worker.
+ */
+export declare function wrapWorker(worker: Worker): Promise<WorkerRunner>;

package/dist/background/worker.js

@@ -0,0 +1,30 @@
+// Optional off-main-thread execution via Comlink. The BackgroundTaskManager
+// works fully WITHOUT any of this — use these helpers only when you want a task
+// to run inside a Web Worker (or service worker) instead of on the main thread.
+//
+// Comlink is an optional peer dependency; it is imported lazily so this module
+// can sit in the barrel without forcing Comlink to load for callers that never
+// use a worker.
+/**
+ * Call inside a Web Worker / Service Worker to expose a WorkerRunner to the main
+ * thread via Comlink. No-op (with a console warning) if not in a worker scope.
+ */
+export async function exposeBackgroundWorker(api) {
+    const inWorkerScope = typeof self !== 'undefined' &&
+        typeof globalThis.document === 'undefined';
+    if (!inWorkerScope) {
+        // eslint-disable-next-line no-console
+        console.warn('[background] exposeBackgroundWorker called outside a worker scope; ignoring.');
+        return;
+    }
+    const Comlink = await import('comlink');
+    Comlink.expose(api);
+}
+/**
+ * Main-thread side: wrap a Worker into a WorkerRunner proxy via Comlink. The
+ * returned object's `run` calls execute inside the worker.
+ */
+export async function wrapWorker(worker) {
+    const Comlink = await import('comlink');
+    return Comlink.wrap(worker);
+}

package/dist/commands/builtins.d.ts

@@ -0,0 +1,2 @@
+import type { SlashCommand } from './types.js';
+export declare const BUILTIN_COMMANDS: SlashCommand[];

package/dist/commands/builtins.js

@@ -0,0 +1,306 @@
+// Built-in slash commands: /help, /clear, /compact, /tools, /cost, /model.
+/** Render the conversation (minus the system message) as a plain transcript. */
+function transcript(history) {
+    return history
+        .slice(1)
+        .map((m) => {
+        const body = typeof m.content === 'string'
+            ? m.content
+            : m.content
+                .map((b) => b.type === 'text'
+                ? b.text
+                : b.type === 'tool_use'
+                    ? `[tool_use ${b.name} ${JSON.stringify(b.input)}]`
+                    : b.type === 'tool_result'
+                        ? `[tool_result ${typeof b.content === 'string' ? b.content : '...'}]`
+                        : `[${b.type}]`)
+                .join('\n');
+        const calls = m.tool_calls?.length
+            ? ' ' + m.tool_calls.map((c) => `[call ${c.function.name}(${c.function.arguments})]`).join(' ')
+            : '';
+        return `${m.role.toUpperCase()}: ${body}${calls}`;
+    })
+        .join('\n\n');
+}
+const help = {
+    name: 'help',
+    description: 'List available slash commands',
+    run(_args, ctx) {
+        const lines = ctx.commands
+            .slice()
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((c) => `  /${c.name}${c.argumentHint ? ' ' + c.argumentHint : ''} — ${c.description}`);
+        return { systemText: `Available commands:\n${lines.join('\n')}` };
+    },
+};
+const clear = {
+    name: 'clear',
+    description: 'Clear the conversation history (keeps the system prompt)',
+    run(_args, ctx) {
+        return {
+            newHistory: ctx.history.length ? [ctx.history[0]] : [],
+            systemText: 'Conversation cleared.',
+        };
+    },
+};
+const compact = {
+    name: 'compact',
+    description: 'Summarize the conversation so far to free up context',
+    argumentHint: '[focus instructions]',
+    async run(args, ctx) {
+        if (!ctx.llm) {
+            return { systemText: 'Compaction requires an LLM client, which is not available here.' };
+        }
+        if (ctx.history.length <= 1) {
+            return { systemText: 'Nothing to compact yet.' };
+        }
+        const focus = args.trim();
+        const instruction = 'Summarize the following conversation transcript concisely but completely. ' +
+            'Preserve: the user’s goals, key decisions, files created/edited (with paths), ' +
+            'important findings, and any unfinished work or next steps. Use short sections.' +
+            (focus ? `\nPay special attention to: ${focus}` : '');
+        const messages = [
+            { role: 'system', content: 'You are a precise conversation summarizer.' },
+            { role: 'user', content: `${instruction}\n\n---\n${transcript(ctx.history)}` },
+        ];
+        let summary = '';
+        try {
+            const res = await ctx.llm.streamChat(messages, {
+                model: ctx.model,
+                signal: ctx.signal,
+                onToken: () => { },
+            });
+            summary = res.text?.trim() ?? '';
+        }
+        catch (err) {
+            return {
+                systemText: `Compaction failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        if (!summary)
+            return { systemText: 'Compaction produced no summary; history left unchanged.' };
+        const newHistory = [
+            ctx.history[0],
+            { role: 'user', content: `Summary of the conversation so far:\n${summary}` },
+        ];
+        return {
+            newHistory,
+            compacted: true,
+            systemText: 'Conversation compacted into a summary.',
+        };
+    },
+};
+const tools = {
+    name: 'tools',
+    description: 'List the tools available to the agent',
+    run(_args, ctx) {
+        if (!ctx.tools.length)
+            return { systemText: 'No tools available.' };
+        const lines = ctx.tools.map((t) => `  ${t.name} — ${t.description.split('\n')[0]}`);
+        return { systemText: `Available tools (${ctx.tools.length}):\n${lines.join('\n')}` };
+    },
+};
+const cost = {
+    name: 'cost',
+    description: 'Show token usage for this session',
+    run(_args, ctx) {
+        if (!ctx.usage)
+            return { systemText: 'No usage recorded yet.' };
+        const u = ctx.usage;
+        return {
+            systemText: `Token usage — input: ${u.input_tokens}, output: ${u.output_tokens}${u.cache_read_input_tokens ? `, cache read: ${u.cache_read_input_tokens}` : ''}`,
+        };
+    },
+};
+const model = {
+    name: 'model',
+    description: 'Show the active model',
+    run(_args, ctx) {
+        return { systemText: `Model: ${ctx.model ?? 'unknown'}` };
+    },
+};
+const sessions = {
+    name: 'sessions',
+    description: 'List saved sessions',
+    async run(_args, ctx) {
+        if (!ctx.sessionStore)
+            return { systemText: 'No session store configured.' };
+        const list = await ctx.sessionStore.list();
+        if (!list.length)
+            return { systemText: 'No saved sessions.' };
+        const lines = list.map((s) => `  ${s.sessionId}${s.sessionId === ctx.sessionId ? ' (current)' : ''} — ${s.title ?? '(untitled)'} · ${s.messageCount} msgs`);
+        return { systemText: `Saved sessions:\n${lines.join('\n')}\n\nResume with: /resume <id>` };
+    },
+};
+const resume = {
+    name: 'resume',
+    description: 'Resume a saved session by id',
+    argumentHint: '<session-id>',
+    async run(args, ctx) {
+        if (!ctx.sessionStore)
+            return { systemText: 'No session store configured.' };
+        const id = args.trim();
+        if (!id)
+            return { systemText: 'Usage: /resume <session-id>  (see /sessions)' };
+        const prior = await ctx.sessionStore.load(id);
+        if (!prior || !prior.length)
+            return { systemText: `No transcript found for session "${id}".` };
+        return { newHistory: prior, systemText: `Resumed session ${id} (${prior.length - 1} prior messages).` };
+    },
+};
+const rename = {
+    name: 'rename',
+    description: 'Rename the current session',
+    argumentHint: '<title>',
+    async run(args, ctx) {
+        if (!ctx.sessionStore || !ctx.sessionId)
+            return { systemText: 'No active session to rename.' };
+        const title = args.trim();
+        if (!title)
+            return { systemText: 'Usage: /rename <title>' };
+        await ctx.sessionStore.rename(ctx.sessionId, title);
+        return { systemText: `Session renamed to "${title}".` };
+    },
+};
+const diff = {
+    name: 'diff',
+    description: 'Show uncommitted git changes',
+    async run(_args, ctx) {
+        if (!ctx.exec)
+            return { systemText: 'No shell available for /diff.' };
+        const { output, exitCode } = await ctx.exec('git diff --stat && echo "---" && git diff');
+        if (exitCode !== 0 && !output.trim())
+            return { systemText: 'No changes, or not a git repository.' };
+        return { systemText: '```diff\n' + (output.trim() || '(no changes)').slice(0, 8000) + '\n```' };
+    },
+};
+const tasks = {
+    name: 'tasks',
+    description: 'List background tasks',
+    run(_args, ctx) {
+        if (!ctx.background)
+            return { systemText: 'Background tasks are not enabled.' };
+        const list = ctx.background.list();
+        if (!list.length)
+            return { systemText: 'No background tasks.' };
+        return { systemText: 'Background tasks:\n' + list.map((t) => `  ${t.id} [${t.status}] ${t.description}`).join('\n') };
+    },
+};
+const board = {
+    name: 'board',
+    description: 'List the team task board',
+    run(_args, ctx) {
+        if (!ctx.board)
+            return { systemText: 'Teammates are not enabled.' };
+        const list = ctx.board.list();
+        if (!list.length)
+            return { systemText: 'Task board is empty.' };
+        return { systemText: 'Task board:\n' + list.map((t) => `  ${t.id} [${t.status}]${t.owner ? ' @' + t.owner : ''} — ${t.subject}`).join('\n') };
+    },
+};
+const context = {
+    name: 'context',
+    description: 'Show approximate context usage',
+    run(_args, ctx) {
+        let chars = 0;
+        for (const m of ctx.history) {
+            chars += typeof m.content === 'string' ? m.content.length : JSON.stringify(m.content).length;
+        }
+        const approxTokens = Math.round(chars / 4);
+        return {
+            systemText: `Context: ${ctx.history.length} messages, ~${approxTokens.toLocaleString()} tokens (${chars.toLocaleString()} chars).`,
+        };
+    },
+};
+const files = {
+    name: 'files',
+    description: 'List files read this session',
+    run(_args, ctx) {
+        const fs = ctx.readFiles ? [...ctx.readFiles] : [];
+        if (!fs.length)
+            return { systemText: 'No files read yet this session.' };
+        return { systemText: `Files read (${fs.length}):\n${fs.map((f) => '  ' + f).join('\n')}` };
+    },
+};
+const agents = {
+    name: 'agents',
+    description: 'List configured sub-agents',
+    run(_args, ctx) {
+        const a = ctx.agents ? Object.entries(ctx.agents) : [];
+        if (!a.length)
+            return { systemText: 'No custom agents configured.' };
+        return { systemText: 'Agents:\n' + a.map(([n, d]) => `  ${n}${d.model ? ' (' + d.model + ')' : ''} — ${d.description}`).join('\n') };
+    },
+};
+const mcp = {
+    name: 'mcp',
+    description: 'Show MCP server status',
+    run(_args, ctx) {
+        const s = ctx.mcpServers ?? [];
+        if (!s.length)
+            return { systemText: 'No MCP servers configured.' };
+        return { systemText: 'MCP servers:\n' + s.map((x) => `  ${x.name} — ${x.status}`).join('\n') };
+    },
+};
+const permissions = {
+    name: 'permissions',
+    description: 'Show the active permission mode',
+    run(_args, ctx) {
+        return { systemText: `Permission mode: ${ctx.permissionMode ?? 'default'}` };
+    },
+};
+const memory = {
+    name: 'memory',
+    description: 'Show persistent memory (store + CLAUDE.md / MEMORY.md)',
+    async run(_args, ctx) {
+        const parts = [];
+        if (ctx.memory) {
+            const rendered = await ctx.memory.render();
+            if (rendered)
+                parts.push(rendered);
+        }
+        if (ctx.fs) {
+            for (const name of ['CLAUDE.md', 'MEMORY.md', '.claude/CLAUDE.md']) {
+                const c = await ctx.fs.readFile(name);
+                if (c) {
+                    parts.push(`# ${name}\n\n${c.slice(0, 4000)}`);
+                    break;
+                }
+            }
+        }
+        return { systemText: parts.length ? parts.join('\n\n---\n\n') : 'No memory or CLAUDE.md/MEMORY.md found.' };
+    },
+};
+const exportCmd = {
+    name: 'export',
+    description: 'Export the conversation transcript (markdown)',
+    run(_args, ctx) {
+        return { systemText: '```markdown\n' + transcript(ctx.history) + '\n```' };
+    },
+};
+const review = {
+    name: 'review',
+    description: 'Ask the agent to review recent changes',
+    argumentHint: '[path or focus]',
+    run(args) {
+        return {
+            expandedPrompt: `Review the code changes${args.trim() ? ' in/related to ' + args.trim() : ''} for bugs, security issues, and quality. ` +
+                'Use git diff and read the relevant files, then give a prioritized list of findings.',
+        };
+    },
+};
+const init = {
+    name: 'init',
+    description: 'Analyze the project and write a CLAUDE.md',
+    run() {
+        return {
+            expandedPrompt: 'Analyze this project (structure, key files, build/test commands, conventions) and write a concise CLAUDE.md ' +
+                'at the project root capturing what a coding agent needs to know. Use list_files/read_file/grep to investigate first.',
+        };
+    },
+};
+export const BUILTIN_COMMANDS = [
+    help, clear, compact, tools, cost, model,
+    sessions, resume, rename, diff, tasks, board, context, files, agents, mcp,
+    permissions, memory, exportCmd, review, init,
+];

package/dist/commands/index.d.ts

@@ -0,0 +1,21 @@
+import type { SlashCommand, SlashCommandContext, SlashOutcome } from './types.js';
+export * from './types.js';
+export { BUILTIN_COMMANDS } from './builtins.js';
+/** Parse `/name args...` → { name (lowercased, no slash), args }. Null if not a command. */
+export declare function parseSlashCommand(text: string): {
+    name: string;
+    args: string;
+} | null;
+/**
+ * Resolve and execute a slash command. Returns the command's SlashOutcome, or
+ * null when the text isn't a slash command or names an unknown command (so the
+ * caller can fall back to treating it as a normal prompt).
+ */
+export declare function runSlashCommand(text: string, ctx: Omit<SlashCommandContext, 'commands'> & {
+    commands?: SlashCommand[];
+}): Promise<SlashOutcome | null>;
+/**
+ * Define a custom prompt-template command (like a Claude Code markdown command).
+ * `$ARGUMENTS` in the template is replaced with the invocation args.
+ */
+export declare function promptCommand(name: string, description: string, prompt: string, argumentHint?: string): SlashCommand;