@kenkaiiii/gg-agent 5.69.0 → 5.70.0

package/dist/index.cjs

@@ -41,11 +41,11 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/agent.ts
-var import_gg_ai2 = require("@kenkaiiii/gg-ai");
+var import_gg_ai3 = require("@kenkaiiii/gg-ai");
 
 // src/agent-loop.ts
 var import_zod = require("zod");
-var import_gg_ai = require("@kenkaiiii/gg-ai");
+var import_gg_ai2 = require("@kenkaiiii/gg-ai");
 
 // src/local-backend.ts
 function isLocalBackendUrl(baseUrl) {
@@ -69,6 +69,107 @@ function isLocalBackendUrl(baseUrl) {
   return false;
 }
 
+// src/tool-call-hints.ts
+var import_gg_ai = require("@kenkaiiii/gg-ai");
+function normalizeName(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function editDistance(a, b) {
+  let beforePrevious = [];
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let distance = Math.min(
+        (previous[j] ?? 0) + 1,
+        (current[j - 1] ?? 0) + 1,
+        (previous[j - 1] ?? 0) + cost
+      );
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        distance = Math.min(distance, (beforePrevious[j - 2] ?? 0) + 1);
+      }
+      current[j] = distance;
+    }
+    beforePrevious = previous;
+    previous = current;
+  }
+  return previous[b.length] ?? 0;
+}
+function closestName(name, candidates) {
+  const target = normalizeName(name);
+  if (!target) return void 0;
+  const limit = Math.min(3, Math.max(1, Math.floor(target.length / 3)));
+  let best;
+  for (const candidate of [...candidates].sort()) {
+    if (candidate === name) continue;
+    const distance = editDistance(target, normalizeName(candidate));
+    if (distance > limit) continue;
+    if (!best || distance < best.distance) best = { name: candidate, distance };
+  }
+  return best?.name;
+}
+function unknownToolMessage(name, available) {
+  const suggestion = closestName(name, available);
+  if (suggestion) return `Unknown tool: ${name}. Did you mean \`${suggestion}\`?`;
+  const names = [...available].sort();
+  const listed = names.length > 40 ? `${names.slice(0, 40).join(", ")}, \u2026` : names.join(", ");
+  const searchHint = available.includes("tool_search") ? " If the capability is not listed, call `tool_search` to load it." : "";
+  return `Unknown tool: ${name}. Available tools: ${listed}.${searchHint}`;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function typeLabel(node) {
+  if (!isRecord(node)) return "any";
+  if (Array.isArray(node.enum)) {
+    return node.enum.map((value) => JSON.stringify(value)).join(" | ");
+  }
+  const variants = node.anyOf ?? node.oneOf;
+  if (Array.isArray(variants)) {
+    return [...new Set(variants.map(typeLabel))].filter((t) => t !== "null").join(" | ") || "any";
+  }
+  if (node.type === "array") return `${typeLabel(node.items)}[]`;
+  if (Array.isArray(node.type)) {
+    return node.type.filter((t) => t !== "null").join(" | ") || "any";
+  }
+  return typeof node.type === "string" ? node.type : "any";
+}
+function objectShape(tool) {
+  let schema;
+  try {
+    schema = (0, import_gg_ai.resolveToolSchema)(tool);
+  } catch {
+    return void 0;
+  }
+  if (!isRecord(schema) || !isRecord(schema.properties)) return void 0;
+  const required = new Set(
+    Array.isArray(schema.required) ? schema.required.filter((r) => typeof r === "string") : []
+  );
+  return { properties: schema.properties, required };
+}
+function argumentHints(tool, args) {
+  const shape = objectShape(tool);
+  if (!shape) return "";
+  const names = Object.keys(shape.properties);
+  if (names.length === 0) return `Expected arguments: none.`;
+  const fields = names.map((name) => {
+    const optional = shape.required.has(name) ? "" : "?";
+    return `${name}${optional}: ${typeLabel(shape.properties[name])}`;
+  });
+  const lines = [`Expected arguments: { ${fields.join(", ")} }`];
+  if (isRecord(args)) {
+    for (const key of Object.keys(args).sort()) {
+      if (key in shape.properties) continue;
+      const suggestion = closestName(key, names);
+      lines.push(
+        suggestion ? `Unknown field \`${key}\` \u2014 did you mean \`${suggestion}\`?` : `Unknown field \`${key}\` is not a parameter of this tool.`
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
 // src/output-ceiling.ts
 var TTL_MS = 24 * 60 * 60 * 1e3;
 var MIN_PLAUSIBLE_CEILING = 256;
@@ -278,7 +379,7 @@ Partial output:` },
 }
 var _toolRedaction;
 function toolRedactionOptions() {
-  _toolRedaction ??= { secrets: (0, import_gg_ai.environmentSecrets)(process.env) };
+  _toolRedaction ??= { secrets: (0, import_gg_ai2.environmentSecrets)(process.env) };
   return _toolRedaction;
 }
 var _diagFn = null;
@@ -361,7 +462,7 @@ function isBillingError(err) {
   if (!(err instanceof Error)) return false;
   const statusCode = err.statusCode;
   if (statusCode === 402) return true;
-  return (0, import_gg_ai.isHardBillingMessage)(err.message);
+  return (0, import_gg_ai2.isHardBillingMessage)(err.message);
 }
 function isUsageLimitError(err) {
   if (!(err instanceof Error)) return false;
@@ -730,7 +831,7 @@ async function* agentLoop(messages, options) {
             });
           }
         }
-        const result = (0, import_gg_ai.stream)({
+        const result = (0, import_gg_ai2.stream)({
           provider: options.provider,
           model: options.model,
           messages,
@@ -1193,7 +1294,7 @@ async function* agentLoop(messages, options) {
           });
           yield {
             type: "error",
-            error: new import_gg_ai.GGAIError(
+            error: new import_gg_ai2.GGAIError(
               `The connection to the API provider stopped responding after ${MAX_STALL_RETRIES} automatic retries. Your conversation is preserved.`,
               {
                 source: "network",
@@ -1607,7 +1708,7 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
     options.seenToolCalls.add(signature);
   }
   if (!tool) {
-    resultContent = `Unknown tool: ${toolCall.name}`;
+    resultContent = unknownToolMessage(toolCall.name, [...options.toolMap.keys()]);
     isError = true;
   } else {
     try {
@@ -1641,8 +1742,8 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
       };
       const raw = await tool.execute(parsed, ctx);
       const normalized = normalizeToolResult(raw);
-      resultContent = (0, import_gg_ai.redactValue)(normalized.content, toolRedactionOptions());
-      details = (0, import_gg_ai.redactValue)(normalized.details, toolRedactionOptions());
+      resultContent = (0, import_gg_ai2.redactValue)(normalized.content, toolRedactionOptions());
+      details = (0, import_gg_ai2.redactValue)(normalized.details, toolRedactionOptions());
       if (options.transformToolResult) {
         try {
           resultContent = options.transformToolResult(
@@ -1663,12 +1764,14 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
         const failureCount = (options.invalidToolArgumentCounts.get(failureKey) ?? 0) + 1;
         options.invalidToolArgumentCounts.set(failureKey, failureCount);
         invalidArgAttempt = failureCount;
+        const hints = argumentHints(tool, toolCall.args);
         resultContent = `Invalid arguments for tool \`${toolCall.name}\`:
-` + prettyError + "\nRe-issue the call with each field as the correct type.";
+` + prettyError + (hints ? `
+${hints}` : "") + "\nRe-issue the call with each field as the correct type.";
         if (failureCount >= 3) {
           const recoverable = Object.keys(toolCall.args ?? {}).length === 0;
           options.markFatalToolArgumentError(
-            new import_gg_ai.GGAIError(
+            new import_gg_ai2.GGAIError(
               `The model repeatedly issued invalid arguments for tool \`${toolCall.name}\`. This is usually an upstream model/tool-calling bug` + (recoverable ? " (the provider's stream returned empty tool-call arguments)" : "") + `. Your conversation is preserved; send another message or switch models to continue.`,
               {
                 source: "provider",
@@ -1680,15 +1783,15 @@ async function executeSingleToolCall(toolCall, options, pushEvent) {
           );
         }
       } else {
-        resultContent = (0, import_gg_ai.redactValue)(
+        resultContent = (0, import_gg_ai2.redactValue)(
           err instanceof Error ? err.message : String(err),
           toolRedactionOptions()
         );
       }
     }
   }
-  resultContent = (0, import_gg_ai.redactValue)(resultContent, toolRedactionOptions());
-  details = (0, import_gg_ai.redactValue)(details, toolRedactionOptions());
+  resultContent = (0, import_gg_ai2.redactValue)(resultContent, toolRedactionOptions());
+  details = (0, import_gg_ai2.redactValue)(details, toolRedactionOptions());
   if (options.preemptSignal?.aborted && isInterruptibleTool(options.toolMap.get(toolCall.name), toolCall.name)) {
     const marked = markSteerInterrupted({
       toolCallId: toolCall.id,
@@ -1764,7 +1867,7 @@ function createPreemptTracker(options, eventStream, state, resultsById, dispatch
   };
 }
 async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
-  const eventStream = new import_gg_ai.EventStream();
+  const eventStream = new import_gg_ai2.EventStream();
   const state = { finalized: false };
   const resultsById = /* @__PURE__ */ new Map();
   const dispatchedIds = /* @__PURE__ */ new Set();
@@ -1832,7 +1935,7 @@ async function* executeToolCallsMixed(toolCalls, initialToolResults, options) {
   return { toolResults, aborted, preempted: !aborted && tracker.preempted() };
 }
 async function* executeToolCallsParallel(toolCalls, initialToolResults, options) {
-  const eventStream = new import_gg_ai.EventStream();
+  const eventStream = new import_gg_ai2.EventStream();
   const state = { finalized: false };
   const resultsById = /* @__PURE__ */ new Map();
   const dispatchedIds = /* @__PURE__ */ new Set();
@@ -1903,8 +2006,8 @@ function capToolResults(toolResults, maxToolResultChars) {
     const originalChars = toolResult.content.length;
     const headChars = Math.floor(max * 0.7);
     const tailChars = max - headChars;
-    const head = (0, import_gg_ai.sliceHead)(toolResult.content, headChars);
-    const tail = (0, import_gg_ai.sliceTail)(toolResult.content, tailChars);
+    const head = (0, import_gg_ai2.sliceHead)(toolResult.content, headChars);
+    const tail = (0, import_gg_ai2.sliceTail)(toolResult.content, tailChars);
     const omitted = originalChars - head.length - tail.length;
     toolResult.content = head + `
 
@@ -1940,11 +2043,11 @@ function capTurnToolResults(toolResults, maxTurnToolResultChars) {
     const headChars = Math.floor(fairShare * 0.7);
     const tailChars = fairShare - headChars;
     const omitted = originalChars - fairShare;
-    toolResult.content = (0, import_gg_ai.sliceHead)(toolResult.content, headChars) + `
+    toolResult.content = (0, import_gg_ai2.sliceHead)(toolResult.content, headChars) + `
 
 [... ${omitted} characters trimmed: this turn's combined tool results exceeded the per-turn budget. Re-run this call alone with narrower filters or offset/limit if you need the omitted content ...]
 
-` + (0, import_gg_ai.sliceTail)(toolResult.content, tailChars);
+` + (0, import_gg_ai2.sliceTail)(toolResult.content, tailChars);
     toolResult.capped = {
       originalChars: toolResult.capped?.originalChars ?? originalChars,
       keptChars: toolResult.content.length,
@@ -1963,8 +2066,8 @@ function truncateToolResultText(text, maxChars) {
   if (text.length <= maxChars) return text;
   const tailChars = Math.min(Math.floor(maxChars * 0.3), 2e4);
   const headChars = Math.max(maxChars - tailChars, 0);
-  const head = (0, import_gg_ai.sliceHead)(text, headChars);
-  const tail = (0, import_gg_ai.sliceTail)(text, tailChars);
+  const head = (0, import_gg_ai2.sliceHead)(text, headChars);
+  const tail = (0, import_gg_ai2.sliceTail)(text, tailChars);
   const omitted = text.length - head.length - tail.length;
   return `${head}
 
@@ -2113,7 +2216,7 @@ var AgentStream = class {
   rejectResult;
   hasConsumer = false;
   constructor(generator, onDone) {
-    this.events = new import_gg_ai2.EventStream();
+    this.events = new import_gg_ai3.EventStream();
     this.resultPromise = new Promise((resolve, reject) => {
       this.resolveResult = resolve;
       this.rejectResult = reject;