captify 0.1.17 → 0.1.19

package/dist/agents/services/agent-tools.js

@@ -1,233 +1,428 @@
+import { createChartTool } from "../../charts/services/chart-tool";
+import { DynamoDbInstances } from "../../shared/services/dynamodb";
+import { KendraInstances } from "../../shared/services/kendra";
+import { TABLE_INDEXES, TABLES } from "../../shared/shared.constants";
 import { tool } from "ai";
 import { z } from "zod";
 /**
- * Tool Registry
+ * Creates a DynamoDB tool with user context pre-injected
  *
- * Define all available tools here. Each tool needs:
- * - description: What the tool does
- * - inputSchema: Zod schema for inputs
- * - execute: Async function that implements the tool
- *
- * Agents can enable tools by referencing their names in the tools field.
- */
-/**
- * Calculator tool - performs basic arithmetic operations
+ * The tool provides schema-aware read access to application tables.
+ * User's tenantId and userId are automatically used from their session.
  */
-export const calculator = tool({
-    description: "Performs mathematical calculations. Supports addition, subtraction, multiplication, and division.",
-    inputSchema: z.object({
-        operation: z
-            .enum(["add", "subtract", "multiply", "divide"])
-            .describe("The mathematical operation to perform"),
-        a: z.number().describe("First number"),
-        b: z.number().describe("Second number"),
-    }),
-    execute: async ({ operation, a, b }) => {
-        switch (operation) {
-            case "add":
-                return { result: a + b };
-            case "subtract":
-                return { result: a - b };
-            case "multiply":
-                return { result: a * b };
-            case "divide":
-                if (b === 0) {
-                    throw new Error("Cannot divide by zero");
+export function createDynamoDbTool(context) {
+    return tool({
+        description: `Query application database tables. Your context: tenantId=${context.tenantId}, userId=${context.userId}. Available operations:
+- getMySessions: Get your chat sessions (optionally filter by status: active/archived)
+- getSessionMessages: Get messages in a chat session (requires sessionId)
+- getAgents: Get available AI agents
+- getAgent: Get a specific agent by ID (requires agentId)
+- getProviders: Get available LLM providers
+- getMyBookmarks: Get your bookmarks
+- getFeedbacks: Get feedback entries`,
+        inputSchema: z.object({
+            operation: z
+                .enum([
+                "getMySessions",
+                "getSessionMessages",
+                "getAgents",
+                "getAgent",
+                "getProviders",
+                "getMyBookmarks",
+                "getFeedbacks",
+            ])
+                .describe("The query operation to perform"),
+            sessionId: z.string().optional().describe("Chat session ID (for getSessionMessages)"),
+            agentId: z.string().optional().describe("Agent ID (for getAgent)"),
+            status: z
+                .enum(["active", "archived"])
+                .optional()
+                .describe("Filter sessions by status (default: active)"),
+            limit: z
+                .number()
+                .optional()
+                .describe("Maximum number of items to return (default: 50, max: 100)"),
+        }),
+        execute: async ({ operation, sessionId, agentId, status, limit }) => {
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
+            try {
+                const { tenantId, userId, userCredentials } = context;
+                const effectiveLimit = Math.min(limit !== null && limit !== void 0 ? limit : 50, 100);
+                switch (operation) {
+                    case "getMySessions": {
+                        const service = DynamoDbInstances.getInstance(TABLES.chatSessions);
+                        const gsiPk = `TENANT#${tenantId}#USER#${userId}`;
+                        // If status is specified, filter by archived status
+                        // GSI_SK format: {isArchived}#{updatedAt} where isArchived is 0 (active) or 1 (archived)
+                        const queryParams = status
+                            ? {
+                                IndexName: TABLE_INDEXES.chatSessions.ByUserStatus,
+                                KeyConditionExpression: "GSI_PK = :pk AND begins_with(GSI_SK, :prefix)",
+                                ExpressionAttributeValues: {
+                                    ":pk": gsiPk,
+                                    ":prefix": status === "archived" ? "1#" : "0#",
+                                },
+                                Limit: effectiveLimit,
+                                ScanIndexForward: false,
+                            }
+                            : {
+                                IndexName: TABLE_INDEXES.chatSessions.ByUserStatus,
+                                KeyConditionExpression: "GSI_PK = :pk",
+                                ExpressionAttributeValues: {
+                                    ":pk": gsiPk,
+                                },
+                                Limit: effectiveLimit,
+                                ScanIndexForward: false,
+                            };
+                        const result = await service.queryItems(queryParams, {
+                            userCredentials,
+                        });
+                        return {
+                            operation: "getMySessions",
+                            sessions: (_a = result.Items) !== null && _a !== void 0 ? _a : [],
+                            count: (_b = result.Count) !== null && _b !== void 0 ? _b : 0,
+                            hasMore: Boolean(result.LastEvaluatedKey),
+                        };
+                    }
+                    case "getSessionMessages": {
+                        if (!sessionId) {
+                            return {
+                                operation: "getSessionMessages",
+                                error: true,
+                                message: "sessionId is required for getSessionMessages",
+                                shouldRetry: false,
+                            };
+                        }
+                        // Verify session ownership before returning messages
+                        // Session key structure: PK = TENANT#{tenantId}#USER#{userId}, SK = CHAT#{sessionId}
+                        const sessionService = DynamoDbInstances.getInstance(TABLES.chatSessions);
+                        const sessionResult = await sessionService.getItem({
+                            PK: `TENANT#${tenantId}#USER#${userId}`,
+                            SK: `CHAT#${sessionId}`,
+                        }, { userCredentials });
+                        const session = sessionResult.Item;
+                        if (!session) {
+                            // Session not found means either it doesn't exist or user doesn't have access
+                            return {
+                                operation: "getSessionMessages",
+                                error: true,
+                                message: `Session ${sessionId} not found or access denied`,
+                                shouldRetry: false,
+                            };
+                        }
+                        const service = DynamoDbInstances.getInstance(TABLES.chatMessages);
+                        const pk = `CHAT#${sessionId}`;
+                        const result = await service.queryItems({
+                            KeyConditionExpression: "PK = :pk",
+                            ExpressionAttributeValues: { ":pk": pk },
+                            Limit: effectiveLimit,
+                            ScanIndexForward: false, // Newest first - most relevant for agent queries
+                        }, { userCredentials });
+                        // Reverse to return in chronological order (oldest to newest) for readability
+                        // Add human-readable dateTime to help agent interpret timestamps correctly
+                        const messages = ((_c = result.Items) !== null && _c !== void 0 ? _c : []).reverse().map((msg) => (Object.assign(Object.assign({}, msg), { 
+                            // timestamp is Unix milliseconds - convert to ISO string for clarity
+                            dateTime: msg.timestamp ? new Date(msg.timestamp).toISOString() : undefined })));
+                        return {
+                            operation: "getSessionMessages",
+                            messages,
+                            count: (_d = result.Count) !== null && _d !== void 0 ? _d : 0,
+                            hasMore: Boolean(result.LastEvaluatedKey),
+                        };
+                    }
+                    case "getAgents": {
+                        const service = DynamoDbInstances.getInstance(TABLES.agents);
+                        const pk = `TENANT#${tenantId}`;
+                        const result = await service.queryItems({
+                            KeyConditionExpression: "PK = :pk AND begins_with(SK, :prefix)",
+                            ExpressionAttributeValues: {
+                                ":pk": pk,
+                                ":prefix": "METADATA#AGENT#",
+                            },
+                            Limit: effectiveLimit,
+                        }, { userCredentials });
+                        return {
+                            operation: "getAgents",
+                            agents: (_e = result.Items) !== null && _e !== void 0 ? _e : [],
+                            count: (_f = result.Count) !== null && _f !== void 0 ? _f : 0,
+                            hasMore: Boolean(result.LastEvaluatedKey),
+                        };
+                    }
+                    case "getAgent": {
+                        if (!agentId) {
+                            return {
+                                operation: "getAgent",
+                                error: true,
+                                message: "agentId is required for getAgent",
+                                shouldRetry: false,
+                            };
+                        }
+                        const service = DynamoDbInstances.getInstance(TABLES.agents);
+                        const result = await service.getItem({
+                            PK: `TENANT#${tenantId}`,
+                            SK: `METADATA#AGENT#${agentId}`,
+                        }, { userCredentials });
+                        return {
+                            operation: "getAgent",
+                            agent: (_g = result.Item) !== null && _g !== void 0 ? _g : null,
+                            found: Boolean(result.Item),
+                        };
+                    }
+                    case "getProviders": {
+                        const service = DynamoDbInstances.getInstance(TABLES.providers);
+                        const pk = `TENANT#${tenantId}`;
+                        const result = await service.queryItems({
+                            KeyConditionExpression: "PK = :pk",
+                            ExpressionAttributeValues: { ":pk": pk },
+                            Limit: effectiveLimit,
+                        }, { userCredentials });
+                        return {
+                            operation: "getProviders",
+                            providers: (_h = result.Items) !== null && _h !== void 0 ? _h : [],
+                            count: (_j = result.Count) !== null && _j !== void 0 ? _j : 0,
+                            hasMore: Boolean(result.LastEvaluatedKey),
+                        };
+                    }
+                    case "getMyBookmarks": {
+                        const service = DynamoDbInstances.getInstance(TABLES.bookmarks);
+                        const pk = `TENANT#${tenantId}#USER#${userId}`;
+                        const result = await service.queryItems({
+                            KeyConditionExpression: "PK = :pk",
+                            ExpressionAttributeValues: { ":pk": pk },
+                            Limit: effectiveLimit,
+                        }, { userCredentials });
+                        return {
+                            operation: "getMyBookmarks",
+                            bookmarks: (_k = result.Items) !== null && _k !== void 0 ? _k : [],
+                            count: (_l = result.Count) !== null && _l !== void 0 ? _l : 0,
+                            hasMore: Boolean(result.LastEvaluatedKey),
+                        };
+                    }
+                    case "getFeedbacks": {
+                        const service = DynamoDbInstances.getInstance(TABLES.feedbacks);
+                        const pk = `TENANT#${tenantId}`;
+                        const result = await service.queryItems({
+                            KeyConditionExpression: "PK = :pk AND begins_with(SK, :prefix)",
+                            ExpressionAttributeValues: {
+                                ":pk": pk,
+                                ":prefix": "METADATA#FEEDBACK#",
+                            },
+                            Limit: effectiveLimit,
+                        }, { userCredentials });
+                        return {
+                            operation: "getFeedbacks",
+                            feedbacks: (_m = result.Items) !== null && _m !== void 0 ? _m : [],
+                            count: (_o = result.Count) !== null && _o !== void 0 ? _o : 0,
+                            hasMore: Boolean(result.LastEvaluatedKey),
+                        };
+                    }
+                    default:
+                        return {
+                            operation,
+                            error: true,
+                            message: `Unknown operation: ${operation}`,
+                            shouldRetry: false,
+                        };
                 }
-                return { result: a / b };
-            default:
-                throw new Error(`Unknown operation: ${operation}`);
-        }
-    },
-});
-/**
- * Get current time tool
- */
-export const getCurrentTime = tool({
-    description: "Gets the current date and time in ISO format, including timezone information.",
-    inputSchema: z.object({}),
-    execute: async () => {
-        const now = new Date();
-        return {
-            timestamp: now.toISOString(),
-            timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
-            unixTime: Math.floor(now.getTime() / 1000),
-        };
-    },
-});
-/**
- * String manipulation tool
- */
-export const stringManipulator = tool({
-    description: "Manipulates strings - convert to uppercase, lowercase, reverse, or get length.",
-    inputSchema: z.object({
-        text: z.string().describe("The text to manipulate"),
-        operation: z
-            .enum(["uppercase", "lowercase", "reverse", "length", "word_count"])
-            .describe("The operation to perform"),
-    }),
-    execute: async ({ text, operation }) => {
-        switch (operation) {
-            case "uppercase":
-                return { result: text.toUpperCase() };
-            case "lowercase":
-                return { result: text.toLowerCase() };
-            case "reverse":
-                return { result: text.split("").reverse().join("") };
-            case "length":
-                return { result: text.length };
-            case "word_count":
-                return { result: text.trim() === "" ? 0 : text.trim().split(/\s+/).length };
-            default:
-                throw new Error(`Unknown operation: ${operation}`);
-        }
-    },
-});
-/**
- * Random number generator tool
- */
-export const randomNumber = tool({
-    description: "Generates a random number within a specified range (inclusive).",
-    inputSchema: z.object({
-        min: z.number().describe("Minimum value (inclusive)"),
-        max: z.number().describe("Maximum value (inclusive)"),
-        count: z.number().optional().default(1).describe("How many random numbers to generate"),
-    }),
-    execute: async ({ min, max, count = 1 }) => {
-        if (min > max) {
-            throw new Error("Minimum value cannot be greater than maximum value");
-        }
-        if (count < 1 || count > 100) {
-            throw new Error("Count must be between 1 and 100");
-        }
-        const numbers = Array.from({ length: count }, () => Math.floor(Math.random() * (max - min + 1)) + min);
-        return {
-            numbers,
-            count: numbers.length,
-            min,
-            max,
-        };
-    },
-});
+            }
+            catch (error) {
+                // Return error information instead of throwing to allow agent to handle gracefully
+                const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+                const isAccessDenied = errorMessage.includes("Access denied") || errorMessage.includes("not authorized");
+                const isThrottling = errorMessage.includes("throttl") ||
+                    errorMessage.includes("ProvisionedThroughputExceeded");
+                return {
+                    operation,
+                    error: true,
+                    message: errorMessage,
+                    // Retry on throttling/transient errors, not on access or validation errors
+                    shouldRetry: isThrottling && !isAccessDenied,
+                    hint: isAccessDenied
+                        ? "You don't have permission to perform this operation."
+                        : isThrottling
+                            ? "The service is temporarily overloaded. Please try again in a moment."
+                            : "An unexpected error occurred. Please try a different query.",
+                };
+            }
+        },
+    });
+}
 /**
- * JSON validator tool
+ * Creates a Kendra tool with user context pre-injected
+ *
+ * The tool provides document search and retrieval capabilities using Amazon Kendra.
+ * User's credentials are automatically used for governance compliance.
  */
-export const jsonValidator = tool({
-    description: "Validates if a string is valid JSON and returns parsed result or error message.",
-    inputSchema: z.object({
-        jsonString: z.string().describe("The JSON string to validate"),
-    }),
-    execute: async ({ jsonString }) => {
-        try {
-            const parsed = JSON.parse(jsonString);
-            return {
-                valid: true,
-                parsed,
-                type: Array.isArray(parsed) ? "array" : typeof parsed,
-            };
-        }
-        catch (error) {
-            return {
-                valid: false,
-                error: error instanceof Error ? error.message : "Unknown error",
+export function createKendraTool(context) {
+    return tool({
+        description: `Search and retrieve documents from the knowledge base. Your context: tenantId=${context.tenantId}, userId=${context.userId}. Available operations:
+- search: Search for documents using natural language queries (returns document excerpts and metadata)
+- retrieve: Retrieve relevant passages from documents (optimized for RAG/context retrieval)
+
+IMPORTANT: Make only ONE call to this tool per user request, then summarize the results. Do not make multiple sequential calls.`,
+        inputSchema: z.object({
+            operation: z
+                .enum(["search", "retrieve"])
+                .describe("The operation to perform: 'search' for document search, 'retrieve' for passage extraction"),
+            query: z.string().min(1).max(1000).describe("The search query text (natural language)"),
+            indexId: z
+                .string()
+                .optional()
+                .describe("Kendra index ID to search (optional - uses default if not provided)"),
+            pageSize: z
+                .number()
+                .min(1)
+                .max(10)
+                .optional()
+                .describe("Maximum number of results to return (default: 5, max: 10)"),
+            filters: z
+                .object({
+                category: z.string().optional().describe("Filter by document category"),
+                source: z.string().optional().describe("Filter by document source"),
+                documentType: z
+                    .string()
+                    .optional()
+                    .describe("Filter by document type (e.g., 'pdf', 'html')"),
+            })
+                .optional()
+                .describe("Optional filters to narrow search results"),
+        }),
+        execute: async ({ operation, query, indexId, pageSize, filters }) => {
+            const { userCredentials } = context;
+            // Default: 5, max: 10 - keeps context manageable for the agent
+            const effectivePageSize = Math.min(pageSize !== null && pageSize !== void 0 ? pageSize : 5, 10);
+            // Build attribute filter if filters provided
+            const buildFilter = () => {
+                if (!filters)
+                    return undefined;
+                const filterConditions = [];
+                if (filters.category) {
+                    filterConditions.push({
+                        equalsTo: { key: "_category", value: filters.category },
+                    });
+                }
+                if (filters.source) {
+                    filterConditions.push({
+                        equalsTo: { key: "_source_uri", value: filters.source },
+                    });
+                }
+                if (filters.documentType) {
+                    filterConditions.push({
+                        equalsTo: { key: "_file_type", value: filters.documentType },
+                    });
+                }
+                if (filterConditions.length === 0)
+                    return undefined;
+                if (filterConditions.length === 1)
+                    return filterConditions[0];
+                return { andAllFilters: filterConditions };
             };
-        }
-    },
-});
+            const attributeFilter = buildFilter();
+            try {
+                // Use provided indexId or fall back to default from environment
+                const service = indexId
+                    ? KendraInstances.getInstance(indexId)
+                    : KendraInstances.getDefaultInstance();
+                switch (operation) {
+                    case "search": {
+                        const result = await service.query({
+                            queryText: query,
+                            pageSize: effectivePageSize,
+                            attributeFilter,
+                            userCredentials,
+                        });
+                        // Truncate excerpts to avoid overwhelming context
+                        const truncate = (text, maxLen = 300) => text && text.length > maxLen ? text.slice(0, maxLen) + "..." : text;
+                        return {
+                            operation: "search",
+                            queryId: result.queryId,
+                            documents: result.documents.map((doc) => ({
+                                id: doc.id,
+                                title: truncate(doc.title, 100),
+                                excerpt: truncate(doc.excerpt, 300),
+                                uri: doc.documentUri,
+                                confidence: doc.scoreConfidence,
+                            })),
+                            totalResults: result.totalNumberOfResults,
+                            count: result.documents.length,
+                        };
+                    }
+                    case "retrieve": {
+                        const result = await service.retrieve({
+                            queryText: query,
+                            pageSize: effectivePageSize,
+                            attributeFilter,
+                            userCredentials,
+                        });
+                        // Truncate content to avoid overwhelming context
+                        const truncate = (text, maxLen = 500) => text && text.length > maxLen ? text.slice(0, maxLen) + "..." : text;
+                        return {
+                            operation: "retrieve",
+                            queryId: result.queryId,
+                            passages: result.passages.map((passage) => ({
+                                documentId: passage.documentId,
+                                title: truncate(passage.documentTitle, 100),
+                                uri: passage.documentUri,
+                                content: truncate(passage.content, 500),
+                            })),
+                            count: result.passages.length,
+                        };
+                    }
+                    default:
+                        throw new Error(`Unknown operation: ${operation}`);
+                }
+            }
+            catch (error) {
+                // Return error information instead of throwing to allow agent to handle gracefully
+                const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+                const isAccessDenied = errorMessage.includes("Access denied") || errorMessage.includes("not authorized");
+                return {
+                    operation,
+                    error: true,
+                    message: errorMessage,
+                    // Clear instruction to agent to not retry on permission errors
+                    shouldRetry: !isAccessDenied,
+                    hint: isAccessDenied
+                        ? "This is a permission error. Do not retry - inform the user that they don't have access to the knowledge base."
+                        : "You may retry with different parameters if appropriate.",
+                    query,
+                };
+            }
+        },
+    });
+}
 /**
- * URL parser tool
+ * Tool definitions for listing available tools (name + description)
  */
-export const urlParser = tool({
-    description: "Parses a URL and extracts its components (protocol, hostname, path, query parameters, etc.).",
-    inputSchema: z.object({
-        url: z.string().describe("The URL to parse"),
-    }),
-    execute: async ({ url }) => {
-        try {
-            const parsed = new URL(url);
-            const params = {};
-            parsed.searchParams.forEach((value, key) => {
-                params[key] = value;
-            });
-            return {
-                valid: true,
-                protocol: parsed.protocol,
-                hostname: parsed.hostname,
-                port: parsed.port,
-                pathname: parsed.pathname,
-                search: parsed.search,
-                hash: parsed.hash,
-                queryParams: params,
-                origin: parsed.origin,
-            };
-        }
-        catch (error) {
-            return {
-                valid: false,
-                error: error instanceof Error ? error.message : "Invalid URL",
-            };
-        }
+export const TOOL_DEFINITIONS = {
+    dynamoDb: {
+        description: "Query application database tables including chat sessions, messages, agents, providers, bookmarks, and feedbacks.",
     },
-});
-/**
- * Array operations tool
- */
-export const arrayOperations = tool({
-    description: "Performs operations on arrays - sum, average, min, max, sort, unique values.",
-    inputSchema: z.object({
-        numbers: z.array(z.number()).describe("Array of numbers to operate on"),
-        operation: z
-            .enum(["sum", "average", "min", "max", "sort_asc", "sort_desc", "unique"])
-            .describe("The operation to perform"),
-    }),
-    execute: async ({ numbers, operation }) => {
-        if (numbers.length === 0) {
-            throw new Error("Array cannot be empty");
-        }
-        switch (operation) {
-            case "sum":
-                return { result: numbers.reduce((a, b) => a + b, 0) };
-            case "average":
-                return { result: numbers.reduce((a, b) => a + b, 0) / numbers.length };
-            case "min":
-                return { result: Math.min(...numbers) };
-            case "max":
-                return { result: Math.max(...numbers) };
-            case "sort_asc":
-                return { result: [...numbers].sort((a, b) => a - b) };
-            case "sort_desc":
-                return { result: [...numbers].sort((a, b) => b - a) };
-            case "unique":
-                return { result: Array.from(new Set(numbers)) };
-            default:
-                throw new Error(`Unknown operation: ${operation}`);
-        }
+    kendra: {
+        description: "Search and retrieve documents from the knowledge base using natural language queries.",
+    },
+    chart: {
+        description: "Create interactive data visualizations including line charts, bar charts, and pie charts from datasets.",
     },
-});
-/**
- * Tool Registry Map
- * Add new tools here to make them available to agents.
- * NOTE: Tool names must match TOOL_NAMES in constants.ts
- */
-export const TOOL_REGISTRY = {
-    calculator,
-    getCurrentTime,
-    stringManipulator,
-    randomNumber,
-    jsonValidator,
-    urlParser,
-    arrayOperations,
 };
 /**
- * Get tools by their names
+ * Get tools by their names with user context
+ *
  * @param toolNames - Array of tool names to retrieve
+ * @param context - User context for tools
  * @returns Object with selected tools
  */
-export function getToolsByNames(toolNames) {
+export function getToolsByNames(toolNames, context) {
     const tools = {};
     for (const name of toolNames) {
-        if (name in TOOL_REGISTRY) {
-            tools[name] = TOOL_REGISTRY[name];
+        if (name === "dynamoDb") {
+            tools[name] = createDynamoDbTool(context);
+        }
+        else if (name === "kendra") {
+            tools[name] = createKendraTool(context);
+        }
+        else if (name === "chart") {
+            tools[name] = createChartTool(context);
         }
     }
     return tools;