@jaypie/llm 1.3.6 → 1.3.8

package/dist/cjs/index.cjs

@@ -490,6 +490,18 @@ var LlmResponseStatus;
     LlmResponseStatus["Incomplete"] = "incomplete";
     LlmResponseStatus["InProgress"] = "in_progress";
 })(LlmResponseStatus || (LlmResponseStatus = {}));
+// Progress
+exports.LlmProgressEventType = void 0;
+(function (LlmProgressEventType) {
+    LlmProgressEventType["Done"] = "done";
+    LlmProgressEventType["ModelRequest"] = "model_request";
+    LlmProgressEventType["ModelResponse"] = "model_response";
+    LlmProgressEventType["Retry"] = "retry";
+    LlmProgressEventType["Start"] = "start";
+    LlmProgressEventType["ToolCall"] = "tool_call";
+    LlmProgressEventType["ToolError"] = "tool_error";
+    LlmProgressEventType["ToolResult"] = "tool_result";
+})(exports.LlmProgressEventType || (exports.LlmProgressEventType = {}));
 
 //
 //
@@ -5408,11 +5420,7 @@ class Toolkit {
             return toolCopy;
         });
     }
-    async call({ name, arguments: args }) {
-        const tool = this._tools.find((t) => t.name === name);
-        if (!tool) {
-            throw new Error(`Tool '${name}' not found`);
-        }
+    parseArgs(args) {
         let parsedArgs;
         try {
             parsedArgs = JSON.parse(args);
@@ -5423,35 +5431,53 @@ class Toolkit {
         catch {
             parsedArgs = args;
         }
+        return parsedArgs;
+    }
+    /**
+     * Resolve a tool's `message` (static string or function of args) without
+     * calling the tool. Returns undefined when the tool is missing or defines
+     * no message. Never throws; resolution errors log at warn.
+     */
+    async resolveMessage({ name, arguments: args, }) {
+        const tool = this._tools.find((t) => t.name === name);
+        if (!tool || !tool.message) {
+            return undefined;
+        }
+        try {
+            if (typeof tool.message === "string") {
+                return tool.message;
+            }
+            const parsedArgs = this.parseArgs(args);
+            if (typeof tool.message === "function") {
+                return await kit.resolveValue(tool.message(parsedArgs, { name }));
+            }
+            log.warn("[Toolkit] Tool provided unknown message type");
+            return String(tool.message);
+        }
+        catch (error) {
+            log.warn("[Toolkit] Caught error resolving tool message");
+            log.var({ error });
+            return undefined;
+        }
+    }
+    async call({ name, arguments: args, message: resolvedMessage, }) {
+        const tool = this._tools.find((t) => t.name === name);
+        if (!tool) {
+            throw new Error(`Tool '${name}' not found`);
+        }
+        const parsedArgs = this.parseArgs(args);
         if (this.log !== false) {
             try {
                 const context = {
                     name,
                     args: parsedArgs,
                 };
-                let message;
                 if (this.explain) {
                     context.explanation = parsedArgs.__Explanation;
                 }
-                if (tool.message) {
-                    if (typeof tool.message === "string") {
-                        log.trace("[Toolkit] Tool provided string message");
-                        message = tool.message;
-                    }
-                    else if (typeof tool.message === "function") {
-                        log.trace("[Toolkit] Tool provided function message");
-                        log.trace("[Toolkit] Resolving message result");
-                        message = await kit.resolveValue(tool.message(parsedArgs, { name }));
-                    }
-                    else {
-                        log.warn("[Toolkit] Tool provided unknown message type");
-                        message = String(tool.message);
-                    }
-                }
-                else {
-                    log.trace("[Toolkit] Log tool call with default message");
-                    message = `${tool.name}:${JSON.stringify(parsedArgs)}`;
-                }
+                const message = resolvedMessage ??
+                    (await this.resolveMessage({ arguments: args, name })) ??
+                    `${tool.name}:${JSON.stringify(parsedArgs)}`;
                 if (typeof this.log === "function") {
                     log.trace("[Toolkit] Log tool call with custom logger");
                     await kit.resolveValue(this.log(message, context));
@@ -6133,6 +6159,25 @@ class InputProcessor {
 // Export singleton instance for convenience
 const inputProcessor = new InputProcessor();
 
+/**
+ * Deliver a progress event to the caller's onProgress callback.
+ * Errors thrown by the callback are logged and swallowed — progress
+ * reporting must never interrupt the operate loop.
+ */
+async function emitProgress({ event, onProgress, }) {
+    if (!onProgress) {
+        return;
+    }
+    try {
+        await onProgress(event);
+    }
+    catch (error) {
+        const log = getLogger$6();
+        log.warn(`[operate] onProgress callback threw on "${event.type}" event`);
+        log.var({ error });
+    }
+}
+
 //
 //
 // Main
@@ -6558,12 +6603,21 @@ class OperateLoop {
         const log = getLogger$6();
         // Log what was passed to operate
         log.trace("[operate] Starting operate loop");
-        log.var({ "operate.input": input });
-        log.var({ "operate.options": options });
+        log.trace.var({ "operate.input": input });
+        log.trace.var({ "operate.options": options });
         // Initialize state
         const state = await this.initializeState(input, options);
         const context = this.createContext(options);
         const modelName = options.model ?? this.adapter.defaultModel;
+        await emitProgress({
+            event: {
+                maxTurns: state.maxTurns,
+                model: modelName,
+                provider: this.adapter.name,
+                type: exports.LlmProgressEventType.Start,
+            },
+            onProgress: options.onProgress,
+        });
         // Enclosing LLM Observability span (no-op when DD_LLMOBS_ENABLED is unset).
         // Child llm/tool spans nest under it via the SDK's active-span context.
         return withLlmObsSpan({
@@ -6601,6 +6655,15 @@ class OperateLoop {
                 metrics: usageToLlmObsMetrics(response.usage),
                 outputData: response.content,
             });
+            await emitProgress({
+                event: {
+                    content: response.content,
+                    turn: state.currentTurn,
+                    type: exports.LlmProgressEventType.Done,
+                    usage: response.usage,
+                },
+                onProgress: options.onProgress,
+            });
             return response;
         });
     }
@@ -6695,18 +6758,54 @@ class OperateLoop {
         });
         // Build provider-specific request
         const providerRequest = this.adapter.buildRequest(request);
-        // Log what was passed to the model
+        // Log a draconian subset of the request; the full payload is available
+        // via the beforeEachModelRequest hook
         log.trace("[operate] Calling model");
-        log.var({ "operate.request": providerRequest });
+        log.trace.var({
+            "operate.request": {
+                latest: this.summarizeHistoryItem(request.messages[request.messages.length - 1]),
+                messages: request.messages.length,
+                model: request.model,
+                turn: state.currentTurn,
+            },
+        });
+        await emitProgress({
+            event: {
+                model: request.model,
+                turn: state.currentTurn,
+                type: exports.LlmProgressEventType.ModelRequest,
+            },
+            onProgress: options.onProgress,
+        });
         // Execute beforeEachModelRequest hook
         await this.hookRunnerInstance.runBeforeModelRequest(context.hooks, {
             input: state.currentInput,
             options,
             providerRequest,
         });
+        // Emit retry progress alongside the caller's onRetryableModelError hook
+        const hooks = context.hooks;
+        const hooksWithProgress = options.onProgress
+            ? {
+                ...hooks,
+                onRetryableModelError: async (retryContext) => {
+                    await emitProgress({
+                        event: {
+                            error: retryContext.error instanceof Error
+                                ? retryContext.error.message
+                                : String(retryContext.error),
+                            turn: state.currentTurn,
+                            type: exports.LlmProgressEventType.Retry,
+                        },
+                        onProgress: options.onProgress,
+                    });
+                    return hooks?.onRetryableModelError?.(retryContext);
+                },
+            }
+            : hooks;
         // Execute with retry inside a child llm span (no-op when llmobs disabled).
         // RetryExecutor handles error hooks and throws appropriate errors.
-        const { parsed, response } = await withLlmObsSpan({
+        const { parsed, response, toolCalls } = await withLlmObsSpan({
             kind: "llm",
             modelName: options.model ?? this.adapter.defaultModel,
             modelProvider: this.adapter.name,
@@ -6718,19 +6817,43 @@ class OperateLoop {
                     options,
                     providerRequest,
                 },
-                hooks: context.hooks,
+                hooks: hooksWithProgress,
             });
-            // Log what was returned from the model
-            log.trace("[operate] Model response received");
-            log.var({ "operate.response": response });
             // Parse response
             const parsed = this.adapter.parseResponse(response, options);
+            const toolCalls = parsed.hasToolCalls
+                ? this.adapter.extractToolCalls(response)
+                : [];
+            // Log only the text or tool calls; the full payload is available
+            // via the afterEachModelResponse hook
+            log.trace("[operate] Model response received");
+            log.trace.var({
+                "operate.response": toolCalls.length > 0
+                    ? toolCalls.map(({ arguments: args, name }) => ({
+                        arguments: args,
+                        name,
+                    }))
+                    : parsed.content,
+            });
             annotateLlmObs({
                 inputData: state.currentInput,
                 metrics: usageToLlmObsMetrics(parsed.usage ? [parsed.usage] : undefined),
                 outputData: parsed.content ?? "",
             });
-            return { parsed, response };
+            return { parsed, response, toolCalls };
+        });
+        await emitProgress({
+            event: {
+                content: parsed.content,
+                toolCalls: toolCalls.map(({ arguments: args, name }) => ({
+                    arguments: args,
+                    name,
+                })),
+                turn: state.currentTurn,
+                type: exports.LlmProgressEventType.ModelResponse,
+                usage: parsed.usage ? [parsed.usage] : undefined,
+            },
+            onProgress: options.onProgress,
         });
         // Track usage
         if (parsed.usage) {
@@ -6759,7 +6882,6 @@ class OperateLoop {
         }
         // Handle tool calls
         if (parsed.hasToolCalls) {
-            const toolCalls = this.adapter.extractToolCalls(response);
             if (toolCalls.length > 0 && state.toolkit && state.maxTurns > 1) {
                 // Track updated provider request for tool results
                 let currentProviderRequest = providerRequest;
@@ -6770,10 +6892,28 @@ class OperateLoop {
                 this.appendResponseItemsToRequest(currentProviderRequest, responseItems);
                 // Process each tool call
                 for (const toolCall of toolCalls) {
+                    // Resolved once per call; never throws (undefined when tool has no message)
+                    const toolMessage = await state.toolkit.resolveMessage({
+                        arguments: toolCall.arguments,
+                        name: toolCall.name,
+                    });
                     try {
+                        await emitProgress({
+                            event: {
+                                tool: {
+                                    arguments: toolCall.arguments,
+                                    message: toolMessage,
+                                    name: toolCall.name,
+                                },
+                                turn: state.currentTurn,
+                                type: exports.LlmProgressEventType.ToolCall,
+                            },
+                            onProgress: options.onProgress,
+                        });
                         // Execute beforeEachTool hook
                         await this.hookRunnerInstance.runBeforeTool(context.hooks, {
                             args: toolCall.arguments,
+                            message: toolMessage,
                             toolName: toolCall.name,
                         });
                         // Call the tool inside a child tool span (no-op when disabled)
@@ -6781,6 +6921,7 @@ class OperateLoop {
                         const result = await withLlmObsSpan({ kind: "tool", name: toolCall.name }, async () => {
                             const result = await state.toolkit.call({
                                 arguments: toolCall.arguments,
+                                message: toolMessage,
                                 name: toolCall.name,
                             });
                             annotateLlmObs({
@@ -6790,9 +6931,18 @@ class OperateLoop {
                             });
                             return result;
                         });
+                        await emitProgress({
+                            event: {
+                                tool: { name: toolCall.name },
+                                turn: state.currentTurn,
+                                type: exports.LlmProgressEventType.ToolResult,
+                            },
+                            onProgress: options.onProgress,
+                        });
                         // Execute afterEachTool hook
                         await this.hookRunnerInstance.runAfterTool(context.hooks, {
                             args: toolCall.arguments,
+                            message: toolMessage,
                             result,
                             toolName: toolCall.name,
                         });
@@ -6813,10 +6963,20 @@ class OperateLoop {
                         state.responseBuilder.appendToHistory(toolResultFormatted);
                     }
                     catch (error) {
+                        await emitProgress({
+                            event: {
+                                error: error.message,
+                                tool: { name: toolCall.name },
+                                turn: state.currentTurn,
+                                type: exports.LlmProgressEventType.ToolError,
+                            },
+                            onProgress: options.onProgress,
+                        });
                         // Execute onToolError hook
                         await this.hookRunnerInstance.runOnToolError(context.hooks, {
                             args: toolCall.arguments,
                             error: error,
+                            message: toolMessage,
                             toolName: toolCall.name,
                         });
                         // Set error on response
@@ -6886,6 +7046,20 @@ class OperateLoop {
         }
         return false; // Stop loop
     }
+    /**
+     * Draconian summary of a history item for trace logging: string message
+     * content is kept; everything else is reduced to its type.
+     */
+    summarizeHistoryItem(item) {
+        if (!item) {
+            return undefined;
+        }
+        const record = item;
+        if (typeof record.content === "string") {
+            return { content: record.content, role: record.role };
+        }
+        return { type: record.type ?? "message" };
+    }
     /**
      * Reconcile structured output against the declared `format` contract. A
      * declared `format` is a schema contract: returned keys should match the
@@ -7313,10 +7487,16 @@ class StreamLoop {
     async *processToolCalls(toolCalls, state, context) {
         const log = getLogger$6();
         for (const toolCall of toolCalls) {
+            // Resolved once per call; never throws (undefined when tool has no message)
+            const toolMessage = await state.toolkit.resolveMessage({
+                arguments: toolCall.arguments,
+                name: toolCall.name,
+            });
             try {
                 // Execute beforeEachTool hook
                 await this.hookRunnerInstance.runBeforeTool(context.hooks, {
                     args: toolCall.arguments,
+                    message: toolMessage,
                     toolName: toolCall.name,
                 });
                 // Call the tool inside a child tool span (no-op when disabled)
@@ -7324,6 +7504,7 @@ class StreamLoop {
                 const result = await withLlmObsSpan({ kind: "tool", name: toolCall.name }, async () => {
                     const result = await state.toolkit.call({
                         arguments: toolCall.arguments,
+                        message: toolMessage,
                         name: toolCall.name,
                     });
                     annotateLlmObs({
@@ -7336,6 +7517,7 @@ class StreamLoop {
                 // Execute afterEachTool hook
                 await this.hookRunnerInstance.runAfterTool(context.hooks, {
                     args: toolCall.arguments,
+                    message: toolMessage,
                     result,
                     toolName: toolCall.name,
                 });
@@ -7363,6 +7545,7 @@ class StreamLoop {
                 await this.hookRunnerInstance.runOnToolError(context.hooks, {
                     args: toolCall.arguments,
                     error: error,
+                    message: toolMessage,
                     toolName: toolCall.name,
                 });
                 // Yield error chunk