@chatbotkit/agent 1.28.0 → 1.29.1

package/dist/cjs/execute.cjs

@@ -0,0 +1,309 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.complete = complete;
+exports.execute = execute;
+const zod_1 = require("zod");
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+async function* complete(options) {
+    const { client, tools, abortSignal, ...request } = options;
+    const channelToTool = new Map();
+    const functions = tools
+        ? Object.entries(tools).map(([name, tool]) => {
+            const randomSuffix = Math.random().toString(36).substring(2, 15);
+            const channel = `${name}_${randomSuffix}`.padEnd(16, '0');
+            channelToTool.set(channel, { name, tool });
+            if (!tool.input) {
+                return {
+                    name,
+                    description: tool.description,
+                    parameters: ({
+                        type: 'object',
+                        properties: {},
+                    }),
+                    result: {
+                        channel,
+                    },
+                };
+            }
+            const schema = ((0, zod_to_json_schema_1.zodToJsonSchema)(tool.input, { target: 'openApi3' }));
+            const parameters = {
+                type: 'object',
+                properties: schema.properties || {},
+                ...(schema.required && schema.required.length > 0
+                    ? { required: schema.required }
+                    : {}),
+            };
+            return {
+                name,
+                description: tool.description,
+                parameters: (parameters),
+                result: {
+                    channel,
+                },
+            };
+        })
+        : undefined;
+    const stream = client.conversation
+        .complete(null, {
+        ...request,
+        functions,
+        limits: {
+            iterations: 1,
+        },
+    })
+        .stream({ abortSignal });
+    const toolEventQueue = [];
+    const runningToolPromises = [];
+    const executeToolAsync = async (channel, name, tool, args) => {
+        try {
+            let parsedArgs = args;
+            if (tool.input) {
+                const parseResult = tool.input.safeParse(args);
+                if (!parseResult.success) {
+                    const errorMsg = `Invalid arguments: ${parseResult.error.message}`;
+                    toolEventQueue.push({
+                        type: 'toolCallError',
+                        data: { name, error: errorMsg },
+                    });
+                    await client.channel.publish(String(channel), {
+                        message: { error: errorMsg },
+                    });
+                    return;
+                }
+                parsedArgs = parseResult.data;
+            }
+            const result = await tool.handler(parsedArgs);
+            toolEventQueue.push({
+                type: 'toolCallEnd',
+                data: { name, result },
+            });
+            await client.channel.publish(String(channel), {
+                message: { data: result },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            toolEventQueue.push({
+                type: 'toolCallError',
+                data: { name, error: errorMessage },
+            });
+            await client.channel.publish(String(channel), {
+                message: { error: errorMessage },
+            });
+        }
+    };
+    for await (const event of stream) {
+        if (abortSignal?.aborted) {
+            break;
+        }
+        while (toolEventQueue.length > 0) {
+            const toolEvent = toolEventQueue.shift();
+            if (toolEvent) {
+                yield toolEvent;
+            }
+        }
+        if (event.type === 'waitForChannelMessageBegin' &&
+            event.data &&
+            'channel' in event.data &&
+            'function' in event.data) {
+            const channel = (event.data.channel);
+            const args = (event.data.function).args;
+            const toolInfo = channelToTool.get(String(channel));
+            if (toolInfo) {
+                const { name, tool } = toolInfo;
+                yield {
+                    type: 'toolCallStart',
+                    data: {
+                        name,
+                        args,
+                    },
+                };
+                const toolPromise = executeToolAsync(channel, name, tool, args);
+                runningToolPromises.push(toolPromise);
+            }
+        }
+        yield event;
+    }
+    while (toolEventQueue.length > 0) {
+        const toolEvent = toolEventQueue.shift();
+        if (toolEvent) {
+            yield toolEvent;
+        }
+    }
+    if (runningToolPromises.length > 0) {
+        await Promise.allSettled(runningToolPromises);
+        while (toolEventQueue.length > 0) {
+            const toolEvent = toolEventQueue.shift();
+            if (toolEvent) {
+                yield toolEvent;
+            }
+        }
+    }
+}
+async function* execute(options) {
+    const { client, tools = {}, maxIterations = 100, abortSignal, ...request } = options;
+    const messages = request.messages || [];
+    let exitResult = null;
+    let internalAbort = null;
+    const systemTools = {
+        plan: {
+            description: 'Create or update a plan for approaching the task. Break down the task into clear, actionable steps. Use this at the start and whenever you need to revise your approach.',
+            input: zod_1.z.object({
+                steps: zod_1.z
+                    .array(zod_1.z.string())
+                    .describe('Array of step descriptions in order of execution'),
+                rationale: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Brief explanation of the plan approach'),
+            }),
+            handler: async (input) => {
+                return {
+                    success: true,
+                    message: `Plan created with ${input.steps.length} steps${input.rationale ? ': ' + input.rationale : ''}`,
+                };
+            },
+        },
+        progress: {
+            description: 'Update progress on the current task. Use this to track completed steps, report current status, and identify blockers.',
+            input: zod_1.z.object({
+                completed: zod_1.z
+                    .array(zod_1.z.string())
+                    .optional()
+                    .describe('Steps that have been completed'),
+                current: zod_1.z.string().optional().describe('Current step being worked on'),
+                blockers: zod_1.z
+                    .array(zod_1.z.string())
+                    .optional()
+                    .describe('Any issues preventing progress'),
+                nextSteps: zod_1.z
+                    .array(zod_1.z.string())
+                    .optional()
+                    .describe('Next actions to take'),
+            }),
+            handler: async (input) => {
+                return {
+                    success: true,
+                    message: 'Progress updated',
+                    ...input,
+                };
+            },
+        },
+        exit: {
+            description: 'Exit the task execution with a status code and optional message. Status code 0 indicates success, non-zero indicates failure. Use this when all the tasks are complete or cannot proceed.',
+            input: zod_1.z.object({
+                code: zod_1.z
+                    .number()
+                    .int()
+                    .min(0)
+                    .max(255)
+                    .describe('Exit status code (0 = success, non-zero = failure)'),
+                message: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Optional message explaining the exit reason'),
+            }),
+            handler: async (input) => {
+                exitResult = { code: input.code, message: input.message };
+                return {
+                    success: true,
+                    message: `Task exiting with code ${input.code}${input.message ? ': ' + input.message : ''}`,
+                };
+            },
+        },
+        abort: {
+            description: 'Immediately abort the current task. Use this when the user explicitly asks you to stop, cancel, or abort what you are doing. Set hard to true to kill running processes immediately.',
+            input: zod_1.z.object({
+                reason: zod_1.z.string().optional().describe('Brief reason for aborting'),
+                hard: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe('If true, immediately kill running processes. If false (default), finish the current operation gracefully.'),
+            }),
+            handler: async (input) => {
+                const reason = input.reason || 'aborted by user request';
+                exitResult = { code: 1, message: reason };
+                if (input.hard && internalAbort) {
+                    internalAbort.abort(reason);
+                }
+                return {
+                    success: true,
+                    message: `Task aborted: ${reason}`,
+                };
+            },
+        },
+    };
+    const allTools = { ...tools, ...systemTools };
+    const systemInstruction = `
+${options.extensions?.backstory || ''}
+
+# Task Execution Guidelines
+
+The goal is to complete the assigned task efficiently and effectively. Follow these guidelines:
+
+1. **Plan First**: Use the 'plan' function to create a clear strategy before starting work
+2. **Track Progress**: Regularly use the 'progress' function to update status and identify issues
+3. **Use Tools**: Leverage available tools to accomplish each step of your plan
+4. **Exit When Done**: Call the 'exit' function with code 0 when successful, or non-zero code if unable to complete
+5. **Abort**: If the user asks you to stop, cancel, or abort, call the 'abort' function immediately. Use hard=true if processes are running that need to be killed right away.
+6. **Be Autonomous**: Work through the task systematically without waiting for additional input
+7. **Be Responsive**: If the user sends a new message while you are working, acknowledge it briefly and adjust your approach if needed. Always prioritize user input over your current plan.
+`.trim();
+    let iteration = 0;
+    while (iteration < maxIterations && exitResult === null) {
+        if (abortSignal?.aborted) {
+            exitResult = {
+                code: 1,
+                message: 'Task execution aborted',
+            };
+            break;
+        }
+        iteration++;
+        yield { type: 'iteration', data: { iteration } };
+        let lastEndReason = null;
+        internalAbort = new AbortController();
+        if (abortSignal?.aborted) {
+            internalAbort.abort(abortSignal.reason);
+        }
+        else if (abortSignal) {
+            const capturedAbort = internalAbort;
+            abortSignal.addEventListener('abort', () => capturedAbort.abort(abortSignal.reason), { once: true });
+        }
+        const iterSignal = internalAbort.signal;
+        for await (const event of complete({
+            ...request,
+            client,
+            messages,
+            tools: allTools,
+            abortSignal: iterSignal,
+            extensions: {
+                ...options.extensions,
+                backstory: systemInstruction,
+            },
+        })) {
+            if (event.type === 'message') {
+                messages.push(event.data);
+            }
+            if (event.type === 'result') {
+                if (event.data.end.reason) {
+                    lastEndReason = event.data.end.reason;
+                }
+            }
+            yield event;
+        }
+        if (exitResult) {
+            break;
+        }
+        if (lastEndReason === 'stop') {
+            exitResult = { code: 0 };
+            break;
+        }
+    }
+    if (exitResult === null) {
+        exitResult = {
+            code: 1,
+            message: `Task did not complete within ${maxIterations} iterations`,
+        };
+    }
+    yield { type: 'exit', data: exitResult };
+}

package/dist/cjs/execute.d.ts

@@ -0,0 +1,56 @@
+export function complete(options: Omit<ConversationCompleteRequest, "functions" | "limits"> & {
+    client: ChatBotKit;
+    tools?: Tools;
+    abortSignal?: AbortSignal;
+}): AsyncGenerator<ConversationCompleteStreamType | ToolCallStartEvent | ToolCallEndEvent | ToolCallErrorEvent, void, unknown>;
+export function execute(options: Omit<ConversationCompleteRequest, "functions" | "limits"> & {
+    client: ChatBotKit;
+    tools?: Tools;
+    maxIterations?: number;
+    abortSignal?: AbortSignal;
+}): AsyncGenerator<ConversationCompleteStreamType | ToolCallStartEvent | ToolCallEndEvent | ToolCallErrorEvent | IterationEvent | ExitEvent, void, unknown>;
+export type ZodObject = import("zod").ZodObject<any>;
+export type ChatBotKit = import("@chatbotkit/sdk").ChatBotKit;
+export type ConversationCompleteRequest = any;
+export type ConversationCompleteStreamType = any;
+export type ToolDefinition<T extends ZodObject> = {
+    description: string;
+    input?: T;
+    handler: (input: any) => Promise<any>;
+};
+export type Tools = Record<string, ToolDefinition<ZodObject>>;
+export type ExitResult = {
+    code: number;
+    message?: string;
+};
+export type ToolCallStartEvent = {
+    type: "toolCallStart";
+    data: {
+        name: string;
+        args: any;
+    };
+};
+export type ToolCallEndEvent = {
+    type: "toolCallEnd";
+    data: {
+        name: string;
+        result: any;
+    };
+};
+export type ToolCallErrorEvent = {
+    type: "toolCallError";
+    data: {
+        name: string;
+        error: string;
+    };
+};
+export type IterationEvent = {
+    type: "iteration";
+    data: {
+        iteration: number;
+    };
+};
+export type ExitEvent = {
+    type: "exit";
+    data: ExitResult;
+};

package/dist/cjs/index.cjs

@@ -1,8 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.tools = exports.execute = exports.complete = void 0;
-var agent_js_1 = require("./agent.cjs");
-Object.defineProperty(exports, "complete", { enumerable: true, get: function () { return agent_js_1.complete; } });
-Object.defineProperty(exports, "execute", { enumerable: true, get: function () { return agent_js_1.execute; } });
+exports.loadAgent = exports.createSkillsFeature = exports.loadSkills = exports.tools = exports.execute = exports.complete = void 0;
+var execute_js_1 = require("./execute.cjs");
+Object.defineProperty(exports, "complete", { enumerable: true, get: function () { return execute_js_1.complete; } });
+Object.defineProperty(exports, "execute", { enumerable: true, get: function () { return execute_js_1.execute; } });
 var tools_js_1 = require("./tools.cjs");
 Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return tools_js_1.tools; } });
+var skills_js_1 = require("./skills.cjs");
+Object.defineProperty(exports, "loadSkills", { enumerable: true, get: function () { return skills_js_1.loadSkills; } });
+Object.defineProperty(exports, "createSkillsFeature", { enumerable: true, get: function () { return skills_js_1.createSkillsFeature; } });
+var agent_js_1 = require("./agent.cjs");
+Object.defineProperty(exports, "loadAgent", { enumerable: true, get: function () { return agent_js_1.loadAgent; } });

package/dist/cjs/index.d.ts

@@ -1,2 +1,4 @@
 export { tools } from "./tools.js";
-export { complete, execute } from "./agent.js";
+export { loadAgent } from "./agent.js";
+export { complete, execute } from "./execute.js";
+export { loadSkills, createSkillsFeature } from "./skills.js";

package/dist/cjs/skills.cjs

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSkills = loadSkills;
+exports.createSkillsFeature = createSkillsFeature;
+const tslib_1 = require("tslib");
+const promises_1 = require("fs/promises");
+const js_yaml_1 = tslib_1.__importDefault(require("js-yaml"));
+const path_1 = require("path");
+function parseFrontMatter(content) {
+    const frontMatterRegex = /^---\s*\n([\s\S]*?)\n---/;
+    const match = content.match(frontMatterRegex);
+    if (!match) {
+        return {};
+    }
+    try {
+        const frontMatter = match[1];
+        const parsed = (js_yaml_1.default.load(frontMatter));
+        if (typeof parsed !== 'object' || parsed === null) {
+            return {};
+        }
+        return {
+            name: typeof parsed.name === 'string' ? parsed.name : undefined,
+            description: typeof parsed.description === 'string' ? parsed.description : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+async function loadSkillFromDirectory(skillDir) {
+    const skillFilePath = (0, path_1.join)(skillDir, 'SKILL.md');
+    try {
+        const content = await (0, promises_1.readFile)(skillFilePath, 'utf-8');
+        const { name, description } = parseFrontMatter(content);
+        if (!name || !description) {
+            return null;
+        }
+        return {
+            name,
+            description,
+            path: (0, path_1.resolve)(skillFilePath),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function loadSkills(directories, options = {}) {
+    const skills = ([]);
+    const watchControllers = ([]);
+    async function scanDirectory(baseDir) {
+        try {
+            const entries = await (0, promises_1.readdir)(baseDir);
+            for (const entry of entries) {
+                const entryPath = (0, path_1.join)(baseDir, entry);
+                const entryStat = await (0, promises_1.stat)(entryPath);
+                if (entryStat.isDirectory()) {
+                    const skill = await loadSkillFromDirectory(entryPath);
+                    if (skill) {
+                        const existingIdx = skills.findIndex((s) => s.path === skill.path);
+                        if (existingIdx !== -1) {
+                            skills[existingIdx] = skill;
+                        }
+                        else {
+                            skills.push(skill);
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+        }
+    }
+    for (const dir of directories) {
+        await scanDirectory(dir);
+    }
+    if (options.watch) {
+        for (const dir of directories) {
+            const controller = new AbortController();
+            watchControllers.push(controller);
+            (async () => {
+                try {
+                    const watcher = (0, promises_1.watch)(dir, {
+                        recursive: true,
+                        signal: controller.signal,
+                    });
+                    for await (const event of watcher) {
+                        if (event.filename?.endsWith('SKILL.md')) {
+                            await scanDirectory(dir);
+                        }
+                    }
+                }
+                catch (err) {
+                    if (err instanceof Error &&
+                        err.name !== 'AbortError' &&
+                        !err.message.includes('AbortError')) {
+                    }
+                }
+            })();
+        }
+    }
+    return {
+        skills,
+        close: () => {
+            for (const controller of watchControllers) {
+                controller.abort();
+            }
+        },
+    };
+}
+function createSkillsFeature(skills) {
+    return {
+        name: ('skills'),
+        options: { skills },
+    };
+}

package/dist/cjs/skills.d.ts

@@ -0,0 +1,18 @@
+export function loadSkills(directories: string[], options?: {
+    watch?: boolean;
+}): Promise<SkillsResult>;
+export function createSkillsFeature(skills: SkillDefinition[]): {
+    name: "skills";
+    options: {
+        skills: SkillDefinition[];
+    };
+};
+export type SkillDefinition = {
+    name: string;
+    description: string;
+    path: string;
+};
+export type SkillsResult = {
+    skills: SkillDefinition[];
+    close: () => void;
+};

package/dist/esm/agent.d.ts

@@ -1,54 +1,10 @@
-export function complete(options: ConversationCompleteRequest & {
-    client: ChatBotKit;
-    tools?: Tools;
-}): AsyncGenerator<ConversationCompleteStreamType | ToolCallStartEvent | ToolCallEndEvent | ToolCallErrorEvent, void, unknown>;
-export function execute(options: ConversationCompleteRequest & {
-    client: ChatBotKit;
-    tools?: Tools;
-    maxIterations?: number;
-}): AsyncGenerator<ConversationCompleteStreamType | ToolCallStartEvent | ToolCallEndEvent | ToolCallErrorEvent | IterationEvent | ExitEvent, void, unknown>;
-export type ZodObject = import("zod").ZodObject<any>;
-export type ChatBotKit = import("@chatbotkit/sdk").ChatBotKit;
-export type ConversationCompleteRequest = import("@chatbotkit/sdk/conversation/v1").ConversationCompleteRequest;
-export type ConversationCompleteStreamType = import("@chatbotkit/sdk/conversation/v1").ConversationCompleteStreamType;
-export type ToolDefinition<T extends ZodObject> = {
-    description: string;
-    input?: T;
-    handler: (input: any) => Promise<any>;
-};
-export type Tools = Record<string, ToolDefinition<ZodObject>>;
-export type ExitResult = {
-    code: number;
-    message?: string;
-};
-export type ToolCallStartEvent = {
-    type: "toolCallStart";
-    data: {
-        name: string;
-        args: any;
-    };
-};
-export type ToolCallEndEvent = {
-    type: "toolCallEnd";
-    data: {
-        name: string;
-        result: any;
-    };
-};
-export type ToolCallErrorEvent = {
-    type: "toolCallError";
-    data: {
-        name: string;
-        error: string;
-    };
-};
-export type IterationEvent = {
-    type: "iteration";
-    data: {
-        iteration: number;
-    };
-};
-export type ExitEvent = {
-    type: "exit";
-    data: ExitResult;
+export function loadAgent(filePath: string): Promise<AgentDefinition>;
+export type AgentDefinition = {
+    name?: string;
+    description?: string;
+    backstory?: string;
+    model?: string;
+    botId?: string;
+    skillsetId?: string;
+    datasetId?: string;
 };