@jaypie/llm 1.3.6 → 1.3.8

package/dist/cjs/index.d.cts

@@ -227,9 +227,21 @@ declare class Toolkit {
     private readonly log;
     constructor(tools: LlmTool[], options?: ToolkitOptions);
     get tools(): Omit<LlmTool, "call">[];
-    call({ name, arguments: args }: {
+    private parseArgs;
+    /**
+     * 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.
+     */
+    resolveMessage({ name, arguments: args, }: {
         name: string;
         arguments: string;
+    }): Promise<string | undefined>;
+    call({ name, arguments: args, message: resolvedMessage, }: {
+        name: string;
+        arguments: string;
+        /** Pre-resolved tool message; skips re-resolving `tool.message` for logging */
+        message?: string;
     }): Promise<_jaypie_types.AnyValue>;
     extend(tools: LlmTool[], options?: {
         warn?: boolean;
@@ -402,6 +414,51 @@ interface LlmMessageOptions {
     response?: NaturalSchema | z.ZodType;
     system?: string;
 }
+declare enum LlmProgressEventType {
+    Done = "done",
+    ModelRequest = "model_request",
+    ModelResponse = "model_response",
+    Retry = "retry",
+    Start = "start",
+    ToolCall = "tool_call",
+    ToolError = "tool_error",
+    ToolResult = "tool_result"
+}
+interface LlmProgressToolCall {
+    /** JSON string of arguments (tool_call events only) */
+    arguments?: string;
+    /** Resolved `LlmTool.message`, when the tool defines one (tool_call events only) */
+    message?: string;
+    /** Tool name */
+    name: string;
+}
+/**
+ * Lightweight, serializable progress event emitted by the operate loop.
+ * Suitable for forwarding directly to websockets, queues, or UI updates.
+ */
+interface LlmProgressEvent {
+    /** Text or structured content (model_response, done) */
+    content?: string | JsonObject;
+    /** Error message (tool_error, retry) */
+    error?: string;
+    /** Maximum turns allowed for the loop (start) */
+    maxTurns?: number;
+    /** Model handling the request (start, model_request) */
+    model?: string;
+    /** Provider name (start) */
+    provider?: string;
+    /** The tool involved (tool_call, tool_result, tool_error) */
+    tool?: LlmProgressToolCall;
+    /** Tools the model requested (model_response) */
+    toolCalls?: LlmProgressToolCall[];
+    /** Current turn, 1-indexed */
+    turn?: number;
+    /** Event type */
+    type: LlmProgressEventType;
+    /** Usage: this turn for model_response, cumulative for done */
+    usage?: LlmUsage;
+}
+type LlmProgressCallback = (event: LlmProgressEvent) => unknown | Promise<unknown>;
 interface LlmOperateOptions {
     data?: NaturalMap;
     explain?: boolean;
@@ -418,19 +475,23 @@ interface LlmOperateOptions {
             content: string | JsonObject;
             usage: LlmUsage;
         }) => unknown | Promise<unknown>;
-        afterEachTool?: ({ result, toolName, args, }: {
+        afterEachTool?: ({ result, toolName, args, message, }: {
             result: unknown;
             toolName: string;
             args: string;
+            /** Resolved `LlmTool.message`, when the tool defines one */
+            message?: string;
         }) => unknown | Promise<unknown>;
         beforeEachModelRequest?: ({ input, options, providerRequest, }: {
             input: string | LlmHistory | LlmInputMessage;
             options?: LlmOperateOptions;
             providerRequest: any;
         }) => unknown | Promise<unknown>;
-        beforeEachTool?: ({ toolName, args, }: {
+        beforeEachTool?: ({ toolName, args, message, }: {
             toolName: string;
             args: string;
+            /** Resolved `LlmTool.message`, when the tool defines one */
+            message?: string;
         }) => unknown | Promise<unknown>;
         onRetryableModelError?: ({ input, options, providerRequest, error, }: {
             input: string | LlmHistory | LlmInputMessage;
@@ -438,10 +499,12 @@ interface LlmOperateOptions {
             providerRequest: any;
             error: any;
         }) => unknown | Promise<unknown>;
-        onToolError?: ({ error, toolName, args, }: {
+        onToolError?: ({ error, toolName, args, message, }: {
             error: Error;
             toolName: string;
             args: string;
+            /** Resolved `LlmTool.message`, when the tool defines one */
+            message?: string;
         }) => unknown | Promise<unknown>;
         onUnrecoverableModelError?: ({ input, options, providerRequest, error, }: {
             input: string | LlmHistory | LlmInputMessage;
@@ -452,6 +515,13 @@ interface LlmOperateOptions {
     };
     instructions?: string;
     model?: string;
+    /**
+     * Receives lightweight progress events as the operate loop runs:
+     * start, model_request, model_response, tool_call, tool_result,
+     * tool_error, retry, done. Errors thrown by the callback are logged
+     * and never interrupt the loop.
+     */
+    onProgress?: LlmProgressCallback;
     placeholders?: {
         input?: boolean;
         instructions?: boolean;
@@ -669,5 +739,5 @@ declare class XaiProvider implements LlmProvider {
     stream(input: string | LlmHistory | LlmInputMessage, options?: LlmOperateOptions): AsyncIterable<LlmStreamChunk>;
 }
 
-export { BedrockProvider, GoogleProvider as GeminiProvider, GoogleProvider, JaypieToolkit, constants as LLM, Llm, LlmMessageRole, LlmMessageType, LlmStreamChunkType, OpenRouterProvider, Toolkit, XaiProvider, extractReasoning, isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, jsonSchemaToNaturalSchema, naturalSchemaToJsonSchema, toolkit, tools };
-export type { LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };
+export { BedrockProvider, GoogleProvider as GeminiProvider, GoogleProvider, JaypieToolkit, constants as LLM, Llm, LlmMessageRole, LlmMessageType, LlmProgressEventType, LlmStreamChunkType, OpenRouterProvider, Toolkit, XaiProvider, extractReasoning, isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, jsonSchemaToNaturalSchema, naturalSchemaToJsonSchema, toolkit, tools };
+export type { LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };

package/dist/cjs/src/index.d.ts

@@ -1,7 +1,7 @@
 export { default as Llm } from "./Llm.js";
 export * as LLM from "./constants.js";
-export type { LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProvider, } from "./types/LlmProvider.interface.js";
-export { LlmMessageRole, LlmMessageType, } from "./types/LlmProvider.interface.js";
+export type { LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, } from "./types/LlmProvider.interface.js";
+export { LlmMessageRole, LlmMessageType, LlmProgressEventType, } from "./types/LlmProvider.interface.js";
 export { isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, } from "./types/LlmOperateInput.guards.js";
 export type { LlmTool } from "./types/LlmTool.interface.js";
 export type { LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, } from "./types/LlmStreamChunk.interface.js";

package/dist/cjs/src/operate/OperateLoop.d.ts

@@ -34,6 +34,11 @@ export declare class OperateLoop {
     private createContext;
     private buildInitialRequest;
     private executeOneTurn;
+    /**
+     * Draconian summary of a history item for trace logging: string message
+     * content is kept; everything else is reduced to its type.
+     */
+    private summarizeHistoryItem;
     /**
      * Reconcile structured output against the declared `format` contract. A
      * declared `format` is a schema contract: returned keys should match the

package/dist/cjs/src/operate/hooks/HookRunner.d.ts

@@ -15,16 +15,19 @@ export interface AfterModelResponseContext {
 }
 export interface BeforeToolContext {
     args: string;
+    message?: string;
     toolName: string;
 }
 export interface AfterToolContext {
     args: string;
+    message?: string;
     result: unknown;
     toolName: string;
 }
 export interface ToolErrorContext {
     args: string;
     error: Error;
+    message?: string;
     toolName: string;
 }
 export interface RetryableErrorContext {

package/dist/cjs/src/operate/progress/emitProgress.d.ts

@@ -0,0 +1,10 @@
+import { LlmProgressCallback, LlmProgressEvent } from "../../types/LlmProvider.interface.js";
+/**
+ * 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.
+ */
+export declare function emitProgress({ event, onProgress, }: {
+    event: LlmProgressEvent;
+    onProgress?: LlmProgressCallback;
+}): Promise<void>;

package/dist/cjs/src/operate/progress/index.d.ts

@@ -0,0 +1 @@
+export { emitProgress } from "./emitProgress.js";

package/dist/cjs/src/tools/Toolkit.class.d.ts

@@ -14,9 +14,21 @@ export declare class Toolkit {
     private readonly log;
     constructor(tools: LlmTool[], options?: ToolkitOptions);
     get tools(): Omit<LlmTool, "call">[];
-    call({ name, arguments: args }: {
+    private parseArgs;
+    /**
+     * 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.
+     */
+    resolveMessage({ name, arguments: args, }: {
         name: string;
         arguments: string;
+    }): Promise<string | undefined>;
+    call({ name, arguments: args, message: resolvedMessage, }: {
+        name: string;
+        arguments: string;
+        /** Pre-resolved tool message; skips re-resolving `tool.message` for logging */
+        message?: string;
     }): Promise<import("@jaypie/types").AnyValue>;
     extend(tools: LlmTool[], options?: {
         warn?: boolean;

package/dist/cjs/src/types/LlmProvider.interface.d.ts

@@ -166,6 +166,51 @@ export interface LlmMessageOptions {
     response?: NaturalSchema | z.ZodType;
     system?: string;
 }
+export declare enum LlmProgressEventType {
+    Done = "done",
+    ModelRequest = "model_request",
+    ModelResponse = "model_response",
+    Retry = "retry",
+    Start = "start",
+    ToolCall = "tool_call",
+    ToolError = "tool_error",
+    ToolResult = "tool_result"
+}
+export interface LlmProgressToolCall {
+    /** JSON string of arguments (tool_call events only) */
+    arguments?: string;
+    /** Resolved `LlmTool.message`, when the tool defines one (tool_call events only) */
+    message?: string;
+    /** Tool name */
+    name: string;
+}
+/**
+ * Lightweight, serializable progress event emitted by the operate loop.
+ * Suitable for forwarding directly to websockets, queues, or UI updates.
+ */
+export interface LlmProgressEvent {
+    /** Text or structured content (model_response, done) */
+    content?: string | JsonObject;
+    /** Error message (tool_error, retry) */
+    error?: string;
+    /** Maximum turns allowed for the loop (start) */
+    maxTurns?: number;
+    /** Model handling the request (start, model_request) */
+    model?: string;
+    /** Provider name (start) */
+    provider?: string;
+    /** The tool involved (tool_call, tool_result, tool_error) */
+    tool?: LlmProgressToolCall;
+    /** Tools the model requested (model_response) */
+    toolCalls?: LlmProgressToolCall[];
+    /** Current turn, 1-indexed */
+    turn?: number;
+    /** Event type */
+    type: LlmProgressEventType;
+    /** Usage: this turn for model_response, cumulative for done */
+    usage?: LlmUsage;
+}
+export type LlmProgressCallback = (event: LlmProgressEvent) => unknown | Promise<unknown>;
 export interface LlmOperateOptions {
     data?: NaturalMap;
     explain?: boolean;
@@ -182,19 +227,23 @@ export interface LlmOperateOptions {
             content: string | JsonObject;
             usage: LlmUsage;
         }) => unknown | Promise<unknown>;
-        afterEachTool?: ({ result, toolName, args, }: {
+        afterEachTool?: ({ result, toolName, args, message, }: {
             result: unknown;
             toolName: string;
             args: string;
+            /** Resolved `LlmTool.message`, when the tool defines one */
+            message?: string;
         }) => unknown | Promise<unknown>;
         beforeEachModelRequest?: ({ input, options, providerRequest, }: {
             input: string | LlmHistory | LlmInputMessage;
             options?: LlmOperateOptions;
             providerRequest: any;
         }) => unknown | Promise<unknown>;
-        beforeEachTool?: ({ toolName, args, }: {
+        beforeEachTool?: ({ toolName, args, message, }: {
             toolName: string;
             args: string;
+            /** Resolved `LlmTool.message`, when the tool defines one */
+            message?: string;
         }) => unknown | Promise<unknown>;
         onRetryableModelError?: ({ input, options, providerRequest, error, }: {
             input: string | LlmHistory | LlmInputMessage;
@@ -202,10 +251,12 @@ export interface LlmOperateOptions {
             providerRequest: any;
             error: any;
         }) => unknown | Promise<unknown>;
-        onToolError?: ({ error, toolName, args, }: {
+        onToolError?: ({ error, toolName, args, message, }: {
             error: Error;
             toolName: string;
             args: string;
+            /** Resolved `LlmTool.message`, when the tool defines one */
+            message?: string;
         }) => unknown | Promise<unknown>;
         onUnrecoverableModelError?: ({ input, options, providerRequest, error, }: {
             input: string | LlmHistory | LlmInputMessage;
@@ -216,6 +267,13 @@ export interface LlmOperateOptions {
     };
     instructions?: string;
     model?: string;
+    /**
+     * Receives lightweight progress events as the operate loop runs:
+     * start, model_request, model_response, tool_call, tool_result,
+     * tool_error, retry, done. Errors thrown by the callback are logged
+     * and never interrupt the loop.
+     */
+    onProgress?: LlmProgressCallback;
     placeholders?: {
         input?: boolean;
         instructions?: boolean;

package/dist/esm/index.d.ts

@@ -227,9 +227,21 @@ declare class Toolkit {
     private readonly log;
     constructor(tools: LlmTool[], options?: ToolkitOptions);
     get tools(): Omit<LlmTool, "call">[];
-    call({ name, arguments: args }: {
+    private parseArgs;
+    /**
+     * 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.
+     */
+    resolveMessage({ name, arguments: args, }: {
         name: string;
         arguments: string;
+    }): Promise<string | undefined>;
+    call({ name, arguments: args, message: resolvedMessage, }: {
+        name: string;
+        arguments: string;
+        /** Pre-resolved tool message; skips re-resolving `tool.message` for logging */
+        message?: string;
     }): Promise<_jaypie_types.AnyValue>;
     extend(tools: LlmTool[], options?: {
         warn?: boolean;
@@ -402,6 +414,51 @@ interface LlmMessageOptions {
     response?: NaturalSchema | z.ZodType;
     system?: string;
 }
+declare enum LlmProgressEventType {
+    Done = "done",
+    ModelRequest = "model_request",
+    ModelResponse = "model_response",
+    Retry = "retry",
+    Start = "start",
+    ToolCall = "tool_call",
+    ToolError = "tool_error",
+    ToolResult = "tool_result"
+}
+interface LlmProgressToolCall {
+    /** JSON string of arguments (tool_call events only) */
+    arguments?: string;
+    /** Resolved `LlmTool.message`, when the tool defines one (tool_call events only) */
+    message?: string;
+    /** Tool name */
+    name: string;
+}
+/**
+ * Lightweight, serializable progress event emitted by the operate loop.
+ * Suitable for forwarding directly to websockets, queues, or UI updates.
+ */
+interface LlmProgressEvent {
+    /** Text or structured content (model_response, done) */
+    content?: string | JsonObject;
+    /** Error message (tool_error, retry) */
+    error?: string;
+    /** Maximum turns allowed for the loop (start) */
+    maxTurns?: number;
+    /** Model handling the request (start, model_request) */
+    model?: string;
+    /** Provider name (start) */
+    provider?: string;
+    /** The tool involved (tool_call, tool_result, tool_error) */
+    tool?: LlmProgressToolCall;
+    /** Tools the model requested (model_response) */
+    toolCalls?: LlmProgressToolCall[];
+    /** Current turn, 1-indexed */
+    turn?: number;
+    /** Event type */
+    type: LlmProgressEventType;
+    /** Usage: this turn for model_response, cumulative for done */
+    usage?: LlmUsage;
+}
+type LlmProgressCallback = (event: LlmProgressEvent) => unknown | Promise<unknown>;
 interface LlmOperateOptions {
     data?: NaturalMap;
     explain?: boolean;
@@ -418,19 +475,23 @@ interface LlmOperateOptions {
             content: string | JsonObject;
             usage: LlmUsage;
         }) => unknown | Promise<unknown>;
-        afterEachTool?: ({ result, toolName, args, }: {
+        afterEachTool?: ({ result, toolName, args, message, }: {
             result: unknown;
             toolName: string;
             args: string;
+            /** Resolved `LlmTool.message`, when the tool defines one */
+            message?: string;
         }) => unknown | Promise<unknown>;
         beforeEachModelRequest?: ({ input, options, providerRequest, }: {
             input: string | LlmHistory | LlmInputMessage;
             options?: LlmOperateOptions;
             providerRequest: any;
         }) => unknown | Promise<unknown>;
-        beforeEachTool?: ({ toolName, args, }: {
+        beforeEachTool?: ({ toolName, args, message, }: {
             toolName: string;
             args: string;
+            /** Resolved `LlmTool.message`, when the tool defines one */
+            message?: string;
         }) => unknown | Promise<unknown>;
         onRetryableModelError?: ({ input, options, providerRequest, error, }: {
             input: string | LlmHistory | LlmInputMessage;
@@ -438,10 +499,12 @@ interface LlmOperateOptions {
             providerRequest: any;
             error: any;
         }) => unknown | Promise<unknown>;
-        onToolError?: ({ error, toolName, args, }: {
+        onToolError?: ({ error, toolName, args, message, }: {
             error: Error;
             toolName: string;
             args: string;
+            /** Resolved `LlmTool.message`, when the tool defines one */
+            message?: string;
         }) => unknown | Promise<unknown>;
         onUnrecoverableModelError?: ({ input, options, providerRequest, error, }: {
             input: string | LlmHistory | LlmInputMessage;
@@ -452,6 +515,13 @@ interface LlmOperateOptions {
     };
     instructions?: string;
     model?: string;
+    /**
+     * Receives lightweight progress events as the operate loop runs:
+     * start, model_request, model_response, tool_call, tool_result,
+     * tool_error, retry, done. Errors thrown by the callback are logged
+     * and never interrupt the loop.
+     */
+    onProgress?: LlmProgressCallback;
     placeholders?: {
         input?: boolean;
         instructions?: boolean;
@@ -669,5 +739,5 @@ declare class XaiProvider implements LlmProvider {
     stream(input: string | LlmHistory | LlmInputMessage, options?: LlmOperateOptions): AsyncIterable<LlmStreamChunk>;
 }
 
-export { BedrockProvider, GoogleProvider as GeminiProvider, GoogleProvider, JaypieToolkit, constants as LLM, Llm, LlmMessageRole, LlmMessageType, LlmStreamChunkType, OpenRouterProvider, Toolkit, XaiProvider, extractReasoning, isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, jsonSchemaToNaturalSchema, naturalSchemaToJsonSchema, toolkit, tools };
-export type { LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };
+export { BedrockProvider, GoogleProvider as GeminiProvider, GoogleProvider, JaypieToolkit, constants as LLM, Llm, LlmMessageRole, LlmMessageType, LlmProgressEventType, LlmStreamChunkType, OpenRouterProvider, Toolkit, XaiProvider, extractReasoning, isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, jsonSchemaToNaturalSchema, naturalSchemaToJsonSchema, toolkit, tools };
+export type { LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };