anyclaude-sdk 0.1.0

package/dist/tools/types.d.ts

@@ -0,0 +1,82 @@
+import type { AgentStore, CommandExecutor, ContentBlockParam, FileSystem, ToolDef } from '../types/index.js';
+/** Tunable caps for the read_file tool. */
+export interface FileReadLimits {
+    /** Max total file size in bytes before a text read is rejected. Default 256 KB. */
+    maxSizeBytes: number;
+    /** Max output tokens (rough estimate) before a text read is rejected. Default 25000. */
+    maxTokens: number;
+    /** Max image bytes after downsampling. Default ~3.75 MB. */
+    maxImageBytes: number;
+    /** Max PDF pages returned per read. Default 20. */
+    maxPdfPages: number;
+}
+/**
+ * Execution context handed to every tool. The agent loop owns the lifetime of
+ * `readFiles` (the set of paths the model has read this session) so that
+ * edit_file can enforce the "read before edit" rule.
+ */
+export interface ToolContext {
+    fs: FileSystem;
+    exec: CommandExecutor;
+    cwd: string;
+    readFiles: Set<string>;
+    signal?: AbortSignal;
+    /** Mutable session state (e.g. todos). The agent loop owns its lifetime. */
+    store?: AgentStore;
+    /** Optional read limits; tools fall back to sensible defaults when omitted. */
+    limits?: Partial<FileReadLimits>;
+    /**
+     * Spawn a sub-agent to completion and return its final text. Provided by the
+     * agent loop when sub-agents are enabled; the `task` tool relies on it.
+     */
+    runSubagent?: (opts: {
+        description: string;
+        prompt: string;
+        agentType?: string;
+        /** Abort signal (e.g. a background task's stop) — cancels the sub-agent. */
+        signal?: AbortSignal;
+        /** Streamed progress (assistant text + tool names) as the sub-agent works. */
+        onProgress?: (text: string) => void;
+    }) => Promise<{
+        text: string;
+        isError?: boolean;
+    }>;
+    /** Background task manager, present when background tasks are enabled. */
+    background?: import('../background/manager.js').BackgroundTaskManager;
+    /** Inter-agent mailbox, present when teammates are enabled. Shared with sub-agents. */
+    mailbox?: import('../team/mailbox.js').Mailbox;
+    /** Shared task board, present when teammates are enabled. Shared with sub-agents. */
+    board?: import('../team/taskBoard.js').TaskBoard;
+    /** This agent's name/label (e.g. 'coordinator' or a sub-agent type) for messaging. */
+    agentName?: string;
+    /** Index of all tools available this session (name + description), for tool_search. */
+    toolIndex?: Array<{
+        name: string;
+        description: string;
+    }>;
+    /** Persistent memory store, present when memory is enabled. Shared with sub-agents. */
+    memory?: import('../memory/store.js').MemoryStore;
+    /** Available skills (markdown prompt templates), for the `skill` tool. */
+    skills?: import('../skills/index.js').Skill[];
+    /** Plan-mode state; when active, mutating tools are denied. */
+    planMode?: {
+        active: boolean;
+    };
+}
+/** Result returned by a tool run. */
+export interface ToolResult {
+    content: string | ContentBlockParam[];
+    isError?: boolean;
+}
+/** 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>;
+    /**
+     * 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).
+     * Set to `Infinity` to opt out (e.g. read_file, which is already self-bounded).
+     * When omitted, the loop uses its global default threshold.
+     */
+    maxResultChars?: number;
+}

package/dist/tools/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/walk.d.ts

@@ -0,0 +1,29 @@
+import type { FileSystem } from '../types/index.js';
+/** Directories that are skipped during recursive walks by default. */
+export declare const DEFAULT_IGNORE: Set<string>;
+/** Join two path segments with a single separator, normalizing `.`. */
+export declare function joinPath(base: string, name: string): string;
+export interface WalkEntry {
+    /** Path relative to the walk root (POSIX separators). */
+    path: string;
+    isDir: boolean;
+}
+export interface WalkOptions {
+    /** Directory names to skip. Defaults to {@link DEFAULT_IGNORE}. */
+    ignore?: Set<string>;
+    /** Hard cap on entries yielded, to bound runaway trees. */
+    maxEntries?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Recursively walk a directory tree, yielding files and directories with paths
+ * relative to `root`. Directories in the ignore set are pruned. Unreadable
+ * directories are skipped silently.
+ */
+export declare function walk(fs: FileSystem, root: string, opts?: WalkOptions): AsyncGenerator<WalkEntry>;
+/**
+ * Translate a glob pattern into a RegExp.
+ * Supports `**` (any depth, including zero segments), `*` (within a segment),
+ * and `?` (single non-separator char). Other regex metachars are escaped.
+ */
+export declare function globToRegExp(pattern: string): RegExp;

package/dist/tools/walk.js

@@ -0,0 +1,82 @@
+/** Directories that are skipped during recursive walks by default. */
+export const DEFAULT_IGNORE = new Set(['node_modules', '.git', 'dist']);
+/** Join two path segments with a single separator, normalizing `.`. */
+export function joinPath(base, name) {
+    if (base === '' || base === '.')
+        return name;
+    return `${base.replace(/\/+$/, '')}/${name}`;
+}
+/**
+ * Recursively walk a directory tree, yielding files and directories with paths
+ * relative to `root`. Directories in the ignore set are pruned. Unreadable
+ * directories are skipped silently.
+ */
+export async function* walk(fs, root, opts = {}) {
+    const ignore = opts.ignore ?? DEFAULT_IGNORE;
+    const max = opts.maxEntries ?? 50_000;
+    let count = 0;
+    // Iterative BFS to avoid deep recursion and keep ordering stable.
+    const queue = [''];
+    while (queue.length > 0) {
+        if (opts.signal?.aborted)
+            return;
+        const rel = queue.shift();
+        const dirPath = rel === '' ? root : joinPath(root, rel);
+        const entries = await fs.readdir(dirPath);
+        if (!entries)
+            continue;
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            const childRel = rel === '' ? entry.name : `${rel}/${entry.name}`;
+            if (entry.isDir) {
+                if (ignore.has(entry.name))
+                    continue;
+                yield { path: childRel, isDir: true };
+                queue.push(childRel);
+            }
+            else {
+                yield { path: childRel, isDir: false };
+            }
+            if (++count >= max)
+                return;
+        }
+    }
+}
+/**
+ * Translate a glob pattern into a RegExp.
+ * Supports `**` (any depth, including zero segments), `*` (within a segment),
+ * and `?` (single non-separator char). Other regex metachars are escaped.
+ */
+export function globToRegExp(pattern) {
+    let re = '';
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === '*') {
+            if (pattern[i + 1] === '*') {
+                // `**` — match across directory separators.
+                i++;
+                // Consume a trailing slash so `**/foo` also matches `foo`.
+                if (pattern[i + 1] === '/') {
+                    i++;
+                    re += '(?:.*/)?';
+                }
+                else {
+                    re += '.*';
+                }
+            }
+            else {
+                re += '[^/]*';
+            }
+        }
+        else if (c === '?') {
+            re += '[^/]';
+        }
+        else if ('\\^$.|+()[]{}'.includes(c)) {
+            re += '\\' + c;
+        }
+        else {
+            re += c;
+        }
+    }
+    return new RegExp(`^${re}$`);
+}

package/dist/tools/web_fetch.d.ts

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

package/dist/tools/web_fetch.js

@@ -0,0 +1,76 @@
+const DESCRIPTION = `Fetches content from a URL and returns it as clean, readable text.
+
+- Takes a \`url\` and an optional \`prompt\` describing what to extract.
+- Powered by the Jina Reader (https://r.jina.ai/), which renders the page and returns LLM-ready Markdown — so JavaScript-heavy pages work and there are no CORS restrictions in the browser.
+- This tool is read-only and does not modify files.
+- The output may be truncated if the page is very large.`;
+/** Jina Reader endpoint. GET https://r.jina.ai/<target-url> → clean Markdown. */
+const JINA_READER = 'https://r.jina.ai/';
+const MAX_OUTPUT = 50_000;
+export const webFetch = {
+    def: {
+        type: 'function',
+        function: {
+            name: 'web_fetch',
+            description: DESCRIPTION,
+            parameters: {
+                type: 'object',
+                properties: {
+                    url: { type: 'string', description: 'Fully-formed URL to fetch.' },
+                    prompt: {
+                        type: 'string',
+                        description: 'What information to extract from the page (for your own focus).',
+                    },
+                },
+                required: ['url'],
+            },
+        },
+    },
+    async run(input, ctx) {
+        let url = String(input.url ?? '').trim();
+        if (!url)
+            return { content: 'Error: `url` is required.', isError: true };
+        if (!/^https?:\/\//i.test(url))
+            url = 'https://' + url;
+        // Route through Jina Reader: https://r.jina.ai/<target-url>.
+        const readerUrl = JINA_READER + url;
+        let res;
+        try {
+            res = await fetch(readerUrl, {
+                signal: ctx.signal,
+                redirect: 'follow',
+                headers: {
+                    accept: 'text/plain, text/markdown, */*',
+                    // Ask the reader to skip inline images so the text stays compact.
+                    'x-retain-images': 'none',
+                },
+            });
+        }
+        catch (err) {
+            return {
+                content: `Error fetching ${url} via Jina Reader: ${err instanceof Error ? err.message : String(err)}`,
+                isError: true,
+            };
+        }
+        if (!res.ok) {
+            return {
+                content: `Error: Jina Reader returned HTTP ${res.status} ${res.statusText} for ${url}.`,
+                isError: true,
+            };
+        }
+        let body;
+        try {
+            body = await res.text();
+        }
+        catch (err) {
+            return { content: `Error reading content of ${url}: ${err.message}`, isError: true };
+        }
+        let text = body.trim();
+        let note = '';
+        if (text.length > MAX_OUTPUT) {
+            text = text.slice(0, MAX_OUTPUT);
+            note = `\n\n[truncated to ${MAX_OUTPUT} characters]`;
+        }
+        return { content: `Fetched ${url} (via r.jina.ai):\n\n${text}${note}` };
+    },
+};

package/dist/tools/web_search.d.ts

@@ -0,0 +1,22 @@
+import type { Tool } from './types.js';
+export type SearchResult = {
+    title: string;
+    url: string;
+    snippet: string;
+};
+export declare const webSearch: Tool;
+/**
+ * Parse the Jina-rendered DuckDuckGo HTML results page (Markdown) into
+ * structured results.
+ *
+ * Each result renders as a block:
+ *   ## [Title](//duckduckgo.com/l/?uddg=<real-url>&rut=…)
+ *   [![Image N](favicon)](…redirect…)[www.example.com](…redirect…)
+ *   [Snippet text with **bold** terms…](…redirect…)
+ *
+ * We split on the `##` headings, take the title + decoded real URL from the
+ * heading link, and pick the longest prose link text in the block as the
+ * snippet (the bare-domain and favicon links are skipped). Falls back to a
+ * generic link scan if the page isn't heading-structured.
+ */
+export declare function parseDuckDuckGoResults(markdown: string): SearchResult[];

package/dist/tools/web_search.js

@@ -0,0 +1,195 @@
+const DESCRIPTION = `Searches the web and returns the top results (title, URL, snippet).
+
+- Takes a \`query\` and an optional \`num_results\` (default 5).
+- Powered by the Jina Reader over DuckDuckGo's HTML endpoint, so it works in the
+  browser without CORS issues and returns clean, parseable results.
+- Use this to find pages; follow up with \`web_fetch\` to read a specific result.`;
+/** Jina Reader prefix — renders a target URL to clean Markdown. */
+const JINA_READER = 'https://r.jina.ai/';
+/** DuckDuckGo's no-JS HTML results endpoint. */
+const DDG_HTML = 'https://html.duckduckgo.com/html/?q=';
+const DEFAULT_RESULTS = 5;
+const MAX_RESULTS = 20;
+export const webSearch = {
+    def: {
+        type: 'function',
+        function: {
+            name: 'web_search',
+            description: DESCRIPTION,
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'The search query.' },
+                    num_results: {
+                        type: 'number',
+                        description: `How many results to return (default ${DEFAULT_RESULTS}, max ${MAX_RESULTS}).`,
+                    },
+                },
+                required: ['query'],
+            },
+        },
+    },
+    async run(input, ctx) {
+        const query = String(input.query ?? '').trim();
+        if (!query)
+            return { content: 'Error: `query` is required.', isError: true };
+        const n = clampResults(input.num_results);
+        // Route the DuckDuckGo HTML results page through the Jina Reader.
+        const target = DDG_HTML + encodeURIComponent(query);
+        const readerUrl = JINA_READER + target;
+        let res;
+        try {
+            res = await fetch(readerUrl, {
+                signal: ctx.signal,
+                redirect: 'follow',
+                headers: { accept: 'text/plain, text/markdown, */*', 'x-retain-images': 'none' },
+            });
+        }
+        catch (err) {
+            return {
+                content: `Error searching for "${query}" via Jina/DuckDuckGo: ${err instanceof Error ? err.message : String(err)}`,
+                isError: true,
+            };
+        }
+        if (!res.ok) {
+            return {
+                content: `Error: search backend returned HTTP ${res.status} ${res.statusText}.`,
+                isError: true,
+            };
+        }
+        const markdown = await res.text().catch(() => '');
+        const results = parseDuckDuckGoResults(markdown).slice(0, n);
+        if (!results.length) {
+            return {
+                content: `No results found for "${query}".`,
+            };
+        }
+        const rendered = results
+            .map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}${r.snippet ? `\n   ${r.snippet}` : ''}`)
+            .join('\n\n');
+        return { content: `Search results for "${query}" (top ${results.length}):\n\n${rendered}` };
+    },
+};
+function clampResults(raw) {
+    const v = typeof raw === 'number' ? raw : parseInt(String(raw ?? ''), 10);
+    if (!Number.isFinite(v) || v <= 0)
+        return DEFAULT_RESULTS;
+    return Math.min(Math.floor(v), MAX_RESULTS);
+}
+/**
+ * Parse the Jina-rendered DuckDuckGo HTML results page (Markdown) into
+ * structured results.
+ *
+ * Each result renders as a block:
+ *   ## [Title](//duckduckgo.com/l/?uddg=<real-url>&rut=…)
+ *   [![Image N](favicon)](…redirect…)[www.example.com](…redirect…)
+ *   [Snippet text with **bold** terms…](…redirect…)
+ *
+ * We split on the `##` headings, take the title + decoded real URL from the
+ * heading link, and pick the longest prose link text in the block as the
+ * snippet (the bare-domain and favicon links are skipped). Falls back to a
+ * generic link scan if the page isn't heading-structured.
+ */
+export function parseDuckDuckGoResults(markdown) {
+    const out = [];
+    const seen = new Set();
+    // Split into per-result blocks on the `##` result headings.
+    const blocks = markdown.split(/^\s*##\s+/m).slice(1);
+    for (const block of blocks) {
+        const head = block.match(/^\[([^\]]+)\]\(([^)]+)\)/);
+        if (!head)
+            continue;
+        const title = cleanText(head[1]);
+        const url = decodeDdgUrl(head[2].trim());
+        if (!title || !url || !isResultUrl(url) || seen.has(url))
+            continue;
+        // Snippet = the longest prose link text in the block (has spaces, not the
+        // title, not an image, not a bare domain/url).
+        let snippet = '';
+        const linkRe = /\[([^\]]+)\]\([^)]+\)/g;
+        let m;
+        while ((m = linkRe.exec(block)) !== null) {
+            const t = cleanText(m[1]);
+            if (!t || t === title || t.startsWith('!'))
+                continue;
+            if (!/\s/.test(t))
+                continue; // bare domain / url fragment
+            if (t.length > snippet.length)
+                snippet = t;
+        }
+        seen.add(url);
+        out.push({ title, url, snippet: snippet.slice(0, 300) });
+    }
+    if (out.length)
+        return out;
+    return parseGenericLinks(markdown, seen);
+}
+/** Fallback: scan every markdown link when the page isn't heading-structured. */
+function parseGenericLinks(markdown, seen) {
+    const out = [];
+    const linkRe = /\[([^\]]+)\]\(([^)]+)\)/g;
+    let m;
+    while ((m = linkRe.exec(markdown)) !== null) {
+        const title = cleanText(m[1]);
+        if (!title || title.startsWith('!'))
+            continue;
+        const url = decodeDdgUrl(m[2].trim());
+        if (!url || !isResultUrl(url) || seen.has(url))
+            continue;
+        seen.add(url);
+        out.push({ title, url, snippet: '' });
+    }
+    return out;
+}
+/** Decode DuckDuckGo's `/l/?uddg=` redirect wrapper to the real URL. */
+function decodeDdgUrl(raw) {
+    let url = raw;
+    if (url.startsWith('//'))
+        url = 'https:' + url;
+    try {
+        const u = new URL(url, 'https://duckduckgo.com');
+        if (u.pathname.startsWith('/l/') || u.hostname.endsWith('duckduckgo.com')) {
+            const uddg = u.searchParams.get('uddg');
+            if (uddg)
+                return decodeURIComponent(uddg);
+        }
+        return u.toString();
+    }
+    catch {
+        return url;
+    }
+}
+/** Keep only http(s) result links; drop DDG nav/ad/internal anchors. */
+function isResultUrl(url) {
+    if (!/^https?:\/\//i.test(url))
+        return false;
+    if (/duckduckgo\.com\/(?!l\/)/i.test(url))
+        return false; // nav/settings links
+    if (/(^|\.)duckduckgo\.com$/i.test(safeHost(url)) && !/\/l\//.test(url))
+        return false;
+    return true;
+}
+function safeHost(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return '';
+    }
+}
+function extractSnippet(text) {
+    // Take the first non-empty, non-link paragraph as the snippet.
+    const lines = text.split('\n');
+    for (const line of lines) {
+        const t = cleanText(line);
+        if (t && !t.startsWith('[') && t.length > 20)
+            return t.slice(0, 300);
+    }
+    return '';
+}
+function cleanText(s) {
+    return s
+        .replace(/[*_`>#]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}

package/dist/tools/write_file.d.ts

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

package/dist/tools/write_file.js

@@ -0,0 +1,39 @@
+const DESCRIPTION = `Writes a file to the workspace filesystem, creating parent directories as needed and overwriting any existing file.
+
+Prefer edit_file for modifying existing files; use write_file for new files or full rewrites.`;
+export const writeFile = {
+    def: {
+        type: 'function',
+        function: {
+            name: 'write_file',
+            description: DESCRIPTION,
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'Path to the file to write.' },
+                    content: { type: 'string', description: 'Full contents to write.' },
+                },
+                required: ['path', 'content'],
+            },
+        },
+    },
+    async run(input, ctx) {
+        const path = String(input.path ?? '');
+        if (!path)
+            return { content: 'Error: `path` is required.', isError: true };
+        const content = typeof input.content === 'string' ? input.content : '';
+        try {
+            await ctx.fs.writeFile(path, content);
+        }
+        catch (err) {
+            return {
+                content: `Error writing ${path}: ${err.message}`,
+                isError: true,
+            };
+        }
+        // A freshly written file counts as "read" so it can be edited next.
+        ctx.readFiles.add(path);
+        const bytes = new TextEncoder().encode(content).length;
+        return { content: `Wrote ${bytes} bytes to ${path}` };
+    },
+};