kagent-ts 0.1.3 → 0.1.5

package/dist/llm/factory.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLLMProvider = createLLMProvider;
+const openai_provider_1 = require("./openai-provider");
+const anthropic_provider_1 = require("./anthropic-provider");
+// ─── Detection ───────────────────────────────────────────────────────────────
+/**
+ * Determine which provider to use.
+ *
+ * Detection rules:
+ * 1. If `explicitProvider` is `"openai"` or `"anthropic"`, use that.
+ * 2. If `"auto"` or `undefined`, inspect `baseURL`:
+ *    - Contains "anthropic" (case-insensitive) → Anthropic
+ *    - Otherwise → OpenAI (default / backward compatible)
+ */
+function detectProvider(explicitProvider, baseURL) {
+    if (explicitProvider === "openai")
+        return "openai";
+    if (explicitProvider === "anthropic")
+        return "anthropic";
+    // `"auto"` or `undefined`: detect from baseURL
+    if (baseURL && /anthropic/i.test(baseURL)) {
+        return "anthropic";
+    }
+    return "openai"; // default
+}
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create an LLM provider instance, auto-detecting the backend from `baseURL`.
+ *
+ * @example
+ * ```ts
+ * // Auto-detect: baseURL contains "anthropic" → AnthropicProvider
+ * const llm = createLLMProvider({
+ *   apiKey: process.env.ANTHROPIC_API_KEY!,
+ *   model: "claude-sonnet-4-6",
+ *   baseURL: "https://api.anthropic.com",
+ * });
+ *
+ * // Explicit provider selection
+ * const llm = createLLMProvider({
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   model: "gpt-4o",
+ *   provider: "openai",
+ * });
+ *
+ * // Backward-compatible: no baseURL → OpenAI
+ * const llm = createLLMProvider({
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   model: "gpt-4o",
+ * });
+ * ```
+ */
+function createLLMProvider(config) {
+    const provider = detectProvider(config.provider, config.baseURL);
+    if (provider === "anthropic") {
+        return new anthropic_provider_1.AnthropicProvider({
+            apiKey: config.apiKey,
+            model: config.model,
+            temperature: config.temperature,
+            maxTokens: config.maxTokens,
+            baseURL: config.baseURL,
+            retry: config.retry,
+            timeout: config.timeout,
+        });
+    }
+    return new openai_provider_1.OpenAIProvider({
+        apiKey: config.apiKey,
+        model: config.model,
+        temperature: config.temperature,
+        maxTokens: config.maxTokens,
+        baseURL: config.baseURL,
+        retry: config.retry,
+        timeout: config.timeout,
+    });
+}
+//# sourceMappingURL=factory.js.map

package/dist/llm/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/llm/factory.ts"],"names":[],"mappings":";;AA4GA,8CAwBC;AAnID,uDAAmD;AACnD,6DAAyD;AAoDzD,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,SAAS,cAAc,CACrB,gBAA0C,EAC1C,OAA2B;IAE3B,IAAI,gBAAgB,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IACnD,IAAI,gBAAgB,KAAK,WAAW;QAAE,OAAO,WAAW,CAAC;IAEzD,+CAA+C;IAC/C,IAAI,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1C,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,OAAO,QAAQ,CAAC,CAAC,UAAU;AAC7B,CAAC;AAED,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,iBAAiB,CAAC,MAAyB;IACzD,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAEjE,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC7B,OAAO,IAAI,sCAAiB,CAAC;YAC3B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,IAAI,gCAAc,CAAC;QACxB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC,CAAC;AACL,CAAC"}

package/dist/llm/fallback-provider.d.ts

@@ -0,0 +1,47 @@
+import { LLMProvider, LLMResponse, LLMStreamEvent } from "./interface";
+import { MessageData } from "../messages/types";
+import { Tool } from "../tools/types";
+import { Logger } from "../logging/logger";
+/**
+ * Configuration for the FallbackProvider.
+ */
+export interface FallbackProviderConfig {
+    /** Primary provider (tried first). */
+    primary: LLMProvider;
+    /** Fallback providers (tried in order if the primary fails with a network error). */
+    fallbacks: LLMProvider[];
+    /** Logger instance (defaults to ConsoleLogger). */
+    logger?: Logger;
+}
+/**
+ * LLMProvider that automatically falls back to a backup model when the
+ * primary fails with a network error.
+ *
+ * Flow:
+ * 1. Try `primary.chat()`.
+ * 2. If it succeeds → return the response.
+ * 3. If it throws `LLMNetworkError` → log warning, try `fallbacks[0].chat()`.
+ * 4. Repeat until a provider succeeds or all are exhausted.
+ * 5. Non-network errors (auth, bad request) propagate immediately.
+ *
+ * Usage:
+ * ```ts
+ * const provider = new FallbackProvider({
+ *   primary: new OpenAIProvider({ apiKey, model: "gpt-4o" }),
+ *   fallbacks: [
+ *     new AnthropicProvider({ apiKey, model: "claude-haiku-4-5-20251001" }),
+ *   ],
+ * });
+ * const agent = new ReActAgent({ llm: provider });
+ * ```
+ */
+export declare class FallbackProvider implements LLMProvider {
+    private providers;
+    private logger;
+    constructor(config: FallbackProviderConfig);
+    get model(): string;
+    chat(messages: MessageData[], tools?: Tool[], signal?: AbortSignal): Promise<LLMResponse>;
+    chatStream(messages: MessageData[], tools?: Tool[], signal?: AbortSignal): AsyncIterable<LLMStreamEvent>;
+    getTokenCount(text: string, model?: string): number;
+}
+//# sourceMappingURL=fallback-provider.d.ts.map

package/dist/llm/fallback-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback-provider.d.ts","sourceRoot":"","sources":["../../src/llm/fallback-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEvE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,MAAM,EAAiB,MAAM,mBAAmB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,sCAAsC;IACtC,OAAO,EAAE,WAAW,CAAC;IACrB,qFAAqF;IACrF,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,gBAAiB,YAAW,WAAW;IAClD,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,sBAAsB;IAS1C,IAAI,KAAK,IAAI,MAAM,CAElB;IAEK,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAiCxF,UAAU,CACf,QAAQ,EAAE,WAAW,EAAE,EACvB,KAAK,CAAC,EAAE,IAAI,EAAE,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,aAAa,CAAC,cAAc,CAAC;IAwBhC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;CAGpD"}

package/dist/llm/fallback-provider.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FallbackProvider = void 0;
+const errors_1 = require("./errors");
+const logger_1 = require("../logging/logger");
+/**
+ * LLMProvider that automatically falls back to a backup model when the
+ * primary fails with a network error.
+ *
+ * Flow:
+ * 1. Try `primary.chat()`.
+ * 2. If it succeeds → return the response.
+ * 3. If it throws `LLMNetworkError` → log warning, try `fallbacks[0].chat()`.
+ * 4. Repeat until a provider succeeds or all are exhausted.
+ * 5. Non-network errors (auth, bad request) propagate immediately.
+ *
+ * Usage:
+ * ```ts
+ * const provider = new FallbackProvider({
+ *   primary: new OpenAIProvider({ apiKey, model: "gpt-4o" }),
+ *   fallbacks: [
+ *     new AnthropicProvider({ apiKey, model: "claude-haiku-4-5-20251001" }),
+ *   ],
+ * });
+ * const agent = new ReActAgent({ llm: provider });
+ * ```
+ */
+class FallbackProvider {
+    providers;
+    logger;
+    constructor(config) {
+        this.providers = [config.primary, ...config.fallbacks];
+        this.logger = config.logger ?? new logger_1.ConsoleLogger();
+        if (this.providers.length === 0) {
+            throw new Error("FallbackProvider: at least one provider is required.");
+        }
+    }
+    get model() {
+        return this.providers[0].model;
+    }
+    async chat(messages, tools, signal) {
+        let lastError;
+        for (let i = 0; i < this.providers.length; i++) {
+            const provider = this.providers[i];
+            try {
+                const response = await provider.chat(messages, tools, signal);
+                if (i > 0) {
+                    this.logger.info("Fallback", `Recovered via fallback provider "${provider.model}" (attempt ${i + 1}/${this.providers.length}).`);
+                }
+                return response;
+            }
+            catch (err) {
+                // Non-network errors propagate immediately
+                if (!(err instanceof errors_1.LLMNetworkError))
+                    throw err;
+                lastError = err;
+                this.logger.warn("Fallback", `Provider "${provider.model}" failed: ${err.message}. ` +
+                    (i < this.providers.length - 1
+                        ? `Trying next provider...`
+                        : `All providers exhausted.`));
+            }
+        }
+        // All providers exhausted
+        throw lastError;
+    }
+    async *chatStream(messages, tools, signal) {
+        let lastError;
+        for (let i = 0; i < this.providers.length; i++) {
+            const provider = this.providers[i];
+            try {
+                const stream = provider.chatStream(messages, tools, signal);
+                if (i > 0) {
+                    this.logger.info("Fallback", `Stream recovered via fallback provider "${provider.model}".`);
+                }
+                yield* stream;
+                return;
+            }
+            catch (err) {
+                if (!(err instanceof errors_1.LLMNetworkError))
+                    throw err;
+                lastError = err;
+            }
+        }
+        throw lastError;
+    }
+    getTokenCount(text, model) {
+        return this.providers[0].getTokenCount(text, model);
+    }
+}
+exports.FallbackProvider = FallbackProvider;
+//# sourceMappingURL=fallback-provider.js.map

package/dist/llm/fallback-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback-provider.js","sourceRoot":"","sources":["../../src/llm/fallback-provider.ts"],"names":[],"mappings":"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"}

package/dist/llm/interface.d.ts

@@ -1,23 +1,64 @@
 import { Tool } from "../tools/types";
-import { MessageData } from "../messages/types";
+import { MessageData, ToolCall } from "../messages/types";
+export type { ToolCall };
+/**
+ * Standardised error / quality codes for LLM responses.
+ *
+ * Unlike `LLMNetworkError` (thrown when the API call itself fails),
+ * these codes describe issues with a successfully-received response
+ * that may affect agent behaviour — truncated content, missing output, etc.
+ */
+export declare enum LLMResponseErrorCode {
+    /** No issues detected. */
+    OK = "ok",
+    /**
+     * The response was truncated because `max_tokens` was reached.
+     * Tool call arguments or final answer may be incomplete.
+     */
+    MAX_TOKENS = "max_tokens",
+    /**
+     * The response content is empty (no text, no tool calls).
+     * Typically indicates a model-side issue or extreme truncation.
+     */
+    EMPTY = "empty",
+    /**
+     * The structured JSON in the response content could not be parsed.
+     * This is set by the agent after attempting to parse the LLM output.
+     */
+    INVALID_JSON = "invalid_json",
+    /**
+     * A non-specific quality issue — `stop_reason` is unusual or
+     * the response otherwise looks degraded.
+     */
+    UNKNOWN = "unknown"
+}
 /**
  * Response returned by an LLM provider after a chat call.
  */
 export interface LLMResponse {
     content: string;
-    tool_calls?: Array<{
-        id: string;
-        type: "function";
-        function: {
-            name: string;
-            arguments: string;
-        };
-    }>;
+    tool_calls?: ToolCall[];
     usage?: {
         prompt_tokens: number;
         completion_tokens: number;
         total_tokens: number;
     };
+    /**
+     * The reason the model stopped generating.
+     * Examples: "end_turn", "tool_use", "max_tokens", "stop", "length".
+     * Useful for detecting truncated output or tool-use signalling.
+     */
+    stop_reason?: string;
+    /**
+     * Response-level error / quality flag.
+     * Set by the LLM provider when the response shows signs of degradation
+     * (e.g., max_tokens truncation). Agents should check this before acting
+     * on tool calls or final answers.
+     */
+    responseError?: {
+        code: LLMResponseErrorCode;
+        message: string;
+    };
 }
 /**
  * A streaming chunk from the LLM, containing partial content or tool call data.
@@ -63,8 +104,9 @@ export interface LLMProvider {
      * Send a chat completion request (non-streaming).
      * @param messages  The conversation messages so far.
      * @param tools     Optional tool definitions for function calling.
+     * @param signal    Optional AbortSignal for cancellation.
      */
-    chat(messages: MessageData[], tools?: Tool[]): Promise<LLMResponse>;
+    chat(messages: MessageData[], tools?: Tool[], signal?: AbortSignal): Promise<LLMResponse>;
     /**
      * Send a chat completion request and yield events as they arrive.
      *
@@ -73,8 +115,9 @@ export interface LLMProvider {
      *
      * @param messages  The conversation messages so far.
      * @param tools     Optional tool definitions for function calling.
+     * @param signal    Optional AbortSignal for cancellation.
      */
-    chatStream(messages: MessageData[], tools?: Tool[]): AsyncIterable<LLMStreamEvent>;
+    chatStream(messages: MessageData[], tools?: Tool[], signal?: AbortSignal): AsyncIterable<LLMStreamEvent>;
     /**
      * Count tokens in a text string.
      * Uses tiktoken (by model name) when available, falling back to heuristic estimation.

package/dist/llm/interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/llm/interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,UAAU,CAAC;QACjB,QAAQ,EAAE;YACR,IAAI,EAAE,MAAM,CAAC;YACb,SAAS,EAAE,MAAM,CAAC;SACnB,CAAC;KACH,CAAC,CAAC;IACH,KAAK,CAAC,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,6EAA6E;QAC7E,KAAK,EAAE,MAAM,CAAC;QACd,kFAAkF;QAClF,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,QAAQ,CAAC,EAAE;YACT,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,SAAS,CAAC,EAAE,MAAM,CAAC;SACpB,CAAC;KACH,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,KAAK,CAAC,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,aAAa,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEpE;;;;;;;;OAQG;IACH,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;IAEnF;;;;;;OAMG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACrD"}
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/llm/interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE1D,YAAY,EAAE,QAAQ,EAAE,CAAC;AAIzB;;;;;;GAMG;AACH,oBAAY,oBAAoB;IAC9B,0BAA0B;IAC1B,EAAE,OAAO;IACT;;;OAGG;IACH,UAAU,eAAe;IACzB;;;OAGG;IACH,KAAK,UAAU;IACf;;;OAGG;IACH,YAAY,iBAAiB;IAC7B;;;OAGG;IACH,OAAO,YAAY;CACpB;AAID;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,aAAa,CAAC,EAAE;QACd,IAAI,EAAE,oBAAoB,CAAC;QAC3B,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,6EAA6E;QAC7E,KAAK,EAAE,MAAM,CAAC;QACd,kFAAkF;QAClF,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,QAAQ,CAAC,EAAE;YACT,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,SAAS,CAAC,EAAE,MAAM,CAAC;SACpB,CAAC;KACH,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,KAAK,CAAC,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,aAAa,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;;;;OAKG;IACH,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAE1F;;;;;;;;;OASG;IACH,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;IAEzG;;;;;;OAMG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACrD"}

package/dist/llm/interface.js

@@ -1,3 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMResponseErrorCode = void 0;
+// ─── LLM Response Error Codes ────────────────────────────────────────────────
+/**
+ * Standardised error / quality codes for LLM responses.
+ *
+ * Unlike `LLMNetworkError` (thrown when the API call itself fails),
+ * these codes describe issues with a successfully-received response
+ * that may affect agent behaviour — truncated content, missing output, etc.
+ */
+var LLMResponseErrorCode;
+(function (LLMResponseErrorCode) {
+    /** No issues detected. */
+    LLMResponseErrorCode["OK"] = "ok";
+    /**
+     * The response was truncated because `max_tokens` was reached.
+     * Tool call arguments or final answer may be incomplete.
+     */
+    LLMResponseErrorCode["MAX_TOKENS"] = "max_tokens";
+    /**
+     * The response content is empty (no text, no tool calls).
+     * Typically indicates a model-side issue or extreme truncation.
+     */
+    LLMResponseErrorCode["EMPTY"] = "empty";
+    /**
+     * The structured JSON in the response content could not be parsed.
+     * This is set by the agent after attempting to parse the LLM output.
+     */
+    LLMResponseErrorCode["INVALID_JSON"] = "invalid_json";
+    /**
+     * A non-specific quality issue — `stop_reason` is unusual or
+     * the response otherwise looks degraded.
+     */
+    LLMResponseErrorCode["UNKNOWN"] = "unknown";
+})(LLMResponseErrorCode || (exports.LLMResponseErrorCode = LLMResponseErrorCode = {}));
 //# sourceMappingURL=interface.js.map

package/dist/llm/interface.js.map

@@ -1 +1 @@
-{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../src/llm/interface.ts"],"names":[],"mappings":""}
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../src/llm/interface.ts"],"names":[],"mappings":";;;AAKA,gFAAgF;AAEhF;;;;;;GAMG;AACH,IAAY,oBAuBX;AAvBD,WAAY,oBAAoB;IAC9B,0BAA0B;IAC1B,iCAAS,CAAA;IACT;;;OAGG;IACH,iDAAyB,CAAA;IACzB;;;OAGG;IACH,uCAAe,CAAA;IACf;;;OAGG;IACH,qDAA6B,CAAA;IAC7B;;;OAGG;IACH,2CAAmB,CAAA;AACrB,CAAC,EAvBW,oBAAoB,oCAApB,oBAAoB,QAuB/B"}

package/dist/llm/model-router.d.ts

@@ -0,0 +1,126 @@
+import { LLMProvider, LLMResponse, LLMStreamEvent } from "./interface";
+import { MessageData } from "../messages/types";
+import { Tool } from "../tools/types";
+import { Logger } from "../logging/logger";
+/**
+ * Task categories for model routing.
+ *
+ * Each category maps to a model provider. When a category has no explicit
+ * provider configured, it falls back to `main`.
+ */
+export type ModelRoute = "main" | "subAgent" | "reflection" | "lightweight";
+/**
+ * Configuration for the ModelRouter.
+ */
+export interface ModelRouterConfig {
+    /** Primary model for the main reasoning loop (required). */
+    main: LLMProvider;
+    /**
+     * Model for sub-agents spawned by the main agent.
+     * Default: `main`.
+     */
+    subAgent?: LLMProvider;
+    /**
+     * Model for post-execution reflection / QA.
+     * Default: `main`.
+     * Using a different model here provides an independent review perspective.
+     */
+    reflection?: LLMProvider;
+    /**
+     * Model for lightweight tasks (memory operations, error listing, etc.).
+     * Default: `main`.
+     */
+    lightweight?: LLMProvider;
+    /**
+     * Shared fallback providers tried in order when the primary for
+     * any route fails with a network error.
+     *
+     * Each route wraps its primary + these fallbacks. Non-network errors
+     * (auth, bad request) propagate immediately.
+     *
+     * Default: none (network error = immediate failure).
+     */
+    fallbacks?: LLMProvider[];
+    /** Logger instance (defaults to ConsoleLogger). */
+    logger?: Logger;
+}
+/**
+ * ModelRouter — routes LLM calls to different providers based on task type.
+ *
+ * Implements `LLMProvider` so it drops in anywhere a plain provider is
+ * expected. The default route is `main` — call `.forSubAgent()`,
+ * `.forReflection()`, or `.forLightweight()` to get a task-specific
+ * provider handle.
+ *
+ * Each route automatically wraps its model in a fallback chain when
+ * `fallbacks` are configured.
+ *
+ * Usage:
+ * ```ts
+ * const router = new ModelRouter({
+ *   main: new OpenAIProvider({ model: "gpt-4o" }),
+ *   subAgent: new OpenAIProvider({ model: "gpt-4o-mini" }),
+ *   reflection: new AnthropicProvider({ model: "claude-haiku-4-5-20251001" }),
+ *   fallbacks: [new AnthropicProvider({ model: "claude-sonnet-4-6" })],
+ * });
+ *
+ * const agent = new ReActAgent({ llm: router, subAgentsDir: "./subagents" });
+ * // Main loop uses gpt-4o; sub-agents use gpt-4o-mini.
+ *
+ * // For reflection hook:
+ * const hook = createReflectionHook({
+ *   llm: router.forReflection(),
+ *   notebook: errorNotebook,
+ * });
+ * ```
+ */
+export declare class ModelRouter implements LLMProvider {
+    private config;
+    private logger;
+    constructor(config: ModelRouterConfig);
+    /** The main model identifier. */
+    get model(): string;
+    chat(messages: MessageData[], tools?: Tool[], signal?: AbortSignal): Promise<LLMResponse>;
+    chatStream(messages: MessageData[], tools?: Tool[], signal?: AbortSignal): AsyncIterable<LLMStreamEvent>;
+    getTokenCount(text: string, model?: string): number;
+    /**
+     * Get the LLM provider for sub-agents.
+     *
+     * Delegates to `subAgent` when configured, otherwise falls back to `main`.
+     * Wraps the provider with any shared fallback chain.
+     */
+    forSubAgent(): LLMProvider;
+    /**
+     * Get the LLM provider for post-execution reflection / QA.
+     *
+     * Delegates to `reflection` when configured, otherwise falls back to `main`.
+     * Wraps the provider with any shared fallback chain.
+     */
+    forReflection(): LLMProvider;
+    /**
+     * Get the LLM provider for lightweight tasks.
+     *
+     * Delegates to `lightweight` when configured, otherwise falls back to `main`.
+     * Wraps the provider with any shared fallback chain.
+     */
+    forLightweight(): LLMProvider;
+    /**
+     * Resolve a route to its effective provider.
+     *
+     * Priority: route-specific provider → main.
+     * If fallbacks are configured, the provider is wrapped in a fallback chain.
+     */
+    private route;
+    /**
+     * Resolve the primary provider for a route.
+     */
+    private resolveRoute;
+    /**
+     * Create a lightweight inline fallback wrapper around a primary provider.
+     *
+     * This avoids importing FallbackProvider to keep the dependency graph
+     * clean. The inline wrapper behaves identically.
+     */
+    private createFallbackWrapper;
+}
+//# sourceMappingURL=model-router.d.ts.map

package/dist/llm/model-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-router.d.ts","sourceRoot":"","sources":["../../src/llm/model-router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEvE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,MAAM,EAAiB,MAAM,mBAAmB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,UAAU,GAAG,YAAY,GAAG,aAAa,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,IAAI,EAAE,WAAW,CAAC;IAElB;;;OAGG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC;IAEvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,WAAW,CAAC;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC;IAE1B,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,WAAY,YAAW,WAAW;IAC7C,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,iBAAiB;IAUrC,iCAAiC;IACjC,IAAI,KAAK,IAAI,MAAM,CAElB;IAEK,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAIxF,UAAU,CACf,QAAQ,EAAE,WAAW,EAAE,EACvB,KAAK,CAAC,EAAE,IAAI,EAAE,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,aAAa,CAAC,cAAc,CAAC;IAIhC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;IAMnD;;;;;OAKG;IACH,WAAW,IAAI,WAAW;IAI1B;;;;;OAKG;IACH,aAAa,IAAI,WAAW;IAI5B;;;;;OAKG;IACH,cAAc,IAAI,WAAW;IAM7B;;;;;OAKG;IACH,OAAO,CAAC,KAAK;IAYb;;OAEG;IACH,OAAO,CAAC,YAAY;IAapB;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;CA2E9B"}