anyclaude-sdk 0.1.0

package/dist/tools/notebook_edit.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare const notebookEdit: Tool;

package/dist/tools/notebook_edit.js

@@ -0,0 +1,118 @@
+const DESCRIPTION = `Edits a cell in a Jupyter notebook (.ipynb file).
+
+- \`cell_id\` is the 0-indexed cell position.
+- edit_mode=replace (default): completely replaces the source of the cell at cell_id.
+- edit_mode=insert: inserts a new cell at index cell_id (use cell_type to choose code/markdown).
+- edit_mode=delete: removes the cell at cell_id.
+- New code cells are created with empty outputs and a null execution_count.`;
+/** Store source as an array of newline-terminated lines (the canonical .ipynb form). */
+function toSourceLines(text) {
+    const parts = text.split('\n');
+    return parts.map((line, i) => (i < parts.length - 1 ? line + '\n' : line));
+}
+export const notebookEdit = {
+    def: {
+        type: 'function',
+        function: {
+            name: 'notebook_edit',
+            description: DESCRIPTION,
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'Path to the .ipynb notebook.' },
+                    cell_id: {
+                        type: ['number', 'string'],
+                        description: '0-indexed cell position to edit/insert/delete.',
+                    },
+                    new_source: {
+                        type: 'string',
+                        description: 'New cell source (ignored for delete).',
+                    },
+                    cell_type: {
+                        type: 'string',
+                        enum: ['code', 'markdown'],
+                        description: 'Cell type for replace/insert. Defaults to code.',
+                    },
+                    edit_mode: {
+                        type: 'string',
+                        enum: ['replace', 'insert', 'delete'],
+                        description: 'Operation to perform. Defaults to replace.',
+                    },
+                },
+                required: ['path', 'new_source'],
+            },
+        },
+    },
+    async run(input, ctx) {
+        const path = String(input.path ?? '');
+        if (!path)
+            return { content: 'Error: `path` is required.', isError: true };
+        const editMode = input.edit_mode ?? 'replace';
+        if (!['replace', 'insert', 'delete'].includes(editMode)) {
+            return { content: `Error: invalid edit_mode "${editMode}".`, isError: true };
+        }
+        const raw = await ctx.fs.readFile(path);
+        if (raw === null)
+            return { content: `Error: file not found: ${path}`, isError: true };
+        let nb;
+        try {
+            nb = JSON.parse(raw);
+        }
+        catch (err) {
+            return { content: `Error: ${path} is not valid JSON: ${err.message}`, isError: true };
+        }
+        if (!nb || !Array.isArray(nb.cells)) {
+            return { content: `Error: ${path} is not a valid notebook (missing cells array).`, isError: true };
+        }
+        const index = Number(input.cell_id ?? 0);
+        if (!Number.isInteger(index) || index < 0) {
+            return { content: `Error: cell_id must be a non-negative integer.`, isError: true };
+        }
+        const newSource = typeof input.new_source === 'string' ? input.new_source : '';
+        const cellType = input.cell_type ?? 'code';
+        if (editMode === 'delete') {
+            if (index >= nb.cells.length) {
+                return { content: `Error: cell index ${index} out of range (notebook has ${nb.cells.length} cells).`, isError: true };
+            }
+            nb.cells.splice(index, 1);
+        }
+        else if (editMode === 'insert') {
+            if (index > nb.cells.length) {
+                return { content: `Error: insert index ${index} out of range (notebook has ${nb.cells.length} cells).`, isError: true };
+            }
+            const cell = {
+                cell_type: cellType,
+                metadata: {},
+                source: toSourceLines(newSource),
+            };
+            if (cellType === 'code') {
+                cell.outputs = [];
+                cell.execution_count = null;
+            }
+            nb.cells.splice(index, 0, cell);
+        }
+        else {
+            // replace
+            if (index >= nb.cells.length) {
+                return { content: `Error: cell index ${index} out of range (notebook has ${nb.cells.length} cells).`, isError: true };
+            }
+            const cell = nb.cells[index];
+            cell.source = toSourceLines(newSource);
+            if (input.cell_type) {
+                cell.cell_type = cellType;
+                if (cellType === 'code' && cell.outputs === undefined) {
+                    cell.outputs = [];
+                    cell.execution_count = null;
+                }
+            }
+        }
+        try {
+            await ctx.fs.writeFile(path, JSON.stringify(nb, null, 2));
+        }
+        catch (err) {
+            return { content: `Error writing ${path}: ${err.message}`, isError: true };
+        }
+        const verb = editMode === 'delete' ? 'Deleted' : editMode === 'insert' ? 'Inserted' : 'Replaced';
+        return { content: `${verb} cell ${index} in ${path}. Notebook now has ${nb.cells.length} cells.` };
+    },
+};

package/dist/tools/plan_mode.d.ts

@@ -0,0 +1,4 @@
+import type { Tool } from './types.js';
+export declare const enterPlanMode: Tool;
+export declare const exitPlanMode: Tool;
+export declare const PLAN_MODE_TOOLS: Tool[];

package/dist/tools/plan_mode.js

@@ -0,0 +1,44 @@
+const ENTER_DESC = `Enter plan mode: research and design WITHOUT making changes.
+
+While in plan mode, mutating tools (write_file, edit_file, bash that changes state, etc.) are blocked. Use read-only tools to investigate, then present a clear plan and call exit_plan_mode to proceed.`;
+const EXIT_DESC = `Exit plan mode and present your plan.
+
+Pass the finalized \`plan\` (markdown). After this, mutating tools are allowed again so you can execute.`;
+export const enterPlanMode = {
+    def: {
+        type: 'function',
+        function: {
+            name: 'enter_plan_mode',
+            description: ENTER_DESC,
+            parameters: { type: 'object', properties: {}, required: [] },
+        },
+    },
+    async run(_input, ctx) {
+        if (!ctx.planMode)
+            return { content: 'Plan mode is not available in this session.', isError: true };
+        ctx.planMode.active = true;
+        return { content: 'Entered plan mode. Mutating tools are disabled; investigate with read-only tools, then call exit_plan_mode with your plan.' };
+    },
+};
+export const exitPlanMode = {
+    def: {
+        type: 'function',
+        function: {
+            name: 'exit_plan_mode',
+            description: EXIT_DESC,
+            parameters: {
+                type: 'object',
+                properties: { plan: { type: 'string', description: 'The finalized plan (markdown).' } },
+                required: [],
+            },
+        },
+    },
+    async run(input, ctx) {
+        if (!ctx.planMode)
+            return { content: 'Plan mode is not available in this session.', isError: true };
+        ctx.planMode.active = false;
+        const plan = String(input.plan ?? '').trim();
+        return { content: `Exited plan mode. Mutating tools are enabled.${plan ? '\n\nPlan:\n' + plan : ''}` };
+    },
+};
+export const PLAN_MODE_TOOLS = [enterPlanMode, exitPlanMode];

package/dist/tools/read_file.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare const readFile: Tool;

package/dist/tools/read_file.js

@@ -0,0 +1,193 @@
+import { DEFAULT_FILE_READ_LIMITS, bytesToBase64, detectImageFormatFromBytes, extOf, formatBytes, hasBinaryExtension, imageMediaType, isImageExtension, isNotebookExtension, isPdfExtension, looksBinary, roughTokenCount, } from './fileTypes.js';
+import { processImage } from './imageProcessor.js';
+const DESCRIPTION = `Reads a file from the workspace filesystem.
+
+- \`path\` may be absolute or relative to the workspace root.
+- Text files are returned with line numbers (cat -n style). Use \`offset\`/\`limit\` (1-based lines) to read a slice of large files.
+- Image files (png/jpg/jpeg/gif/webp/bmp) are returned as a viewable image block, downsampled if large.
+- PDF files are returned as a document block for the model to read directly.
+- Jupyter notebooks (.ipynb) are rendered as cells with their outputs.
+- Reads are capped by size and token count; very large text files must be read with offset/limit or searched with grep.`;
+const PARAMS = {
+    type: 'object',
+    properties: {
+        path: { type: 'string', description: 'Path to the file to read.' },
+        offset: { type: 'number', description: 'Line number to start reading from (1-based, text files).' },
+        limit: { type: 'number', description: 'Maximum number of lines to read (text files).' },
+        pages: { type: 'string', description: 'PDF page range hint, e.g. "1-5,8" (informational only).' },
+    },
+    required: ['path'],
+};
+function limitsOf(ctx) {
+    return { ...DEFAULT_FILE_READ_LIMITS, ...(ctx.limits ?? {}) };
+}
+function baseName(path) {
+    const slash = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+    return slash === -1 ? path : path.slice(slash + 1);
+}
+const NOT_FOUND = (path) => `Error: file not found: ${path}. Check the path is correct and relative to the workspace root, or use list_files/glob to locate it.`;
+const CELL_OUTPUT_CAP = 10_000;
+function joinSource(src) {
+    if (!src)
+        return '';
+    return Array.isArray(src) ? src.join('') : src;
+}
+function truncate(text, cap) {
+    return text.length > cap ? text.slice(0, cap) + `\n… [output truncated, ${text.length - cap} more chars]` : text;
+}
+function renderOutput(out) {
+    switch (out.output_type) {
+        case 'stream':
+            return truncate(joinSource(out.text), CELL_OUTPUT_CAP);
+        case 'execute_result':
+        case 'display_data': {
+            const text = joinSource(out.data?.['text/plain']);
+            const hasImg = typeof out.data?.['image/png'] === 'string' || typeof out.data?.['image/jpeg'] === 'string';
+            const parts = [text ? truncate(text, CELL_OUTPUT_CAP) : '', hasImg ? '[image output]' : ''];
+            return parts.filter(Boolean).join('\n');
+        }
+        case 'error':
+            return truncate(`${out.ename ?? 'Error'}: ${out.evalue ?? ''}\n${(out.traceback ?? []).join('\n')}`, CELL_OUTPUT_CAP);
+        default:
+            return '';
+    }
+}
+function renderNotebook(text) {
+    let nb;
+    try {
+        nb = JSON.parse(text);
+    }
+    catch {
+        return 'Error: notebook is not valid JSON.';
+    }
+    const cells = nb.cells ?? [];
+    const out = [];
+    cells.forEach((cell, i) => {
+        const kind = cell.cell_type ?? 'unknown';
+        out.push(`#%% [cell ${i + 1}] (${kind})`);
+        const source = joinSource(cell.source);
+        if (source)
+            out.push(source);
+        if (kind === 'code' && cell.outputs?.length) {
+            const rendered = cell.outputs.map(renderOutput).filter(Boolean).join('\n');
+            if (rendered)
+                out.push('# --- output ---\n' + rendered);
+        }
+        out.push('');
+    });
+    return out.join('\n').trimEnd() || '(empty notebook)';
+}
+// ---------------------------------------------------------------------------
+// Tool
+// ---------------------------------------------------------------------------
+export const readFile = {
+    def: { type: 'function', function: { name: 'read_file', description: DESCRIPTION, parameters: PARAMS } },
+    // read_file is already self-bounded by size/token caps; never spill its
+    // output to a file (that would be circular — the model reads files with this).
+    maxResultChars: Infinity,
+    async run(input, ctx) {
+        const path = String(input.path ?? '');
+        if (!path)
+            return { content: 'Error: `path` is required.', isError: true };
+        const limits = limitsOf(ctx);
+        const ext = extOf(path);
+        const name = baseName(path);
+        // ---- Image ----
+        if (isImageExtension(path)) {
+            const bytes = await ctx.fs.readBinary(path);
+            if (!bytes)
+                return { content: NOT_FOUND(path), isError: true };
+            ctx.readFiles.add(path);
+            const media = detectImageFormatFromBytes(bytes) ?? imageMediaType(ext);
+            const img = await processImage(bytes, media, limits.maxImageBytes);
+            const dims = img.width && img.height ? `${img.width}x${img.height}, ` : '';
+            const meta = `Image: ${name} (${dims}${formatBytes(bytes.length)}${img.media_type !== media ? `, re-encoded as ${img.media_type}` : ''}).${img.note ? ' ' + img.note : ''}`;
+            const blocks = [
+                { type: 'image', source: { type: 'base64', media_type: img.media_type, data: img.data } },
+                { type: 'text', text: meta },
+            ];
+            return { content: blocks };
+        }
+        // ---- PDF ----
+        if (isPdfExtension(path)) {
+            const bytes = await ctx.fs.readBinary(path);
+            if (!bytes)
+                return { content: NOT_FOUND(path), isError: true };
+            ctx.readFiles.add(path);
+            const large = bytes.length > 3 * 1024 * 1024;
+            const pagesNote = typeof input.pages === 'string' && input.pages.trim()
+                ? ` Requested pages "${input.pages}" — page-range extraction is not performed client-side; the full document is provided.`
+                : '';
+            const doc = {
+                type: 'document',
+                source: { type: 'base64', media_type: 'application/pdf', data: bytesToBase64(bytes) },
+                title: name,
+            };
+            const note = {
+                type: 'text',
+                text: `PDF: ${name} (${formatBytes(bytes.length)}).${large ? ' Large file.' : ''}${pagesNote} The full document is attached for the model to read.`,
+            };
+            return { content: [doc, note] };
+        }
+        // ---- Notebook ----
+        if (isNotebookExtension(path)) {
+            const text = await ctx.fs.readFile(path);
+            if (text === null)
+                return { content: NOT_FOUND(path), isError: true };
+            ctx.readFiles.add(path);
+            return { content: renderNotebook(text) };
+        }
+        // ---- Binary by extension ----
+        if (hasBinaryExtension(path)) {
+            return {
+                content: `Error: cannot read binary file ${name} (${ext || 'unknown type'}) as text. Use the bash tool or a dedicated tool if you need its contents.`,
+                isError: true,
+            };
+        }
+        // ---- Text (with binary sniff) ----
+        const bytes = await ctx.fs.readBinary(path);
+        if (bytes === null)
+            return { content: NOT_FOUND(path), isError: true };
+        if (looksBinary(bytes)) {
+            return {
+                content: `Error: ${name} appears to be a binary file (contains NUL bytes) and cannot be read as text. Use the bash tool if needed.`,
+                isError: true,
+            };
+        }
+        if (bytes.length > limits.maxSizeBytes) {
+            return {
+                content: `Error: file ${name} is ${formatBytes(bytes.length)}, exceeding the ${formatBytes(limits.maxSizeBytes)} read limit. Read a slice with offset/limit, or search with grep instead of reading the whole file.`,
+                isError: true,
+            };
+        }
+        const text = await ctx.fs.readFile(path);
+        if (text === null)
+            return { content: NOT_FOUND(path), isError: true };
+        ctx.readFiles.add(path);
+        if (text === '')
+            return { content: '(file is empty)' };
+        const lines = text.split('\n');
+        const offset = typeof input.offset === 'number' && input.offset > 0 ? Math.floor(input.offset) : 1;
+        const limit = typeof input.limit === 'number' && input.limit > 0 ? Math.floor(input.limit) : lines.length;
+        const start = offset - 1;
+        const slice = lines.slice(start, start + limit);
+        // cat -n style: right-aligned line number, tab, content.
+        const lastNum = start + slice.length;
+        const width = String(lastNum).length;
+        const numbered = slice
+            .map((line, i) => `${String(start + i + 1).padStart(width, ' ')}\t${line}`)
+            .join('\n');
+        const tokens = roughTokenCount(numbered);
+        if (tokens > limits.maxTokens) {
+            return {
+                content: `Error: the requested content is ~${tokens} tokens, exceeding the ${limits.maxTokens}-token cap. Narrow the read with offset/limit, or search with grep.`,
+                isError: true,
+            };
+        }
+        const shownEnd = start + slice.length;
+        const note = shownEnd < lines.length || start > 0
+            ? `\n\n[showing lines ${offset}-${shownEnd} of ${lines.length}]`
+            : '';
+        return { content: numbered + note };
+    },
+};

package/dist/tools/task.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare const task: Tool;

package/dist/tools/task.js

@@ -0,0 +1,77 @@
+const DESCRIPTION = `Launch a sub-agent to handle a complex, multi-step task autonomously.
+
+- Provide a short \`description\` (3-5 words) and a detailed \`prompt\` describing exactly what the sub-agent should do.
+- Optionally set \`subagent_type\` to select a configured agent; otherwise a general-purpose agent is used.
+- The sub-agent runs its own tool loop to completion and returns only its final result — its intermediate steps do not enter this conversation.
+- Use this to parallelize or isolate self-contained work (research, broad searches, multi-file changes). For a single quick action, just call the relevant tool directly.`;
+export const task = {
+    def: {
+        type: 'function',
+        function: {
+            name: 'task',
+            description: DESCRIPTION,
+            parameters: {
+                type: 'object',
+                properties: {
+                    description: {
+                        type: 'string',
+                        description: 'A short (3-5 word) description of the task.',
+                    },
+                    prompt: {
+                        type: 'string',
+                        description: 'The detailed task for the sub-agent to perform.',
+                    },
+                    subagent_type: {
+                        type: 'string',
+                        description: 'Optional name of a configured agent type to use.',
+                    },
+                    run_in_background: {
+                        type: 'boolean',
+                        description: 'Run the sub-agent in the background and return immediately with a task id. Poll it with task_output/task_list.',
+                    },
+                },
+                required: ['description', 'prompt'],
+            },
+        },
+    },
+    async run(input, ctx) {
+        if (!ctx.runSubagent) {
+            return {
+                content: 'Sub-agents are not enabled for this session.',
+                isError: true,
+            };
+        }
+        const prompt = String(input.prompt ?? '').trim();
+        if (!prompt)
+            return { content: 'Error: `prompt` is required.', isError: true };
+        const description = String(input.description ?? '').trim();
+        const agentType = input.subagent_type ? String(input.subagent_type) : undefined;
+        // Background mode: detach via the BackgroundTaskManager and return a handle.
+        if (input.run_in_background) {
+            if (!ctx.background) {
+                return {
+                    content: 'Background tasks are not enabled for this session.',
+                    isError: true,
+                };
+            }
+            const id = ctx.background.start(description || 'sub-agent', async (signal, append) => {
+                const r = await ctx.runSubagent({
+                    description,
+                    prompt,
+                    agentType,
+                    signal, // so task_stop actually aborts the sub-agent
+                    onProgress: (t) => append(t.endsWith('\n') ? t : t + '\n'), // stream progress to task_output
+                });
+                return r.text;
+            });
+            return {
+                content: `Started background task ${id} (${description || 'sub-agent'}). Use task_output with task_id "${id}" to read its results, or task_list to see status.`,
+            };
+        }
+        const result = await ctx.runSubagent({ description, prompt, agentType });
+        return {
+            content: result.text || '(sub-agent produced no output)',
+            isError: result.isError,
+        };
+    },
+};

package/dist/tools/todo_write.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare const todoWrite: Tool;

package/dist/tools/todo_write.js

@@ -0,0 +1,104 @@
+const DESCRIPTION = `Create and manage a structured task list for the current session.
+
+## When to use
+- Complex multi-step tasks (3+ distinct steps).
+- Non-trivial tasks that benefit from planning.
+- When the user provides multiple tasks, or explicitly asks for a todo list.
+
+## When NOT to use
+- A single, straightforward, or trivial task.
+- Purely conversational/informational requests.
+
+## Rules
+- Mark a task in_progress BEFORE starting it; keep only ONE task in_progress at a time.
+- Mark a task completed IMMEDIATELY after finishing it — don't batch completions.
+- Each todo has \`content\` (imperative, e.g. "Add tests") and optionally \`activeForm\` (present continuous, e.g. "Adding tests").
+- Calling this tool replaces the entire todo list with the provided array.`;
+// Fallback store used when the agent loop doesn't supply ctx.store (e.g. tools
+// used standalone). Keeps the tool functional in isolation.
+const fallbackStore = { todos: [] };
+const GLYPH = {
+    pending: '☐',
+    in_progress: '◐',
+    completed: '☒',
+};
+function render(todos) {
+    if (!todos.length)
+        return 'Todo list cleared (no items).';
+    return todos
+        .map((t) => `${GLYPH[t.status] ?? '☐'} ${t.content}`)
+        .join('\n');
+}
+export const todoWrite = {
+    def: {
+        type: 'function',
+        function: {
+            name: 'todo_write',
+            description: DESCRIPTION,
+            parameters: {
+                type: 'object',
+                properties: {
+                    todos: {
+                        type: 'array',
+                        description: 'The complete, updated todo list (replaces any existing list).',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                content: { type: 'string', description: 'Imperative task description.' },
+                                status: {
+                                    type: 'string',
+                                    enum: ['pending', 'in_progress', 'completed'],
+                                    description: 'Current status of the task.',
+                                },
+                                activeForm: {
+                                    type: 'string',
+                                    description: 'Present-continuous form shown while in progress.',
+                                },
+                            },
+                            required: ['content', 'status'],
+                        },
+                    },
+                },
+                required: ['todos'],
+            },
+        },
+    },
+    async run(input, ctx) {
+        if (!Array.isArray(input.todos)) {
+            return { content: 'Error: `todos` must be an array.', isError: true };
+        }
+        const todos = [];
+        for (const raw of input.todos) {
+            const t = raw;
+            const content = typeof t?.content === 'string' ? t.content : '';
+            const status = t?.status;
+            if (!content)
+                return { content: 'Error: every todo needs a non-empty `content`.', isError: true };
+            if (status !== 'pending' && status !== 'in_progress' && status !== 'completed') {
+                return { content: `Error: invalid status "${String(status)}" for "${content}".`, isError: true };
+            }
+            todos.push({
+                content,
+                status,
+                ...(typeof t.activeForm === 'string' ? { activeForm: t.activeForm } : {}),
+            });
+        }
+        const inProgress = todos.filter((t) => t.status === 'in_progress').length;
+        if (inProgress > 1) {
+            return {
+                content: `Error: only one task may be in_progress at a time (found ${inProgress}).`,
+                isError: true,
+            };
+        }
+        const target = ctx.store ?? fallbackStore;
+        target.todos = todos;
+        const counts = {
+            pending: todos.filter((t) => t.status === 'pending').length,
+            in_progress: inProgress,
+            completed: todos.filter((t) => t.status === 'completed').length,
+        };
+        return {
+            content: `${render(todos)}\n\n(${counts.completed} done, ${counts.in_progress} in progress, ${counts.pending} pending)`,
+        };
+    },
+};

package/dist/tools/tool_search.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare const toolSearch: Tool;

package/dist/tools/tool_search.js

@@ -0,0 +1,49 @@
+const DESCRIPTION = `Searches the available tools by keyword and returns the best matches (name + description).
+
+Use this to discover which tool fits a task when many tools are loaded (e.g. lots of MCP tools). Returns ranked matches; then call the chosen tool directly.`;
+export const toolSearch = {
+    def: {
+        type: 'function',
+        function: {
+            name: 'tool_search',
+            description: DESCRIPTION,
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Keywords describing what you want to do.' },
+                    limit: { type: 'number', description: 'Max results (default 8).' },
+                },
+                required: ['query'],
+            },
+        },
+    },
+    async run(input, ctx) {
+        const index = ctx.toolIndex ?? [];
+        if (!index.length)
+            return { content: 'No tool index available.', isError: true };
+        const q = String(input.query ?? '').toLowerCase().trim();
+        const terms = q.split(/\s+/).filter(Boolean);
+        const limit = Math.min(Math.max(Number(input.limit) || 8, 1), 25);
+        const scored = index
+            .map((t) => {
+            const hay = (t.name + ' ' + t.description).toLowerCase();
+            let score = 0;
+            for (const term of terms) {
+                if (t.name.toLowerCase().includes(term))
+                    score += 3;
+                else if (hay.includes(term))
+                    score += 1;
+            }
+            return { t, score };
+        })
+            .filter((x) => x.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+        if (!scored.length)
+            return { content: `No tools matched "${q}".` };
+        return {
+            content: `Matching tools for "${q}":\n` +
+                scored.map(({ t }) => `  ${t.name} — ${t.description.split('\n')[0]}`).join('\n'),
+        };
+    },
+};