@jaypie/llm 1.3.6 → 1.3.7

package/dist/esm/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/esm/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/esm/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/esm/src/operate/progress/index.d.ts

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

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

@@ -166,6 +166,49 @@ 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;
+    /** 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;
@@ -216,6 +259,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/llm",
-  "version": "1.3.6",
+  "version": "1.3.7",
   "description": "Large language model utilities",
   "repository": {
     "type": "git",