@stackfactor/agent-utils 1.13.0 → 1.13.1

package/README.md

@@ -103,7 +103,9 @@ Constructs a LangChain agent with a model, system prompt, and tools. When `onRep
 
 ### `langChain.runAIAgent(agent, prompt, config, onProgress?)`
 
-Executes a LangChain agent with a user prompt. Registers callbacks for `tool_start`, `tool_end`, `agent_action`, and error events when `onProgress` is provided. Logs execution time on completion.
+Executes a LangChain agent with a user prompt. Registers callbacks for `tool_start`, `agent_action`, and error events when `onProgress` is provided. Logs execution time on completion.
+
+A tool event's `message` is plain language for the progress bar: the web tools read "Searching the web", "Reading web pages", "Listing the pages of a site" and "Reading the pages of a site", and any other tool reads as its name in words (`lookup_record` → "Using lookup record"). It never carries the model's reasoning or the tool's input; the raw name and input stay on the event's `tool` and `input`.
 
 | Parameter    | Type               | Default | Description                      |
 | ------------ | ------------------ | ------- | -------------------------------- |

package/dist/cjs/langChain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAoGA,KAAK,UAAU,GAAG;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IAKtB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrD;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AA0iBF;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,QAAQ,GAAG,EACX,SAAQ,GAAU,KACjB,GAwHF,CAAC;;8CAkb+C,OAAO,UAAU,GAAG,KAAG,OAAO;oCAWxC,GAAG,KAAG,OAAO;0CAgBtC,MAAM,cACN,GAAG,SACR,GAAG,KACT,MAAM;2CA0CqC,GAAG,UAAU,GAAG,KAAG,MAAM;sCA5xC9B,MAAM,KAAG,OAAO;0CAuGZ,GAAG,KAAG,IAAI;wBA8sB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,iBACG,YAAY,GAAG,IAAI,KAChC,GAAG;sBAsCG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,aACvB,MAAM,KACf,OAAO,CAAC,GAAG,CAAC;oCAihBF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDA2sBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAmTF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CAz6C8B,GAAG,KAAG,MAAM;uCAxyB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,YACP,GAAG,WACJ,GAAG,YACF,QAAQ,GAAG,QAAQ,KAC5B,IAAI;kCA5CI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,SACV,UAAU,GAAG,IAAI,YACd,GAAG,KACZ,IAAI;+CA0FI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,YACZ,GAAG,KACZ,IAAI;uCAoBI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,WACR,MAAM,YACL,GAAG,KACZ,IAAI;mCAyuBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AA48CT,wBAkBE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAoGA,KAAK,UAAU,GAAG;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IAKtB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrD;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AA0iBF;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,QAAQ,GAAG,EACX,SAAQ,GAAU,KACjB,GAwHF,CAAC;;8CAgd+C,OAAO,UAAU,GAAG,KAAG,OAAO;oCAWxC,GAAG,KAAG,OAAO;0CAgBtC,MAAM,cACN,GAAG,SACR,GAAG,KACT,MAAM;2CA0CqC,GAAG,UAAU,GAAG,KAAG,MAAM;sCA1zC9B,MAAM,KAAG,OAAO;0CAuGZ,GAAG,KAAG,IAAI;wBA8sB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,iBACG,YAAY,GAAG,IAAI,KAChC,GAAG;sBAiEG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,aACvB,MAAM,KACf,OAAO,CAAC,GAAG,CAAC;oCAohBF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDA2sBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAmTF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CAz6C8B,GAAG,KAAG,MAAM;uCAt0B9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,YACP,GAAG,WACJ,GAAG,YACF,QAAQ,GAAG,QAAQ,KAC5B,IAAI;kCA5CI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,SACV,UAAU,GAAG,IAAI,YACd,GAAG,KACZ,IAAI;+CA0FI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,YACZ,GAAG,KACZ,IAAI;uCAoBI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,WACR,MAAM,YACL,GAAG,KACZ,IAAI;mCAuwBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AA48CT,wBAkBE"}

package/dist/cjs/langChain.js

@@ -765,10 +765,36 @@ const createAgent = (name, modelName, systemPrompt, tools = [], responseFormat,
     });
     return agent;
 };
+// What the progress bar says while each tool agent-utils registers (the
+// Tavily tools in tavily.ts) runs. A Map, so a tool named after an
+// Object.prototype key ("constructor") is not mistaken for a label.
+const TOOL_PROGRESS_LABELS = new Map([
+    ["web_search", "Searching the web"],
+    ["web_extract", "Reading web pages"],
+    ["web_map", "Listing the pages of a site"],
+    ["web_crawl", "Reading the pages of a site"],
+]);
+/**
+ * The progress message for a tool call, in words the person watching the run
+ * can read. A tool without a label (an agent's own) reads as its name with
+ * underscores as spaces: `lookup_record` → "Using lookup record".
+ * @param name - The tool's registered name
+ * @returns A plain-language message; never the raw name in quotes
+ */
+const toolProgressLabel = (name) => {
+    const text = String(name ?? "");
+    const label = TOOL_PROGRESS_LABELS.get(text);
+    if (label)
+        return label;
+    const words = text.replace(/_+/g, " ").trim();
+    return words ? `Using ${words}` : "Using a tool";
+};
 /**
  * Executes a LangChain agent with a single user prompt and returns the raw agent
  * response. When an `onProgress` callback is provided, LangChain callbacks are
  * registered to forward `tool_start`, `agent_action`, and error events to the caller.
+ * A tool event's `message` is plain language (see `toolProgressLabel`); the raw tool
+ * name and input stay on its `tool` and `input` fields.
  * Execution time is logged at the info level on completion.
  * @param agent - A LangChain agent instance created by `createAgent`
  * @param prompt - The user message string to send to the agent
@@ -798,15 +824,18 @@ const runAgent = async (agent, prompt, config, onProgress = null, usageTracker =
                     if (name)
                         onProgress({
                             type: "tool_start",
-                            message: `Using "${name}" tool`,
+                            message: toolProgressLabel(name),
                             tool: name,
                             progress,
                         });
                 },
+                // `action.log` is the model's own text (LangChain's default reads
+                // "Invoking: `web_extract` with `{...}`", the raw tool input), so it
+                // never reaches the progress bar.
                 handleAgentAction: (action) => {
                     onProgress({
                         type: "agent_action",
-                        message: action.log || `Calling "${action.tool}" action`,
+                        message: toolProgressLabel(action.tool),
                         tool: action.tool,
                         input: action.toolInput,
                         progress,

package/dist/esm/langChain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAoGA,KAAK,UAAU,GAAG;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IAKtB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrD;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AA0iBF;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,QAAQ,GAAG,EACX,SAAQ,GAAU,KACjB,GAwHF,CAAC;;8CAkb+C,OAAO,UAAU,GAAG,KAAG,OAAO;oCAWxC,GAAG,KAAG,OAAO;0CAgBtC,MAAM,cACN,GAAG,SACR,GAAG,KACT,MAAM;2CA0CqC,GAAG,UAAU,GAAG,KAAG,MAAM;sCA5xC9B,MAAM,KAAG,OAAO;0CAuGZ,GAAG,KAAG,IAAI;wBA8sB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,iBACG,YAAY,GAAG,IAAI,KAChC,GAAG;sBAsCG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,aACvB,MAAM,KACf,OAAO,CAAC,GAAG,CAAC;oCAihBF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDA2sBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAmTF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CAz6C8B,GAAG,KAAG,MAAM;uCAxyB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,YACP,GAAG,WACJ,GAAG,YACF,QAAQ,GAAG,QAAQ,KAC5B,IAAI;kCA5CI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,SACV,UAAU,GAAG,IAAI,YACd,GAAG,KACZ,IAAI;+CA0FI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,YACZ,GAAG,KACZ,IAAI;uCAoBI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,WACR,MAAM,YACL,GAAG,KACZ,IAAI;mCAyuBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AA48CT,wBAkBE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAoGA,KAAK,UAAU,GAAG;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IAKtB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrD;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AA0iBF;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,QAAQ,GAAG,EACX,SAAQ,GAAU,KACjB,GAwHF,CAAC;;8CAgd+C,OAAO,UAAU,GAAG,KAAG,OAAO;oCAWxC,GAAG,KAAG,OAAO;0CAgBtC,MAAM,cACN,GAAG,SACR,GAAG,KACT,MAAM;2CA0CqC,GAAG,UAAU,GAAG,KAAG,MAAM;sCA1zC9B,MAAM,KAAG,OAAO;0CAuGZ,GAAG,KAAG,IAAI;wBA8sB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,iBACG,YAAY,GAAG,IAAI,KAChC,GAAG;sBAiEG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,aACvB,MAAM,KACf,OAAO,CAAC,GAAG,CAAC;oCAohBF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDA2sBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAmTF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CAz6C8B,GAAG,KAAG,MAAM;uCAt0B9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,YACP,GAAG,WACJ,GAAG,YACF,QAAQ,GAAG,QAAQ,KAC5B,IAAI;kCA5CI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,SACV,UAAU,GAAG,IAAI,YACd,GAAG,KACZ,IAAI;+CA0FI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,YACZ,GAAG,KACZ,IAAI;uCAoBI,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,WACR,MAAM,YACL,GAAG,KACZ,IAAI;mCAuwBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AA48CT,wBAkBE"}

package/dist/esm/langChain.js

@@ -758,10 +758,36 @@ const createAgent = (name, modelName, systemPrompt, tools = [], responseFormat,
     });
     return agent;
 };
+// What the progress bar says while each tool agent-utils registers (the
+// Tavily tools in tavily.ts) runs. A Map, so a tool named after an
+// Object.prototype key ("constructor") is not mistaken for a label.
+const TOOL_PROGRESS_LABELS = new Map([
+    ["web_search", "Searching the web"],
+    ["web_extract", "Reading web pages"],
+    ["web_map", "Listing the pages of a site"],
+    ["web_crawl", "Reading the pages of a site"],
+]);
+/**
+ * The progress message for a tool call, in words the person watching the run
+ * can read. A tool without a label (an agent's own) reads as its name with
+ * underscores as spaces: `lookup_record` → "Using lookup record".
+ * @param name - The tool's registered name
+ * @returns A plain-language message; never the raw name in quotes
+ */
+const toolProgressLabel = (name) => {
+    const text = String(name ?? "");
+    const label = TOOL_PROGRESS_LABELS.get(text);
+    if (label)
+        return label;
+    const words = text.replace(/_+/g, " ").trim();
+    return words ? `Using ${words}` : "Using a tool";
+};
 /**
  * Executes a LangChain agent with a single user prompt and returns the raw agent
  * response. When an `onProgress` callback is provided, LangChain callbacks are
  * registered to forward `tool_start`, `agent_action`, and error events to the caller.
+ * A tool event's `message` is plain language (see `toolProgressLabel`); the raw tool
+ * name and input stay on its `tool` and `input` fields.
  * Execution time is logged at the info level on completion.
  * @param agent - A LangChain agent instance created by `createAgent`
  * @param prompt - The user message string to send to the agent
@@ -791,15 +817,18 @@ const runAgent = async (agent, prompt, config, onProgress = null, usageTracker =
                     if (name)
                         onProgress({
                             type: "tool_start",
-                            message: `Using "${name}" tool`,
+                            message: toolProgressLabel(name),
                             tool: name,
                             progress,
                         });
                 },
+                // `action.log` is the model's own text (LangChain's default reads
+                // "Invoking: `web_extract` with `{...}`", the raw tool input), so it
+                // never reaches the progress bar.
                 handleAgentAction: (action) => {
                     onProgress({
                         type: "agent_action",
-                        message: action.log || `Calling "${action.tool}" action`,
+                        message: toolProgressLabel(action.tool),
                         tool: action.tool,
                         input: action.toolInput,
                         progress,

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.13.0",
+  "version": "1.13.1",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",