@falai/agent 0.1.0-alpha2

package/dist/cjs/src/utils/retry.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTimeoutAndRetry = void 0;
+exports.retry = retry;
+/**
+ * Retry utility with exponential backoff
+ */
+const logger_1 = require("./logger");
+async function retry(options) {
+    const { operation, maxRetries, delay, onRetry, onFailure } = options;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === maxRetries) {
+                const shouldRethrow = onFailure ? onFailure(lastError) : true;
+                if (shouldRethrow) {
+                    throw lastError;
+                }
+                break;
+            }
+            if (onRetry) {
+                onRetry(attempt, lastError);
+            }
+            const delayMs = delay(attempt);
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/only-throw-error
+    throw lastError ?? new Error("Operation failed");
+}
+const withTimeoutAndRetry = async (operation, timeoutMs = 60000, maxRetries = 3, operationName = "AI operation") => {
+    const createTimeoutOperation = () => async () => {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => {
+            controller.abort();
+        }, timeoutMs);
+        try {
+            const result = await Promise.race([
+                operation(),
+                new Promise((_, reject) => {
+                    controller.signal.addEventListener("abort", () => {
+                        reject(new Error(`Operation timed out after ${timeoutMs}ms`));
+                    });
+                }),
+            ]);
+            clearTimeout(timeoutId);
+            return result;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            throw error;
+        }
+    };
+    return retry({
+        operation: createTimeoutOperation(),
+        maxRetries,
+        delay: (attempt) => Math.min(1000 * Math.pow(2, attempt), 5000),
+        onRetry: (attempt, error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            logger_1.logger.error(`[${operationName}] Failed attempt ${attempt + 1}:`, message);
+            const delay = Math.min(1000 * Math.pow(2, attempt), 5000);
+            logger_1.logger.debug(`[${operationName}] Retrying in ${delay}ms...`);
+            logger_1.logger.debug(`[${operationName}] Attempt ${attempt + 2}/${maxRetries + 1}`);
+        },
+        onFailure: (_error) => {
+            logger_1.logger.error(`[${operationName}] All ${maxRetries + 1} attempts failed`);
+            return true;
+        },
+    });
+};
+exports.withTimeoutAndRetry = withTimeoutAndRetry;
+//# sourceMappingURL=retry.js.map

package/dist/cjs/src/utils/retry.js.map

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

package/dist/cjs/src/utils/session.d.ts

@@ -0,0 +1,51 @@
+import type { SessionState } from "../types/session";
+import type { CollectedStateData } from "../types/persistence";
+/**
+ * Helper to create a new session
+ * @param sessionId - Optional session ID (e.g., from database)
+ * @param metadata - Optional metadata to attach
+ */
+export declare function createSession<TData = Record<string, unknown>>(sessionId?: string, metadata?: SessionState<TData>["metadata"]): SessionState<TData>;
+/**
+ * Helper to create a new session ID
+ */
+export declare function createSessionId(): string;
+/**
+ * Clones a session to prevent mutation
+ */
+export declare function cloneSession<TData>(session: SessionState<TData>): SessionState<TData>;
+/**
+ * Helper to update session with new route
+ * With agent-level data, routes share the same data structure
+ */
+export declare function enterRoute<TData = Record<string, unknown>>(session: SessionState<TData>, routeId: string, routeTitle: string): SessionState<TData>;
+/**
+ * Helper to update session with new step
+ */
+export declare function enterStep<TData = Record<string, unknown>>(session: SessionState<TData>, stepId: string, stepDescription?: string): SessionState<TData>;
+/**
+ * Helper to merge collected data into session
+ * Updates agent-level data structure
+ */
+export declare function mergeCollected<TData = Record<string, unknown>>(session: SessionState<TData>, data: Partial<unknown>): SessionState<TData>;
+/**
+ * Helper to convert SessionState to persistence-friendly format
+ * Used when saving to database
+ */
+export declare function sessionStepToData<TData = Record<string, unknown>>(session: SessionState<TData>): {
+    currentRoute?: string;
+    currentStep?: string;
+    collectedData: CollectedStateData<TData>;
+};
+/**
+ * Helper to convert database SessionData back to SessionState
+ * Used when loading from database
+ * @param sessionId - The database session ID
+ * @param data - The database session data
+ */
+export declare function sessionDataToStep<TData = Record<string, unknown>>(sessionId: string, data: {
+    currentRoute?: string;
+    currentStep?: string;
+    collectedData?: CollectedStateData<TData>;
+}): SessionState<TData>;
+//# sourceMappingURL=session.d.ts.map

package/dist/cjs/src/utils/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../../src/utils/session.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,SAAS,CAAC,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,GACzC,YAAY,CAAC,KAAK,CAAC,CAcrB;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AACD;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAChC,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,GAC3B,YAAY,CAAC,KAAK,CAAC,CAErB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxD,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,EAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,YAAY,CAAC,KAAK,CAAC,CAoCrB;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvD,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,EAC5B,MAAM,EAAE,MAAM,EACd,eAAe,CAAC,EAAE,MAAM,GACvB,YAAY,CAAC,KAAK,CAAC,CAarB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,EAC5B,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,GACrB,YAAY,CAAC,KAAK,CAAC,CAcrB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,GAC3B;IACD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;CAC1C,CAaA;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;IACJ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;CAC3C,GACA,YAAY,CAAC,KAAK,CAAC,CA+BrB"}

package/dist/cjs/src/utils/session.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSession = createSession;
+exports.createSessionId = createSessionId;
+exports.cloneSession = cloneSession;
+exports.enterRoute = enterRoute;
+exports.enterStep = enterStep;
+exports.mergeCollected = mergeCollected;
+exports.sessionStepToData = sessionStepToData;
+exports.sessionDataToStep = sessionDataToStep;
+const clone_1 = require("./clone");
+/**
+ * Helper to create a new session
+ * @param sessionId - Optional session ID (e.g., from database)
+ * @param metadata - Optional metadata to attach
+ */
+function createSession(sessionId, metadata) {
+    const id = sessionId || `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    return {
+        id,
+        data: {}, // Agent-level data structure
+        routeHistory: [],
+        metadata: {
+            ...metadata,
+            createdAt: new Date(),
+            lastUpdatedAt: new Date(),
+        },
+    };
+}
+/**
+ * Helper to create a new session ID
+ */
+function createSessionId() {
+    return `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+/**
+ * Clones a session to prevent mutation
+ */
+function cloneSession(session) {
+    return (0, clone_1.cloneDeep)(session);
+}
+/**
+ * Helper to update session with new route
+ * With agent-level data, routes share the same data structure
+ */
+function enterRoute(session, routeId, routeTitle) {
+    // Exit current route if exists
+    const routeHistory = [...(session.routeHistory || [])];
+    if (session.currentRoute) {
+        const lastRouteIndex = routeHistory.findIndex((r) => r.routeId === session.currentRoute?.id && !r.exitedAt);
+        if (lastRouteIndex >= 0) {
+            routeHistory[lastRouteIndex].exitedAt = new Date();
+        }
+    }
+    // Enter new route - data persists across routes at agent level
+    const now = new Date();
+    return {
+        ...session,
+        currentRoute: {
+            id: routeId,
+            title: routeTitle,
+            enteredAt: now,
+        },
+        currentStep: undefined,
+        // data remains the same - shared across all routes
+        routeHistory: [
+            ...routeHistory,
+            {
+                routeId,
+                enteredAt: now,
+                completed: false,
+            },
+        ],
+        metadata: {
+            ...session.metadata,
+            lastUpdatedAt: now,
+        },
+    };
+}
+/**
+ * Helper to update session with new step
+ */
+function enterStep(session, stepId, stepDescription) {
+    return {
+        ...session,
+        currentStep: {
+            id: stepId,
+            description: stepDescription,
+            enteredAt: new Date(),
+        },
+        metadata: {
+            ...session.metadata,
+            lastUpdatedAt: new Date(),
+        },
+    };
+}
+/**
+ * Helper to merge collected data into session
+ * Updates agent-level data structure
+ */
+function mergeCollected(session, data) {
+    const newCollected = {
+        ...session.data,
+        ...data,
+    };
+    return {
+        ...session,
+        data: newCollected, // Agent-level data update
+        metadata: {
+            ...session.metadata,
+            lastUpdatedAt: new Date(),
+        },
+    };
+}
+/**
+ * Helper to convert SessionState to persistence-friendly format
+ * Used when saving to database
+ */
+function sessionStepToData(session) {
+    return {
+        currentRoute: session.currentRoute?.id,
+        currentStep: session.currentStep?.id,
+        collectedData: {
+            data: session.data || {},
+            routeHistory: session.routeHistory,
+            history: session.history, // Include conversation history
+            currentRouteTitle: session.currentRoute?.title,
+            currentStepDescription: session.currentStep?.description,
+            metadata: session.metadata,
+        },
+    };
+}
+/**
+ * Helper to convert database SessionData back to SessionState
+ * Used when loading from database
+ * @param sessionId - The database session ID
+ * @param data - The database session data
+ */
+function sessionDataToStep(sessionId, data) {
+    const collectedData = data.collectedData || {
+        data: {},
+        routeHistory: [],
+        history: [],
+        metadata: {},
+        currentRouteTitle: undefined,
+        currentStepDescription: undefined,
+    };
+    return {
+        id: sessionId,
+        currentRoute: data.currentRoute
+            ? {
+                id: data.currentRoute,
+                title: collectedData.currentRouteTitle || data.currentRoute,
+                enteredAt: new Date(),
+            }
+            : undefined,
+        currentStep: data.currentStep
+            ? {
+                id: data.currentStep,
+                description: collectedData.currentStepDescription || undefined,
+                enteredAt: new Date(),
+            }
+            : undefined,
+        data: collectedData.data || {},
+        routeHistory: collectedData.routeHistory || [],
+        history: collectedData.history || [],
+        metadata: collectedData.metadata || {},
+    };
+}
+//# sourceMappingURL=session.js.map

package/dist/cjs/src/utils/session.js.map

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

package/dist/cjs/src/utils/template.d.ts

@@ -0,0 +1,155 @@
+import type { Template, TemplateContext } from "../types";
+import type { Event } from "../types/history";
+import { MessageRole } from "../types/history";
+/**
+ * Renders a template, which can be a string or a function, using the provided context.
+ * This function is asynchronous to support template functions that perform async operations.
+ *
+ * @param template - The template to render (string or function).
+ * @param params - The context object to pass to the template function.
+ * @returns A promise that resolves to the rendered string.
+ *
+ * @example
+ * ```typescript
+ * // With a string template
+ * const result1 = await render("Hello {{name}}", { context: { name: "Alice" } });
+ * // Result: "Hello Alice"
+ *
+ * // With a function template
+ * const fnTemplate = ({ context }) => `Hello ${context.name}`;
+ * const result2 = await render(fnTemplate, { context: { name: "Bob" } });
+ * // Result: "Hello Bob"
+ * ```
+ */
+export declare function render<TContext = unknown, TData = unknown>(template: Template<TContext, TData> | undefined, params: TemplateContext<TContext, TData>): Promise<string>;
+/**
+ * Renders an array of templates.
+ *
+ * @param templates - An array of templates to render.
+ * @param params - The context object.
+ * @returns A promise that resolves to an array of rendered strings.
+ */
+export declare function renderMany<TContext = unknown, TData = unknown>(templates: Template<TContext, TData>[] | undefined, params: TemplateContext<TContext, TData>): Promise<string[]>;
+/**
+ * @deprecated Use the asynchronous `render` function instead.
+ * Renders template variables in a string using the provided context.
+ * Supports {{variable}} and {{object.property}} syntax for property access.
+ *
+ * @param template - The template string containing {{variable}} placeholders
+ * @param context - The context object to pull values from
+ * @returns The rendered string with variables replaced
+ *
+ * @example
+ * ```typescript
+ * const template = "Hello {{user.name}}, welcome to {{company.name}}!";
+ * const context = {
+ *   user: { name: "Alice", age: 30 },
+ *   company: { name: "Acme Corp", location: "NYC" }
+ * };
+ * const result = renderTemplate(template, context);
+ * // Result: "Hello Alice, welcome to Acme Corp!"
+ *
+ * // Array handling
+ * const template2 = "Items: {{items}}";
+ * const context2 = { items: ["apple", "banana", "cherry"] };
+ * const result2 = renderTemplate(template2, context2);
+ * // Result: "Items: apple, banana, cherry"
+ * ```
+ */
+export declare function renderTemplate(template: string, context: Record<string, unknown> | undefined): string;
+/**
+ * @deprecated This function does not support async template functions.
+ * Renders template variables in an object recursively.
+ * Handles nested objects and arrays.
+ *
+ * @param obj - The object to render templates in
+ * @param context - The context object to pull values from
+ * @returns The object with all string templates rendered
+ */
+export declare function renderTemplateObject(obj: unknown, context: Record<string, unknown> | undefined): unknown;
+/**
+ * Creates helper functions for working with history and context in templates.
+ * These helpers make it easier to access message content and perform common operations.
+ *
+ * @param history - The event history array
+ * @returns Object containing helper functions
+ */
+export declare function createTemplateHelpers(history?: Event[]): {
+    /**
+     * Get the last message from history, optionally filtered by role.
+     * @param role - Optional role to filter by (user, assistant, etc.)
+     * @returns The message content or undefined if not found
+     */
+    getLastMessage(role?: MessageRole): string | undefined;
+    /**
+     * Get the last user message from history.
+     * @returns The user message content or undefined if not found
+     */
+    getLastUserMessage(): string | undefined;
+    /**
+     * Get the last assistant message from history.
+     * @returns The assistant message content or undefined if not found
+     */
+    getLastAssistantMessage(): string | undefined;
+    /**
+     * Get all messages from history, optionally filtered by role.
+     * @param role - Optional role to filter by
+     * @returns Array of message contents
+     */
+    getMessages(role?: MessageRole): string[];
+    /**
+     * Check if the last message contains any of the given keywords.
+     * @param keywords - Keywords to search for
+     * @param caseSensitive - Whether to perform case-sensitive search (default: false)
+     * @returns True if any keyword is found
+     */
+    lastMessageContains(keywords: string | string[], caseSensitive?: boolean): boolean;
+};
+/**
+ * Creates a complete TemplateContext with helpers included.
+ * This is a convenience function for creating template contexts with all the helper methods.
+ *
+ * @param params - The base template context parameters
+ * @returns Complete TemplateContext with helpers
+ */
+export declare function createTemplateContext<TContext = unknown, TData = unknown>(params: Omit<Partial<TemplateContext<TContext, TData>>, 'helpers'>): TemplateContext<TContext, TData>;
+/**
+ * Formats a JSON structure into readable markdown format.
+ * Handles nested objects, arrays, and primitive values.
+ *
+ * @param data - The JSON data to format
+ * @param title - Optional title for the knowledge base section
+ * @param maxDepth - Maximum nesting depth (default: 3)
+ * @returns Formatted markdown string
+ *
+ * @example
+ * ```typescript
+ * const knowledge = {
+ *   company: {
+ *     name: "Acme Corp",
+ *     products: ["Widget A", "Widget B"],
+ *     locations: {
+ *       headquarters: "NYC",
+ *       branches: ["LA", "Chicago"]
+ *     }
+ *   }
+ * };
+ *
+ * const markdown = formatKnowledgeBase(knowledge, "Company Information");
+ * // Output:
+ * // ## Company Information
+ * //
+ * // ### company
+ * // - **name**: Acme Corp
+ * // - **products**:
+ * //   - Widget A
+ * //   - Widget B
+ * // - **locations**:
+ * //   - **headquarters**: NYC
+ * //   - **branches**:
+ * //     - LA
+ * //     - Chicago
+ * ```
+ */
+export declare function formatKnowledgeBase(data: Record<string, unknown>, title?: string, maxDepth?: number): string;
+//# sourceMappingURL=template.d.ts.map

package/dist/cjs/src/utils/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../../../src/utils/template.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAoB,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAa,MAAM,kBAAkB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,MAAM,CAAC,QAAQ,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO,EAC9D,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,SAAS,EAC/C,MAAM,EAAE,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,GACvC,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,QAAQ,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO,EAClE,SAAS,EAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,GAAG,SAAS,EAClD,MAAM,EAAE,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,GACvC,OAAO,CAAC,MAAM,EAAE,CAAC,CAKnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,MAAM,CAeR;AAoED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,OAAO,CAsBT;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE;IAEnD;;;;OAIG;0BACmB,WAAW,GAAG,MAAM,GAAG,SAAS;IAiBtD;;;OAGG;0BACmB,MAAM,GAAG,SAAS;IAIxC;;;OAGG;+BACwB,MAAM,GAAG,SAAS;IAI7C;;;;OAIG;uBACgB,WAAW,GAAG,MAAM,EAAE;IAezC;;;;;OAKG;kCAC2B,MAAM,GAAG,MAAM,EAAE,kBAAiB,OAAO,GAAW,OAAO;EAe5F;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO,EACvE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,GACjE,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,CAMlC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,CAAC,EAAE,MAAM,EACd,QAAQ,GAAE,MAAU,GACnB,MAAM,CAgBR"}