anyclaude-sdk 0.4.9 → 0.5.0

package/dist/agent.d.ts

@@ -49,6 +49,11 @@ export interface AgentOptions {
         content: string | ContentBlockParam[];
         is_error?: boolean;
     }>;
+    /** Validate tool arguments before executing; on malformed/incomplete JSON,
+     *  return a corrective `is_error` tool_result (with the expected schema) so the
+     *  model self-heals instead of running with garbage. Default `true`. The single
+     *  biggest reliability win for weak/cheap models. See `anyclaude-sdk/llm` repair. */
+    repairToolCalls?: boolean;
     cwd?: string;
     sessionId?: string;
     abortController?: AbortController;

package/dist/agent.js

@@ -24,6 +24,7 @@ import { defaultSystemPrompt, defaultSubagentPrompt } from './prompt.js';
 import { DEFAULT_MAX_RESULT_CHARS, maybePersistLargeResult } from './persist.js';
 import { computeCostUSD, contextWindowFor } from './util/pricing.js';
 import { estimateTokens, summarizeHistory } from './compact.js';
+import { validateToolArguments } from './llm/repair.js';
 import { uuid } from './util/ids.js';
 /** Wrap a single text prompt into the async-iterable form runAgent expects. */
 async function* singleUserPrompt(text) {
@@ -203,6 +204,7 @@ export async function* runAgent(options) {
         : undefined;
     const messageQueue = options.messageQueue;
     const clientTools = new Set(options.clientTools ?? []);
+    const repairToolCalls = options.repairToolCalls !== false;
     // Teammates: a shared Mailbox + TaskBoard (reused from the parent when this
     // is a sub-agent) + team tools + coordinator prompt.
     const teamEnabled = options.team === true;
@@ -717,7 +719,19 @@ export async function* runAgent(options) {
                 let content = '';
                 let isError = false;
                 let extraContext = '';
-                if (!tool || !tool.run) {
+                // Repair: validate args against the tool schema before running a server
+                // tool; on malformed/incomplete JSON, return a corrective tool_result so
+                // the model retries with valid JSON instead of executing with garbage.
+                const repairCheck = repairToolCalls && tool && tool.run
+                    ? validateToolArguments(tool.def, call.function.arguments)
+                    : null;
+                if (repairCheck && repairCheck.ok)
+                    input = repairCheck.input;
+                if (repairCheck && !repairCheck.ok) {
+                    content = repairCheck.error;
+                    isError = true;
+                }
+                else if (!tool || !tool.run) {
                     // Unknown, or a run-less (client-delegated) tool that somehow reached
                     // server execution — both are errors here (delegated tools are handled
                     // above via clientTools).

package/dist/llm/dialects.d.ts

@@ -0,0 +1,32 @@
+import type { ToolCall } from '../types/index.js';
+export interface ParsedToolCalls {
+    /** Tool calls recovered from the text (empty if none matched). */
+    calls: ToolCall[];
+    /** The text with tool-call markup removed (safe to show the user). */
+    cleanedText: string;
+}
+export interface ToolDialect {
+    /** Stable id, e.g. 'xml-function' | 'hermes' | 'json-fence'. */
+    name: string;
+    /** Cheap presence check — does this dialect's markup appear at all? */
+    test(text: string): boolean;
+    /** Extract calls + strip markup. `idBase` seeds generated call ids. */
+    parse(text: string, idBase?: number): ParsedToolCalls;
+}
+export declare const xmlFunctionDialect: ToolDialect;
+export declare const hermesDialect: ToolDialect;
+export declare const jsonFenceDialect: ToolDialect;
+/** All built-in dialects, keyed by name. */
+export declare const dialects: Record<string, ToolDialect>;
+/** Default attempt order — xml-function first preserves original behavior. */
+export declare const DEFAULT_DIALECTS: string[];
+/**
+ * Try a list of dialects (by name) against text and return the first that
+ * yields tool calls. Falls back to `{ calls: [], cleanedText: text }`.
+ */
+export declare function parseToolCalls(text: string, opts?: {
+    dialects?: string[];
+    idBase?: number;
+}): ParsedToolCalls;
+/** True if ANY of the given dialects (default: all) detects tool-call markup. */
+export declare function hasToolCalls(text: string, order?: string[]): boolean;

package/dist/llm/dialects.js

@@ -0,0 +1,218 @@
+/** Strip a single leading newline and trailing whitespace from a param value. */
+function trimEdges(v) {
+    return v.replace(/^\r?\n/, '').replace(/\s+$/, '');
+}
+// ---------------------------------------------------------------------------
+// xml-function — <function=name><parameter=key>value</parameter></function>
+// (closing tags optional; wrapper <tool_call> optional). This is the original
+// anyclaude inline format and stays first in the default order for back-compat.
+// ---------------------------------------------------------------------------
+const XML_FUNCTION_MARKER = /<function\s*=/;
+export const xmlFunctionDialect = {
+    name: 'xml-function',
+    test: (text) => XML_FUNCTION_MARKER.test(text),
+    parse(text, idBase = 0) {
+        if (!text || !XML_FUNCTION_MARKER.test(text))
+            return { calls: [], cleanedText: text };
+        const calls = [];
+        const markerRe = /<function\s*=\s*([^>\s]+)\s*>/g;
+        const markers = [];
+        let m;
+        while ((m = markerRe.exec(text)) !== null) {
+            markers.push({ name: m[1], bodyStart: markerRe.lastIndex, markerStart: m.index });
+        }
+        for (let i = 0; i < markers.length; i++) {
+            const cur = markers[i];
+            const end = i + 1 < markers.length ? markers[i + 1].markerStart : text.length;
+            let body = text.slice(cur.bodyStart, end);
+            body = body.replace(/<\/function>[\s\S]*$/, '').replace(/<\/tool_call>[\s\S]*$/, '');
+            const args = {};
+            const parts = body.split(/<parameter\s*=/).slice(1);
+            for (const part of parts) {
+                const gt = part.indexOf('>');
+                if (gt < 0)
+                    continue;
+                const key = part.slice(0, gt).trim();
+                let val = part.slice(gt + 1);
+                val = val
+                    .replace(/<\/parameter>[\s\S]*$/, '')
+                    .replace(/<\/function>[\s\S]*$/, '')
+                    .replace(/<\/tool_call>[\s\S]*$/, '');
+                args[key] = trimEdges(val);
+            }
+            calls.push({
+                id: `call_inline_${idBase + i}`,
+                type: 'function',
+                function: { name: cur.name.trim(), arguments: JSON.stringify(args) },
+            });
+        }
+        const cut = text.search(/<tool_call>|<function\s*=/);
+        const cleanedText = cut >= 0 ? text.slice(0, cut).trim() : text;
+        return { calls, cleanedText };
+    },
+};
+// ---------------------------------------------------------------------------
+// hermes — <tool_call>{"name": "...", "arguments": {...}}</tool_call>
+// Accepts "arguments" | "parameters" | "args"; tolerates a missing closing tag.
+// Used by Qwen, Hermes/NousResearch, and many Ollama-served models.
+// ---------------------------------------------------------------------------
+const HERMES_OPEN = /<tool_call>/i;
+export const hermesDialect = {
+    name: 'hermes',
+    test: (text) => HERMES_OPEN.test(text) && text.includes('{'),
+    parse(text, idBase = 0) {
+        if (!HERMES_OPEN.test(text))
+            return { calls: [], cleanedText: text };
+        const calls = [];
+        const blockRe = /<tool_call>\s*([\s\S]*?)(?:<\/tool_call>|$)/gi;
+        let m;
+        let i = 0;
+        while ((m = blockRe.exec(text)) !== null) {
+            const obj = extractFirstJsonObject(m[1]);
+            if (!obj)
+                continue;
+            const call = jsonToToolCall(obj, idBase + i);
+            if (call) {
+                calls.push(call);
+                i++;
+            }
+        }
+        const cut = text.search(HERMES_OPEN);
+        const cleanedText = cut >= 0 ? text.slice(0, cut).trim() : text;
+        return { calls, cleanedText };
+    },
+};
+// ---------------------------------------------------------------------------
+// json-fence — a fenced code block whose JSON looks like a tool call:
+//   ```json | ```tool_call | ```tool
+//   {"name": "...", "arguments": {...}}   (also "tool"/"args"/"parameters")
+//   ```
+// Conservative: only treats a block as a call when it has BOTH a name key
+// (name|tool|function) AND an args key (arguments|args|parameters|input), so
+// ordinary JSON the model prints for the user is not misread as a tool call.
+// ---------------------------------------------------------------------------
+const FENCE_RE = /```(?:json|tool_call|tool)?\s*\n?([\s\S]*?)```/gi;
+export const jsonFenceDialect = {
+    name: 'json-fence',
+    test: (text) => /```/.test(text) && /"(name|tool|function)"\s*:/.test(text),
+    parse(text, idBase = 0) {
+        const calls = [];
+        let firstMatchIndex = -1;
+        let m;
+        let i = 0;
+        while ((m = FENCE_RE.exec(text)) !== null) {
+            const obj = extractFirstJsonObject(m[1]);
+            if (!obj)
+                continue;
+            const call = jsonToToolCall(obj, idBase + i);
+            if (call) {
+                if (firstMatchIndex < 0)
+                    firstMatchIndex = m.index;
+                calls.push(call);
+                i++;
+            }
+        }
+        FENCE_RE.lastIndex = 0;
+        const cleanedText = firstMatchIndex >= 0 ? text.slice(0, firstMatchIndex).trim() : text;
+        return { calls, cleanedText };
+    },
+};
+/** All built-in dialects, keyed by name. */
+export const dialects = {
+    'xml-function': xmlFunctionDialect,
+    hermes: hermesDialect,
+    'json-fence': jsonFenceDialect,
+};
+/** Default attempt order — xml-function first preserves original behavior. */
+export const DEFAULT_DIALECTS = ['xml-function', 'hermes', 'json-fence'];
+/**
+ * Try a list of dialects (by name) against text and return the first that
+ * yields tool calls. Falls back to `{ calls: [], cleanedText: text }`.
+ */
+export function parseToolCalls(text, opts = {}) {
+    if (!text)
+        return { calls: [], cleanedText: text };
+    const order = opts.dialects ?? DEFAULT_DIALECTS;
+    for (const name of order) {
+        const d = dialects[name];
+        if (!d || !d.test(text))
+            continue;
+        const parsed = d.parse(text, opts.idBase ?? 0);
+        if (parsed.calls.length)
+            return parsed;
+    }
+    return { calls: [], cleanedText: text };
+}
+/** True if ANY of the given dialects (default: all) detects tool-call markup. */
+export function hasToolCalls(text, order = DEFAULT_DIALECTS) {
+    return order.some((n) => dialects[n]?.test(text));
+}
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+/** Find and parse the first balanced top-level `{...}` JSON object in a string. */
+function extractFirstJsonObject(s) {
+    const start = s.indexOf('{');
+    if (start < 0)
+        return null;
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (let i = start; i < s.length; i++) {
+        const ch = s[i];
+        if (inStr) {
+            if (esc)
+                esc = false;
+            else if (ch === '\\')
+                esc = true;
+            else if (ch === '"')
+                inStr = false;
+            continue;
+        }
+        if (ch === '"')
+            inStr = true;
+        else if (ch === '{')
+            depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0) {
+                const slice = s.slice(start, i + 1);
+                try {
+                    const v = JSON.parse(slice);
+                    return v && typeof v === 'object' ? v : null;
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+    }
+    return null;
+}
+/** Coerce a `{name|tool|function, arguments|args|parameters|input}` object into a ToolCall. */
+function jsonToToolCall(obj, idx) {
+    // Some emitters wrap as { "tool_call": {...} } or { "function": {name, arguments} }.
+    if (obj.tool_call && typeof obj.tool_call === 'object') {
+        return jsonToToolCall(obj.tool_call, idx);
+    }
+    let name = obj.name ?? obj.tool ?? obj.function;
+    let rawArgs = obj.arguments ?? obj.args ?? obj.parameters ?? obj.input;
+    // Nested OpenAI shape: { function: { name, arguments } }
+    if (name && typeof name === 'object') {
+        const fn = name;
+        rawArgs = rawArgs ?? fn.arguments ?? fn.args;
+        name = fn.name;
+    }
+    if (typeof name !== 'string' || !name)
+        return null;
+    const argsStr = typeof rawArgs === 'string'
+        ? rawArgs
+        : rawArgs === undefined
+            ? '{}'
+            : JSON.stringify(rawArgs);
+    return {
+        id: `call_inline_${idx}`,
+        type: 'function',
+        function: { name: name.trim(), arguments: argsStr || '{}' },
+    };
+}

package/dist/llm/index.d.ts

@@ -2,4 +2,7 @@ export * from './openai.js';
 export * from './anthropic.js';
 export * from './responses.js';
 export { hasInlineToolCalls, parseInlineToolCalls } from './inlineTools.js';
+export { parseToolCalls, hasToolCalls, dialects, DEFAULT_DIALECTS, xmlFunctionDialect, hermesDialect, jsonFenceDialect, type ToolDialect, type ParsedToolCalls, } from './dialects.js';
+export { profileForModel, toolGuidancePrompt, builtinProfiles, genericProfile, type ModelProfile, } from './profiles.js';
+export { validateToolArguments, schemaHint, type ArgValidation } from './repair.js';
 export type { LLMClient, ChatMsg, StreamResult, ToolCall, ToolDef, StopReason, Usage, ContentBlockParam, } from '../types/index.js';

package/dist/llm/index.js

@@ -4,3 +4,12 @@ export * from './responses.js';
 // Inline tool-call parsing — recover tool calls a model emitted as TEXT
 // (e.g. weak models that narrate tool calls instead of using native function calls).
 export { hasInlineToolCalls, parseInlineToolCalls } from './inlineTools.js';
+// Tool-call dialects — pluggable parsers for the inline formats cheap/open
+// models use (xml-function, hermes, json-fence) when they skip native tool_calls.
+export { parseToolCalls, hasToolCalls, dialects, DEFAULT_DIALECTS, xmlFunctionDialect, hermesDialect, jsonFenceDialect, } from './dialects.js';
+// Model profiles — per-model quirks (dialects, tool_choice, parallel, temperature,
+// guidance) for reliable tool use across the long tail of OpenAI-compatible endpoints.
+export { profileForModel, toolGuidancePrompt, builtinProfiles, genericProfile, } from './profiles.js';
+// Tool-call repair — validate args before executing and feed the model a
+// corrective tool_result so it self-heals (the big reliability win for weak models).
+export { validateToolArguments, schemaHint } from './repair.js';

package/dist/llm/inlineTools.d.ts

@@ -1,9 +1,8 @@
 import type { ToolCall } from '../types/index.js';
 export declare function hasInlineToolCalls(text: string): boolean;
 /**
- * Extract inline tool calls from assistant text. Returns the parsed calls and
- * the text with the tool-call markup removed. If none are found, returns the
- * original text and an empty array.
+ * Extract inline tool calls from assistant text across all built-in dialects.
+ * Returns the parsed calls and the text with the tool-call markup removed.
  */
 export declare function parseInlineToolCalls(text: string): {
     calls: ToolCall[];

package/dist/llm/inlineTools.js

@@ -1,72 +1,11 @@
-// Fallback parser for models/proxies that emit tool calls as inline TEXT
-// instead of native function-calling blocks. Several relays and open models use
-// an "XML" tool-call format like:
-//
-//   <tool_call>
-//   <function=write_file>
-//   <parameter=path>index.html</parameter>
-//   <parameter=content>
-//   <!DOCTYPE html> ...
-//   </parameter>
-//   </function>
-//   </tool_call>
-//
-// Parameters may or may not have closing </parameter> tags, and the wrapper
-// <tool_call> may be absent. This parser is tolerant of all those variants and
-// also strips the markup out of the user-visible text.
-const FUNCTION_MARKER = /<function\s*=/;
+import { hasToolCalls, parseToolCalls } from './dialects.js';
 export function hasInlineToolCalls(text) {
-    return FUNCTION_MARKER.test(text);
+    return hasToolCalls(text);
 }
 /**
- * Extract inline tool calls from assistant text. Returns the parsed calls and
- * the text with the tool-call markup removed. If none are found, returns the
- * original text and an empty array.
+ * Extract inline tool calls from assistant text across all built-in dialects.
+ * Returns the parsed calls and the text with the tool-call markup removed.
  */
 export function parseInlineToolCalls(text) {
-    if (!text || !FUNCTION_MARKER.test(text))
-        return { calls: [], cleanedText: text };
-    const calls = [];
-    const markerRe = /<function\s*=\s*([^>\s]+)\s*>/g;
-    const markers = [];
-    let m;
-    while ((m = markerRe.exec(text)) !== null) {
-        markers.push({ name: m[1], bodyStart: markerRe.lastIndex, markerStart: m.index });
-    }
-    for (let i = 0; i < markers.length; i++) {
-        const cur = markers[i];
-        const end = i + 1 < markers.length ? markers[i + 1].markerStart : text.length;
-        let body = text.slice(cur.bodyStart, end);
-        // Trim at the function/tool_call closers if present.
-        body = body.replace(/<\/function>[\s\S]*$/, '').replace(/<\/tool_call>[\s\S]*$/, '');
-        const args = {};
-        const parts = body.split(/<parameter\s*=/).slice(1);
-        for (const part of parts) {
-            const gt = part.indexOf('>');
-            if (gt < 0)
-                continue;
-            const key = part.slice(0, gt).trim();
-            let val = part.slice(gt + 1);
-            // Value ends at its own closer (or the function/tool_call closer, or the
-            // next parameter — already removed by the split).
-            val = val
-                .replace(/<\/parameter>[\s\S]*$/, '')
-                .replace(/<\/function>[\s\S]*$/, '')
-                .replace(/<\/tool_call>[\s\S]*$/, '');
-            args[key] = trimEdges(val);
-        }
-        calls.push({
-            id: `call_inline_${i}`,
-            type: 'function',
-            function: { name: cur.name.trim(), arguments: JSON.stringify(args) },
-        });
-    }
-    // Everything from the first tool-call/function marker onward is markup.
-    const cut = text.search(/<tool_call>|<function\s*=/);
-    const cleanedText = cut >= 0 ? text.slice(0, cut).trim() : text;
-    return { calls, cleanedText };
-}
-/** Strip a single leading newline and trailing whitespace from a param value. */
-function trimEdges(v) {
-    return v.replace(/^\r?\n/, '').replace(/\s+$/, '');
+    return parseToolCalls(text);
 }

package/dist/llm/openai.d.ts

@@ -1,4 +1,5 @@
 import type { ChatMsg, ContentBlockParam, LLMClient } from '../types/index.js';
+import { type ModelProfile } from './profiles.js';
 export interface OpenAIClientOptions {
     /** API key, or a function returning one per request (for round-robin key pools). */
     apiKey?: string | (() => string | undefined);
@@ -16,6 +17,20 @@ export interface OpenAIClientOptions {
     reasoningEffort?: string;
     /** Allow the model to batch multiple tool calls → sets `parallel_tool_calls` (when tools present). */
     parallelToolCalls?: boolean;
+    /**
+     * Per-model quirks for reliable tool use on cheap/open endpoints. Pass a
+     * `ModelProfile`, a built-in name ('qwen'|'deepseek'|'moonshot'|'zhipu'|
+     * 'mistral'|'llama'|'openai'|'anthropic'|'generic'), or omit to AUTO-DETECT
+     * from the model id. The profile supplies inline tool-call dialects + sane
+     * tool_choice / parallel / temperature defaults; explicit options above always win.
+     */
+    profile?: string | ModelProfile;
+    /**
+     * Inline tool-call dialects to attempt when the model emits tool calls as TEXT
+     * instead of native function-calls (e.g. ['hermes','json-fence','xml-function']).
+     * Overrides the profile's dialects. Set `[]` to disable inline recovery.
+     */
+    toolDialects?: string[];
 }
 /**
  * Creates an LLMClient backed by any OpenAI-compatible /chat/completions

package/dist/llm/openai.js

@@ -1,4 +1,5 @@
-import { parseInlineToolCalls } from './inlineTools.js';
+import { parseToolCalls } from './dialects.js';
+import { profileForModel } from './profiles.js';
 /**
  * Creates an LLMClient backed by any OpenAI-compatible /chat/completions
  * endpoint (OpenAI, Groq, Together, OpenRouter, local llama.cpp, etc.).
@@ -12,14 +13,20 @@ export function createOpenAIClient(options = {}) {
     return {
         async streamChat(messages, opts) {
             const model = opts.model || defaultModel;
+            // Resolve a model profile (explicit > auto-detect from model id). It only
+            // fills gaps — any option set explicitly on the client always wins.
+            const profile = profileForModel(options.profile ?? model);
+            const dialects = options.toolDialects ?? profile.dialects;
+            const temperature = options.temperature ?? profile.temperature;
+            const parallel = options.parallelToolCalls ?? profile.parallelToolCalls;
             const body = {
                 model,
                 messages: messages.map(toOpenAIMessage),
                 stream: true,
                 stream_options: { include_usage: true },
             };
-            if (options.temperature !== undefined)
-                body.temperature = options.temperature;
+            if (temperature !== undefined)
+                body.temperature = temperature;
             if (options.maxTokens !== undefined)
                 body.max_tokens = options.maxTokens;
             // Reasoning models (e.g. xAI grok-4.x): 'none' → 0 reasoning tokens (cheaper/faster).
@@ -27,9 +34,9 @@ export function createOpenAIClient(options = {}) {
                 body.reasoning_effort = options.reasoningEffort;
             if (opts.tools?.length) {
                 body.tools = opts.tools;
-                body.tool_choice = 'auto';
-                if (options.parallelToolCalls !== undefined)
-                    body.parallel_tool_calls = options.parallelToolCalls;
+                body.tool_choice = profile.toolChoice ?? 'auto';
+                if (parallel !== undefined)
+                    body.parallel_tool_calls = parallel;
             }
             const apiKey = typeof options.apiKey === 'function' ? options.apiKey() : options.apiKey;
             const headers = {
@@ -102,10 +109,11 @@ export function createOpenAIClient(options = {}) {
                 function: { name: t.name, arguments: t.args || '{}' },
             }));
             // Fallback: some endpoints emit tool calls as inline text rather than
-            // native tool_calls. Parse them out and clean the visible text.
+            // native tool_calls. Parse them with the profile's dialects and clean the
+            // visible text. (Empty `dialects` — e.g. for native GPT/Claude — skips this.)
             let finalText = text;
-            if (!toolCalls.length) {
-                const inline = parseInlineToolCalls(text);
+            if (!toolCalls.length && (!dialects || dialects.length)) {
+                const inline = parseToolCalls(text, { dialects });
                 if (inline.calls.length) {
                     toolCalls.push(...inline.calls);
                     finalText = inline.cleanedText;

package/dist/llm/profiles.d.ts

@@ -0,0 +1,35 @@
+import type { ToolDef } from '../types/index.js';
+export interface ModelProfile {
+    /** Stable id, e.g. 'qwen' | 'deepseek' | 'openai' | 'generic'. */
+    name: string;
+    /** Match by model id (already lowercased before this is called). */
+    match: (model: string) => boolean;
+    /** Inline dialects to attempt (in order) when native tool_calls are absent. */
+    dialects?: string[];
+    /** tool_choice to send when tools are present. */
+    toolChoice?: 'auto' | 'required' | 'none';
+    /** parallel_tool_calls. Some models break or loop on parallel calls. */
+    parallelToolCalls?: boolean;
+    /** Suggested temperature for stable tool use (lower = more deterministic). */
+    temperature?: number;
+    /** Whether a short tool-use scaffolding prompt helps this family. */
+    injectToolGuidance?: boolean;
+    /** Human note surfaced in the compatibility matrix / docs. */
+    note?: string;
+}
+export declare const builtinProfiles: ModelProfile[];
+/** Catch-all for unknown models: try everything, guide, keep parallel off. */
+export declare const genericProfile: ModelProfile;
+/**
+ * Resolve a profile for a model id. Pass a `ModelProfile` to use it verbatim, a
+ * string name to look up a built-in, or a model id to auto-detect. Unknown →
+ * `genericProfile`.
+ */
+export declare function profileForModel(model?: string | ModelProfile): ModelProfile;
+/**
+ * A short, model-agnostic tool-use scaffolding prompt for weak models that
+ * narrate tool calls instead of using native function-calling. Append it to the
+ * system prompt (e.g. via `query({ appendSystemPrompt })`) when a profile sets
+ * `injectToolGuidance`. Lists the available tools so the model knows the names.
+ */
+export declare function toolGuidancePrompt(tools: ToolDef[]): string;

package/dist/llm/profiles.js

@@ -0,0 +1,123 @@
+import { DEFAULT_DIALECTS } from './dialects.js';
+const has = (...needles) => (model) => needles.some((n) => model.includes(n));
+// Ordered most-specific → most-general; first match wins.
+export const builtinProfiles = [
+    {
+        name: 'openai',
+        match: has('gpt-', 'gpt4', 'o1', 'o3', 'o4', 'chatgpt'),
+        dialects: [], // native tool_calls are reliable
+        toolChoice: 'auto',
+        parallelToolCalls: true,
+        note: 'Native tool_calls; no inline fallback needed.',
+    },
+    {
+        name: 'anthropic',
+        match: has('claude'),
+        dialects: [],
+        toolChoice: 'auto',
+        note: 'Native tool use; clean function-calling.',
+    },
+    {
+        name: 'qwen',
+        match: has('qwen', 'qwq'),
+        dialects: ['hermes', 'xml-function', 'json-fence'],
+        toolChoice: 'auto',
+        parallelToolCalls: false,
+        temperature: 0.3,
+        injectToolGuidance: true,
+        note: 'Hermes-style <tool_call>{json}</tool_call>; parallel calls unreliable.',
+    },
+    {
+        name: 'deepseek',
+        match: has('deepseek'),
+        dialects: ['json-fence', 'hermes', 'xml-function'],
+        toolChoice: 'auto',
+        parallelToolCalls: false,
+        temperature: 0.3,
+        injectToolGuidance: true,
+        note: 'Often emits tool calls in JSON code fences; keep parallel off.',
+    },
+    {
+        name: 'moonshot',
+        match: has('kimi', 'moonshot'),
+        dialects: ['hermes', 'json-fence'],
+        toolChoice: 'auto',
+        parallelToolCalls: false,
+        note: 'Kimi/Moonshot — Hermes-style; Anthropic-compatible endpoint also offered.',
+    },
+    {
+        name: 'zhipu',
+        match: has('glm', 'zhipu', 'chatglm'),
+        dialects: ['xml-function', 'hermes', 'json-fence'],
+        toolChoice: 'auto',
+        parallelToolCalls: false,
+        injectToolGuidance: true,
+        note: 'GLM/Zhipu — mixed dialects; sponsors claude-code-router as a cheap backend.',
+    },
+    {
+        name: 'mistral',
+        match: has('mistral', 'mixtral', 'codestral', 'devstral', 'magistral'),
+        dialects: ['json-fence', 'hermes', 'xml-function'],
+        toolChoice: 'auto',
+        parallelToolCalls: false,
+        temperature: 0.2,
+        injectToolGuidance: true,
+        note: 'Tool-calling historically fragile; low temperature + repair recommended.',
+    },
+    {
+        name: 'llama',
+        match: has('llama', 'codellama'),
+        dialects: ['json-fence', 'hermes', 'xml-function'],
+        toolChoice: 'auto',
+        parallelToolCalls: false,
+        temperature: 0.3,
+        injectToolGuidance: true,
+        note: 'Llama family (often via Ollama) — inline fallback + guidance help a lot.',
+    },
+];
+/** Catch-all for unknown models: try everything, guide, keep parallel off. */
+export const genericProfile = {
+    name: 'generic',
+    match: () => true,
+    dialects: DEFAULT_DIALECTS,
+    toolChoice: 'auto',
+    parallelToolCalls: false,
+    injectToolGuidance: true,
+    note: 'Unknown model — full inline fallback + guidance, parallel off, repair on.',
+};
+/**
+ * Resolve a profile for a model id. Pass a `ModelProfile` to use it verbatim, a
+ * string name to look up a built-in, or a model id to auto-detect. Unknown →
+ * `genericProfile`.
+ */
+export function profileForModel(model) {
+    if (model && typeof model === 'object')
+        return model;
+    const id = (model ?? '').toLowerCase();
+    if (id) {
+        const byName = builtinProfiles.find((p) => p.name === id);
+        if (byName)
+            return byName;
+        const byMatch = builtinProfiles.find((p) => p.match(id));
+        if (byMatch)
+            return byMatch;
+    }
+    return genericProfile;
+}
+/**
+ * A short, model-agnostic tool-use scaffolding prompt for weak models that
+ * narrate tool calls instead of using native function-calling. Append it to the
+ * system prompt (e.g. via `query({ appendSystemPrompt })`) when a profile sets
+ * `injectToolGuidance`. Lists the available tools so the model knows the names.
+ */
+export function toolGuidancePrompt(tools) {
+    const names = tools.map((t) => `- ${t.function.name}: ${t.function.description}`).join('\n');
+    return [
+        'When you need to use a tool, prefer the native function-calling format.',
+        'If you cannot, emit EXACTLY one tool call per turn as a single JSON object',
+        'wrapped in <tool_call>…</tool_call> tags, with this shape:',
+        '<tool_call>{"name": "<tool_name>", "arguments": { /* params */ }}</tool_call>',
+        'Do not wrap it in prose. Use only these tools:',
+        names,
+    ].join('\n');
+}

package/dist/llm/repair.d.ts

@@ -0,0 +1,20 @@
+import type { ToolDef } from '../types/index.js';
+export interface ArgValidation {
+    /** True when the arguments parsed and satisfied required props / basic types. */
+    ok: boolean;
+    /** Parsed arguments (best-effort: `{}` when unparseable). */
+    input: Record<string, unknown>;
+    /** When `ok` is false, a concise, model-facing explanation + schema hint. */
+    error?: string;
+}
+/**
+ * Validate raw tool-call argument JSON against a tool definition.
+ *
+ * - Unparseable JSON → `ok:false` with the parse error and the expected schema.
+ * - Missing required properties → `ok:false` listing them.
+ * - Wrong primitive type on a provided property → `ok:false`.
+ * - No def (unknown tool / client tool) → parse-only; never blocks.
+ */
+export declare function validateToolArguments(def: ToolDef | undefined, rawArgs: string): ArgValidation;
+/** A compact one-line schema hint: `{ path: string (required), recursive?: boolean }`. */
+export declare function schemaHint(def: ToolDef): string;

package/dist/llm/repair.js

@@ -0,0 +1,96 @@
+/**
+ * Validate raw tool-call argument JSON against a tool definition.
+ *
+ * - Unparseable JSON → `ok:false` with the parse error and the expected schema.
+ * - Missing required properties → `ok:false` listing them.
+ * - Wrong primitive type on a provided property → `ok:false`.
+ * - No def (unknown tool / client tool) → parse-only; never blocks.
+ */
+export function validateToolArguments(def, rawArgs) {
+    const raw = rawArgs?.trim() ? rawArgs : '{}';
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return {
+            ok: false,
+            input: {},
+            error: def
+                ? `Arguments for "${def.function.name}" were not valid JSON (${msg}). Call the tool again with a single valid JSON object matching: ${schemaHint(def)}`
+                : `Tool arguments were not valid JSON (${msg}). Send a single valid JSON object.`,
+        };
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            input: {},
+            error: def
+                ? `Arguments for "${def.function.name}" must be a JSON object. Expected: ${schemaHint(def)}`
+                : 'Tool arguments must be a JSON object.',
+        };
+    }
+    const input = parsed;
+    // No schema to check against (unknown / client-delegated tool) — accept.
+    if (!def)
+        return { ok: true, input };
+    const props = (def.function.parameters?.properties ?? {});
+    const required = def.function.parameters?.required ?? [];
+    const missing = required.filter((k) => input[k] === undefined || input[k] === null);
+    if (missing.length) {
+        return {
+            ok: false,
+            input,
+            error: `Missing required argument${missing.length > 1 ? 's' : ''} for "${def.function.name}": ${missing
+                .map((k) => `"${k}"`)
+                .join(', ')}. Call it again including ${missing.length > 1 ? 'them' : 'it'}. Expected: ${schemaHint(def)}`,
+        };
+    }
+    // Light primitive type check on provided props.
+    for (const [key, val] of Object.entries(input)) {
+        const want = props[key]?.type;
+        if (!want || val === null || val === undefined)
+            continue;
+        if (!matchesType(val, want)) {
+            return {
+                ok: false,
+                input,
+                error: `Argument "${key}" for "${def.function.name}" should be ${want}, got ${jsType(val)}. Call it again with the correct type. Expected: ${schemaHint(def)}`,
+            };
+        }
+    }
+    return { ok: true, input };
+}
+/** A compact one-line schema hint: `{ path: string (required), recursive?: boolean }`. */
+export function schemaHint(def) {
+    const props = (def.function.parameters?.properties ?? {});
+    const required = new Set(def.function.parameters?.required ?? []);
+    const parts = Object.entries(props).map(([k, v]) => {
+        const req = required.has(k);
+        return `${k}${req ? '' : '?'}: ${v?.type ?? 'any'}${req ? ' (required)' : ''}`;
+    });
+    return `{ ${parts.join(', ')} }`;
+}
+function jsType(v) {
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+function matchesType(v, want) {
+    switch (want) {
+        case 'string':
+            return typeof v === 'string';
+        case 'number':
+        case 'integer':
+            return typeof v === 'number';
+        case 'boolean':
+            return typeof v === 'boolean';
+        case 'array':
+            return Array.isArray(v);
+        case 'object':
+            return typeof v === 'object' && !Array.isArray(v) && v !== null;
+        default:
+            return true; // unknown/`any` — don't block
+    }
+}

package/dist/loop.d.ts

@@ -35,6 +35,13 @@ export interface RunToolLoopOptions {
     includePartialMessages?: boolean;
     /** Correlation id stamped on every emitted SDKMessage. */
     sessionId?: string;
+    /**
+     * Validate tool arguments before executing; on malformed/incomplete JSON,
+     * feed the model a corrective `is_error` tool_result (with the expected
+     * schema) instead of running the tool with garbage, so it self-heals.
+     * Default `true`. Set `false` to pass raw args straight through.
+     */
+    repairToolCalls?: boolean;
 }
 /**
  * Run the bare tool loop, yielding SDKMessages until the model stops or maxTurns.

package/dist/loop.js

@@ -1,4 +1,5 @@
 import { toolByName, toolDefs } from './tools/index.js';
+import { validateToolArguments } from './llm/repair.js';
 import { uuid } from './util/ids.js';
 const emptyUsage = () => ({ input_tokens: 0, output_tokens: 0 });
 function addUsage(t, b) {
@@ -78,6 +79,7 @@ export async function* runToolLoop(opts) {
     const { history, llm, model, ctx, signal, canUseTool, onClientTool } = opts;
     const tools = opts.tools;
     const clientTools = new Set(opts.clientTools ?? []);
+    const repair = opts.repairToolCalls !== false;
     const maxTurns = opts.maxTurns ?? 50;
     const sessionId = opts.sessionId ?? uuid();
     const emitPartial = !!opts.includePartialMessages;
@@ -187,50 +189,62 @@ export async function* runToolLoop(opts) {
             const tool = byName.get(name);
             let content = '';
             let isError = false;
-            // Delegated tool (listed in clientTools, or has no `run`): execute on the
-            // host via onClientTool instead of `ctx` — never touches the server FS.
-            const delegated = clientTools.has(name) || (tool != null && !tool.run);
-            if (delegated) {
-                if (!onClientTool) {
-                    content = `No client executor for "${name}" (delegated tool; pass onClientTool).`;
-                    isError = true;
-                }
-                else {
-                    try {
-                        const r = await onClientTool({ tool_use_id: call.id, name, input });
-                        content = (typeof r.content === 'string' ? r.content : JSON.stringify(r.content ?? ''));
-                        isError = !!r.is_error;
-                    }
-                    catch (err) {
-                        content = `Error (client) ${name}: ${err instanceof Error ? err.message : String(err)}`;
-                        isError = true;
-                    }
-                }
-            }
-            else if (!tool) {
-                content = `Error: unknown tool "${name}"`;
+            // Repair: validate args against the tool's schema before running. On a
+            // malformed/incomplete call, hand the model a corrective tool_result so
+            // it retries with valid JSON instead of executing with garbage.
+            const check = repair && tool ? validateToolArguments(tool.def, call.function.arguments) : null;
+            if (check && !check.ok) {
+                content = check.error;
                 isError = true;
             }
             else {
-                const decision = canUseTool
-                    ? await canUseTool(name, input, { signal, toolUseId: call.id })
-                    : { behavior: 'allow' };
-                if (decision.behavior === 'deny') {
-                    content = `Permission denied: ${decision.message}`;
+                if (check)
+                    input = check.input;
+                // Delegated tool (listed in clientTools, or has no `run`): execute on the
+                // host via onClientTool instead of `ctx` — never touches the server FS.
+                const delegated = clientTools.has(name) || (tool != null && !tool.run);
+                if (delegated) {
+                    if (!onClientTool) {
+                        content = `No client executor for "${name}" (delegated tool; pass onClientTool).`;
+                        isError = true;
+                    }
+                    else {
+                        try {
+                            const r = await onClientTool({ tool_use_id: call.id, name, input });
+                            content = (typeof r.content === 'string' ? r.content : JSON.stringify(r.content ?? ''));
+                            isError = !!r.is_error;
+                        }
+                        catch (err) {
+                            content = `Error (client) ${name}: ${err instanceof Error ? err.message : String(err)}`;
+                            isError = true;
+                        }
+                    }
+                }
+                else if (!tool) {
+                    content = `Error: unknown tool "${name}"`;
                     isError = true;
                 }
                 else {
-                    if ('updatedInput' in decision && decision.updatedInput)
-                        input = decision.updatedInput;
-                    try {
-                        const r = await tool.run(input, ctx);
-                        content = r.content;
-                        isError = !!r.isError;
-                    }
-                    catch (err) {
-                        content = `Error executing ${name}: ${err instanceof Error ? err.message : String(err)}`;
+                    const decision = canUseTool
+                        ? await canUseTool(name, input, { signal, toolUseId: call.id })
+                        : { behavior: 'allow' };
+                    if (decision.behavior === 'deny') {
+                        content = `Permission denied: ${decision.message}`;
                         isError = true;
                     }
+                    else {
+                        if ('updatedInput' in decision && decision.updatedInput)
+                            input = decision.updatedInput;
+                        try {
+                            const r = await tool.run(input, ctx);
+                            content = r.content;
+                            isError = !!r.isError;
+                        }
+                        catch (err) {
+                            content = `Error executing ${name}: ${err instanceof Error ? err.message : String(err)}`;
+                            isError = true;
+                        }
+                    }
                 }
             }
             const textOut = resultToText(content);

package/package.json

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