praisonai 1.3.6 → 1.4.0

package/dist/ai/agent-loop.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Agent Loop - Manual Agent Loop Control
+ *
+ * Provides utilities for manual control of agent execution loops.
+ */
+import type { Message } from './types';
+export interface AgentLoopConfig {
+    /** Model to use */
+    model: string;
+    /** System prompt */
+    system?: string;
+    /** Available tools */
+    tools?: Record<string, AgentTool>;
+    /** Maximum steps (default: 10) */
+    maxSteps?: number;
+    /** Stop condition */
+    stopWhen?: StopCondition;
+    /** On step finish callback */
+    onStepFinish?: (step: AgentStep) => void | Promise<void>;
+    /** On tool call callback (for approval) */
+    onToolCall?: (toolCall: ToolCallInfo) => Promise<boolean>;
+}
+export interface AgentTool {
+    description: string;
+    parameters: any;
+    execute: (args: any) => Promise<any>;
+}
+export interface AgentStep {
+    stepNumber: number;
+    text: string;
+    toolCalls: ToolCallInfo[];
+    toolResults: ToolResultInfo[];
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    finishReason: string;
+}
+export interface ToolCallInfo {
+    toolCallId: string;
+    toolName: string;
+    args: any;
+}
+export interface ToolResultInfo {
+    toolCallId: string;
+    toolName: string;
+    result: any;
+    isError?: boolean;
+}
+export type StopCondition = {
+    type: 'stepCount';
+    count: number;
+} | {
+    type: 'noToolCalls';
+} | {
+    type: 'custom';
+    check: (step: AgentStep) => boolean;
+};
+export interface AgentLoopResult {
+    text: string;
+    steps: AgentStep[];
+    totalUsage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    finishReason: string;
+}
+/**
+ * Create a manual agent loop for fine-grained control.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const loop = createAgentLoop({
+ *   model: 'gpt-4o',
+ *   system: 'You are a helpful assistant',
+ *   tools: {
+ *     search: {
+ *       description: 'Search the web',
+ *       parameters: z.object({ query: z.string() }),
+ *       execute: async ({ query }) => searchWeb(query)
+ *     }
+ *   },
+ *   maxSteps: 5
+ * });
+ *
+ * const result = await loop.run('Find information about AI');
+ * ```
+ *
+ * @example With approval
+ * ```typescript
+ * const loop = createAgentLoop({
+ *   model: 'gpt-4o',
+ *   tools: { ... },
+ *   onToolCall: async (toolCall) => {
+ *     const approved = await askUserForApproval(toolCall);
+ *     return approved;
+ *   }
+ * });
+ * ```
+ *
+ * @example Step-by-step control
+ * ```typescript
+ * const loop = createAgentLoop({ model: 'gpt-4o', tools: { ... } });
+ *
+ * // Initialize with a prompt
+ * loop.addMessage({ role: 'user', content: 'Hello' });
+ *
+ * // Run one step at a time
+ * while (!loop.isComplete()) {
+ *   const step = await loop.step();
+ *   console.log('Step:', step);
+ *
+ *   // Optionally modify messages or tools between steps
+ *   if (needsMoreContext) {
+ *     loop.addMessage({ role: 'user', content: 'Additional context...' });
+ *   }
+ * }
+ *
+ * const result = loop.getResult();
+ * ```
+ */
+export declare function createAgentLoop(config: AgentLoopConfig): AgentLoop;
+export declare class AgentLoop {
+    private config;
+    private messages;
+    private steps;
+    private currentStep;
+    private complete;
+    private totalUsage;
+    constructor(config: AgentLoopConfig);
+    /**
+     * Add a message to the conversation.
+     */
+    addMessage(message: Message): void;
+    /**
+     * Get all messages in the conversation.
+     */
+    getMessages(): Message[];
+    /**
+     * Check if the loop is complete.
+     */
+    isComplete(): boolean;
+    /**
+     * Run a single step of the agent loop.
+     */
+    step(): Promise<AgentStep>;
+    /**
+     * Run the full agent loop until completion.
+     */
+    run(prompt: string): Promise<AgentLoopResult>;
+    /**
+     * Get the final result.
+     */
+    getResult(): AgentLoopResult;
+    /**
+     * Check if the loop should stop.
+     */
+    private shouldStop;
+    /**
+     * Reset the agent loop.
+     */
+    reset(): void;
+}
+/**
+ * Create a stop condition that stops after N steps.
+ */
+export declare function stopAfterSteps(count: number): StopCondition;
+/**
+ * Create a stop condition that stops when no tool calls are made.
+ */
+export declare function stopWhenNoToolCalls(): StopCondition;
+/**
+ * Create a custom stop condition.
+ */
+export declare function stopWhen(check: (step: AgentStep) => boolean): StopCondition;

package/dist/ai/agent-loop.js

@@ -0,0 +1,313 @@
+"use strict";
+/**
+ * Agent Loop - Manual Agent Loop Control
+ *
+ * Provides utilities for manual control of agent execution loops.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentLoop = void 0;
+exports.createAgentLoop = createAgentLoop;
+exports.stopAfterSteps = stopAfterSteps;
+exports.stopWhenNoToolCalls = stopWhenNoToolCalls;
+exports.stopWhen = stopWhen;
+/**
+ * Create a manual agent loop for fine-grained control.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const loop = createAgentLoop({
+ *   model: 'gpt-4o',
+ *   system: 'You are a helpful assistant',
+ *   tools: {
+ *     search: {
+ *       description: 'Search the web',
+ *       parameters: z.object({ query: z.string() }),
+ *       execute: async ({ query }) => searchWeb(query)
+ *     }
+ *   },
+ *   maxSteps: 5
+ * });
+ *
+ * const result = await loop.run('Find information about AI');
+ * ```
+ *
+ * @example With approval
+ * ```typescript
+ * const loop = createAgentLoop({
+ *   model: 'gpt-4o',
+ *   tools: { ... },
+ *   onToolCall: async (toolCall) => {
+ *     const approved = await askUserForApproval(toolCall);
+ *     return approved;
+ *   }
+ * });
+ * ```
+ *
+ * @example Step-by-step control
+ * ```typescript
+ * const loop = createAgentLoop({ model: 'gpt-4o', tools: { ... } });
+ *
+ * // Initialize with a prompt
+ * loop.addMessage({ role: 'user', content: 'Hello' });
+ *
+ * // Run one step at a time
+ * while (!loop.isComplete()) {
+ *   const step = await loop.step();
+ *   console.log('Step:', step);
+ *
+ *   // Optionally modify messages or tools between steps
+ *   if (needsMoreContext) {
+ *     loop.addMessage({ role: 'user', content: 'Additional context...' });
+ *   }
+ * }
+ *
+ * const result = loop.getResult();
+ * ```
+ */
+function createAgentLoop(config) {
+    return new AgentLoop(config);
+}
+class AgentLoop {
+    constructor(config) {
+        this.messages = [];
+        this.steps = [];
+        this.currentStep = 0;
+        this.complete = false;
+        this.totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+        this.config = {
+            maxSteps: 10,
+            ...config,
+        };
+        // Add system message if provided
+        if (config.system) {
+            this.messages.push({ role: 'system', content: config.system });
+        }
+    }
+    /**
+     * Add a message to the conversation.
+     */
+    addMessage(message) {
+        this.messages.push(message);
+    }
+    /**
+     * Get all messages in the conversation.
+     */
+    getMessages() {
+        return [...this.messages];
+    }
+    /**
+     * Check if the loop is complete.
+     */
+    isComplete() {
+        return this.complete;
+    }
+    /**
+     * Run a single step of the agent loop.
+     */
+    async step() {
+        if (this.complete) {
+            throw new Error('Agent loop is already complete');
+        }
+        this.currentStep++;
+        // Check max steps
+        if (this.currentStep > (this.config.maxSteps || 10)) {
+            this.complete = true;
+            throw new Error(`Maximum steps (${this.config.maxSteps}) reached`);
+        }
+        // Import and call generateText
+        const { generateText } = await Promise.resolve().then(() => __importStar(require('./generate-text')));
+        const result = await generateText({
+            model: this.config.model,
+            messages: this.messages,
+            tools: this.config.tools,
+            maxSteps: 1, // Single step
+        });
+        // Build step result
+        const step = {
+            stepNumber: this.currentStep,
+            text: result.text,
+            toolCalls: result.toolCalls.map(tc => ({
+                toolCallId: tc.toolCallId,
+                toolName: tc.toolName,
+                args: tc.args,
+            })),
+            toolResults: result.toolResults.map(tr => ({
+                toolCallId: tr.toolCallId,
+                toolName: tr.toolName,
+                result: tr.result,
+            })),
+            usage: result.usage,
+            finishReason: result.finishReason,
+        };
+        // Update total usage
+        this.totalUsage.promptTokens += result.usage.promptTokens;
+        this.totalUsage.completionTokens += result.usage.completionTokens;
+        this.totalUsage.totalTokens += result.usage.totalTokens;
+        // Add assistant message
+        if (result.text) {
+            this.messages.push({ role: 'assistant', content: result.text });
+        }
+        // Handle tool calls
+        if (step.toolCalls.length > 0) {
+            // Check for approval if callback provided
+            if (this.config.onToolCall) {
+                for (const toolCall of step.toolCalls) {
+                    const approved = await this.config.onToolCall(toolCall);
+                    if (!approved) {
+                        this.complete = true;
+                        step.finishReason = 'tool_rejected';
+                        break;
+                    }
+                }
+            }
+            // Add tool call message
+            const toolCallParts = step.toolCalls.map(tc => ({
+                type: 'tool-call',
+                toolCallId: tc.toolCallId,
+                toolName: tc.toolName,
+                args: tc.args,
+            }));
+            this.messages.push({ role: 'assistant', content: '', toolCalls: toolCallParts });
+            // Add tool results
+            for (const tr of step.toolResults) {
+                const toolResultPart = {
+                    type: 'tool-result',
+                    toolCallId: tr.toolCallId,
+                    toolName: tr.toolName,
+                    result: tr.result,
+                };
+                this.messages.push({
+                    role: 'tool',
+                    content: [toolResultPart],
+                    toolCallId: tr.toolCallId,
+                });
+            }
+        }
+        // Store step
+        this.steps.push(step);
+        // Call step finish callback
+        if (this.config.onStepFinish) {
+            await this.config.onStepFinish(step);
+        }
+        // Check stop conditions
+        if (this.shouldStop(step)) {
+            this.complete = true;
+        }
+        return step;
+    }
+    /**
+     * Run the full agent loop until completion.
+     */
+    async run(prompt) {
+        // Add user message
+        this.addMessage({ role: 'user', content: prompt });
+        // Run steps until complete
+        while (!this.isComplete()) {
+            try {
+                await this.step();
+            }
+            catch (error) {
+                if (error.message.includes('Maximum steps')) {
+                    break;
+                }
+                throw error;
+            }
+        }
+        return this.getResult();
+    }
+    /**
+     * Get the final result.
+     */
+    getResult() {
+        const lastStep = this.steps[this.steps.length - 1];
+        return {
+            text: lastStep?.text || '',
+            steps: this.steps,
+            totalUsage: this.totalUsage,
+            finishReason: lastStep?.finishReason || 'unknown',
+        };
+    }
+    /**
+     * Check if the loop should stop.
+     */
+    shouldStop(step) {
+        // Check custom stop condition
+        if (this.config.stopWhen) {
+            switch (this.config.stopWhen.type) {
+                case 'stepCount':
+                    return this.currentStep >= this.config.stopWhen.count;
+                case 'noToolCalls':
+                    return step.toolCalls.length === 0;
+                case 'custom':
+                    return this.config.stopWhen.check(step);
+            }
+        }
+        // Default: stop when no tool calls
+        return step.toolCalls.length === 0 && step.finishReason === 'stop';
+    }
+    /**
+     * Reset the agent loop.
+     */
+    reset() {
+        this.messages = [];
+        this.steps = [];
+        this.currentStep = 0;
+        this.complete = false;
+        this.totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+        if (this.config.system) {
+            this.messages.push({ role: 'system', content: this.config.system });
+        }
+    }
+}
+exports.AgentLoop = AgentLoop;
+/**
+ * Create a stop condition that stops after N steps.
+ */
+function stopAfterSteps(count) {
+    return { type: 'stepCount', count };
+}
+/**
+ * Create a stop condition that stops when no tool calls are made.
+ */
+function stopWhenNoToolCalls() {
+    return { type: 'noToolCalls' };
+}
+/**
+ * Create a custom stop condition.
+ */
+function stopWhen(check) {
+    return { type: 'custom', check };
+}

package/dist/ai/devtools.d.ts

@@ -0,0 +1,74 @@
+/**
+ * DevTools - AI SDK v6 DevTools Integration
+ *
+ * Provides optional DevTools integration for debugging AI SDK calls.
+ * This is an optional dependency that provides visibility into LLM calls.
+ */
+export interface DevToolsConfig {
+    /** Enable DevTools (default: auto-detect from NODE_ENV) */
+    enabled?: boolean;
+    /** DevTools server port (default: 3001) */
+    port?: number;
+    /** DevTools server host (default: localhost) */
+    host?: string;
+    /** Project name for DevTools UI */
+    projectName?: string;
+    /** Custom metadata to include */
+    metadata?: Record<string, unknown>;
+}
+export interface DevToolsState {
+    enabled: boolean;
+    initialized: boolean;
+    port?: number;
+    host?: string;
+}
+/**
+ * Enable AI SDK DevTools for debugging.
+ *
+ * @example
+ * ```typescript
+ * // Enable in development
+ * if (process.env.NODE_ENV === 'development') {
+ *   await enableDevTools();
+ * }
+ * ```
+ *
+ * @example With configuration
+ * ```typescript
+ * await enableDevTools({
+ *   port: 3001,
+ *   projectName: 'My AI App'
+ * });
+ * ```
+ */
+export declare function enableDevTools(config?: DevToolsConfig): Promise<void>;
+/**
+ * Disable DevTools.
+ */
+export declare function disableDevTools(): Promise<void>;
+/**
+ * Check if DevTools is enabled.
+ */
+export declare function isDevToolsEnabled(): boolean;
+/**
+ * Get DevTools state.
+ */
+export declare function getDevToolsState(): DevToolsState;
+/**
+ * Get DevTools URL.
+ */
+export declare function getDevToolsUrl(): string | null;
+/**
+ * Create middleware that logs to DevTools.
+ *
+ * @example
+ * ```typescript
+ * const model = wrapModel(openai('gpt-4o'), createDevToolsMiddleware());
+ * ```
+ */
+export declare function createDevToolsMiddleware(): any;
+/**
+ * Auto-enable DevTools if in development mode.
+ * Call this at app startup.
+ */
+export declare function autoEnableDevTools(): Promise<void>;