@falai/agent 2.6.1 → 3.0.0

package/src/utils/serialize.ts

@@ -2,6 +2,44 @@
  * Serialization utilities for tool results and other data
  */
 
+import type { Directive } from "../types/flow.js";
+import type { ToolResult } from "../types/tool.js";
+
+/**
+ * Decide whether a tool handler's return value is a ToolResult-shaped object.
+ * Only SEMANTIC markers identify one — bare `{data}` / `{error}` shapes are
+ * indistinguishable from ordinary business payloads (e.g. upstream API
+ * envelopes) and must be wrapped as raw results instead. Shared by the
+ * sequential (ToolManager) and concurrent (StreamingToolExecutor) paths so the
+ * definition of "is a ToolResult" can't drift between them.
+ */
+export function isToolResultLike(result: unknown): result is ToolResult {
+  return (
+    result !== null &&
+    typeof result === "object" &&
+    (("success" in result &&
+      typeof (result as Record<string, unknown>).success === "boolean") ||
+      "directive" in result ||
+      "directives" in result ||
+      "dataUpdate" in result ||
+      "contextUpdate" in result)
+  );
+}
+
+/**
+ * Collect a ToolResult's directives — `{directive}` (singular shorthand) and
+ * `{directives}` both count. Singular merges FIRST so plural entries win reply
+ * ties (last-wins merge), identical on both executor paths.
+ */
+export function extractResultDirectives<TContext = unknown, TData = unknown>(
+  result: ToolResult<unknown, TContext, TData>
+): Directive<TContext, TData>[] {
+  const directives: Directive<TContext, TData>[] = [];
+  if (result.directive) directives.push(result.directive);
+  if (Array.isArray(result.directives)) directives.push(...result.directives);
+  return directives;
+}
+
 /**
  * Serialize a tool execution result into a string suitable for conversation history.
  *

package/src/utils/session.ts

@@ -1,8 +1,9 @@
-import { cloneDeep } from "./clone";
-import type { SessionState } from "../types/session";
-import type { Directive } from "../types/flow";
-import type { CollectedStateData } from "../types/persistence";
-import { logger } from "./logger";
+import { cloneDeep } from "./clone.js";
+import type { SessionState } from "../types/session.js";
+import type { History } from "../types/history.js";
+import type { Directive } from "../types/flow.js";
+import type { CollectedStateData } from "../types/persistence.js";
+import { logger } from "./logger.js";
 
 /**
  * Helper to create a new session
@@ -68,8 +69,44 @@ export function createSession<TData = Record<string, unknown>>(
 }
 
 /**
- * Helper to create a new session ID
+ * Default conversation-history bound applied when the agent configures neither
+ * `maxHistoryMessages` nor compaction: generous enough to never bite a real
+ * thread, finite so a long-running chat()/stream() session can't grow until
+ * the provider context limit bricks it.
  */
+export const DEFAULT_MAX_HISTORY_MESSAGES = 400;
+
+/**
+ * Bound a conversation history to its most recent `max` entries. The left
+ * edge never opens on an orphaned role:'tool' message (whose assistant
+ * tool_calls parent was cut) — providers reject such histories. Returns the
+ * SAME array reference when no truncation is needed.
+ */
+export function boundConversationHistory(
+  history: History,
+  max: number
+): History {
+  if (!history || history.length <= max || max <= 0) return history;
+  let start = history.length - max;
+  while (start < history.length && (history[start] as { role?: string }).role === "tool") {
+    start++;
+  }
+  return history.slice(start);
+}
+
+/**
+ * Restore a session from a persisted blob (the named inverse of
+ * `createPersistedState`). Restores data + flowHistory verbatim — including a
+ * completed-flow blob, whose collected state MUST survive the round trip.
+ * Prefer this over the ambiguous `createSession(state)` overload.
+ */
+export function restoreSession<TData = Record<string, unknown>>(
+  state: Partial<SessionState<TData>>
+): SessionState<TData> {
+  return createSession<TData>(state);
+}
+
+/** Helper to create a new session ID */
 export function createSessionId(): string {
   return `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
 }
@@ -361,9 +398,9 @@ export function sessionDataToStep<TData = Record<string, unknown>>(
  * `appendPrompt`, `injectTools`, and `halt` are transient (one-turn lifetime)
  * and must not be serialized. This is a belt-and-suspenders safety net —
  * `Agent.dispatch` already strips before setting `pendingDirective`, and the
- * DirectiveBus's post-LLM drain strips from post-LLM emitters. This function
- * ensures the persistence layer never writes these fields regardless of the
- * upstream path.
+ * signal pipeline strips pre-LLM-only fields from post-phase directives. This
+ * function ensures the persistence layer never writes these fields regardless
+ * of the upstream path.
  */
 function stripPreDirectiveFields<TData>(
   directive: Directive<unknown, TData>

package/src/utils/template.ts

@@ -1,6 +1,6 @@
-import type { Template, TemplateContext } from "../types";
-import type { Event, MessageEventData } from "../types/history";
-import { MessageRole, EventKind } from "../types/history";
+import type { Template, TemplateContext } from "../types/index.js";
+import type { Event, MessageEventData } from "../types/history.js";
+import { MessageRole, EventKind } from "../types/history.js";
 
 /**
  * Renders a template, which can be a string or a function, using the provided context.

package/dist/cjs/core/DirectiveBus.d.ts

@@ -1,88 +0,0 @@
-/**
- * DirectiveBus — per-turn collection mechanism for directives emitted by
- * hooks, tools, and branches.
- *
- * Two phases per turn:
- * 1. Pre-LLM: collects from `prepare` hooks and `onEnter` hooks.
- * 2. Post-LLM: collects from `finalize`, tools via `executeToolCalls`,
- *    branches via `evaluateBranches`.
- *
- * Each entry is stamped with an emitter ID for debug logging. At phase
- * boundaries, the bus contents are merged using `flow.merge` and the
- * result is returned via `drain()`.
- *
- * Algorithm 4: position precedence `abort > complete > goTo/goToStep > reset`,
- * ties broken by emission order (last wins).
- *
- * **Validates: Requirements 1.3, 10.4, 10.5, 10.6**
- */
-import type { Directive } from "../types/flow";
-/** Phase of the turn pipeline the bus is currently collecting for. */
-export type DirectiveBusPhase = "pre-llm" | "post-llm";
-/** A single entry on the bus, stamped with its emitter for debug logging. */
-export interface DirectiveBusEntry<TContext = unknown, TData = unknown> {
-    directive: Directive<TContext, TData>;
-    emitterId: string;
-    phase: DirectiveBusPhase;
-    /** Monotonically increasing emission index within the phase. */
-    order: number;
-}
-/**
- * Per-turn directive collection bus.
- *
- * Usage:
- * ```ts
- * const bus = new DirectiveBus();
- * bus.setPhase('pre-llm');
- * bus.emit({ goTo: 'Booking' }, 'step.onEnter:ask_date');
- * bus.emit({ appendPrompt: ['Be concise.'] }, 'step.prepare:ask_date');
- * const merged = bus.drain(); // merges all collected directives
- * bus.setPhase('post-llm');
- * // ... collect post-LLM emissions ...
- * const postMerged = bus.drain();
- * ```
- */
-export declare class DirectiveBus<TContext = unknown, TData = unknown> {
-    private entries;
-    private currentPhase;
-    private orderCounter;
-    /** Set the current collection phase. Resets the order counter for the new phase. */
-    setPhase(phase: DirectiveBusPhase): void;
-    /** Get the current phase. */
-    getPhase(): DirectiveBusPhase;
-    /**
-     * Emit a directive onto the bus.
-     *
-     * @param directive - The directive to collect.
-     * @param emitterId - Human-readable identifier of the emitter (for debug logging).
-     */
-    emit(directive: Directive<TContext, TData>, emitterId: string): void;
-    /**
-     * Drain the bus: merge all collected directives for the current phase
-     * using Algorithm 4 (position precedence, last-wins tie-breaking,
-     * shallow-merge for state writes).
-     *
-     * Returns `undefined` if no directives were collected.
-     * After draining, the entries for the current phase are cleared.
-     */
-    drain(): Directive<TContext, TData> | undefined;
-    /**
-     * Drain ALL entries regardless of phase. Used for final turn cleanup.
-     * Returns `undefined` if no directives were collected.
-     */
-    drainAll(): Directive<TContext, TData> | undefined;
-    /** Clear all collected entries and reset the bus for a new turn. */
-    clear(): void;
-    /** Get the number of entries currently on the bus. */
-    get size(): number;
-    /** Get all entries (for inspection/testing). */
-    getEntries(): ReadonlyArray<DirectiveBusEntry<TContext, TData>>;
-    /** Check if the bus has any entries for the current phase. */
-    hasEntries(): boolean;
-    /**
-     * Log debug-level conflict warnings when multiple emitters set position
-     * fields or reply fields in the same phase.
-     */
-    private logConflicts;
-}
-//# sourceMappingURL=DirectiveBus.d.ts.map

package/dist/cjs/core/DirectiveBus.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"DirectiveBus.d.ts","sourceRoot":"","sources":["../../../src/core/DirectiveBus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAI/C,sEAAsE;AACtE,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,UAAU,CAAC;AAEvD,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB,CAAC,QAAQ,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO;IAClE,SAAS,EAAE,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,iBAAiB,CAAC;IACzB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,YAAY,CAAC,QAAQ,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO;IACzD,OAAO,CAAC,OAAO,CAA4C;IAC3D,OAAO,CAAC,YAAY,CAAgC;IACpD,OAAO,CAAC,YAAY,CAAK;IAEzB,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAMxC,6BAA6B;IAC7B,QAAQ,IAAI,iBAAiB;IAI7B;;;;;OAKG;IACH,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAyBpE;;;;;;;OAOG;IACH,KAAK,IAAI,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,SAAS;IA4D/C;;;OAGG;IACH,QAAQ,IAAI,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,SAAS;IAgBlD,oEAAoE;IACpE,KAAK,IAAI,IAAI;IAMb,sDAAsD;IACtD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,gDAAgD;IAChD,UAAU,IAAI,aAAa,CAAC,iBAAiB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAI/D,8DAA8D;IAC9D,UAAU,IAAI,OAAO;IAMrB;;;OAGG;IACH,OAAO,CAAC,YAAY;CAiCvB"}

package/dist/cjs/core/DirectiveBus.js

@@ -1,196 +0,0 @@
-"use strict";
-/**
- * DirectiveBus — per-turn collection mechanism for directives emitted by
- * hooks, tools, and branches.
- *
- * Two phases per turn:
- * 1. Pre-LLM: collects from `prepare` hooks and `onEnter` hooks.
- * 2. Post-LLM: collects from `finalize`, tools via `executeToolCalls`,
- *    branches via `evaluateBranches`.
- *
- * Each entry is stamped with an emitter ID for debug logging. At phase
- * boundaries, the bus contents are merged using `flow.merge` and the
- * result is returned via `drain()`.
- *
- * Algorithm 4: position precedence `abort > complete > goTo/goToStep > reset`,
- * ties broken by emission order (last wins).
- *
- * **Validates: Requirements 1.3, 10.4, 10.5, 10.6**
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DirectiveBus = void 0;
-const flow_namespace_1 = require("./flow-namespace");
-const utils_1 = require("../utils");
-/**
- * Per-turn directive collection bus.
- *
- * Usage:
- * ```ts
- * const bus = new DirectiveBus();
- * bus.setPhase('pre-llm');
- * bus.emit({ goTo: 'Booking' }, 'step.onEnter:ask_date');
- * bus.emit({ appendPrompt: ['Be concise.'] }, 'step.prepare:ask_date');
- * const merged = bus.drain(); // merges all collected directives
- * bus.setPhase('post-llm');
- * // ... collect post-LLM emissions ...
- * const postMerged = bus.drain();
- * ```
- */
-class DirectiveBus {
-    constructor() {
-        this.entries = [];
-        this.currentPhase = "pre-llm";
-        this.orderCounter = 0;
-    }
-    /** Set the current collection phase. Resets the order counter for the new phase. */
-    setPhase(phase) {
-        this.currentPhase = phase;
-        // Order counter is NOT reset — emission order is global within the turn
-        // so that cross-phase comparisons (if ever needed) remain consistent.
-    }
-    /** Get the current phase. */
-    getPhase() {
-        return this.currentPhase;
-    }
-    /**
-     * Emit a directive onto the bus.
-     *
-     * @param directive - The directive to collect.
-     * @param emitterId - Human-readable identifier of the emitter (for debug logging).
-     */
-    emit(directive, emitterId) {
-        if (!directive || typeof directive !== "object" || Array.isArray(directive)) {
-            return; // Silently ignore non-object values (void returns from hooks)
-        }
-        // Check if the directive has any meaningful fields set
-        const hasFields = Object.keys(directive).some((k) => directive[k] !== undefined);
-        if (!hasFields) {
-            return; // Empty directive — nothing to collect
-        }
-        this.entries.push({
-            directive,
-            emitterId,
-            phase: this.currentPhase,
-            order: this.orderCounter++,
-        });
-        utils_1.logger.debug(`[DirectiveBus] Collected directive from "${emitterId}" (phase=${this.currentPhase}, order=${this.orderCounter - 1})`);
-    }
-    /**
-     * Drain the bus: merge all collected directives for the current phase
-     * using Algorithm 4 (position precedence, last-wins tie-breaking,
-     * shallow-merge for state writes).
-     *
-     * Returns `undefined` if no directives were collected.
-     * After draining, the entries for the current phase are cleared.
-     */
-    drain() {
-        const phaseEntries = this.entries.filter((e) => e.phase === this.currentPhase);
-        if (phaseEntries.length === 0) {
-            return undefined;
-        }
-        // Log conflicts when multiple emitters set position or reply fields
-        this.logConflicts(phaseEntries);
-        // Merge all directives in emission order using flow.merge (pairwise reduction).
-        // flow.merge implements Algorithm 4: position precedence with last-wins tie-breaking.
-        let merged = phaseEntries[0].directive;
-        for (let i = 1; i < phaseEntries.length; i++) {
-            merged = flow_namespace_1.flow.merge(merged, phaseEntries[i].directive);
-        }
-        // Strip pre-LLM-only fields from post-LLM phase emissions
-        if (this.currentPhase === "post-llm") {
-            const asAny = merged;
-            const preLlmFields = ["appendPrompt", "injectTools", "halt"];
-            // Identify which fields are present BEFORE stripping (the merge may
-            // alias phaseEntries[0].directive when there is a single emitter, so
-            // we must collect emitter names first).
-            const droppedFields = [];
-            for (const f of preLlmFields) {
-                if (asAny[f] !== undefined) {
-                    droppedFields.push(f);
-                }
-            }
-            if (droppedFields.length > 0) {
-                // Identify emitters that contributed the dropped fields.
-                const emitters = phaseEntries
-                    .filter((e) => {
-                    const d = e.directive;
-                    return droppedFields.some((f) => d[f] !== undefined);
-                })
-                    .map((e) => e.emitterId);
-                // Now strip the fields from the merged result.
-                for (const f of droppedFields) {
-                    delete asAny[f];
-                }
-                utils_1.logger.debug(`[DirectiveBus] Dropped pre-LLM-only fields [${droppedFields.join(", ")}] from post-LLM emitters: ${emitters.join(", ")}`);
-            }
-        }
-        // Clear entries for the drained phase
-        this.entries = this.entries.filter((e) => e.phase !== this.currentPhase);
-        return merged;
-    }
-    /**
-     * Drain ALL entries regardless of phase. Used for final turn cleanup.
-     * Returns `undefined` if no directives were collected.
-     */
-    drainAll() {
-        if (this.entries.length === 0) {
-            return undefined;
-        }
-        this.logConflicts(this.entries);
-        let merged = this.entries[0].directive;
-        for (let i = 1; i < this.entries.length; i++) {
-            merged = flow_namespace_1.flow.merge(merged, this.entries[i].directive);
-        }
-        this.entries = [];
-        return merged;
-    }
-    /** Clear all collected entries and reset the bus for a new turn. */
-    clear() {
-        this.entries = [];
-        this.orderCounter = 0;
-        this.currentPhase = "pre-llm";
-    }
-    /** Get the number of entries currently on the bus. */
-    get size() {
-        return this.entries.length;
-    }
-    /** Get all entries (for inspection/testing). */
-    getEntries() {
-        return this.entries;
-    }
-    /** Check if the bus has any entries for the current phase. */
-    hasEntries() {
-        return this.entries.some((e) => e.phase === this.currentPhase);
-    }
-    // ─── Private helpers ─────────────────────────────────────────────────────
-    /**
-     * Log debug-level conflict warnings when multiple emitters set position
-     * fields or reply fields in the same phase.
-     */
-    logConflicts(entries) {
-        // Check for position field conflicts
-        const positionEmitters = [];
-        for (const entry of entries) {
-            const d = entry.directive;
-            for (const field of ["abort", "complete", "goTo", "goToStep", "reset"]) {
-                if (d[field] !== undefined) {
-                    positionEmitters.push({ emitterId: entry.emitterId, field });
-                }
-            }
-        }
-        if (positionEmitters.length > 1) {
-            const details = positionEmitters
-                .map((e) => `${e.emitterId}(${e.field})`)
-                .join(", ");
-            utils_1.logger.debug(`[DirectiveBus] Multiple position fields in one turn — conflict resolution applied. Emitters: ${details}`);
-        }
-        // Check for reply conflicts
-        const replyEmitters = entries.filter((e) => e.directive.reply !== undefined);
-        if (replyEmitters.length > 1) {
-            const emitterIds = replyEmitters.map((e) => e.emitterId).join(", ");
-            utils_1.logger.debug(`[DirectiveBus] Multiple reply fields in one turn — using last emission. Emitters: ${emitterIds}`);
-        }
-    }
-}
-exports.DirectiveBus = DirectiveBus;
-//# sourceMappingURL=DirectiveBus.js.map

package/dist/cjs/core/DirectiveBus.js.map

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

package/dist/cjs/providers/errorClassification.d.ts

@@ -1,61 +0,0 @@
-/**
- * Shared provider error utilities: classification of SDK/HTTP errors onto
- * normalized ProviderErrorCode values, backup-model eligibility, and
- * wrapping of terminal failures in ProviderError.
- *
- * The classification is derived once and reused for both backup-model
- * decisions and final error wrapping, so the two can never drift apart.
- */
-import { ProviderError, type ProviderErrorCode } from "../types/errors";
-/**
- * Shape of errors with status/code properties thrown by provider SDKs
- */
-export interface ErrorWithStatus {
-    status?: number;
-    code?: string;
-    message?: string;
-    type?: string;
-}
-/**
- * Type guard to check if error is ErrorWithStatus
- */
-export declare function isErrorWithStatus(error: unknown): error is ErrorWithStatus;
-/**
- * Safely extract error message
- */
-export declare function getErrorMessage(error: unknown): string;
-/**
- * Provider-specific signals treated as "overloaded/unavailable", in
- * addition to the shared defaults (HTTP 500/503 and the common message
- * substrings below).
- */
-export interface ErrorClassificationOptions {
-    /** Extra HTTP statuses treated as overloaded (e.g. Anthropic's 529) */
-    overloadedStatuses?: readonly number[];
-    /** Error `code` values treated as overloaded/unavailable (e.g. "model_not_found") */
-    overloadedCodes?: readonly string[];
-    /** Error `type` values treated as overloaded (e.g. Anthropic's "overloaded_error") */
-    overloadedTypes?: readonly string[];
-    /** Extra message substrings treated as overloaded (e.g. OpenRouter's "capacity") */
-    overloadedMessages?: readonly string[];
-}
-/**
- * Classify an unknown error into a normalized ProviderErrorCode.
- *
- * Overload/availability checks run first so that backup-model decisions
- * (rate_limited/overloaded) match the historical shouldUseBackupModel
- * predicate exactly.
- */
-export declare function classifyProviderError(error: unknown, options?: ErrorClassificationOptions): ProviderErrorCode;
-/**
- * Whether an error code qualifies for trying backup models.
- * Mirrors the historical shouldUseBackupModel predicate.
- */
-export declare function isBackupEligible(code: ProviderErrorCode): boolean;
-/**
- * Wrap a terminal failure (after retries/backup exhaustion) in a
- * normalized ProviderError, preserving the original error as `cause`.
- * Already-wrapped errors pass through untouched.
- */
-export declare function toProviderError(error: unknown, provider: string, options?: ErrorClassificationOptions): ProviderError;
-//# sourceMappingURL=errorClassification.d.ts.map

package/dist/cjs/providers/errorClassification.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errorClassification.d.ts","sourceRoot":"","sources":["../../../src/providers/errorClassification.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAM1E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQtD;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,qFAAqF;IACrF,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,sFAAsF;IACtF,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,oFAAoF;IACpF,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAaD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,0BAA+B,GACvC,iBAAiB,CA4DnB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,0BAA0B,GACnC,aAAa,CAUf"}

package/dist/cjs/providers/errorClassification.js

@@ -1,123 +0,0 @@
-"use strict";
-/**
- * Shared provider error utilities: classification of SDK/HTTP errors onto
- * normalized ProviderErrorCode values, backup-model eligibility, and
- * wrapping of terminal failures in ProviderError.
- *
- * The classification is derived once and reused for both backup-model
- * decisions and final error wrapping, so the two can never drift apart.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isErrorWithStatus = isErrorWithStatus;
-exports.getErrorMessage = getErrorMessage;
-exports.classifyProviderError = classifyProviderError;
-exports.isBackupEligible = isBackupEligible;
-exports.toProviderError = toProviderError;
-const errors_1 = require("../types/errors");
-/**
- * Type guard to check if error is ErrorWithStatus
- */
-function isErrorWithStatus(error) {
-    return (typeof error === "object" &&
-        error !== null &&
-        ("status" in error || "code" in error || "message" in error));
-}
-/**
- * Safely extract error message
- */
-function getErrorMessage(error) {
-    if (error instanceof Error) {
-        return error.message;
-    }
-    if (isErrorWithStatus(error) && error.message) {
-        return error.message;
-    }
-    return String(error);
-}
-/**
- * Message substrings every provider historically treated as
- * overloaded/unavailable for backup-model purposes.
- */
-const DEFAULT_OVERLOADED_MESSAGES = [
-    "overloaded",
-    "unavailable",
-    "internal error",
-    "Internal error",
-];
-/**
- * Classify an unknown error into a normalized ProviderErrorCode.
- *
- * Overload/availability checks run first so that backup-model decisions
- * (rate_limited/overloaded) match the historical shouldUseBackupModel
- * predicate exactly.
- */
-function classifyProviderError(error, options = {}) {
-    if (!isErrorWithStatus(error)) {
-        return "unknown";
-    }
-    const { status, code, type } = error;
-    const message = getErrorMessage(error);
-    // Server errors / overload
-    if (status === 500 || status === 503) {
-        return "overloaded";
-    }
-    // Rate limiting
-    if (status === 429) {
-        return "rate_limited";
-    }
-    // Provider-specific overload/unavailability signals
-    if (status !== undefined && options.overloadedStatuses?.includes(status)) {
-        return "overloaded";
-    }
-    if (code !== undefined && options.overloadedCodes?.includes(code)) {
-        return "overloaded";
-    }
-    if (type !== undefined && options.overloadedTypes?.includes(type)) {
-        return "overloaded";
-    }
-    const overloadedMessages = options.overloadedMessages
-        ? [...DEFAULT_OVERLOADED_MESSAGES, ...options.overloadedMessages]
-        : DEFAULT_OVERLOADED_MESSAGES;
-    if (overloadedMessages.some((pattern) => message.includes(pattern))) {
-        return "overloaded";
-    }
-    // Non-retriable classifications (never triggered backup models)
-    if (status === 401 || status === 403) {
-        return "auth";
-    }
-    if (status === 400 || status === 404 || status === 422) {
-        return "invalid_request";
-    }
-    if (status === 408 ||
-        message.includes("timed out") ||
-        message.includes("timeout")) {
-        return "timeout";
-    }
-    if (message.includes("fetch failed") ||
-        message.includes("ECONNREFUSED") ||
-        message.includes("ECONNRESET") ||
-        message.includes("ETIMEDOUT") ||
-        message.includes("network")) {
-        return "network";
-    }
-    return "unknown";
-}
-/**
- * Whether an error code qualifies for trying backup models.
- * Mirrors the historical shouldUseBackupModel predicate.
- */
-function isBackupEligible(code) {
-    return code === "rate_limited" || code === "overloaded";
-}
-/**
- * Wrap a terminal failure (after retries/backup exhaustion) in a
- * normalized ProviderError, preserving the original error as `cause`.
- * Already-wrapped errors pass through untouched.
- */
-function toProviderError(error, provider, options) {
-    if (error instanceof errors_1.ProviderError) {
-        return error;
-    }
-    return new errors_1.ProviderError(classifyProviderError(error, options), provider, getErrorMessage(error), error);
-}
-//# sourceMappingURL=errorClassification.js.map

package/dist/cjs/providers/errorClassification.js.map

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