@jaypie/llm 1.3.13 → 1.3.14

package/dist/cjs/index.d.cts

@@ -525,6 +525,81 @@ interface LlmProgressEvent {
     usage?: LlmUsage;
 }
 type LlmProgressCallback = (event: LlmProgressEvent) => unknown | Promise<unknown>;
+/**
+ * Serializable snapshot of the request side of one operate() call.
+ * `input` is the raw, pre-interpolation input with multimodal parts preserved.
+ */
+interface LlmExchangeRequest {
+    data?: NaturalMap;
+    effort?: LlmEffort;
+    explain?: boolean;
+    /** Format normalized to JSON Schema (Zod/Natural already rendered) */
+    format?: JsonObject;
+    input: string | LlmHistory | LlmInputMessage | LlmOperateInput;
+    instructions?: string;
+    /** Requested model (pre-fallback) */
+    model?: string;
+    placeholders?: {
+        input?: boolean;
+        instructions?: boolean;
+        system?: boolean;
+    };
+    providerOptions?: JsonObject;
+    system?: string;
+    temperature?: number;
+    /** Names of tools offered to the model */
+    tools?: string[];
+    turns?: boolean | number;
+    user?: string;
+}
+/**
+ * Serializable snapshot of the response side of one operate() call.
+ */
+interface LlmExchangeResponse {
+    content?: string | JsonObject;
+    error?: LlmError$1;
+    /** Turns this call added to history (tool calls/results included); never the resent history */
+    historyDelta: LlmHistory;
+    reasoning?: string[];
+    status: LlmResponseStatus;
+    stopReason?: string;
+    /** Per-model-call usage items (provider/model on each item) */
+    usage: LlmUsage;
+    /** Cumulative usage keyed `provider:model` */
+    usageTotals?: Record<string, LlmUsageItem>;
+}
+/**
+ * How the call was actually served after fallback and retry resolution.
+ */
+interface LlmExchangeResolution {
+    fallbackAttempts?: number;
+    fallbackUsed?: boolean;
+    /** Served model */
+    model?: string;
+    /** Served provider */
+    provider?: string;
+    /** Model-request retries within the served attempt */
+    retries?: number;
+}
+interface LlmExchangeTiming {
+    /** Milliseconds from start to settlement */
+    duration: number;
+    /** ISO 8601 */
+    startedAt: string;
+}
+/**
+ * One serializable request/response envelope per operate() settlement
+ * (success or failure). Contains no functions.
+ */
+interface LlmExchangeEnvelope {
+    /** Provider response id(s) per model turn, when available */
+    ids?: string[];
+    request: LlmExchangeRequest;
+    resolution: LlmExchangeResolution;
+    response: LlmExchangeResponse;
+    timing: LlmExchangeTiming;
+}
+type LlmExchangeCallback = (envelope: LlmExchangeEnvelope) => unknown | Promise<unknown>;
 interface LlmOperateOptions {
     data?: NaturalMap;
     /**
@@ -589,6 +664,12 @@ interface LlmOperateOptions {
     };
     instructions?: string;
     model?: string;
+    /**
+     * Fires once per operate() settlement (success or failure) with a fully
+     * serializable request/response envelope. Errors thrown by the callback
+     * are logged and never interrupt the call.
+     */
+    onExchange?: LlmExchangeCallback;
     /**
      * Receives lightweight progress events as the operate loop runs:
      * start, model_request, model_response, tool_call, tool_result,
@@ -635,6 +716,11 @@ type LlmUsage = LlmUsageItem[];
 interface LlmOperateResponse {
     content?: string | JsonObject;
     error?: LlmError$1;
+    /**
+     * Serializable exchange envelope for this call. Present only when
+     * `onExchange` was passed or exchange persistence is enabled.
+     */
+    exchange?: LlmExchangeEnvelope;
     /** Number of providers attempted (1 = primary only, >1 = fallback(s) used) */
     fallbackAttempts?: number;
     /** Whether a fallback provider was used instead of the primary */
@@ -680,6 +766,12 @@ declare class Llm implements LlmProvider {
     operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
         model?: LlmModelOption;
     }): Promise<LlmOperateResponse>;
+    /**
+     * Stamp fallback resolution onto the envelope the operate loop attached to
+     * the response and deliver it to the caller's onExchange. Fires once per
+     * operate() settlement; callback errors are logged and never thrown.
+     */
+    private settleExchange;
     stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
         model?: LlmModelOption;
     }): AsyncIterable<LlmStreamChunk>;
@@ -931,4 +1023,4 @@ declare class XaiProvider implements LlmProvider {
 }
 
 export { BedrockProvider, ErrorCategory, FireworksProvider, GoogleProvider as GeminiProvider, GoogleProvider, JaypieToolkit, constants as LLM, Llm, LlmError, LlmMessageRole, LlmMessageType, LlmProgressEventType, LlmQuotaError, LlmRateLimitError, LlmStreamChunkType, LlmTransientError, LlmUnrecoverableError, OpenRouterProvider, Toolkit, XaiProvider, extractReasoning, isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, jsonSchemaToNaturalSchema, naturalSchemaToJsonSchema, toolkit, tools };
-export type { LlmEffort, LlmErrorOptions, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };
+export type { LlmEffort, LlmErrorOptions, LlmExchangeCallback, LlmExchangeEnvelope, LlmExchangeRequest, LlmExchangeResolution, LlmExchangeResponse, LlmExchangeTiming, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };

package/dist/cjs/index.d.ts

@@ -1,7 +1,7 @@
 export { default as Llm } from "./Llm.js";
 export * as LLM from "./constants.js";
 export type { LlmEffort } from "./constants.js";
-export type { LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, } from "./types/LlmProvider.interface.js";
+export type { LlmExchangeCallback, LlmExchangeEnvelope, LlmExchangeRequest, LlmExchangeResolution, LlmExchangeResponse, LlmExchangeTiming, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelOption, 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";

package/dist/cjs/observability/exchangeStore.d.ts

@@ -0,0 +1,20 @@
+import { LlmExchangeEnvelope } from "../types/LlmProvider.interface.js";
+/** Minimal shape of the @jaypie/dynamodb surface this module uses. */
+interface ExchangeStoreSdk {
+    storeExchange: (envelope: LlmExchangeEnvelope) => Promise<unknown>;
+}
+/** Reset the cached resolution. Exposed for tests. */
+export declare function _resetExchangeStore(): void;
+/**
+ * Inject a store to bypass @jaypie/dynamodb resolution. Test-only: the peer
+ * is optional, so the enabled path cannot otherwise be exercised in unit
+ * tests without it installed.
+ */
+export declare function _setExchangeStore(sdk: ExchangeStoreSdk | null): void;
+/**
+ * Persist an exchange envelope via @jaypie/dynamodb when
+ * LLM_EXCHANGE_ENABLED is set. Silent no-op when the flag is unset or the
+ * peer is absent; persister failures are logged and never thrown.
+ */
+export declare function persistExchange(envelope: LlmExchangeEnvelope): Promise<void>;
+export {};

package/dist/cjs/operate/exchange/buildExchangeEnvelope.d.ts

@@ -0,0 +1,16 @@
+import { LlmExchangeEnvelope, LlmHistory, LlmInputMessage, LlmOperateInput, LlmOperateOptions, LlmOperateResponse } from "../../types/LlmProvider.interface.js";
+import { OperateLoopState } from "../types.js";
+/**
+ * Assemble the serializable exchange envelope for one operate() settlement.
+ * The `resolution` block is stamped by the Llm facade, which is the layer
+ * that knows fallback outcome; the loop fills provider/model best-effort.
+ */
+export declare function buildExchangeEnvelope({ duration, initialHistoryLength, input, options, response, startedAt, state, }: {
+    duration: number;
+    initialHistoryLength: number;
+    input: string | LlmHistory | LlmInputMessage | LlmOperateInput;
+    options: LlmOperateOptions;
+    response: LlmOperateResponse;
+    startedAt: string;
+    state: OperateLoopState;
+}): LlmExchangeEnvelope;

package/dist/cjs/operate/exchange/emitExchange.d.ts

@@ -0,0 +1,20 @@
+import { LlmExchangeCallback, LlmExchangeEnvelope } from "../../types/LlmProvider.interface.js";
+/**
+ * Truthy-except-"false"/"0" gate on LLM_EXCHANGE_ENABLED, matching the
+ * DD_LLMOBS_ENABLED convention in observability/llmobs.ts.
+ */
+export declare function isExchangeStoreEnabled(): boolean;
+/**
+ * Whether the loop should assemble an exchange envelope at settlement.
+ */
+export declare function isExchangeRequested({ onExchange, }: {
+    onExchange?: LlmExchangeCallback;
+}): boolean;
+/**
+ * Deliver an exchange envelope to a callback. Errors thrown by the callback
+ * are logged and swallowed — exchange capture must never interrupt the call.
+ */
+export declare function emitExchange({ envelope, onExchange, }: {
+    envelope: LlmExchangeEnvelope;
+    onExchange?: LlmExchangeCallback;
+}): Promise<void>;

package/dist/cjs/operate/exchange/index.d.ts

@@ -0,0 +1,2 @@
+export { buildExchangeEnvelope } from "./buildExchangeEnvelope.js";
+export { emitExchange, isExchangeRequested, isExchangeStoreEnabled, } from "./emitExchange.js";

package/dist/cjs/operate/types.d.ts

@@ -150,6 +150,10 @@ export interface OperateLoopState {
     currentTurn: number;
     /** Formatted output schema for structured output */
     formattedFormat?: JsonObject;
+    /** Stop reason from the most recent model response */
+    lastStopReason?: string;
+    /** Model-request retries across all turns (exchange envelope) */
+    retries: number;
     /** Formatted tools for the provider */
     formattedTools?: ProviderToolDefinition[];
     /** Maximum allowed turns */

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

@@ -26,7 +26,7 @@ export declare enum LlmResponseStatus {
     Incomplete = "incomplete",
     InProgress = "in_progress"
 }
-interface LlmError {
+export interface LlmError {
     detail?: string;
     status: number | string;
     title: string;
@@ -212,6 +212,81 @@ export interface LlmProgressEvent {
     usage?: LlmUsage;
 }
 export type LlmProgressCallback = (event: LlmProgressEvent) => unknown | Promise<unknown>;
+/**
+ * Serializable snapshot of the request side of one operate() call.
+ * `input` is the raw, pre-interpolation input with multimodal parts preserved.
+ */
+export interface LlmExchangeRequest {
+    data?: NaturalMap;
+    effort?: LlmEffort;
+    explain?: boolean;
+    /** Format normalized to JSON Schema (Zod/Natural already rendered) */
+    format?: JsonObject;
+    input: string | LlmHistory | LlmInputMessage | LlmOperateInput;
+    instructions?: string;
+    /** Requested model (pre-fallback) */
+    model?: string;
+    placeholders?: {
+        input?: boolean;
+        instructions?: boolean;
+        system?: boolean;
+    };
+    providerOptions?: JsonObject;
+    system?: string;
+    temperature?: number;
+    /** Names of tools offered to the model */
+    tools?: string[];
+    turns?: boolean | number;
+    user?: string;
+}
+/**
+ * Serializable snapshot of the response side of one operate() call.
+ */
+export interface LlmExchangeResponse {
+    content?: string | JsonObject;
+    error?: LlmError;
+    /** Turns this call added to history (tool calls/results included); never the resent history */
+    historyDelta: LlmHistory;
+    reasoning?: string[];
+    status: LlmResponseStatus;
+    stopReason?: string;
+    /** Per-model-call usage items (provider/model on each item) */
+    usage: LlmUsage;
+    /** Cumulative usage keyed `provider:model` */
+    usageTotals?: Record<string, LlmUsageItem>;
+}
+/**
+ * How the call was actually served after fallback and retry resolution.
+ */
+export interface LlmExchangeResolution {
+    fallbackAttempts?: number;
+    fallbackUsed?: boolean;
+    /** Served model */
+    model?: string;
+    /** Served provider */
+    provider?: string;
+    /** Model-request retries within the served attempt */
+    retries?: number;
+}
+export interface LlmExchangeTiming {
+    /** Milliseconds from start to settlement */
+    duration: number;
+    /** ISO 8601 */
+    startedAt: string;
+}
+/**
+ * One serializable request/response envelope per operate() settlement
+ * (success or failure). Contains no functions.
+ */
+export interface LlmExchangeEnvelope {
+    /** Provider response id(s) per model turn, when available */
+    ids?: string[];
+    request: LlmExchangeRequest;
+    resolution: LlmExchangeResolution;
+    response: LlmExchangeResponse;
+    timing: LlmExchangeTiming;
+}
+export type LlmExchangeCallback = (envelope: LlmExchangeEnvelope) => unknown | Promise<unknown>;
 export interface LlmOperateOptions {
     data?: NaturalMap;
     /**
@@ -276,6 +351,12 @@ export interface LlmOperateOptions {
     };
     instructions?: string;
     model?: string;
+    /**
+     * Fires once per operate() settlement (success or failure) with a fully
+     * serializable request/response envelope. Errors thrown by the callback
+     * are logged and never interrupt the call.
+     */
+    onExchange?: LlmExchangeCallback;
     /**
      * Receives lightweight progress events as the operate loop runs:
      * start, model_request, model_response, tool_call, tool_result,
@@ -322,6 +403,11 @@ export type LlmUsage = LlmUsageItem[];
 export interface LlmOperateResponse {
     content?: string | JsonObject;
     error?: LlmError;
+    /**
+     * Serializable exchange envelope for this call. Present only when
+     * `onExchange` was passed or exchange persistence is enabled.
+     */
+    exchange?: LlmExchangeEnvelope;
     /** Number of providers attempted (1 = primary only, >1 = fallback(s) used) */
     fallbackAttempts?: number;
     /** Whether a fallback provider was used instead of the primary */

package/dist/esm/Llm.d.ts

@@ -27,6 +27,12 @@ declare class Llm implements LlmProvider {
     operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
         model?: LlmModelOption;
     }): Promise<LlmOperateResponse>;
+    /**
+     * Stamp fallback resolution onto the envelope the operate loop attached to
+     * the response and deliver it to the caller's onExchange. Fires once per
+     * operate() settlement; callback errors are logged and never thrown.
+     */
+    private settleExchange;
     stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
         model?: LlmModelOption;
     }): AsyncIterable<LlmStreamChunk>;

package/dist/esm/index.d.ts

@@ -525,6 +525,81 @@ interface LlmProgressEvent {
     usage?: LlmUsage;
 }
 type LlmProgressCallback = (event: LlmProgressEvent) => unknown | Promise<unknown>;
+/**
+ * Serializable snapshot of the request side of one operate() call.
+ * `input` is the raw, pre-interpolation input with multimodal parts preserved.
+ */
+interface LlmExchangeRequest {
+    data?: NaturalMap;
+    effort?: LlmEffort;
+    explain?: boolean;
+    /** Format normalized to JSON Schema (Zod/Natural already rendered) */
+    format?: JsonObject;
+    input: string | LlmHistory | LlmInputMessage | LlmOperateInput;
+    instructions?: string;
+    /** Requested model (pre-fallback) */
+    model?: string;
+    placeholders?: {
+        input?: boolean;
+        instructions?: boolean;
+        system?: boolean;
+    };
+    providerOptions?: JsonObject;
+    system?: string;
+    temperature?: number;
+    /** Names of tools offered to the model */
+    tools?: string[];
+    turns?: boolean | number;
+    user?: string;
+}
+/**
+ * Serializable snapshot of the response side of one operate() call.
+ */
+interface LlmExchangeResponse {
+    content?: string | JsonObject;
+    error?: LlmError$1;
+    /** Turns this call added to history (tool calls/results included); never the resent history */
+    historyDelta: LlmHistory;
+    reasoning?: string[];
+    status: LlmResponseStatus;
+    stopReason?: string;
+    /** Per-model-call usage items (provider/model on each item) */
+    usage: LlmUsage;
+    /** Cumulative usage keyed `provider:model` */
+    usageTotals?: Record<string, LlmUsageItem>;
+}
+/**
+ * How the call was actually served after fallback and retry resolution.
+ */
+interface LlmExchangeResolution {
+    fallbackAttempts?: number;
+    fallbackUsed?: boolean;
+    /** Served model */
+    model?: string;
+    /** Served provider */
+    provider?: string;
+    /** Model-request retries within the served attempt */
+    retries?: number;
+}
+interface LlmExchangeTiming {
+    /** Milliseconds from start to settlement */
+    duration: number;
+    /** ISO 8601 */
+    startedAt: string;
+}
+/**
+ * One serializable request/response envelope per operate() settlement
+ * (success or failure). Contains no functions.
+ */
+interface LlmExchangeEnvelope {
+    /** Provider response id(s) per model turn, when available */
+    ids?: string[];
+    request: LlmExchangeRequest;
+    resolution: LlmExchangeResolution;
+    response: LlmExchangeResponse;
+    timing: LlmExchangeTiming;
+}
+type LlmExchangeCallback = (envelope: LlmExchangeEnvelope) => unknown | Promise<unknown>;
 interface LlmOperateOptions {
     data?: NaturalMap;
     /**
@@ -589,6 +664,12 @@ interface LlmOperateOptions {
     };
     instructions?: string;
     model?: string;
+    /**
+     * Fires once per operate() settlement (success or failure) with a fully
+     * serializable request/response envelope. Errors thrown by the callback
+     * are logged and never interrupt the call.
+     */
+    onExchange?: LlmExchangeCallback;
     /**
      * Receives lightweight progress events as the operate loop runs:
      * start, model_request, model_response, tool_call, tool_result,
@@ -635,6 +716,11 @@ type LlmUsage = LlmUsageItem[];
 interface LlmOperateResponse {
     content?: string | JsonObject;
     error?: LlmError$1;
+    /**
+     * Serializable exchange envelope for this call. Present only when
+     * `onExchange` was passed or exchange persistence is enabled.
+     */
+    exchange?: LlmExchangeEnvelope;
     /** Number of providers attempted (1 = primary only, >1 = fallback(s) used) */
     fallbackAttempts?: number;
     /** Whether a fallback provider was used instead of the primary */
@@ -680,6 +766,12 @@ declare class Llm implements LlmProvider {
     operate(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
         model?: LlmModelOption;
     }): Promise<LlmOperateResponse>;
+    /**
+     * Stamp fallback resolution onto the envelope the operate loop attached to
+     * the response and deliver it to the caller's onExchange. Fires once per
+     * operate() settlement; callback errors are logged and never thrown.
+     */
+    private settleExchange;
     stream(input: string | LlmHistory | LlmInputMessage | LlmOperateInput, options?: Omit<LlmOperateOptions, "model"> & {
         model?: LlmModelOption;
     }): AsyncIterable<LlmStreamChunk>;
@@ -931,4 +1023,4 @@ declare class XaiProvider implements LlmProvider {
 }
 
 export { BedrockProvider, ErrorCategory, FireworksProvider, GoogleProvider as GeminiProvider, GoogleProvider, JaypieToolkit, constants as LLM, Llm, LlmError, LlmMessageRole, LlmMessageType, LlmProgressEventType, LlmQuotaError, LlmRateLimitError, LlmStreamChunkType, LlmTransientError, LlmUnrecoverableError, OpenRouterProvider, Toolkit, XaiProvider, extractReasoning, isLlmOperateInput, isLlmOperateInputContent, isLlmOperateInputFile, isLlmOperateInputImage, jsonSchemaToNaturalSchema, naturalSchemaToJsonSchema, toolkit, tools };
-export type { LlmEffort, LlmErrorOptions, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };
+export type { LlmEffort, LlmErrorOptions, LlmExchangeCallback, LlmExchangeEnvelope, LlmExchangeRequest, LlmExchangeResolution, LlmExchangeResponse, LlmExchangeTiming, LlmFallbackConfig, LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentImage, LlmInputContentText, LlmInputMessage, LlmMessageOptions, LlmModelOption, LlmOperateInput, LlmOperateInputContent, LlmOperateInputFile, LlmOperateInputImage, LlmOperateOptions, LlmOperateResponse, LlmOptions, LlmProgressCallback, LlmProgressEvent, LlmProgressToolCall, LlmProvider, LlmStreamChunk, LlmStreamChunkDone, LlmStreamChunkError, LlmStreamChunkText, LlmStreamChunkToolCall, LlmStreamChunkToolResult, LlmTool };