@ductape/sdk 0.0.4 → 0.0.5

package/dist/agents/agents.service.js

@@ -0,0 +1,1253 @@
+"use strict";
+/**
+ * Agents Service
+ *
+ * Main service class for agentic workflows operations.
+ * Provides CRUD operations and execution for Ductape Agents.
+ *
+ * Agentic workflows extend Ductape's workflow engine to support AI-driven,
+ * autonomous multi-step processes where an LLM dynamically decides the
+ * next action based on observations and reasoning.
+ */
+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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentsService = exports.AgentsService = exports.AgentError = void 0;
+const crypto_1 = require("crypto");
+const products_service_1 = __importDefault(require("../products/services/products.service"));
+const processor_service_1 = __importDefault(require("../processor/services/processor.service"));
+const logs_service_1 = __importDefault(require("../logs/logs.service"));
+const logs_types_1 = require("../logs/logs.types");
+const processor_utils_1 = require("../processor/utils/processor.utils");
+const productsBuilder_types_1 = require("../types/productsBuilder.types");
+const tool_registry_1 = require("./tool-registry");
+const agent_executor_1 = require("./agent-executor");
+const quota_service_1 = require("../resilience/quota.service");
+const fallback_service_1 = require("../resilience/fallback.service");
+const healthcheck_service_1 = require("../resilience/healthcheck.service");
+const secrets_1 = require("../secrets");
+/**
+ * Error class for agent-related errors
+ */
+class AgentError extends Error {
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'AgentError';
+    }
+    static configurationError(message) {
+        return new AgentError(message, 'CONFIGURATION_ERROR');
+    }
+    static validationError(message, details) {
+        return new AgentError(message, 'VALIDATION_ERROR', details);
+    }
+    static notFoundError(message) {
+        return new AgentError(message, 'NOT_FOUND');
+    }
+    static executionError(message, details) {
+        return new AgentError(message, 'EXECUTION_ERROR', details);
+    }
+}
+exports.AgentError = AgentError;
+/**
+ * Main Agents Service class
+ * Provides unified interface for agent management and execution
+ */
+class AgentsService {
+    /**
+     * Create a new AgentsService instance
+     * @param config - Optional configuration for authentication and workspace context
+     */
+    constructor(config) {
+        /** Service configuration */
+        this.config = null;
+        /** ProductBuilder instances cache (keyed by product tag) */
+        this.productBuilders = new Map();
+        /** Local agent definitions */
+        this.localAgents = new Map();
+        /** Tool registries per agent */
+        this.toolRegistries = new Map();
+        /** Active executors (for status/signal handling) */
+        this.activeExecutors = new Map();
+        /** LogService instance for logging operations */
+        this.logService = null;
+        /** Current product ID for logging */
+        this.productId = '';
+        this.config = config || null;
+        this._privateKey = config ? config.private_key : '';
+    }
+    // ==================== CONFIGURATION ====================
+    /**
+     * Update service configuration
+     */
+    updateConfig(config) {
+        this.config = config;
+    }
+    /**
+     * Get service configuration
+     */
+    getConfig() {
+        return this.config;
+    }
+    // ==================== PRODUCT BUILDER MANAGEMENT ====================
+    /**
+     * Create a new ProductBuilder instance
+     */
+    createNewProductBuilder() {
+        if (!this.config) {
+            throw AgentError.configurationError('AgentsService not configured. Please provide config when initializing.');
+        }
+        return new products_service_1.default({
+            workspace_id: this.config.workspace_id,
+            public_key: this.config.public_key,
+            user_id: this.config.user_id,
+            token: this.config.token,
+            env_type: this.config.env_type,
+        });
+    }
+    /**
+     * Get or create a ProductBuilder instance for the given product tag
+     */
+    async getProductBuilder(productTag) {
+        let builder = this.productBuilders.get(productTag);
+        if (!builder) {
+            builder = this.createNewProductBuilder();
+            await builder.initializeProductByTag(productTag);
+            this.productBuilders.set(productTag, builder);
+            this.productId = builder.fetchProductId() || '';
+        }
+        return builder;
+    }
+    /**
+     * Initialize logging service
+     */
+    initializeLogService() {
+        if (!this.logService && this.config) {
+            this.logService = new logs_service_1.default({
+                product_id: this.productId,
+                workspace_id: this.config.workspace_id,
+                public_key: this.config.public_key,
+                user_id: this.config.user_id,
+                token: this.config.token,
+                env_type: this.config.env_type,
+            });
+        }
+    }
+    /**
+     * Create a new ProcessorService instance
+     */
+    createNewProcessor() {
+        if (!this.config) {
+            throw AgentError.configurationError('AgentsService not configured. Please provide config when initializing.');
+        }
+        return new processor_service_1.default({
+            workspace_id: this.config.workspace_id,
+            public_key: this.config.public_key,
+            user_id: this.config.user_id,
+            token: this.config.token,
+            env_type: this.config.env_type,
+            redis_client: this.config.redis_client,
+            private_key: this._privateKey,
+        });
+    }
+    /**
+     * Create a resilience service wrapper for agent operations
+     */
+    createResilienceService() {
+        if (!this.config) {
+            return undefined;
+        }
+        const serviceConfig = {
+            workspace_id: this.config.workspace_id,
+            public_key: this.config.public_key,
+            user_id: this.config.user_id,
+            token: this.config.token,
+            env_type: this.config.env_type,
+            private_key: this._privateKey,
+            access_key: this.config.access_key,
+        };
+        // Create individual services
+        const quotaService = new quota_service_1.QuotaService(serviceConfig);
+        const fallbackService = new fallback_service_1.FallbackService(serviceConfig);
+        const healthcheckService = new healthcheck_service_1.HealthcheckService(serviceConfig);
+        // Return a wrapper that delegates to the appropriate service
+        return {
+            async runQuota(options) {
+                return quotaService.run({
+                    product: options.product,
+                    env: options.env,
+                    tag: options.tag,
+                    input: options.input,
+                    session: options.session,
+                });
+            },
+            async runFallback(options) {
+                return fallbackService.run({
+                    product: options.product,
+                    env: options.env,
+                    tag: options.tag,
+                    input: options.input,
+                    session: options.session,
+                });
+            },
+            async checkHealth(options) {
+                return healthcheckService.getStatus({
+                    product: options.product,
+                    env: options.env,
+                    tag: options.tag,
+                });
+            },
+            async getQuotaStatus(options) {
+                // This would need to be implemented in QuotaService
+                // For now, return basic status
+                return {
+                    tag: options.tag,
+                    totalQuota: undefined,
+                    usedQuota: undefined,
+                    remainingQuota: undefined,
+                    providers: [],
+                };
+            },
+        };
+    }
+    /**
+     * Get context services for agent execution
+     */
+    getContextServices(resilienceConfig) {
+        return {
+            config: this.config,
+            processorService: this.createNewProcessor(),
+            resilienceService: this.createResilienceService(),
+            resilienceConfig,
+            // Note: These services would be injected from the main Ductape class
+            // databaseService, graphService, storageService, brokersService
+        };
+    }
+    // ==================== AGENT DEFINITION ====================
+    /**
+     * Define a new agent and optionally persist to database
+     *
+     * @example
+     * ```ts
+     * // Define and persist to database
+     * const agent = await ductape.agents.define({
+     *   product: 'my-product',
+     *   tag: 'customer-support',
+     *   name: 'Customer Support Agent',
+     *   model: { provider: 'anthropic', model: 'claude-sonnet-4-20250514' },
+     *   systemPrompt: 'You are a helpful customer support agent...',
+     *   tools: [
+     *     {
+     *       tag: 'lookup-order',
+     *       description: 'Look up order details',
+     *       parameters: { orderId: { type: 'string', description: 'Order ID' } },
+     *       handler: async (ctx, params) => ctx.database.query({ ... }),
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    async define(options) {
+        var _a;
+        // Validate required fields
+        if (!options.tag) {
+            throw AgentError.validationError('Agent tag is required');
+        }
+        if (!options.name) {
+            throw AgentError.validationError('Agent name is required');
+        }
+        if (!options.model) {
+            throw AgentError.validationError('Agent model configuration is required');
+        }
+        if (!options.systemPrompt) {
+            throw AgentError.validationError('Agent system prompt is required');
+        }
+        // Create tool registry
+        const toolRegistry = new tool_registry_1.ToolRegistry();
+        if (options.tools && options.tools.length > 0) {
+            toolRegistry.registerMany(options.tools);
+        }
+        // Store tool registry (with handlers for local execution)
+        this.toolRegistries.set(options.tag, toolRegistry);
+        // Get tool schemas (without handlers for storage)
+        const toolSchemas = toolRegistry.getSchemas();
+        // Create defined agent (without handlers for storage)
+        const definedAgent = {
+            tag: options.tag,
+            name: options.name,
+            description: options.description,
+            model: options.model,
+            modelConfig: options.modelConfig,
+            systemPrompt: options.systemPrompt,
+            toolSchemas,
+            termination: options.termination,
+            memory: options.memory,
+            humanInLoop: options.humanInLoop,
+            streaming: options.streaming,
+            inputSchema: options.inputSchema,
+            envs: options.envs,
+            resilience: options.resilience,
+        };
+        // Store locally
+        this.localAgents.set(options.tag, definedAgent);
+        // If product is specified, persist to database
+        if (options.product) {
+            try {
+                const productBuilder = await this.getProductBuilder(options.product);
+                // Convert to IProductAgent format for storage
+                const productAgent = {
+                    tag: options.tag,
+                    name: options.name,
+                    description: options.description,
+                    model: options.model, // Model is a tag reference to product-level model config
+                    modelConfig: options.modelConfig,
+                    systemPrompt: options.systemPrompt,
+                    tools: toolSchemas.map((schema) => ({
+                        tag: schema.tag,
+                        name: schema.name,
+                        description: schema.description,
+                        parameters: schema.parameters,
+                        requiresConfirmation: schema.requiresConfirmation,
+                        costEstimate: schema.costEstimate,
+                        timeout: schema.timeout,
+                        retries: schema.retries,
+                    })),
+                    termination: options.termination ? {
+                        maxIterations: options.termination.maxIterations,
+                        maxTokens: options.termination.maxTokens,
+                        timeout: typeof options.termination.timeout === 'string'
+                            ? parseInt(options.termination.timeout)
+                            : options.termination.timeout,
+                        allowManualStop: options.termination.allowManualStop,
+                    } : undefined,
+                    memory: options.memory ? {
+                        shortTerm: options.memory.shortTerm,
+                        longTerm: options.memory.longTerm,
+                    } : undefined,
+                    humanInLoop: options.humanInLoop ? {
+                        enabled: options.humanInLoop.enabled,
+                        alwaysRequireApproval: options.humanInLoop.alwaysRequireApproval,
+                        approvalTimeout: typeof options.humanInLoop.approvalTimeout === 'string'
+                            ? parseInt(options.humanInLoop.approvalTimeout)
+                            : options.humanInLoop.approvalTimeout,
+                        approvalWebhook: options.humanInLoop.approvalWebhook,
+                        approvalBroker: options.humanInLoop.approvalBroker,
+                    } : undefined,
+                    streaming: options.streaming ? {
+                        enabled: options.streaming.enabled,
+                        events: options.streaming.events,
+                        webhook: options.streaming.webhook,
+                        broker: options.streaming.broker,
+                    } : undefined,
+                    inputSchema: options.inputSchema,
+                    envs: (_a = options.envs) === null || _a === void 0 ? void 0 : _a.map((env) => ({
+                        slug: env.slug,
+                        active: env.active,
+                        model: env.model, // Model tag override for this environment
+                        modelConfig: env.modelConfig,
+                        toolOverrides: env.toolOverrides,
+                    })),
+                    resilience: options.resilience,
+                };
+                await productBuilder.createAgent(productAgent);
+            }
+            catch (error) {
+                // Log but don't fail - agent is still stored locally
+                console.warn(`Failed to persist agent to database: ${error}`);
+            }
+        }
+        return definedAgent;
+    }
+    /**
+     * Register a defined agent with a product (persists to database)
+     *
+     * @example
+     * ```ts
+     * await ductape.agents.register('my-product', agent);
+     * ```
+     */
+    async register(product, agent) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const process_id = (0, processor_utils_1.generateObjectId)();
+        // Initialize logging
+        await this.getProductBuilder(product);
+        this.initializeLogService();
+        const baseLogs = {
+            product_tag: product,
+            workspace_id: ((_a = this.config) === null || _a === void 0 ? void 0 : _a.workspace_id) || '',
+            env: '',
+            process_id,
+            type: logs_types_1.LogEventTypes.WORKFLOW,
+            parent_tag: agent.tag,
+            data: { agent: agent.tag, operation: 'register' },
+        };
+        (_b = this.logService) === null || _b === void 0 ? void 0 : _b.add(Object.assign(Object.assign({}, baseLogs), { message: 'Agent register - initiated', status: logs_types_1.LogEventStatus.PROCESSING }));
+        try {
+            const productBuilder = await this.getProductBuilder(product);
+            // Convert to IProductAgent format and persist to database
+            const productAgent = {
+                tag: agent.tag,
+                name: agent.name,
+                description: agent.description,
+                model: agent.model, // Model is a tag reference to product-level model config
+                modelConfig: agent.modelConfig,
+                systemPrompt: agent.systemPrompt,
+                tools: agent.toolSchemas.map((schema) => ({
+                    tag: schema.tag,
+                    name: schema.name,
+                    description: schema.description,
+                    parameters: schema.parameters,
+                    requiresConfirmation: schema.requiresConfirmation,
+                    costEstimate: schema.costEstimate,
+                    timeout: schema.timeout,
+                    retries: schema.retries,
+                })),
+                termination: agent.termination ? {
+                    maxIterations: agent.termination.maxIterations,
+                    maxTokens: agent.termination.maxTokens,
+                    timeout: typeof agent.termination.timeout === 'string'
+                        ? parseInt(agent.termination.timeout)
+                        : agent.termination.timeout,
+                    allowManualStop: agent.termination.allowManualStop,
+                } : undefined,
+                memory: agent.memory ? {
+                    shortTerm: agent.memory.shortTerm,
+                    longTerm: agent.memory.longTerm,
+                } : undefined,
+                humanInLoop: agent.humanInLoop ? {
+                    enabled: agent.humanInLoop.enabled,
+                    alwaysRequireApproval: agent.humanInLoop.alwaysRequireApproval,
+                    approvalTimeout: typeof agent.humanInLoop.approvalTimeout === 'string'
+                        ? parseInt(agent.humanInLoop.approvalTimeout)
+                        : agent.humanInLoop.approvalTimeout,
+                    approvalWebhook: agent.humanInLoop.approvalWebhook,
+                    approvalBroker: agent.humanInLoop.approvalBroker,
+                } : undefined,
+                streaming: agent.streaming ? {
+                    enabled: agent.streaming.enabled,
+                    events: agent.streaming.events,
+                    webhook: agent.streaming.webhook,
+                    broker: agent.streaming.broker,
+                } : undefined,
+                inputSchema: agent.inputSchema,
+                envs: (_c = agent.envs) === null || _c === void 0 ? void 0 : _c.map((env) => ({
+                    slug: env.slug,
+                    active: env.active,
+                    model: env.model, // Model tag override for this environment
+                    modelConfig: env.modelConfig,
+                    toolOverrides: env.toolOverrides,
+                })),
+                resilience: agent.resilience,
+            };
+            await productBuilder.createAgent(productAgent);
+            // Also store locally for immediate execution
+            this.localAgents.set(agent.tag, agent);
+            (_d = this.logService) === null || _d === void 0 ? void 0 : _d.add(Object.assign(Object.assign({}, baseLogs), { message: 'Agent register - success', successful_execution: true, status: logs_types_1.LogEventStatus.SUCCESS }));
+            (_e = this.logService) === null || _e === void 0 ? void 0 : _e.publish();
+        }
+        catch (error) {
+            (_f = this.logService) === null || _f === void 0 ? void 0 : _f.add(Object.assign(Object.assign({}, baseLogs), { message: 'Agent register - failed', failed_execution: true, data: { agent: agent.tag, operation: 'register', error: String(error) }, status: logs_types_1.LogEventStatus.FAIL }));
+            await ((_g = this.logService) === null || _g === void 0 ? void 0 : _g.publish());
+            throw AgentError.executionError(`Failed to register agent: ${error}`, { agent: agent.tag });
+        }
+    }
+    // ==================== AGENT EXECUTION ====================
+    /**
+     * Run an agent
+     *
+     * @example
+     * ```ts
+     * const result = await ductape.agents.run({
+     *   product: 'my-product',
+     *   env: 'production',
+     *   tag: 'customer-support',
+     *   input: {
+     *     ticketId: 'TICKET-123',
+     *     message: 'I need help with my order',
+     *   },
+     * });
+     * ```
+     */
+    async run(options) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12;
+        const process_id = (0, processor_utils_1.generateObjectId)();
+        const startTime = Date.now();
+        // Session log fields (will be populated if session is provided)
+        let sessionLogFields = {};
+        let resolvedOptions = options;
+        // Initialize logging
+        const productBuilder = await this.getProductBuilder(options.product);
+        this.initializeLogService();
+        // Process session if provided - verify and resolve $Session{} references
+        if (options.session) {
+            const privateKey = productBuilder.fetchPrivateKey();
+            if (privateKey) {
+                const { processSessionForExecution } = await Promise.resolve().then(() => __importStar(require('../sessions')));
+                const sessionResult = await processSessionForExecution(options.session, privateKey, options, options.env, {
+                    fetchSessionSelector: async (sessionTag) => {
+                        const sessionConfig = await productBuilder.fetchSession(sessionTag);
+                        return sessionConfig === null || sessionConfig === void 0 ? void 0 : sessionConfig.selector;
+                    },
+                });
+                if (sessionResult.error) {
+                    throw AgentError.executionError(`Session validation failed: ${sessionResult.error}`);
+                }
+                resolvedOptions = sessionResult.input;
+                sessionLogFields = sessionResult.logFields;
+            }
+        }
+        const baseLogs = Object.assign({ product_tag: options.product, workspace_id: ((_a = this.config) === null || _a === void 0 ? void 0 : _a.workspace_id) || '', env: options.env, process_id, type: logs_types_1.LogEventTypes.WORKFLOW, parent_tag: options.tag, data: { agent: options.tag, operation: 'run' } }, sessionLogFields);
+        (_b = this.logService) === null || _b === void 0 ? void 0 : _b.add(Object.assign(Object.assign({}, baseLogs), { message: 'Agent run - initiated', status: logs_types_1.LogEventStatus.PROCESSING }));
+        try {
+            // Get agent definition - first check local, then fetch from database
+            let agent = this.localAgents.get(resolvedOptions.tag);
+            let toolRegistry = this.toolRegistries.get(resolvedOptions.tag);
+            if (!agent) {
+                // Try to fetch from database
+                const storedAgent = await productBuilder.fetchAgent(resolvedOptions.tag);
+                if (!storedAgent) {
+                    throw AgentError.notFoundError(`Agent '${resolvedOptions.tag}' not found`);
+                }
+                // Convert IProductAgent to IDefinedAgent
+                agent = this.convertProductAgentToDefinedAgent(storedAgent);
+                // Store locally for future use
+                this.localAgents.set(resolvedOptions.tag, agent);
+                // Create tool registry from stored schemas (without handlers)
+                toolRegistry = new tool_registry_1.ToolRegistry();
+                // Note: Tools from database won't have handlers - they need handlerRef or runtime registration
+                for (const tool of storedAgent.tools || []) {
+                    toolRegistry.register({
+                        tag: tool.tag,
+                        name: tool.name,
+                        description: tool.description,
+                        parameters: tool.parameters,
+                        requiresConfirmation: tool.requiresConfirmation,
+                        costEstimate: tool.costEstimate,
+                        timeout: tool.timeout,
+                        retries: tool.retries,
+                        // Handler will need to be resolved from handlerRef or provided at runtime
+                        handler: tool.handlerRef
+                            ? this.createHandlerFromRef(tool.handlerRef, resolvedOptions.product, resolvedOptions.env)
+                            : async () => { throw new Error(`No handler for tool '${tool.tag}'. Provide handlerRef or register handler at runtime.`); },
+                    });
+                }
+                this.toolRegistries.set(resolvedOptions.tag, toolRegistry);
+            }
+            if (!toolRegistry) {
+                throw AgentError.notFoundError(`Tool registry for agent '${resolvedOptions.tag}' not found`);
+            }
+            // Resolve model config from the model tag
+            const modelConfig = await productBuilder.fetchModel(agent.model);
+            if (!modelConfig) {
+                throw AgentError.notFoundError(`Model '${agent.model}' not found`);
+            }
+            // Find the env-specific config
+            const envConfig = modelConfig.envs.find(e => e.slug === resolvedOptions.env);
+            if (!envConfig) {
+                throw AgentError.configurationError(`Model '${agent.model}' has no configuration for environment '${resolvedOptions.env}'`);
+            }
+            // Decrypt API key using product private key, or resolve secret reference
+            const privateKey = productBuilder.fetchPrivateKey();
+            let apiKey = envConfig.apiKey;
+            if (apiKey) {
+                // Check if it's a secret reference
+                if ((0, secrets_1.isSecretReference)(apiKey).isSecret) {
+                    const secretsService = (0, secrets_1.getSecretsService)();
+                    if (secretsService) {
+                        const resolved = await secretsService.resolve(apiKey, { env: resolvedOptions.env });
+                        apiKey = resolved.value;
+                    }
+                    else {
+                        throw AgentError.configurationError(`Model API key contains secret reference '${apiKey}' but secrets service is not initialized. ` +
+                            `Please ensure the Ductape client is properly initialized.`);
+                    }
+                }
+                else if (privateKey) {
+                    // Try to decrypt if it's not a secret reference
+                    try {
+                        const { decrypt } = await Promise.resolve().then(() => __importStar(require('../processor/utils/processor.utils')));
+                        apiKey = decrypt(apiKey, privateKey);
+                    }
+                    catch (e) {
+                        // If decryption fails, try using the key as-is (might be unencrypted in dev)
+                        console.warn('Failed to decrypt model API key, using as-is');
+                    }
+                }
+            }
+            // Also resolve any secret references in baseUrl
+            let baseUrl = envConfig.baseUrl;
+            if (baseUrl && (0, secrets_1.isSecretReference)(baseUrl).isSecret) {
+                const secretsService = (0, secrets_1.getSecretsService)();
+                if (secretsService) {
+                    const resolved = await secretsService.resolve(baseUrl, { env: resolvedOptions.env });
+                    baseUrl = resolved.value;
+                }
+                else {
+                    throw AgentError.configurationError(`Model baseUrl contains secret reference but secrets service is not initialized.`);
+                }
+            }
+            // Get environment-specific agent config if available
+            const agentEnvConfig = (_c = agent.envs) === null || _c === void 0 ? void 0 : _c.find(e => e.slug === resolvedOptions.env);
+            // Build the resolved LLM config with overrides
+            // Precedence: model entity < agent.modelConfig < agentEnvConfig.modelConfig < resolvedOptions.modelConfig
+            const resolvedModelConfig = {
+                provider: modelConfig.provider,
+                model: modelConfig.model,
+                // Start with model entity values, then apply overrides
+                temperature: (_j = (_g = (_e = (_d = resolvedOptions.modelConfig) === null || _d === void 0 ? void 0 : _d.temperature) !== null && _e !== void 0 ? _e : (_f = agentEnvConfig === null || agentEnvConfig === void 0 ? void 0 : agentEnvConfig.modelConfig) === null || _f === void 0 ? void 0 : _f.temperature) !== null && _g !== void 0 ? _g : (_h = agent.modelConfig) === null || _h === void 0 ? void 0 : _h.temperature) !== null && _j !== void 0 ? _j : modelConfig.temperature,
+                maxTokens: (_q = (_o = (_l = (_k = resolvedOptions.modelConfig) === null || _k === void 0 ? void 0 : _k.maxTokens) !== null && _l !== void 0 ? _l : (_m = agentEnvConfig === null || agentEnvConfig === void 0 ? void 0 : agentEnvConfig.modelConfig) === null || _m === void 0 ? void 0 : _m.maxTokens) !== null && _o !== void 0 ? _o : (_p = agent.modelConfig) === null || _p === void 0 ? void 0 : _p.maxTokens) !== null && _q !== void 0 ? _q : modelConfig.maxTokens,
+                topP: (_w = (_u = (_s = (_r = resolvedOptions.modelConfig) === null || _r === void 0 ? void 0 : _r.topP) !== null && _s !== void 0 ? _s : (_t = agentEnvConfig === null || agentEnvConfig === void 0 ? void 0 : agentEnvConfig.modelConfig) === null || _t === void 0 ? void 0 : _t.topP) !== null && _u !== void 0 ? _u : (_v = agent.modelConfig) === null || _v === void 0 ? void 0 : _v.topP) !== null && _w !== void 0 ? _w : modelConfig.topP,
+                stopSequences: (_2 = (_0 = (_y = (_x = resolvedOptions.modelConfig) === null || _x === void 0 ? void 0 : _x.stopSequences) !== null && _y !== void 0 ? _y : (_z = agentEnvConfig === null || agentEnvConfig === void 0 ? void 0 : agentEnvConfig.modelConfig) === null || _z === void 0 ? void 0 : _z.stopSequences) !== null && _0 !== void 0 ? _0 : (_1 = agent.modelConfig) === null || _1 === void 0 ? void 0 : _1.stopSequences) !== null && _2 !== void 0 ? _2 : modelConfig.stopSequences,
+                timeout: (_8 = (_6 = (_4 = (_3 = resolvedOptions.modelConfig) === null || _3 === void 0 ? void 0 : _3.timeout) !== null && _4 !== void 0 ? _4 : (_5 = agentEnvConfig === null || agentEnvConfig === void 0 ? void 0 : agentEnvConfig.modelConfig) === null || _5 === void 0 ? void 0 : _5.timeout) !== null && _6 !== void 0 ? _6 : (_7 = agent.modelConfig) === null || _7 === void 0 ? void 0 : _7.timeout) !== null && _8 !== void 0 ? _8 : modelConfig.timeout,
+                apiKey,
+                baseUrl,
+            };
+            // Create executor with resolved model config
+            const executor = new agent_executor_1.AgentExecutor(agent, toolRegistry, this.getContextServices(agent.resilience), resolvedOptions, (0, agent_executor_1.createLLMProvider)(resolvedModelConfig), resolvedModelConfig);
+            // Store executor for signal handling
+            const executionId = executor.getState().execution_id;
+            this.activeExecutors.set(executionId, executor);
+            // Execute agent
+            const result = await executor.execute();
+            // Cleanup
+            this.activeExecutors.delete(executionId);
+            (_9 = this.logService) === null || _9 === void 0 ? void 0 : _9.add(Object.assign(Object.assign({}, baseLogs), { message: 'Agent run - success', successful_execution: result.status === 'completed', failed_execution: result.status === 'failed', data: {
+                    agent: resolvedOptions.tag,
+                    operation: 'run',
+                    execution_id: result.execution_id,
+                    iterations: result.iterations,
+                    status: result.status,
+                }, status: result.status === 'completed' ? logs_types_1.LogEventStatus.SUCCESS : logs_types_1.LogEventStatus.FAIL }));
+            (_10 = this.logService) === null || _10 === void 0 ? void 0 : _10.publish();
+            return result;
+        }
+        catch (error) {
+            (_11 = this.logService) === null || _11 === void 0 ? void 0 : _11.add(Object.assign(Object.assign({}, baseLogs), { message: 'Agent run - failed', failed_execution: true, data: { agent: resolvedOptions.tag, operation: 'run', error: String(error) }, status: logs_types_1.LogEventStatus.FAIL }));
+            await ((_12 = this.logService) === null || _12 === void 0 ? void 0 : _12.publish());
+            throw AgentError.executionError(`Failed to run agent: ${error}`, { agent: resolvedOptions.tag });
+        }
+    }
+    // ==================== DISPATCH (SCHEDULED EXECUTION) ====================
+    /**
+     * Dispatch an agent for scheduled or deferred execution
+     *
+     * @example
+     * ```ts
+     * const job = await ductape.agents.dispatch({
+     *   product: 'my-product',
+     *   env: 'production',
+     *   agent: 'daily-report-agent',
+     *   input: { reportType: 'daily' },
+     *   schedule: { cron: '0 9 * * *' }, // Daily at 9 AM
+     * });
+     * ```
+     */
+    async dispatch(options) {
+        var _a, _b, _c, _d, _e, _f;
+        const process_id = (0, processor_utils_1.generateObjectId)();
+        const processorService = this.createNewProcessor();
+        const productBuilder = await this.getProductBuilder(options.product);
+        const schedule = options.schedule || {};
+        const startAt = typeof schedule.start_at === 'string'
+            ? new Date(schedule.start_at).getTime()
+            : schedule.start_at || Date.now();
+        const jobTag = `agent:${options.agent}`;
+        // Initialize logging
+        this.initializeLogService();
+        const baseLogs = {
+            product_tag: options.product,
+            workspace_id: ((_a = this.config) === null || _a === void 0 ? void 0 : _a.workspace_id) || '',
+            env: options.env,
+            process_id,
+            type: logs_types_1.LogEventTypes.WORKFLOW,
+            parent_tag: options.agent,
+            data: { agent: options.agent, operation: 'dispatch' },
+        };
+        (_b = this.logService) === null || _b === void 0 ? void 0 : _b.add(Object.assign(Object.assign({}, baseLogs), { message: 'Agent dispatch - initiated', status: logs_types_1.LogEventStatus.PROCESSING }));
+        try {
+            // Check if job exists, if not create it
+            const existingJob = await productBuilder.fetchJob(jobTag);
+            if (!existingJob) {
+                await productBuilder.createJob({
+                    tag: jobTag,
+                    name: `Agent: ${options.agent}`,
+                    description: `Auto-created job for agent ${options.agent}`,
+                    type: productsBuilder_types_1.JobEventTypes.ACTION, // Agent executions are actions
+                    app: options.agent,
+                    event: 'execute',
+                    executions: 0,
+                    intervals: schedule.every || 0,
+                    start_at: startAt,
+                });
+            }
+            const jobInput = {
+                product: options.product,
+                env: options.env,
+                event: jobTag,
+                input: options.input,
+                retries: options.retries || 0,
+                start_at: startAt,
+                session: options.session,
+                cache: options.cache,
+                repeat: schedule.cron || schedule.every
+                    ? {
+                        cron: schedule.cron,
+                        every: schedule.every,
+                        limit: schedule.limit,
+                        endDate: schedule.endDate,
+                        tz: schedule.tz,
+                    }
+                    : undefined,
+            };
+            await processorService.processJob(jobInput);
+            const isRecurring = !!(schedule.cron || schedule.every);
+            let nextRunAt;
+            if (isRecurring && schedule.every) {
+                nextRunAt = startAt + schedule.every;
+            }
+            const job_id = (0, crypto_1.randomUUID)();
+            (_c = this.logService) === null || _c === void 0 ? void 0 : _c.add(Object.assign(Object.assign({}, baseLogs), { message: 'Agent dispatch - success', successful_execution: true, data: { agent: options.agent, operation: 'dispatch', job_id }, status: logs_types_1.LogEventStatus.SUCCESS }));
+            (_d = this.logService) === null || _d === void 0 ? void 0 : _d.publish();
+            return {
+                job_id,
+                status: startAt > Date.now() ? 'scheduled' : 'queued',
+                scheduled_at: startAt,
+                recurring: isRecurring,
+                next_run_at: nextRunAt,
+            };
+        }
+        catch (error) {
+            (_e = this.logService) === null || _e === void 0 ? void 0 : _e.add(Object.assign(Object.assign({}, baseLogs), { message: 'Agent dispatch - failed', failed_execution: true, data: { agent: options.agent, operation: 'dispatch', error: String(error) }, status: logs_types_1.LogEventStatus.FAIL }));
+            await ((_f = this.logService) === null || _f === void 0 ? void 0 : _f.publish());
+            throw error;
+        }
+    }
+    // ==================== SIGNALS ====================
+    /**
+     * Send a signal to a running agent
+     *
+     * @example
+     * ```ts
+     * // Stop an agent
+     * await ductape.agents.signal({
+     *   product: 'my-product',
+     *   env: 'production',
+     *   execution_id: 'exec-123',
+     *   signal: 'stop',
+     * });
+     *
+     * // Approve a tool call
+     * await ductape.agents.signal({
+     *   product: 'my-product',
+     *   env: 'production',
+     *   execution_id: 'exec-123',
+     *   signal: 'approve',
+     *   payload: { toolCallId: 'tc-456' },
+     * });
+     * ```
+     */
+    async signal(options) {
+        const executor = this.activeExecutors.get(options.execution_id);
+        if (!executor) {
+            throw AgentError.notFoundError(`Agent execution '${options.execution_id}' not found or not active`);
+        }
+        switch (options.signal) {
+            case 'stop':
+                executor.handleStop();
+                break;
+            case 'pause':
+                executor.handlePause();
+                break;
+            case 'resume':
+                executor.handleResume();
+                break;
+            case 'approve':
+                executor.handleApproval(true, options.payload);
+                break;
+            case 'reject':
+                executor.handleApproval(false);
+                break;
+            default:
+                throw AgentError.validationError(`Unknown signal: ${options.signal}`);
+        }
+    }
+    // ==================== STATUS ====================
+    /**
+     * Get the status of an agent execution
+     *
+     * @example
+     * ```ts
+     * const status = await ductape.agents.status({
+     *   product: 'my-product',
+     *   env: 'production',
+     *   execution_id: 'exec-123',
+     * });
+     * ```
+     */
+    async status(options) {
+        const executor = this.activeExecutors.get(options.execution_id);
+        if (!executor) {
+            // Could query from database for completed executions
+            return null;
+        }
+        return executor.getState();
+    }
+    /**
+     * List agent executions
+     *
+     * @example
+     * ```ts
+     * const executions = await ductape.agents.list({
+     *   product: 'my-product',
+     *   env: 'production',
+     *   agent: 'customer-support',
+     *   status: 'completed',
+     *   limit: 10,
+     * });
+     * ```
+     */
+    async list(options) {
+        // For now, return active executions
+        // In production, would query from database
+        const executions = [];
+        for (const [executionId, executor] of this.activeExecutors) {
+            const state = executor.getState();
+            // Apply filters
+            if (options.agent && state.agent_tag !== options.agent) {
+                continue;
+            }
+            if (options.status) {
+                const statuses = Array.isArray(options.status) ? options.status : [options.status];
+                if (!statuses.includes(state.status)) {
+                    continue;
+                }
+            }
+            executions.push({
+                execution_id: state.execution_id,
+                agent_tag: state.agent_tag,
+                status: state.status,
+                startedAt: state.startedAt,
+                completedAt: state.status !== 'running' ? state.updatedAt : undefined,
+                iterations: state.iteration,
+                usage: state.usage,
+            });
+        }
+        // Pagination
+        const page = options.page || 1;
+        const limit = options.limit || 10;
+        const start = (page - 1) * limit;
+        const paginatedExecutions = executions.slice(start, start + limit);
+        return {
+            executions: paginatedExecutions,
+            total: executions.length,
+            page,
+            limit,
+        };
+    }
+    // ==================== TOOL MANAGEMENT ====================
+    /**
+     * Add a tool to an agent
+     *
+     * @example
+     * ```ts
+     * await ductape.agents.addTool('customer-support', {
+     *   tag: 'new-tool',
+     *   description: 'A new tool',
+     *   parameters: { ... },
+     *   handler: async (ctx, params) => { ... },
+     * });
+     * ```
+     */
+    addTool(agentTag, tool) {
+        const registry = this.toolRegistries.get(agentTag);
+        if (!registry) {
+            throw AgentError.notFoundError(`Agent '${agentTag}' not found`);
+        }
+        registry.register(tool);
+        // Update agent definition
+        const agent = this.localAgents.get(agentTag);
+        if (agent) {
+            agent.toolSchemas = registry.getSchemas();
+        }
+    }
+    /**
+     * Remove a tool from an agent
+     */
+    removeTool(agentTag, toolTag) {
+        const registry = this.toolRegistries.get(agentTag);
+        if (!registry) {
+            return false;
+        }
+        const removed = registry.unregister(toolTag);
+        // Update agent definition
+        if (removed) {
+            const agent = this.localAgents.get(agentTag);
+            if (agent) {
+                agent.toolSchemas = registry.getSchemas();
+            }
+        }
+        return removed;
+    }
+    /**
+     * Get tools for an agent
+     */
+    getTools(agentTag) {
+        const registry = this.toolRegistries.get(agentTag);
+        if (!registry) {
+            return [];
+        }
+        return registry.getSchemas();
+    }
+    // ==================== AGENT AS TOOL ====================
+    /**
+     * Convert an agent into a tool that can be used by another agent
+     *
+     * This enables multi-agent orchestration where a "manager" agent can
+     * delegate tasks to specialized agents.
+     *
+     * @example
+     * ```ts
+     * // Define specialized agents
+     * const researchAgent = await ductape.agents.define({
+     *   tag: 'research-agent',
+     *   name: 'Research Agent',
+     *   // ...
+     * });
+     *
+     * const writerAgent = await ductape.agents.define({
+     *   tag: 'writer-agent',
+     *   name: 'Writer Agent',
+     *   // ...
+     * });
+     *
+     * // Create a manager agent that can delegate to specialists
+     * const managerAgent = await ductape.agents.define({
+     *   tag: 'manager-agent',
+     *   name: 'Project Manager',
+     *   tools: [
+     *     ductape.agents.asTool({
+     *       agentTag: 'research-agent',
+     *       product: 'my-product',
+     *       options: {
+     *         toolDescription: 'Delegate research tasks to the research specialist',
+     *       },
+     *     }),
+     *     ductape.agents.asTool({
+     *       agentTag: 'writer-agent',
+     *       product: 'my-product',
+     *       options: {
+     *         toolDescription: 'Delegate writing tasks to the writing specialist',
+     *       },
+     *     }),
+     *   ],
+     * });
+     * ```
+     */
+    asTool(definition) {
+        const { agentTag, product, env, options = {} } = definition;
+        // Get the agent definition to extract metadata
+        const agent = this.localAgents.get(agentTag);
+        // Build input schema - either from options or use a generic input schema
+        const inputSchema = options.inputSchema || {
+            task: {
+                type: 'string',
+                description: 'The task or instruction to give to the agent',
+                required: true,
+            },
+            context: {
+                type: 'object',
+                description: 'Additional context or data to pass to the agent',
+            },
+        };
+        // Create the tool
+        const tool = {
+            tag: options.toolTag || `agent:${agentTag}`,
+            name: options.toolName || (agent === null || agent === void 0 ? void 0 : agent.name) || agentTag,
+            description: options.toolDescription ||
+                (agent === null || agent === void 0 ? void 0 : agent.description) ||
+                `Delegate task to the ${agentTag} agent`,
+            parameters: inputSchema,
+            requiresConfirmation: options.requiresConfirmation,
+            timeout: options.timeout,
+            retries: options.retries,
+            handler: async (ctx, params) => {
+                var _a;
+                // Transform input if transformer provided
+                const input = options.inputTransform
+                    ? options.inputTransform(params)
+                    : params;
+                // Build the input message for the sub-agent
+                const inputMessage = typeof input === 'string'
+                    ? input
+                    : input.task ||
+                        JSON.stringify(input);
+                // Run the sub-agent
+                // When delegating to sub-agent, append agent tag to session for traceability
+                const subAgentSession = ctx.session ? `${ctx.session}:${agentTag}` : undefined;
+                const result = await this.run({
+                    product,
+                    env: env || ctx.env,
+                    tag: agentTag,
+                    input: typeof inputMessage === 'string' ? { message: inputMessage } : inputMessage,
+                    session: subAgentSession,
+                });
+                // Transform output if transformer provided
+                if (options.outputTransform) {
+                    return options.outputTransform(result);
+                }
+                // Return full details or just output based on options
+                if (options.includeDetails) {
+                    return {
+                        agent: agentTag,
+                        status: result.status,
+                        output: result.output,
+                        iterations: result.iterations,
+                        toolCalls: (_a = result.toolCalls) === null || _a === void 0 ? void 0 : _a.map((tc) => ({
+                            tool: tc.tool,
+                            success: tc.success,
+                        })),
+                        executionTime: result.executionTime,
+                    };
+                }
+                // Default: return just the output
+                return result.output;
+            },
+        };
+        return tool;
+    }
+    /**
+     * Create an agent tool from a handlerRef string
+     *
+     * @example
+     * ```ts
+     * // In tool definition
+     * {
+     *   tag: 'delegate-research',
+     *   handlerRef: 'agent:research-agent',
+     * }
+     * ```
+     */
+    createAgentToolFromRef(handlerRef, product, env) {
+        // Parse handlerRef: "agent:agent-tag" or "agent:agent-tag:options"
+        const parts = handlerRef.split(':');
+        if (parts[0] !== 'agent') {
+            throw AgentError.validationError(`Invalid agent handlerRef format: ${handlerRef}. Expected "agent:agent-tag"`);
+        }
+        const agentTag = parts[1];
+        return async (ctx, params) => {
+            const input = typeof params === 'string'
+                ? params
+                : params.task || JSON.stringify(params);
+            // When delegating to sub-agent, append agent tag to session for traceability
+            const subAgentSession = ctx.session ? `${ctx.session}:${agentTag}` : undefined;
+            const result = await this.run({
+                product,
+                env,
+                tag: agentTag,
+                input: typeof input === 'string' ? { message: input } : input,
+                session: subAgentSession,
+            });
+            return result.output;
+        };
+    }
+    // ==================== UTILITIES ====================
+    /**
+     * Get a defined agent by tag
+     */
+    getAgent(tag) {
+        return this.localAgents.get(tag);
+    }
+    /**
+     * List all defined agents
+     */
+    listAgents() {
+        return Array.from(this.localAgents.values());
+    }
+    /**
+     * Delete an agent definition
+     */
+    deleteAgent(tag) {
+        this.toolRegistries.delete(tag);
+        return this.localAgents.delete(tag);
+    }
+    /**
+     * Clear all agent definitions
+     */
+    clearAll() {
+        this.localAgents.clear();
+        this.toolRegistries.clear();
+        this.activeExecutors.clear();
+    }
+    // ==================== PRIVATE HELPERS ====================
+    /**
+     * Convert a stored IProductAgent to IDefinedAgent format
+     */
+    convertProductAgentToDefinedAgent(storedAgent) {
+        var _a;
+        return {
+            tag: storedAgent.tag,
+            name: storedAgent.name,
+            description: storedAgent.description,
+            model: storedAgent.model, // Model tag reference - resolved at runtime
+            modelConfig: storedAgent.modelConfig,
+            systemPrompt: storedAgent.systemPrompt,
+            toolSchemas: (storedAgent.tools || []).map((tool) => ({
+                tag: tool.tag,
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.parameters,
+                requiresConfirmation: tool.requiresConfirmation,
+                costEstimate: tool.costEstimate,
+                timeout: tool.timeout,
+                retries: tool.retries,
+            })),
+            termination: storedAgent.termination ? {
+                maxIterations: storedAgent.termination.maxIterations,
+                maxTokens: storedAgent.termination.maxTokens,
+                timeout: storedAgent.termination.timeout,
+                allowManualStop: storedAgent.termination.allowManualStop,
+            } : undefined,
+            memory: storedAgent.memory ? {
+                shortTerm: storedAgent.memory.shortTerm,
+                longTerm: storedAgent.memory.longTerm,
+            } : undefined,
+            humanInLoop: storedAgent.humanInLoop ? {
+                enabled: storedAgent.humanInLoop.enabled,
+                alwaysRequireApproval: storedAgent.humanInLoop.alwaysRequireApproval,
+                approvalTimeout: storedAgent.humanInLoop.approvalTimeout,
+                approvalWebhook: storedAgent.humanInLoop.approvalWebhook,
+                approvalBroker: storedAgent.humanInLoop.approvalBroker,
+            } : undefined,
+            streaming: storedAgent.streaming ? {
+                enabled: storedAgent.streaming.enabled,
+                events: storedAgent.streaming.events,
+                webhook: storedAgent.streaming.webhook,
+                broker: storedAgent.streaming.broker,
+            } : undefined,
+            inputSchema: storedAgent.inputSchema,
+            envs: (_a = storedAgent.envs) === null || _a === void 0 ? void 0 : _a.map((env) => ({
+                slug: env.slug,
+                active: env.active,
+                model: env.model, // Model tag override - resolved at runtime
+                modelConfig: env.modelConfig,
+                toolOverrides: env.toolOverrides,
+            })),
+            resilience: storedAgent.resilience,
+        };
+    }
+    /**
+     * Create a handler function from a handlerRef string
+     * Format: "type:tag:event" (e.g., "action:payment-app:process-payment", "feature:checkout-flow")
+     */
+    createHandlerFromRef(handlerRef, product, env) {
+        const parts = handlerRef.split(':');
+        const type = parts[0];
+        const tag = parts[1];
+        const event = parts[2];
+        return async (ctx, params) => {
+            switch (type) {
+                case 'action':
+                    return ctx.action.run({
+                        app: tag,
+                        event,
+                        input: params,
+                    });
+                case 'feature':
+                    return ctx.feature.run({
+                        feature: tag,
+                        input: params,
+                    });
+                case 'database':
+                    return ctx.database.execute({
+                        database: tag,
+                        event,
+                        input: params,
+                    });
+                case 'graph':
+                    return ctx.graph.execute({
+                        graph: tag,
+                        action: event,
+                        input: params,
+                    });
+                case 'storage':
+                    return ctx.storage.upload({
+                        storage: tag,
+                        event,
+                        input: params,
+                    });
+                case 'notification':
+                    await ctx.notification.send({
+                        notification: tag,
+                        event,
+                        input: params,
+                    });
+                    return { success: true };
+                case 'publish':
+                    await ctx.messaging.produce({
+                        event: `${tag}:${event}`,
+                        message: (params || {}),
+                    });
+                    return { success: true };
+                case 'agent':
+                    // Delegate to another agent
+                    // Format: "agent:agent-tag"
+                    const input = typeof params === 'string'
+                        ? params
+                        : params.task || JSON.stringify(params);
+                    // When delegating to sub-agent, append agent tag to session for traceability
+                    const subAgentSession = ctx.session ? `${ctx.session}:${tag}` : undefined;
+                    const result = await this.run({
+                        product,
+                        env,
+                        tag,
+                        input: typeof input === 'string' ? { message: input } : input,
+                        session: subAgentSession,
+                    });
+                    return result.output;
+                default:
+                    throw new Error(`Unknown handler type: ${type}`);
+            }
+        };
+    }
+}
+exports.AgentsService = AgentsService;
+// Export singleton instance for convenience
+exports.agentsService = new AgentsService();
+// Default export
+exports.default = AgentsService;
+//# sourceMappingURL=agents.service.js.map