chat-agent-toolkit 1.2.1 → 1.2.3

package/dist/tools/open-connector-mastra.d.ts

@@ -0,0 +1,137 @@
+import { Agent } from '@mastra/core/agent';
+import { MCPClient } from '@mastra/mcp';
+/**
+ * Configuration for OpenConnector + Mastra integration
+ */
+export interface OpenConnectorMastraConfig {
+    /** OpenConnector admin token */
+    adminToken: string;
+    /** Base URL of the deployed OpenConnector Worker */
+    baseUrl: string;
+    /** User ID for scoping the session */
+    userId: string;
+    /** Apps to enable */
+    apps: string[];
+    /** Agent configuration */
+    agent: {
+        id: string;
+        name: string;
+        instructions: string;
+        model: any;
+        maxSteps?: number;
+    };
+    /** Whether to require approval before tool execution */
+    requireToolApproval?: boolean;
+}
+/**
+ * OpenConnector + Mastra session manager
+ * Handles MCP connection lifecycle and agent creation
+ */
+export declare class OpenConnectorMastraSession {
+    private config;
+    private mcpClient;
+    private agent;
+    constructor(config: OpenConnectorMastraConfig);
+    /**
+     * Get or create Mastra MCP client
+     * Connects to OpenConnector's MCP endpoint via HTTP
+     */
+    getMCPClient(): Promise<MCPClient>;
+    /**
+     * Get tools from OpenConnector MCP
+     * Use for static agent setup (same tools for all requests)
+     */
+    getTools(): Promise<Record<string, import('@mastra/core/tools').Tool<any, any, any, any, import('@mastra/core/tools').ToolExecutionContext<any, any, unknown>, string, unknown>>>;
+    /**
+     * Get toolsets from OpenConnector MCP
+     * Use for dynamic per-request tool configuration
+     */
+    getToolsets(): Promise<Record<string, Record<string, import('@mastra/core/tools').Tool<any, any, any, any, import('@mastra/core/tools').ToolExecutionContext<any, any, unknown>, string, unknown>>>>;
+    /**
+     * Create or get Mastra agent with OpenConnector tools
+     * Agent is cached and reused across generate() calls
+     */
+    getAgent(): Promise<Agent>;
+    /**
+     * Execute agent with a prompt
+     * Handles multi-step tool calling automatically
+     *
+     * @param prompt - User prompt
+     * @param options - Generation options
+     * @returns Agent response with text and tool calls
+     */
+    generate(prompt: string, options?: {
+        maxSteps?: number;
+        /** Extra context messages passed to the agent (model messages) */
+        context?: any[];
+    }): Promise<import('@mastra/core/stream').FullOutput<undefined>>;
+    /**
+     * Clean up MCP connection and agent
+     * Call when done with the session
+     */
+    cleanup(): Promise<void>;
+}
+/**
+ * Quick helper to create an OpenConnector + Mastra agent
+ * For one-off usage without session management
+ *
+ * @example
+ * ```ts
+ * const result = await createOpenConnectorMastraAgent({
+ *   adminToken: process.env.OPEN_CONNECTOR_ADMIN_TOKEN!,
+ *   baseUrl: 'https://open-connector.example.workers.dev',
+ *   userId: 'user-123',
+ *   apps: ['gmail', 'slack'],
+ *   agent: {
+ *     id: 'email-agent',
+ *     name: 'Email Assistant',
+ *     instructions: 'Help with email tasks',
+ *     model: openai('gpt-4o'),
+ *   },
+ * }).generate('Check my unread emails');
+ * ```
+ */
+export declare function createOpenConnectorMastraAgent(config: OpenConnectorMastraConfig): Promise<OpenConnectorMastraSession>;
+/**
+ * Create Mastra agent with dynamic per-request apps
+ * Better for multi-user scenarios where tools vary per request
+ *
+ * @example
+ * ```ts
+ * const agent = await createDynamicOpenConnectorAgent({
+ *   adminToken: process.env.OPEN_CONNECTOR_ADMIN_TOKEN!,
+ *   baseUrl: 'https://open-connector.example.workers.dev',
+ *   agent: {
+ *     id: 'dynamic-agent',
+ *     name: 'Dynamic Assistant',
+ *     instructions: 'Use available tools',
+ *     model: openai('gpt-4o'),
+ *   },
+ * });
+ *
+ * // Each request can have different userId/apps
+ * const result = await agent.generate({
+ *   userId: 'user-123',
+ *   apps: ['gmail'],
+ *   prompt: 'Check emails',
+ * });
+ * ```
+ */
+export declare function createDynamicOpenConnectorAgent(config: {
+    adminToken: string;
+    baseUrl: string;
+    agent: {
+        id: string;
+        name: string;
+        instructions: string;
+        model: any;
+        maxSteps?: number;
+    };
+}): Promise<{
+    generate(params: {
+        userId: string;
+        apps: string[];
+        prompt: string;
+        maxSteps?: number;
+    }): Promise<import('@mastra/core/stream').FullOutput<undefined>>;
+}>;

package/dist/tools/open-connector-mcp.d.ts

@@ -0,0 +1,88 @@
+import { MCPClient } from '@ai-sdk/mcp';
+import { ToolSet } from 'ai';
+/**
+ * Configuration for OpenConnector MCP session
+ */
+export interface OpenConnectorMCPConfig {
+    /** OpenConnector admin token (OPEN_CONNECTOR_ADMIN_TOKEN) */
+    adminToken: string;
+    /** Base URL of the deployed OpenConnector Worker */
+    baseUrl: string;
+    /** User ID to scope the session */
+    userId: string;
+    /** Apps to enable (e.g., ['gmail', 'notion', 'slack']) */
+    apps: string[];
+}
+/**
+ * OpenConnector MCP session wrapper
+ * Manages the lifecycle of MCP client connections to OpenConnector
+ */
+export declare class OpenConnectorMCPSession {
+    private config;
+    private client;
+    constructor(config: OpenConnectorMCPConfig);
+    /**
+     * Get or create the MCP client connection
+     * Uses HTTP SSE transport as provided by OpenConnector
+     */
+    getClient(): Promise<MCPClient>;
+    /**
+     * Get all available tools from OpenConnector MCP
+     * These tools can be passed directly to streamText/generateText
+     *
+     * @returns Tools object compatible with AI SDK
+     */
+    getTools(): Promise<ToolSet>;
+    /**
+     * Close the MCP connection
+     * Should be called after request completion or in finally block
+     */
+    close(): Promise<void>;
+    /**
+     * Health check for the OpenConnector Worker
+     */
+    healthCheck(): Promise<boolean>;
+}
+/**
+ * Helper function to create a one-shot OpenConnector MCP session
+ * For quick tool usage without managing session lifecycle
+ *
+ * @example
+ * ```ts
+ * const tools = await getOpenConnectorTools({
+ *   adminToken: process.env.OPEN_CONNECTOR_ADMIN_TOKEN!,
+ *   baseUrl: 'https://open-connector.example.workers.dev',
+ *   userId: 'user-123',
+ *   apps: ['gmail', 'slack'],
+ * });
+ *
+ * const result = await generateText({
+ *   model: openai('gpt-4o'),
+ *   prompt: 'Check my unread emails',
+ *   tools,
+ * });
+ * ```
+ */
+export declare function getOpenConnectorTools(config: OpenConnectorMCPConfig): Promise<ToolSet>;
+/**
+ * Create a reusable OpenConnector MCP session
+ * Better for multiple requests with the same apps
+ *
+ * @example
+ * ```ts
+ * const session = await createOpenConnectorSession({
+ *   adminToken: process.env.OPEN_CONNECTOR_ADMIN_TOKEN!,
+ *   baseUrl: 'https://open-connector.example.workers.dev',
+ *   userId: 'user-123',
+ *   apps: ['gmail', 'notion'],
+ * });
+ *
+ * try {
+ *   const tools = await session.getTools();
+ *   const result = await streamText({ model, messages, tools });
+ * } finally {
+ *   await session.close();
+ * }
+ * ```
+ */
+export declare function createOpenConnectorSession(config: OpenConnectorMCPConfig): Promise<OpenConnectorMCPSession>;

package/dist/tools/qwksearch-api-tools.d.ts

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+/**
+ * List of tools available for agent usage, including their schemas and implementation.
+ */
+export declare const AGENT_TOOLS: ({
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        query: z.ZodString;
+        category: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            general: "general";
+            it: "it";
+            files: "files";
+            news: "news";
+            videos: "videos";
+            images: "images";
+            science: "science";
+        }>>>;
+        recency: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            day: "day";
+            week: "week";
+            month: "month";
+            year: "year";
+        }>>>;
+        page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        language: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        public: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        baseURL: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    func: ({ query, category, recency, page, language, public: isPublic, timeout, baseURL, apiKey }: {
+        query: any;
+        category?: string;
+        recency?: string;
+        page?: number;
+        language?: string;
+        public?: boolean;
+        timeout?: number;
+        baseURL: any;
+        apiKey: any;
+    }) => Promise<string>;
+} | {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        url: z.ZodString;
+        images: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        links: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        formatting: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        absoluteURLs: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        baseURL: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    func: ({ url, images, links, formatting, absoluteURLs, timeout, baseURL, apiKey }: {
+        url: any;
+        images?: boolean;
+        links?: boolean;
+        formatting?: boolean;
+        absoluteURLs?: boolean;
+        timeout?: number;
+        baseURL: any;
+        apiKey: any;
+    }) => Promise<string>;
+} | {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        provider: z.ZodEnum<{
+            anthropic: "anthropic";
+            openai: "openai";
+            groq: "groq";
+            xai: "xai";
+            google: "google";
+            perplexity: "perplexity";
+            together: "together";
+            cloudflare: "cloudflare";
+        }>;
+        key: z.ZodOptional<z.ZodString>;
+        agent: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            question: "question";
+            "summarize-bullets": "summarize-bullets";
+            summarize: "summarize";
+            "suggest-followups": "suggest-followups";
+            "answer-cite-sources": "answer-cite-sources";
+            "query-resolution": "query-resolution";
+            "knowledge-graph-nodes": "knowledge-graph-nodes";
+            "summary-longtext": "summary-longtext";
+        }>>>;
+        model: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        temperature: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        html: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        query: z.ZodOptional<z.ZodString>;
+        chat_history: z.ZodOptional<z.ZodString>;
+        article: z.ZodOptional<z.ZodString>;
+        baseURL: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    func: ({ provider, key, agent, model, temperature, html, query, chat_history, article, baseURL, apiKey }: {
+        provider: any;
+        key: any;
+        agent?: string;
+        model?: string;
+        temperature?: number;
+        html?: boolean;
+        query: any;
+        chat_history: any;
+        article: any;
+        baseURL: any;
+        apiKey: any;
+    }) => Promise<string>;
+} | {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        url: z.ZodString;
+        blockImages: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        wait: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        waitUntil: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            load: "load";
+            domcontentloaded: "domcontentloaded";
+            networkidle0: "networkidle0";
+            networkidle2: "networkidle2";
+        }>>>;
+        bypassCaptcha: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        sessionId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        format: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            json: "json";
+            html: "html";
+        }>>>;
+        scraperUrl: z.ZodOptional<z.ZodString>;
+        scraperApiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    func: ({ url, blockImages, wait, timeout, waitUntil, bypassCaptcha, sessionId, format, scraperUrl, scraperApiKey }: {
+        url: any;
+        blockImages?: boolean;
+        wait?: number;
+        timeout?: number;
+        waitUntil?: string;
+        bypassCaptcha?: boolean;
+        sessionId?: string;
+        format?: string;
+        scraperUrl: any;
+        scraperApiKey: any;
+    }) => Promise<string>;
+})[];

package/dist/tools/search/doc-utils.d.ts

@@ -0,0 +1,11 @@
+import { Document } from './document';
+export interface R2CredentialsInput {
+    accountId: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    bucket: string;
+}
+export declare function buildFallbackDocs(query: string): Document[];
+export declare function normalizeSourcesOutput(output: unknown, query: string): Document[];
+export declare function rerankDocs(query: string, docs: Document[], fileIds: string[], optimizationMode: "speed" | "balanced" | "quality", r2Credentials?: R2CredentialsInput): Promise<Document[]>;
+export declare function processDocs(docs: Document[]): string;

package/dist/tools/search/document.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @module research/search/document
+ * @description Minimal document shape shared across the search pipeline.
+ * A document is a chunk of page content plus citation metadata (title, url, source, etc.).
+ */
+export interface Document<Metadata extends Record<string, any> = Record<string, any>> {
+    pageContent: string;
+    metadata: Metadata;
+}
+/**
+ * Splits text into overlapping chunks on whitespace boundaries.
+ * Default chunkSize 1000, chunkOverlap 200.
+ */
+export declare function splitTextIntoChunks(text: string, chunkSize?: number, chunkOverlap?: number): string[];

package/dist/tools/search/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module agent-toolkit/tools/search
+ * @description Meta search agent tools for AI-powered web search and research
+ */
+export { default as MetaSearchAgent } from './metaSearchAgent';
+export type { MetaSearchAgentType, Config, ChatTurnMessage, SearchingEvent, FewShotExample } from './meta-search-types';
+export { searchHandlers, createSearchHandlers } from './search-handlers';
+export { default as generateSuggestions } from './suggestionGeneratorAgent';
+export { groupAndSummarizeDocs } from './link-summarizer';
+export type { Document } from './document';
+export { splitTextIntoChunks } from './document';
+export { buildFallbackDocs, rerankDocs, processDocs, normalizeSourcesOutput } from './doc-utils';

package/dist/tools/search/link-summarizer.d.ts

@@ -0,0 +1,7 @@
+import { LanguageModel } from 'ai';
+import { Document } from './document';
+/**
+ * Groups fetched link documents by URL (max 10 chunks per URL), then
+ * summarizes each group with the LLM in parallel.
+ */
+export declare function groupAndSummarizeDocs(llm: LanguageModel, linkDocs: Document[], question: string): Promise<Document[]>;

package/dist/tools/search/meta-search-types.d.ts

@@ -0,0 +1,50 @@
+import { LanguageModel } from 'ai';
+import { default as EventEmitter } from 'events';
+/** A single conversation turn, matching the Vercel AI SDK message shape. */
+export interface ChatTurnMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+/** A `[role, content]` tuple used for few-shot prompt examples. */
+export type FewShotExample = [role: "user" | "assistant", content: string];
+export interface MetaSearchAgentType {
+    searchAndAnswer: (message: string, history: ChatTurnMessage[], llm: LanguageModel, optimizationMode: "speed" | "balanced" | "quality", fileIds: string[], systemInstructions: string, category?: string, sourceExtractionEnabled?: boolean, thinkingTimeLimit?: number) => Promise<EventEmitter>;
+}
+/** Emitted on the EventEmitter data channel to report live search progress. */
+export interface SearchingEvent {
+    query: string;
+    /** Display label shown in the UI (e.g. "Academic · max 10"). */
+    category?: string;
+    status: "running" | "done";
+}
+export interface Config {
+    searchWeb: boolean;
+    rerank: boolean;
+    rerankThreshold: number;
+    queryGeneratorPrompt: string;
+    queryGeneratorFewShots: FewShotExample[];
+    responsePrompt: string;
+    activeEngines: string[];
+    /** Optional: Function to fetch documents from URLs */
+    getDocumentsFromLinks?: (options: {
+        links: string[];
+    }) => Promise<any[]>;
+    /** Optional: Function to search via SearXNG */
+    searchSearxng?: (query: string, options: any) => Promise<{
+        results: any[];
+        suggestions: string[];
+    }>;
+    /** Optional: Function to search via Tavily */
+    searchTavily?: (query: string, options: any) => Promise<{
+        results: any[];
+        suggestions: string[];
+    }>;
+    /** Optional: Function to check if Tavily is configured */
+    isTavilyConfigured?: () => boolean;
+    /** Optional: Function to scrape a URL */
+    scrapeURL?: (url: string, options: any) => Promise<string>;
+}
+export type BasicChainInput = {
+    chat_history: ChatTurnMessage[];
+    query: string;
+};

package/dist/tools/search/metaSearchAgent.d.ts

@@ -0,0 +1,21 @@
+import { LanguageModel } from 'ai';
+import { default as EventEmitter } from 'events';
+import { Config, ChatTurnMessage, MetaSearchAgentType } from './meta-search-types';
+export type { MetaSearchAgentType, Config } from './meta-search-types';
+declare class MetaSearchAgent implements MetaSearchAgentType {
+    private config;
+    constructor(config: Config);
+    /**
+     * Rephrases the user's query into a standalone search question (and any
+     * URLs to summarize), runs the web search, and returns the documents to
+     * use as answer context.
+     */
+    private retrieveSearchDocs;
+    /**
+     * Runs the full search-and-answer pipeline, emitting "sources",
+     * "response", "searching", "end", and "error" events on the emitter.
+     */
+    private runPipeline;
+    searchAndAnswer(message: string, history: ChatTurnMessage[], llm: LanguageModel, optimizationMode: "speed" | "balanced" | "quality", fileIds: string[], systemInstructions: string, category?: string, sourceExtractionEnabled?: boolean, thinkingTimeLimit?: number): Promise<EventEmitter<[never]>>;
+}
+export default MetaSearchAgent;

package/dist/tools/search/search-handlers.d.ts

@@ -0,0 +1,27 @@
+import { default as MetaSearchAgent } from './metaSearchAgent';
+import { Config } from './meta-search-types';
+/**
+ * Creates search handler instances with provided search functions.
+ * Pass in search functions from extract-webpage to enable web search.
+ */
+export declare const createSearchHandlers: (searchFunctions?: Partial<Config>) => {
+    webSearch: MetaSearchAgent;
+    academicSearch: MetaSearchAgent;
+    writingAssistant: MetaSearchAgent;
+    wolframAlphaSearch: MetaSearchAgent;
+    youtubeSearch: MetaSearchAgent;
+    redditSearch: MetaSearchAgent;
+};
+/**
+ * Default search handlers without search functions.
+ * These will not perform actual web searches unless search functions are added to the Config.
+ * @deprecated Use createSearchHandlers() with search functions instead
+ */
+export declare const searchHandlers: {
+    webSearch: MetaSearchAgent;
+    academicSearch: MetaSearchAgent;
+    writingAssistant: MetaSearchAgent;
+    wolframAlphaSearch: MetaSearchAgent;
+    youtubeSearch: MetaSearchAgent;
+    redditSearch: MetaSearchAgent;
+};

package/dist/tools/search/suggestionGeneratorAgent.d.ts

@@ -0,0 +1,8 @@
+import { LanguageModel } from 'ai';
+import { ChatTurnMessage } from './meta-search-types';
+type SuggestionGeneratorInput = {
+    chat_history: ChatTurnMessage[];
+    maxQuestions?: number;
+};
+declare const generateSuggestions: (input: SuggestionGeneratorInput, llm: LanguageModel) => Promise<string[]>;
+export default generateSuggestions;

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+export * from './index.js'
+export {}

package/dist/utils/chat-helpers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Chat history formatting utilities
+ */
+type ChatHistoryMessage = {
+    content?: unknown;
+    role?: string;
+    type?: string;
+};
+export declare const formatChatHistoryAsString: (history: ChatHistoryMessage[]) => string;
+export {};

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './chat-helpers';
+export * from './outputParser';

package/dist/utils/markdown-to-html.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Convert markdown text to HTML with Highlight.js syntax highlighting.
+ * Unescapes HTML entities like `&` \u2192 `&`.
+ */
+export declare function convertMarkdownToHTMLEscaped(markdown: string): Promise<string>;

package/dist/utils/outputParser.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @module agent-toolkit/utils/outputParser
+ * @description Parsers that extract values from XML-tagged sections of LLM
+ * output (e.g. `<links>...</links>`, `<question>...</question>`).
+ */
+interface LineListOutputParserArgs {
+    key?: string;
+}
+export declare class LineListOutputParser {
+    private key;
+    constructor(args?: LineListOutputParserArgs);
+    parse(text: string): Promise<string[]>;
+}
+interface LineOutputParserArgs {
+    key?: string;
+}
+export declare class LineOutputParser {
+    private key;
+    constructor(args?: LineOutputParserArgs);
+    parse(text: string): Promise<string | undefined>;
+}
+export default LineOutputParser;