@falai/agent 0.1.3 → 0.1.4

package/dist/cjs/providers/OpenRouterProvider.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * OpenRouter provider implementation
+ * OpenRouter provides access to multiple AI models through a unified OpenAI-compatible API
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenRouterProvider = void 0;
+const openai_1 = __importDefault(require("openai"));
+const retry_1 = require("../utils/retry");
+const DEFAULT_RETRY_CONFIG = {
+    timeout: 60000,
+    retries: 3,
+};
+/**
+ * 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);
+}
+/**
+ * Determines if an error should trigger backup model usage
+ */
+const shouldUseBackupModel = (error) => {
+    if (!isErrorWithStatus(error)) {
+        return false;
+    }
+    // Server errors
+    if (error.status === 500 || error.status === 503) {
+        return true;
+    }
+    // Rate limiting
+    if (error.status === 429) {
+        return true;
+    }
+    // Model not available or overloaded
+    if (error.code === "model_not_found" || error.code === "model_overloaded") {
+        return true;
+    }
+    const message = getErrorMessage(error);
+    if (message.includes("overloaded") ||
+        message.includes("unavailable") ||
+        message.includes("internal error") ||
+        message.includes("Internal error") ||
+        message.includes("capacity")) {
+        return true;
+    }
+    return false;
+};
+/**
+ * OpenRouter provider implementation
+ * Provides access to multiple AI models through OpenRouter's unified API
+ */
+class OpenRouterProvider {
+    constructor(options) {
+        this.name = "openrouter";
+        const { apiKey, model, backupModels = [], siteUrl, siteName, config, retryConfig, } = options;
+        if (!apiKey) {
+            throw new Error("OpenRouter API key is required");
+        }
+        if (!model) {
+            throw new Error("Model is required. See https://openrouter.ai/models");
+        }
+        // Initialize OpenAI client with OpenRouter base URL
+        this.client = new openai_1.default({
+            apiKey,
+            baseURL: "https://openrouter.ai/api/v1",
+            defaultHeaders: {
+                "HTTP-Referer": siteUrl || "",
+                "X-Title": siteName || "",
+            },
+        });
+        this.primaryModel = model;
+        this.backupModels = backupModels;
+        this.config = config;
+        this.retryConfig = {
+            timeout: retryConfig?.timeout || DEFAULT_RETRY_CONFIG.timeout,
+            retries: retryConfig?.retries || DEFAULT_RETRY_CONFIG.retries,
+        };
+    }
+    async generateMessage(input) {
+        return this.generateWithBackup(input);
+    }
+    async generateWithBackup(input) {
+        // Try primary model first
+        try {
+            return await this.generateWithModel(this.primaryModel, input);
+        }
+        catch (primaryError) {
+            const primaryErrMsg = getErrorMessage(primaryError);
+            console.warn(`[OPENROUTER] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`);
+            if (!shouldUseBackupModel(primaryError)) {
+                throw primaryError;
+            }
+            console.log(`[OPENROUTER] Trying backup models`);
+            let lastBackupError = primaryError;
+            for (let i = 0; i < this.backupModels.length; i++) {
+                const backupModel = this.backupModels[i];
+                console.log(`[OPENROUTER] Trying backup model ${i + 1}/${this.backupModels.length}: ${backupModel}`);
+                try {
+                    const result = await this.generateWithModel(backupModel, input);
+                    console.log(`[OPENROUTER] Backup model ${backupModel} succeeded`);
+                    return result;
+                }
+                catch (backupError) {
+                    const backupErrMsg = getErrorMessage(backupError);
+                    console.warn(`[OPENROUTER] Backup model ${backupModel} failed: ${backupErrMsg}`);
+                    lastBackupError = backupError;
+                    if (!shouldUseBackupModel(backupError) &&
+                        i < this.backupModels.length - 1) {
+                        console.log(`[OPENROUTER] Backup model error doesn't qualify for further attempts`);
+                        break;
+                    }
+                }
+            }
+            const lastBackupErrMsg = getErrorMessage(lastBackupError);
+            console.error(`[OPENROUTER] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`);
+            throw lastBackupError;
+        }
+    }
+    async generateWithModel(model, input) {
+        const operation = async () => {
+            const params = {
+                model,
+                messages: [
+                    {
+                        role: "user",
+                        content: input.prompt,
+                    },
+                ],
+                ...this.config,
+            };
+            // Override with input parameters if provided
+            if (input.parameters?.maxOutputTokens !== undefined) {
+                params.max_tokens = input.parameters.maxOutputTokens;
+            }
+            // Use structured output API if JSON mode is enabled
+            if (input.parameters?.jsonMode) {
+                // Define the JSON schema for agent response
+                const agentResponseSchema = {
+                    type: "object",
+                    properties: {
+                        message: {
+                            type: "string",
+                            description: "The actual message to send to the user",
+                        },
+                        route: {
+                            type: ["string", "null"],
+                            description: "The title of the route chosen (or null if no specific route)",
+                        },
+                        state: {
+                            type: ["string", "null"],
+                            description: "The current state within the route (or null if not in a route)",
+                        },
+                        toolCalls: {
+                            type: "array",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    toolName: {
+                                        type: "string",
+                                        description: "Name of the tool to call",
+                                    },
+                                    arguments: {
+                                        type: "object",
+                                        description: "Arguments to pass to the tool",
+                                    },
+                                },
+                                required: ["toolName", "arguments"],
+                            },
+                            description: "Tool calls the agent wants to execute",
+                        },
+                        reasoning: {
+                            type: "string",
+                            description: "Optional: Internal reasoning for this response",
+                        },
+                    },
+                    required: ["message"],
+                    additionalProperties: false,
+                };
+                const response = await this.client.responses.parse({
+                    model,
+                    instructions: input.prompt,
+                    input: "",
+                    reasoning: {
+                        effort: input.parameters?.reasoning?.effort || "low",
+                    },
+                    text: {
+                        format: {
+                            type: "json_schema",
+                            name: "agentResponseSchema",
+                            schema: agentResponseSchema,
+                        },
+                    },
+                });
+                if (!response.output_parsed) {
+                    throw new Error("No parsed output returned from OpenRouter");
+                }
+                const structured = response.output_parsed;
+                const message = structured.message;
+                return {
+                    message,
+                    metadata: {
+                        model: response.model,
+                        tokensUsed: response.usage?.total_tokens,
+                        promptTokens: response.usage?.input_tokens,
+                        completionTokens: response.usage?.output_tokens,
+                    },
+                    structured,
+                };
+            }
+            // Fall back to regular chat completions API if JSON mode not enabled
+            const response = await this.client.chat.completions.create(params);
+            const message = response.choices[0]?.message?.content;
+            if (!message) {
+                throw new Error("No response from OpenRouter");
+            }
+            return {
+                message,
+                metadata: {
+                    model: response.model,
+                    finishReason: response.choices[0]?.finish_reason,
+                    tokensUsed: response.usage?.total_tokens,
+                    promptTokens: response.usage?.prompt_tokens,
+                    completionTokens: response.usage?.completion_tokens,
+                },
+            };
+        };
+        return (0, retry_1.withTimeoutAndRetry)(operation, this.retryConfig.timeout, this.retryConfig.retries, `OpenRouter ${model}`);
+    }
+}
+exports.OpenRouterProvider = OpenRouterProvider;
+//# sourceMappingURL=OpenRouterProvider.js.map

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

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

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

@@ -0,0 +1,105 @@
+/**
+ * Agent-related type definitions
+ */
+import type { AiProvider } from "./ai";
+import type { ToolRef } from "./tool";
+import type { RouteOptions } from "./route";
+/**
+ * Composition mode determines how the agent processes and structures responses
+ */
+export declare enum CompositionMode {
+    /** Fluid, natural conversation without strict structure */
+    FLUID = "fluid",
+    /** Canned responses with fluid fallback */
+    CANNED_FLUID = "canned_fluid",
+    /** Composited canned responses */
+    CANNED_COMPOSITED = "composited_canned",
+    /** Strict canned responses only */
+    CANNED_STRICT = "strict_canned"
+}
+/**
+ * Forward declare observation types
+ */
+import type { ObservationOptions } from "./observation";
+/**
+ * Options for creating an Agent
+ */
+export interface AgentOptions<TContext = unknown> {
+    /** Display name of the agent */
+    name: string;
+    /** Detailed description of the agent's purpose and personality */
+    description?: string;
+    /** The agent's primary goal or objective */
+    goal?: string;
+    /** Default context data available to the agent */
+    context?: TContext;
+    /** AI provider strategy for generating responses */
+    ai: AiProvider;
+    /** Maximum number of processing iterations per request */
+    maxEngineIterations?: number;
+    /** Composition mode for response generation */
+    compositionMode?: CompositionMode;
+    /** Initial terms for domain glossary */
+    terms?: Term[];
+    /** Initial guidelines for agent behavior */
+    guidelines?: Guideline[];
+    /** Initial capabilities */
+    capabilities?: Capability[];
+    /** Initial routes (will be instantiated as Route objects) */
+    routes?: RouteOptions[];
+    /** Initial observations for disambiguation */
+    observations?: ObservationOptions[];
+}
+/**
+ * A term in the domain glossary
+ */
+export interface Term {
+    /** Name of the term */
+    name: string;
+    /** Description/definition of the term */
+    description: string;
+    /** Alternative names or synonyms */
+    synonyms?: string[];
+}
+/**
+ * A behavioral guideline for the agent
+ */
+export interface Guideline {
+    /** Unique identifier */
+    id?: string;
+    /** Condition that triggers this guideline (optional for always-active guidelines) */
+    condition?: string;
+    /** Action the agent should take when the condition is met */
+    action: string;
+    /** Whether this guideline is currently enabled */
+    enabled?: boolean;
+    /** Tags for organizing and filtering guidelines */
+    tags?: string[];
+    /** Tools available when following this guideline */
+    tools?: ToolRef<unknown, unknown[], unknown>[];
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A capability the agent can perform
+ */
+export interface Capability {
+    /** Unique identifier */
+    id?: string;
+    /** Title of the capability */
+    title: string;
+    /** Description of what the capability does */
+    description: string;
+    /** Tools used by this capability */
+    tools?: ToolRef<unknown, unknown[], unknown>[];
+}
+/**
+ * Guideline match with rationale
+ */
+export interface GuidelineMatch {
+    /** The matched guideline */
+    guideline: Guideline;
+    /** Explanation of why this guideline was matched */
+    rationale?: string;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/cjs/types/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/types/agent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;GAEG;AACH,oBAAY,eAAe;IACzB,2DAA2D;IAC3D,KAAK,UAAU;IACf,2CAA2C;IAC3C,YAAY,iBAAiB;IAC7B,kCAAkC;IAClC,iBAAiB,sBAAsB;IACvC,mCAAmC;IACnC,aAAa,kBAAkB;CAChC;AAED;;GAEG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,GAAG,OAAO;IAC9C,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,oDAAoD;IACpD,EAAE,EAAE,UAAU,CAAC;IACf,0DAA0D;IAC1D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,wCAAwC;IACxC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,4CAA4C;IAC5C,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;IAC5B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IACxB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,wBAAwB;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC;IAC/C,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,wBAAwB;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,KAAK,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,SAAS,EAAE,SAAS,CAAC;IACrB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/cjs/types/agent.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Agent-related type definitions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompositionMode = void 0;
+/**
+ * Composition mode determines how the agent processes and structures responses
+ */
+var CompositionMode;
+(function (CompositionMode) {
+    /** Fluid, natural conversation without strict structure */
+    CompositionMode["FLUID"] = "fluid";
+    /** Canned responses with fluid fallback */
+    CompositionMode["CANNED_FLUID"] = "canned_fluid";
+    /** Composited canned responses */
+    CompositionMode["CANNED_COMPOSITED"] = "composited_canned";
+    /** Strict canned responses only */
+    CompositionMode["CANNED_STRICT"] = "strict_canned";
+})(CompositionMode || (exports.CompositionMode = CompositionMode = {}));
+//# sourceMappingURL=agent.js.map

package/dist/cjs/types/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/types/agent.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAMH;;GAEG;AACH,IAAY,eASX;AATD,WAAY,eAAe;IACzB,2DAA2D;IAC3D,kCAAe,CAAA;IACf,2CAA2C;IAC3C,gDAA6B,CAAA;IAC7B,kCAAkC;IAClC,0DAAuC,CAAA;IACvC,mCAAmC;IACnC,kDAA+B,CAAA;AACjC,CAAC,EATW,eAAe,+BAAf,eAAe,QAS1B"}

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

@@ -0,0 +1,102 @@
+/**
+ * AI provider strategy types
+ */
+import type { Event } from "./history";
+/**
+ * Reasoning/thinking configuration for AI models
+ */
+export interface ReasoningConfig {
+    /**
+     * Effort level for reasoning models (OpenAI: gpt-5, o-series)
+     * - minimal: Fastest, least reasoning
+     * - low: Basic reasoning
+     * - medium: Balanced reasoning
+     * - high: Maximum reasoning effort
+     */
+    effort?: "minimal" | "low" | "medium" | "high";
+    /**
+     * Summary detail level of reasoning process
+     * - auto: Model decides
+     * - concise: Brief summary
+     * - detailed: Full reasoning details
+     */
+    summary?: "auto" | "concise" | "detailed";
+    /**
+     * Whether to include thinking/reasoning in response (Gemini)
+     */
+    includeThoughts?: boolean;
+}
+/**
+ * Input for AI message generation
+ */
+export interface GenerateMessageInput<TContext = unknown> {
+    /** The constructed prompt */
+    prompt: string;
+    /** Interaction history */
+    history: Event[];
+    /** Context data */
+    context: TContext;
+    /** Additional generation parameters */
+    parameters?: {
+        /** Maximum output tokens to generate */
+        maxOutputTokens?: number;
+        /** Reasoning/thinking configuration */
+        reasoning?: ReasoningConfig;
+        /** Enable structured JSON output mode */
+        jsonMode?: boolean;
+    };
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Structured response from AI containing message and metadata
+ */
+export interface AgentStructuredResponse {
+    /** The actual message to send to the user */
+    message: string;
+    /** Route chosen by the agent (route title or null if no route) */
+    route?: string | null;
+    /** Current state within the route (state description or null) */
+    state?: string | null;
+    /** Tool calls the agent wants to execute */
+    toolCalls?: Array<{
+        /** Name of the tool to call */
+        toolName: string;
+        /** Arguments to pass to the tool */
+        arguments: Record<string, unknown>;
+    }>;
+    /** Additional reasoning or internal thoughts (optional) */
+    reasoning?: string;
+}
+/**
+ * Output from AI message generation
+ */
+export interface GenerateMessageOutput {
+    /** The generated message */
+    message: string;
+    /** Optional metadata about generation */
+    metadata?: {
+        /** Model used */
+        model?: string;
+        /** Tokens consumed */
+        tokensUsed?: number;
+        /** Finish reason */
+        finishReason?: string;
+        /** Additional provider-specific data */
+        [key: string]: unknown;
+    };
+    /** Structured response data (when JSON mode is enabled) */
+    structured?: AgentStructuredResponse;
+}
+/**
+ * AI provider interface (strategy pattern)
+ */
+export interface AiProvider {
+    /** Provider name/identifier */
+    readonly name: string;
+    /**
+     * Generate a message based on prompt and context
+     */
+    generateMessage<TContext = unknown>(input: GenerateMessageInput<TContext>): Promise<GenerateMessageOutput>;
+}
+//# sourceMappingURL=ai.d.ts.map

package/dist/cjs/types/ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../../src/types/ai.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAEvC;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC/C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;IAC1C;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,QAAQ,GAAG,OAAO;IACtD,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,OAAO,EAAE,KAAK,EAAE,CAAC;IACjB,mBAAmB;IACnB,OAAO,EAAE,QAAQ,CAAC;IAClB,uCAAuC;IACvC,UAAU,CAAC,EAAE;QACX,wCAAwC;QACxC,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,uCAAuC;QACvC,SAAS,CAAC,EAAE,eAAe,CAAC;QAC5B,yCAAyC;QACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;IACF,oCAAoC;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,KAAK,CAAC;QAChB,+BAA+B;QAC/B,QAAQ,EAAE,MAAM,CAAC;QACjB,oCAAoC;QACpC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC,CAAC;IACH,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,QAAQ,CAAC,EAAE;QACT,iBAAiB;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,sBAAsB;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,oBAAoB;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,wCAAwC;QACxC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,2DAA2D;IAC3D,UAAU,CAAC,EAAE,uBAAuB,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,eAAe,CAAC,QAAQ,GAAG,OAAO,EAChC,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACpC,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACnC"}

package/dist/cjs/types/ai.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * AI provider strategy types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ai.js.map

package/dist/cjs/types/ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.js","sourceRoot":"","sources":["../../../src/types/ai.ts"],"names":[],"mappings":";AAAA;;GAEG"}

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

@@ -0,0 +1,112 @@
+/**
+ * Event history and interaction types
+ */
+/**
+ * Types of events in the interaction history
+ */
+export declare enum EventKind {
+    /** A text message event */
+    MESSAGE = "message",
+    /** A tool execution event */
+    TOOL = "tool",
+    /** A status update event */
+    STATUS = "status"
+}
+/**
+ * Source of an event
+ */
+export declare enum EventSource {
+    /** Event originated from the customer/user */
+    CUSTOMER = "customer",
+    /** Event from customer UI application */
+    CUSTOMER_UI = "customer_ui",
+    /** Event from human service agent */
+    HUMAN_AGENT = "human_agent",
+    /** Human agent acting on behalf of AI agent */
+    HUMAN_AGENT_ON_BEHALF_OF_AI_AGENT = "human_agent_on_behalf_of_ai_agent",
+    /** Event generated by AI agent */
+    AI_AGENT = "ai_agent",
+    /** System-generated event */
+    SYSTEM = "system"
+}
+/**
+ * Participant in a conversation
+ */
+export interface Participant {
+    /** Display name */
+    display_name: string;
+    /** Unique identifier */
+    id?: string;
+}
+/**
+ * Data for a message event
+ */
+export interface MessageEventData {
+    /** The participant who sent the message */
+    participant: Participant;
+    /** The message content */
+    message: string;
+    /** Whether the message was flagged/censored */
+    flagged?: boolean;
+    /** Tags/reasons if flagged */
+    tags?: string[];
+}
+/**
+ * Result of a tool execution
+ */
+export interface ToolResult<TData = unknown> {
+    /** The result data */
+    data: TData;
+    /** Optional metadata */
+    meta?: Record<string, unknown>;
+}
+/**
+ * A single tool call within a tool event
+ */
+export interface ToolCall<TArgs = unknown, TResult = unknown> {
+    /** Tool identifier */
+    tool_id: string;
+    /** Arguments passed to the tool */
+    arguments: TArgs;
+    /** Result returned by the tool */
+    result: ToolResult<TResult>;
+}
+/**
+ * Data for a tool event
+ */
+export interface ToolEventData {
+    /** Array of tool calls executed */
+    tool_calls: ToolCall[];
+}
+/**
+ * Data for a status event
+ */
+export interface StatusEventData {
+    /** Status message */
+    status: string;
+    /** Additional details */
+    details?: Record<string, unknown>;
+}
+/**
+ * Base event structure
+ */
+export interface Event<TData = MessageEventData | ToolEventData | StatusEventData> {
+    /** Type of event */
+    kind: EventKind;
+    /** Source of the event */
+    source: EventSource;
+    /** Event-specific data */
+    data: TData;
+    /** Timestamp (ISO string) */
+    timestamp?: string;
+    /** Unique event identifier */
+    id?: string;
+}
+/**
+ * An emitted event (staged for inclusion)
+ */
+export interface EmittedEvent<TData = MessageEventData | ToolEventData | StatusEventData> extends Event<TData> {
+    /** Whether this event has been committed */
+    committed?: boolean;
+}
+//# sourceMappingURL=history.d.ts.map

package/dist/cjs/types/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../../src/types/history.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,oBAAY,SAAS;IACnB,2BAA2B;IAC3B,OAAO,YAAY;IACnB,6BAA6B;IAC7B,IAAI,SAAS;IACb,4BAA4B;IAC5B,MAAM,WAAW;CAClB;AAED;;GAEG;AACH,oBAAY,WAAW;IACrB,8CAA8C;IAC9C,QAAQ,aAAa;IACrB,yCAAyC;IACzC,WAAW,gBAAgB;IAC3B,qCAAqC;IACrC,WAAW,gBAAgB;IAC3B,+CAA+C;IAC/C,iCAAiC,sCAAsC;IACvE,kCAAkC;IAClC,QAAQ,aAAa;IACrB,6BAA6B;IAC7B,MAAM,WAAW;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,mBAAmB;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,wBAAwB;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,WAAW,EAAE,WAAW,CAAC;IACzB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,KAAK,GAAG,OAAO;IACzC,sBAAsB;IACtB,IAAI,EAAE,KAAK,CAAC;IACZ,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ,CAAC,KAAK,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC1D,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,SAAS,EAAE,KAAK,CAAC;IACjB,kCAAkC;IAClC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,UAAU,EAAE,QAAQ,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,KAAK,CACpB,KAAK,GAAG,gBAAgB,GAAG,aAAa,GAAG,eAAe;IAE1D,oBAAoB;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,0BAA0B;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,0BAA0B;IAC1B,IAAI,EAAE,KAAK,CAAC;IACZ,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAC3B,KAAK,GAAG,gBAAgB,GAAG,aAAa,GAAG,eAAe,CAC1D,SAAQ,KAAK,CAAC,KAAK,CAAC;IACpB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB"}

package/dist/cjs/types/history.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Event history and interaction types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventSource = exports.EventKind = void 0;
+/**
+ * Types of events in the interaction history
+ */
+var EventKind;
+(function (EventKind) {
+    /** A text message event */
+    EventKind["MESSAGE"] = "message";
+    /** A tool execution event */
+    EventKind["TOOL"] = "tool";
+    /** A status update event */
+    EventKind["STATUS"] = "status";
+})(EventKind || (exports.EventKind = EventKind = {}));
+/**
+ * Source of an event
+ */
+var EventSource;
+(function (EventSource) {
+    /** Event originated from the customer/user */
+    EventSource["CUSTOMER"] = "customer";
+    /** Event from customer UI application */
+    EventSource["CUSTOMER_UI"] = "customer_ui";
+    /** Event from human service agent */
+    EventSource["HUMAN_AGENT"] = "human_agent";
+    /** Human agent acting on behalf of AI agent */
+    EventSource["HUMAN_AGENT_ON_BEHALF_OF_AI_AGENT"] = "human_agent_on_behalf_of_ai_agent";
+    /** Event generated by AI agent */
+    EventSource["AI_AGENT"] = "ai_agent";
+    /** System-generated event */
+    EventSource["SYSTEM"] = "system";
+})(EventSource || (exports.EventSource = EventSource = {}));
+//# sourceMappingURL=history.js.map