Skip to content

The all-in-one local AI studio for your desktop: chat, image and video generation and a coding agent in one free, open source app. Windows and Linux. No Docker, no terminal, no cloud required.

21.8 KB
Raw Blame
/**
 * Loose tool-call extraction — the safety net for weak local models that
 * "describe" a tool call in their TEXT answer instead of emitting it through
 * the native `tool_calls` channel.
 *
 * Native tool_calls (Ollama `tools`) and Hermes `<tool_call>` XML are handled
 * directly in useAgentChat. This module is the fallback for everything in
 * between — observed LIVE on the only locally-installed agent models:
 *   - gemma4:e4b  → often answers in prose, occasionally writes the call
 *   - qwen2.5-coder:14b → wrote `image_generate(prompt="a small red cube …")`
 *     as plain answer text and never used the structured channel.
 * Without this, the chat-agent image/video flow simply never fires for these
 * models. With it, ANY recognizable call (function-syntax, JSON object, Hermes
 * tag) the model wrote into its answer is lifted into a real tool call.
 *
 * SAFETY: only calls whose name is in `known` are returned, so ordinary prose
 * that happens to contain parentheses or a stray `{}` can't be misread as a
 * tool invocation. The matched snippet is also reported so the caller can strip
 * it from the visible answer (we don't want the raw `foo(...)` echoed as prose).
 */

import { findBalancedObjects, balancedObjectAt } from './json-scan'
import { isRecord, prop } from '../types/json-guards'
import { repairJson } from './tool-call-repair'
import { parseHermesToolCalls } from '../api/hermes-tool-calling'
import { RETIRED_TOOL_NAMES } from './retired-tools'
import { retiredToolRunsOnThisDevice } from './mobile-tools'

/**
 * A9. The sixteen names the 2.6.6 merge retired are not in any `known` list
 * any more, but they still EXECUTE: the registry redirects them and the result
 * carries a note naming the new call form. Every recogniser in this file was
 * gated on `known` alone, so the redirect only ever fired for a name that
 * arrived spotless through the native channel. `functions.git_status` (the
 * harmony recipient namespace, seen live on gpt-oss), `git_status` written
 * into prose, `run_code` from a model that learned that spelling elsewhere:
 * all three walked past the redirect and came back as "Unknown tool".
 *
 * A registered tool always wins; this list is only consulted after `known`
 * has had its full ladder, so nothing can be rerouted away from a live tool.
 */
// On a phone only the names that still run there are recognised, so prose
// that mentions `git_status` is not turned into a call that cannot run.
const RETIRED_NAMES: string[] = [...RETIRED_TOOL_NAMES].filter(retiredToolRunsOnThisDevice)

export interface LooseToolCall {
  name: string
  arguments: Record<string, unknown>
}

export interface LooseParseResult {
  calls: LooseToolCall[]
  /** The exact substrings that were recognized as calls (for stripping from prose). */
  matched: string[]
}

function escapeRe(s: string): string {
  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
}

/** Coerce a scalar token ("..."/'...'/number/true/false) into a JS value. */
function coerceScalar(raw: string): unknown {
  const v = raw.trim()
  if (v === 'true') return true
  if (v === 'false') return false
  if (v === 'null') return null
  if (/^-?\d+(?:\.\d+)?$/.test(v)) return Number(v)
  // quoted string → unquote + unescape
  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
    return v.slice(1, -1).replace(/\\(["'\\])/g, '$1')
  }
  return v
}

/**
 * Parse the inside of a `name( ... )` call into an arguments object.
 * Handles `key="val"`, `key='val'`, `key: "val"`, `key=123`, `key=true`, and a
 * single positional string (mapped to `prompt`, the natural arg for the
 * creative tools this fallback exists for).
 */
function parseCallArgs(inner: string): Record<string, unknown> {
  const args: Record<string, unknown> = {}
  const kw = /([A-Za-z_]\w*)\s*[:=]\s*("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|true|false|null|-?\d+(?:\.\d+)?)/g
  let m: RegExpExecArray | null
  let found = false
  while ((m = kw.exec(inner)) !== null) {
    found = true
    args[m[1]] = coerceScalar(m[2])
  }
  if (!found) {
    // Positional single string → prompt (e.g. image_generate("a red cube")).
    const s = inner.trim().replace(/^["']|["']$/g, '').trim()
    if (s) args.prompt = s
  }
  return args
}

/** Find bare/fenced JSON objects that name a known tool: {"name":"X","arguments":{…}}. */
function parseJsonObjectCalls(text: string, known: Set<string>): { call: LooseToolCall; snippet: string }[] {
  const calls: { call: LooseToolCall; snippet: string }[] = []
  // Every top-level {...} candidate; repairJson tolerates trailing commas /
  // single quotes / unquoted keys. The scan is string-aware (json-scan.ts):
  // the old depth counter treated braces INSIDE a JSON string as structure, so
  // a file_write whose content held a regex or a half-open block either lost
  // its closing brace (candidate never emitted, call silently dropped) or
  // closed one brace early (wrong arguments).
  const candidates: string[] = findBalancedObjects(text)
  for (const cand of candidates) {
    if (!/["']?(?:name|tool|tool_name|tool_call|function|call)["']?\s*[:=]/.test(cand)) continue
    const parsed = repairJson(cand)
    if (!parsed) continue
    // Name + args may arrive in three shapes, all seen from small local models:
    //   flat     {"name":"file_list","arguments":{…}}
    //   nested   {"function":{"name":"file_list","arguments":{…}}}  (OpenAI/Phi)
    //   wrapped  {"tool_call":{"name":…}} or {"tool_call":"file_list","arguments":{…}}
    //   call     !function_call:{"call":"file_list","arguments":{…}}  (GH #147, LU Cloud)
    // Unwrap an object-valued name carrier so the nested forms resolve too.
    let nameField: unknown = parsed.name || prop(parsed, 'tool') || prop(parsed, 'tool_name')
      || prop(parsed, 'tool_call') || prop(parsed, 'function') || prop(parsed, 'call')
    let argsField: unknown = parsed.arguments ?? parsed.parameters ?? prop(parsed, 'args') ?? prop(parsed, 'params')
    if (isRecord(nameField)) {
      argsField = argsField ?? nameField.arguments ?? nameField.parameters ?? nameField.args
      nameField = nameField.name || nameField.tool || nameField.tool_name
    }
    if (typeof nameField === 'string' && known.has(nameField)) {
      // Arguments can arrive as a JSON STRING (OpenAI serializes them) — repair
      // it. `parsed.arguments` is already resolved by repairJson; this still
      // covers the `args` / `params` spellings and the nested-function form.
      let a: unknown = argsField ?? {}
      if (typeof a === 'string') { const p2 = repairJson(a); a = isRecord(p2) ? p2 : {} }
      // Report the source snippet so the caller can strip the raw JSON object
      // from the visible prose (otherwise it leaks as a "notes"/JSON block).
      calls.push({ call: { name: nameField, arguments: isRecord(a) ? a : {} }, snippet: cand })
    }
  }
  return calls
}

/**
 * Extract tool calls a model wrote into its text answer. Returns the calls plus
 * the matched source snippets (so the caller can strip them from the prose).
 * Only `known` tool names are recognized.
 */
export function parseLooseToolCalls(text: string, known: string[]): LooseParseResult {
  if (!text || !text.trim()) return { calls: [], matched: [] }
  // Retired names are recognisable AND runnable, so they belong in the net.
  const knownSet = new Set([...known, ...RETIRED_NAMES])
  const calls: LooseToolCall[] = []
  const matched: string[] = []
  const seen = new Set<string>()

  const push = (c: LooseToolCall, snippet: string) => {
    // Dedupe by name + JSON of args so the same call found by two patterns
    // isn't executed twice.
    const key = c.name + '|' + JSON.stringify(c.arguments)
    if (seen.has(key)) return
    seen.add(key)
    calls.push(c)
    if (snippet) matched.push(snippet)
  }

  // 1) Hermes <tool_call>{…}</tool_call> tags (some models emit these in content).
  if (/<tool_call>/i.test(text)) {
    for (const hc of parseHermesToolCalls(text)) {
      if (knownSet.has(hc.name)) push({ name: hc.name, arguments: hc.arguments || {} }, '')
    }
    const tagRe = /<tool_call>[\s\S]*?<\/tool_call>/gi
    let tm: RegExpExecArray | null
    while ((tm = tagRe.exec(text)) !== null) matched.push(tm[0])
  }

  // 2) JSON objects naming a known tool (snippet reported so prose can be cleaned).
  for (const { call, snippet } of parseJsonObjectCalls(text, knownSet)) push(call, snippet)

  // 3) Function-call syntax  name( ... )  — only for known tool names.
  for (const name of knownSet) {
    const re = new RegExp(`\\b${escapeRe(name)}\\s*\\(([\\s\\S]*?)\\)`, 'g')
    let m: RegExpExecArray | null
    while ((m = re.exec(text)) !== null) {
      const args = parseCallArgs(m[1])
      // Require at least one arg — `image_generate()` with nothing is not a
      // usable call (and is more likely the model naming the tool in prose).
      if (Object.keys(args).length > 0) push({ name, arguments: args }, m[0])
    }
  }

  // 4) Brace / bracket form  name {json}  or  [name {json}]  — only known names.
  //    Phi-4-mini (and other non-Hermes small models) emit the args as a JSON
  //    object placed AFTER the bare name, sometimes wrapped in [ ], with NO
  //    `name` key inside the brace (so patterns 2/3 miss it). Observed live:
  //    `[file_read {"path": "/package.json"}]`. Require a non-empty object so a
  //    stray `tool {}` or prose brace isn't misread as a call.
  for (const name of knownSet) {
    // Locate the bare name, then take the BALANCED object after it. The old
    // regex could only express one level of nesting, so `{"a":{"b":{"c":1}}}`
    // and any content string with braces fell outside it.
    const nameRe = new RegExp(`\\[?\\s*\\b${escapeRe(name)}\\b\\s*(?=\\{)`, 'g')
    let m: RegExpExecArray | null
    while ((m = nameRe.exec(text)) !== null) {
      const obj = balancedObjectAt(text, m.index + m[0].length)
      if (!obj) continue
      nameRe.lastIndex = obj.end // never rescan inside the object we just took
      const parsed = repairJson(obj.text)
      if (!parsed) continue
      // The brace may BE the args, or wrap them under arguments/parameters.
      const inner = parsed.arguments ?? parsed.parameters ?? prop(parsed, 'args') ?? prop(parsed, 'params')
      const args: Record<string, unknown> = isRecord(inner) ? inner : parsed
      if (Object.keys(args).length > 0) {
        let end = obj.end
        const closer = text.slice(end).match(/^\s*\]/)
        if (closer) end += closer[0].length
        push({ name, arguments: args }, text.slice(m.index, end))
      }
    }
  }

  return { calls, matched }
}

// Common near-miss tool names small models emit instead of the registered ones
// (gemma4 live: called `video_generation` → "Unknown tool" → gave up). Maps to
// the canonical builtin names. Only applied when the alias target is actually a
// known/registered tool, so this never invents capabilities.
const TOOL_NAME_ALIASES: Record<string, string> = {
  image_generation: 'image_generate', generate_image: 'image_generate', imagegen: 'image_generate',
  create_image: 'image_generate', make_image: 'image_generate', draw_image: 'image_generate', text_to_image: 'image_generate',
  video_generation: 'video_generate', generate_video: 'video_generate', videogen: 'video_generate',
  create_video: 'video_generate', make_video: 'video_generate', animate: 'video_generate', animate_image: 'video_generate',
  text_to_video: 'video_generate', image_to_video: 'video_generate',
  web: 'web_search', search: 'web_search', fetch: 'web_fetch', research: 'web_research', read_file: 'file_read', write_file: 'file_write',
  list_files: 'file_list', search_files: 'file_search', run_shell: 'shell_execute', run_code: 'code_execute',
  // Retired targets (A9). These resolve only because the retired list is the
  // second ladder in canonicalToolName; while the name was registered they
  // were dead weight, and the moment it retired they became the difference
  // between a redirect and a wasted step.
  execute_code: 'code_execute', run_python: 'code_execute', python_exec: 'code_execute',
  run_test: 'run_tests', test_run: 'run_tests',
  list_processes: 'process_list', current_time: 'get_current_time',
}

/** Exact → lowercase → alias → punctuation-insensitive. Undefined if none hit. */
function matchKnown(name: string, known: readonly string[]): string | undefined {
  if (!name) return undefined
  if (known.includes(name)) return name
  const lc = name.toLowerCase()
  if (known.includes(lc)) return lc
  const alias = TOOL_NAME_ALIASES[lc]
  if (alias && known.includes(alias)) return alias
  // Punctuation/casing-insensitive equality (videoGenerate, video-generate…).
  const norm = (s: string) => s.toLowerCase().replace(/[^a-z0-9]/g, '')
  const target = norm(name)
  for (const k of known) if (norm(k) === target) return k
  return undefined
}

/**
 * Transport noise a model (or a proxy that half-parses its format) can wrap
 * around the bare tool name. Two shapes seen live on gpt-oss via LU Cloud,
 * 2026-07-24:
 *
 *   file_edit<|channel|>commentary   harmony control token leaked into the
 *                                    recipient field, so EVERY write tool call
 *                                    came back "Unknown tool" and the model
 *                                    burned a minute retrying the same name
 *   functions.file_edit              the harmony recipient namespace, verbatim
 *
 * Cutting at the first character a registered name can never contain is safe:
 * builtin names are [a-z_], so the cut can shorten a name but can never turn
 * one tool into a different one. The namespace strip is only ever ACCEPTED by
 * the caller when the tail matches a registered tool, which keeps MCP tools
 * that legitimately carry dots intact.
 */
function toolNameCandidates(name: string): string[] {
  const cut = name.trim().match(/^[A-Za-z0-9_.-]+/)?.[0] ?? ''
  if (!cut) return []
  const dot = cut.lastIndexOf('.')
  return dot > 0 ? [cut, cut.slice(dot + 1)] : [cut]
}

/**
 * Map a model-emitted tool name to a registered one. Tries the name as sent,
 * then the same ladder on the name with transport noise stripped. Returns the
 * original name unchanged when no confident match exists (so genuinely unknown
 * tools still error rather than being silently rerouted).
 */
export function canonicalToolName(name: string, known: string[]): string {
  if (!name) return name
  // Registered tools first, all the way down the ladder, THEN the retired
  // names (A9). Order is the safety property: a live tool can never lose a
  // call to a retired one, and a name that is neither still comes back
  // unchanged so the executor can say "Unknown tool" honestly.
  for (const list of [known, RETIRED_NAMES]) {
    const direct = matchKnown(name, list)
    if (direct) return direct
    for (const candidate of toolNameCandidates(name)) {
      if (candidate === name) continue
      const hit = matchKnown(candidate, list)
      if (hit) return hit
    }
  }
  return name
}

/** Names that say "this is a call" instead of naming one. */
const GENERIC_CALL_NAMES = new Set(['function', 'functions', 'tool', 'tools', 'tool_call', 'call', 'function_call', 'invoke', 'use_tool'])

/** True for a name like "function" that names no tool at all. */
export function isGenericCallName(name: string): boolean {
  return GENERIC_CALL_NAMES.has(name.trim().toLowerCase())
}

interface ToolShape {
  name: string
  inputSchema?: { properties?: Record<string, unknown>; required?: string[] }
}

/**
 * GH #147 (LU Cloud, 2026-10-01): a model sent native calls named "function",
 * once with {"todos": [...]}, once with {"path": "."}, and every one came back
 * "Unknown tool: function" while it retried. A generic name is resolved from
 * the call itself: a tool named inside the arguments, or else the one tool
 * whose parameters the arguments fit. Two tools that fit equally leave the
 * call as it was, and the executor says what to send instead.
 */
export function repairToolCall(
  name: string,
  args: Record<string, unknown>,
  tools: ToolShape[],
): { name: string; arguments: Record<string, unknown> } {
  const known = tools.map((t) => t.name)
  if (!isGenericCallName(name)) return { name: canonicalToolName(name, known), arguments: args }
  for (const key of ['name', 'tool', 'tool_name', 'function', 'call']) {
    const inner = args[key]
    if (typeof inner !== 'string') continue
    const hit = canonicalToolName(inner, known)
    if (!known.includes(hit)) continue
    const nested = args.arguments ?? args.parameters ?? args.args
    const rest = Object.fromEntries(Object.entries(args).filter(([k]) => k !== key))
    return { name: hit, arguments: isRecord(nested) ? nested : rest }
  }
  const keys = Object.keys(args)
  if (keys.length === 0) return { name, arguments: args }
  const fits = tools.filter((t) => {
    const props = Object.keys(t.inputSchema?.properties ?? {})
    const required = t.inputSchema?.required ?? []
    return keys.every((k) => props.includes(k)) && required.every((r) => keys.includes(r))
  })
  return fits.length === 1 ? { name: fits[0].name, arguments: args } : { name, arguments: args }
}

/** Remove the matched call snippets from a prose answer (best-effort). */
export function stripMatchedCalls(text: string, matched: string[]): string {
  let out = text
  for (const snip of matched) {
    if (snip) out = out.split(snip).join('')
  }
  // Tidy leftover empty code fences / blank lines.
  return out.replace(/```(?:json|python|tool_code)?\s*```/gi, '').replace(/!function_call:\s*/g, '').replace(/\n{3,}/g, '\n\n').trim()
}

/**
 * Strip ANY recognizable tool-call text (JSON object, function-syntax, Hermes
 * tag, or a fenced ```json block that is actually a call) out of a model's
 * VISIBLE prose. Unlike the loose-parse → strip path (which only runs when the
 * native channel produced nothing), this is meant to run on EVERY turn's
 * content so a model that emits a proper native call AND echoes the same call
 * as text doesn't leak raw JSON into the chat as a "notes"/JSON block.
 *
 * Only `known` tool names are recognized, so ordinary prose with stray braces
 * is left intact. Tool args/results remain in the agent's internal history —
 * this only cleans what the USER sees in the bubble.
 */
export function stripToolCallText(text: string, known: string[]): string {
  if (!text || !text.trim()) return ''
  const { matched } = parseLooseToolCalls(text, known)
  let out = stripMatchedCalls(text, matched)
  // Drop fenced code blocks whose body is a tool call (```json {"name":…}```).
  out = out.replace(/```(?:json|tool_code|tool|python)?\s*([\s\S]*?)```/gi, (m, inner) => {
    const looksLikeCall =
      /["']?(?:name|tool|function)["']?\s*[:=]/.test(inner) &&
      /["']?(?:arguments|parameters|params|prompt)["']?\s*[:=]/.test(inner)
    return looksLikeCall ? '' : m
  })
  // A fence whose BODY was consumed by the strip above still leaves its
  // container behind. Live Agent run on the ship exe (2026-07-25): the model
  // wrote both of its calls as one ```json ARRAY next to perfectly good native
  // tool_calls, the two objects were lifted out by range, and the bubble was
  // left showing a "notes" block containing `[` , `,` , `]`. A fence with no
  // letter or digit left in it carries nothing for the user, so drop it whole.
  out = out.replace(/```[a-z_]*\s*([\s\S]*?)```/gi, (m, inner) =>
    /[A-Za-z0-9]/.test(inner) ? m : '')
  return out
    // Strip special-token tool-call wrappers some models leave in the prose
    // (Phi-4: <|tool_call|>/<|tool|>; Mistral: [TOOL_CALLS]) so they don't show
    // in the bubble. Detection/parsing above already handled the JSON inside.
    .replace(/<\|\/?tool(?:_call)?(?:_start|_end)?\|>/gi, '')
    // The plain Hermes spelling with no pipes. stripToolCallTags only removes
    // MATCHED pairs, so an unclosed `<tool_call>` (a stream that ended mid-tag,
    // a model that opened one and then answered in prose) walked all the way to
    // the bubble — where the markdown renderer swallowed the `<t` and left the
    // user staring at a bare `ool_call>` (live Agent run, ship exe 2026-07-25).
    .replace(/<[|/\s]*tool_calls?[|/\s]*>/gi, '')
    // A whole line that is nothing but a tool-call tag, INCLUDING a truncated
    // one. Captured from the wire on the ship exe, 2026-07-25: Qwen3-32B on LU
    // Cloud sent `</think>\n\nool_call>` as its content, next to a perfectly
    // good native tool_calls array. The provider's own parser had already eaten
    // the `<t`, so every pattern that starts at `<` misses the remainder and it
    // renders as a stray `ool_call>` above the answer. We cannot stop the model
    // doing it; we can stop showing it. Line-anchored, so prose can never match.
    .replace(/^[ \t]*<?[|/]*t?ool_calls?[|/]*>[ \t]*$/gim, '')
    .replace(/\[\/?TOOL_CALLS?\]/gi, '')
    .replace(/```(?:json|tool_code)?\s*```/gi, '')
    .replace(/\n{3,}/g, '\n\n')
    .trim()
}

/**
 * Calls that landed in the reasoning channel instead of the answer (C59 A3).
 *
 * A server that takes a model for a thinking model puts everything up to the
 * end of the turn into `reasoning_content`, the calls included (llama.cpp
 * #20809, Qwen3-2507; the same seen with Qwen3.5 templates). The turn then
 * reads as "thought, said nothing, called nothing" and the run ended or got
 * a continue steer the model could not act on.
 *
 * Deliberately narrow, because reasoning is where a model THINKS about calls
 * it may not make: only when the turn has no call and no answer at all, only
 * the structured forms (a <tool_call> block or Qwen's <function=…> XML), never
 * the prose `name(arg=…)` form, and only names the run knows.
 */
export function toolCallsFromReasoning(
  thinking: string,
  answer: string,
  existingCalls: number,
  known: readonly string[],
): LooseToolCall[] {
  if (existingCalls > 0 || answer.trim() || !thinking) return []
  if (!/<tool_call>|<function=/.test(thinking)) return []
  const calls = parseHermesToolCalls(thinking)
  return calls
    .filter((c) => known.includes(c.name))
    .map((c) => ({ name: c.name, arguments: (isRecord(c.arguments) ? c.arguments : {}) as Record<string, unknown> }))
}