@ductape/sdk 0.0.4-v51 → 0.0.4-v53

package/README.md

@@ -2,7 +2,7 @@
 
 ### **Simplifying Product Development with Seamless Interoperability**  
 
-Ductape streamlines software development with **composable** and **portable** components that unify services, enable interoperability, and ensure consistency all from your codebase.  
+Ductape streamlines software development with **composable** and **portable** components that unify services, enable interoperability, and ensure consistency—all from your codebase.  
 
 ## 🚀 Why Ductape?  
 

package/dist/agents/agent-context.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Agent Context
+ *
+ * Provides context to agent tool handlers, including access to
+ * Ductape components (actions, database, graph, etc.) and state management.
+ */
+import { IAgentToolContext, IAgentActionContext, IAgentDatabaseContext, IAgentGraphContext, IAgentNotificationContext, IAgentStorageContext, IAgentPublishContext, IAgentFeatureContext, IAgentResilienceContext, IAgentResilienceConfig, IAgentLogger, IConversationMessage, IToolCallResult, IMemoryResult, IAgentState } from './types';
+import { IAgentServiceConfig } from './types';
+/**
+ * Memory adapter interface
+ * Allows pluggable memory implementations (in-memory, vector store, etc.)
+ */
+export interface IMemoryAdapter {
+    /** Store content with metadata */
+    store(content: string, metadata?: Record<string, unknown>): Promise<void>;
+    /** Retrieve similar content */
+    retrieve(query: string, topK?: number): Promise<IMemoryResult[]>;
+    /** Clear memory */
+    clear(): Promise<void>;
+}
+/**
+ * In-memory adapter (fallback when vector store not available)
+ */
+export declare class InMemoryAdapter implements IMemoryAdapter {
+    private memories;
+    store(content: string, metadata?: Record<string, unknown>): Promise<void>;
+    retrieve(query: string, topK?: number): Promise<IMemoryResult[]>;
+    clear(): Promise<void>;
+}
+/**
+ * Service references for context
+ */
+export interface IAgentContextServices {
+    config: IAgentServiceConfig;
+    processorService?: any;
+    productBuilder?: any;
+    databaseService?: any;
+    graphService?: any;
+    storageService?: any;
+    brokersService?: any;
+    resilienceService?: any;
+    /** Agent resilience configuration */
+    resilienceConfig?: IAgentResilienceConfig;
+}
+/**
+ * Agent Context Implementation
+ *
+ * Provides the execution context for agent tool handlers,
+ * wrapping Ductape services and managing state.
+ */
+export declare class AgentContext implements IAgentToolContext {
+    private _state;
+    private _customState;
+    private _services;
+    private _memoryAdapter;
+    private _session?;
+    readonly action: IAgentActionContext;
+    readonly database: IAgentDatabaseContext;
+    readonly graph: IAgentGraphContext;
+    readonly notification: IAgentNotificationContext;
+    readonly storage: IAgentStorageContext;
+    readonly publish: IAgentPublishContext;
+    readonly feature: IAgentFeatureContext;
+    readonly resilience: IAgentResilienceContext;
+    readonly log: IAgentLogger;
+    constructor(state: IAgentState, services: IAgentContextServices, memoryAdapter?: IMemoryAdapter, session?: string);
+    get input(): Record<string, unknown>;
+    get execution_id(): string;
+    get agent_tag(): string;
+    get env(): string;
+    get product(): string;
+    get iteration(): number;
+    get session(): string | undefined;
+    getConversationHistory(): IConversationMessage[];
+    getToolCallHistory(): IToolCallResult[];
+    setState(key: string, value: unknown): void;
+    getState<T>(key: string): T | undefined;
+    remember(content: string, metadata?: Record<string, unknown>): Promise<void>;
+    recall(query: string, topK?: number): Promise<IMemoryResult[]>;
+    private createActionContext;
+    private createDatabaseContext;
+    private createGraphContext;
+    private createNotificationContext;
+    private createStorageContext;
+    private createPublishContext;
+    private createFeatureContext;
+    private createResilienceContext;
+    private createLogger;
+    /**
+     * Update internal state (called by AgentExecutor)
+     */
+    updateState(updates: Partial<IAgentState>): void;
+    /**
+     * Get current state snapshot
+     */
+    getStateSnapshot(): IAgentState;
+}
+export default AgentContext;

package/dist/agents/agent-context.js

@@ -0,0 +1,588 @@
+"use strict";
+/**
+ * Agent Context
+ *
+ * Provides context to agent tool handlers, including access to
+ * Ductape components (actions, database, graph, etc.) and state management.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentContext = exports.InMemoryAdapter = void 0;
+/**
+ * In-memory adapter (fallback when vector store not available)
+ */
+class InMemoryAdapter {
+    constructor() {
+        this.memories = [];
+    }
+    async store(content, metadata) {
+        this.memories.push({ content, metadata });
+    }
+    async retrieve(query, topK = 5) {
+        // Simple keyword matching (basic fallback)
+        const queryLower = query.toLowerCase();
+        const scored = this.memories.map((m) => {
+            const contentLower = m.content.toLowerCase();
+            const words = queryLower.split(/\s+/);
+            const matches = words.filter((w) => contentLower.includes(w)).length;
+            const similarity = words.length > 0 ? matches / words.length : 0;
+            return { content: m.content, metadata: m.metadata, similarity };
+        });
+        return scored
+            .filter((m) => m.similarity > 0)
+            .sort((a, b) => b.similarity - a.similarity)
+            .slice(0, topK);
+    }
+    async clear() {
+        this.memories = [];
+    }
+}
+exports.InMemoryAdapter = InMemoryAdapter;
+/**
+ * Agent Context Implementation
+ *
+ * Provides the execution context for agent tool handlers,
+ * wrapping Ductape services and managing state.
+ */
+class AgentContext {
+    constructor(state, services, memoryAdapter, session) {
+        this._customState = {};
+        this._state = state;
+        this._services = services;
+        this._memoryAdapter = memoryAdapter || new InMemoryAdapter();
+        this._session = session;
+        // Initialize component contexts
+        this.action = this.createActionContext();
+        this.database = this.createDatabaseContext();
+        this.graph = this.createGraphContext();
+        this.notification = this.createNotificationContext();
+        this.storage = this.createStorageContext();
+        this.publish = this.createPublishContext();
+        this.feature = this.createFeatureContext();
+        this.resilience = this.createResilienceContext();
+        this.log = this.createLogger();
+    }
+    // ==================== READ-ONLY PROPERTIES ====================
+    get input() {
+        return Object.freeze(Object.assign({}, this._state.input));
+    }
+    get execution_id() {
+        return this._state.execution_id;
+    }
+    get agent_tag() {
+        return this._state.agent_tag;
+    }
+    get env() {
+        return this._services.config.env || '';
+    }
+    get product() {
+        return this._services.config.product || '';
+    }
+    get iteration() {
+        return this._state.iteration;
+    }
+    get session() {
+        return this._session;
+    }
+    // ==================== CONVERSATION & TOOL HISTORY ====================
+    getConversationHistory() {
+        return [...this._state.conversation];
+    }
+    getToolCallHistory() {
+        return [...this._state.toolCalls];
+    }
+    // ==================== STATE MANAGEMENT ====================
+    setState(key, value) {
+        this._customState[key] = value;
+        this._state.data[key] = value;
+    }
+    getState(key) {
+        return this._customState[key];
+    }
+    // ==================== MEMORY OPERATIONS ====================
+    async remember(content, metadata) {
+        await this._memoryAdapter.store(content, Object.assign(Object.assign({}, metadata), { execution_id: this.execution_id, agent_tag: this.agent_tag, timestamp: Date.now() }));
+    }
+    async recall(query, topK = 5) {
+        return this._memoryAdapter.retrieve(query, topK);
+    }
+    // ==================== COMPONENT CONTEXT FACTORIES ====================
+    createActionContext() {
+        const services = this._services;
+        return {
+            async run(options) {
+                if (!services.processorService) {
+                    throw new Error('ProcessorService not available. Cannot execute actions.');
+                }
+                // Use ProcessorService to run action
+                const result = await services.processorService.processAction({
+                    product: services.config.product,
+                    env: services.config.env,
+                    app: options.app,
+                    event: options.event,
+                    input: options.input,
+                    retries: options.retries || 0,
+                });
+                return result;
+            },
+        };
+    }
+    createDatabaseContext() {
+        const services = this._services;
+        return {
+            async execute(options) {
+                if (!services.databaseService) {
+                    throw new Error('DatabaseService not available. Cannot execute database operations.');
+                }
+                const result = await services.databaseService.execute({
+                    product: services.config.product,
+                    env: services.config.env,
+                    database: options.database,
+                    event: options.event,
+                    input: options.input,
+                });
+                return result;
+            },
+            async query(options) {
+                if (!services.databaseService) {
+                    throw new Error('DatabaseService not available. Cannot execute database queries.');
+                }
+                const result = await services.databaseService.execute({
+                    product: services.config.product,
+                    env: services.config.env,
+                    database: options.database,
+                    event: options.event,
+                    input: { params: options.params },
+                });
+                return Array.isArray(result) ? result : [result];
+            },
+            async insert(options) {
+                if (!services.databaseService) {
+                    throw new Error('DatabaseService not available. Cannot execute database inserts.');
+                }
+                const result = await services.databaseService.execute({
+                    product: services.config.product,
+                    env: services.config.env,
+                    database: options.database,
+                    event: options.event,
+                    input: { body: options.data },
+                });
+                return result;
+            },
+            async update(options) {
+                if (!services.databaseService) {
+                    throw new Error('DatabaseService not available. Cannot execute database updates.');
+                }
+                const result = await services.databaseService.execute({
+                    product: services.config.product,
+                    env: services.config.env,
+                    database: options.database,
+                    event: options.event,
+                    input: { body: options.data, params: options.where },
+                });
+                return result;
+            },
+            async delete(options) {
+                if (!services.databaseService) {
+                    throw new Error('DatabaseService not available. Cannot execute database deletes.');
+                }
+                await services.databaseService.execute({
+                    product: services.config.product,
+                    env: services.config.env,
+                    database: options.database,
+                    event: options.event,
+                    input: { params: options.where },
+                });
+                return true;
+            },
+        };
+    }
+    createGraphContext() {
+        const services = this._services;
+        return {
+            async execute(options) {
+                if (!services.graphService) {
+                    throw new Error('GraphService not available. Cannot execute graph operations.');
+                }
+                const result = await services.graphService.execute({
+                    product: services.config.product,
+                    env: services.config.env,
+                    graph: options.graph,
+                    action: options.action,
+                    input: options.input,
+                });
+                return result.data;
+            },
+            async createNode(options) {
+                if (!services.graphService) {
+                    throw new Error('GraphService not available. Cannot create graph nodes.');
+                }
+                const result = await services.graphService.createNode({
+                    labels: options.labels,
+                    properties: options.properties,
+                });
+                return result.node;
+            },
+            async updateNode(options) {
+                if (!services.graphService) {
+                    throw new Error('GraphService not available. Cannot update graph nodes.');
+                }
+                const result = await services.graphService.updateNode({
+                    id: options.id,
+                    properties: options.properties,
+                });
+                return result.node;
+            },
+            async deleteNode(options) {
+                if (!services.graphService) {
+                    throw new Error('GraphService not available. Cannot delete graph nodes.');
+                }
+                await services.graphService.deleteNode({ id: options.id });
+            },
+            async createRelationship(options) {
+                if (!services.graphService) {
+                    throw new Error('GraphService not available. Cannot create relationships.');
+                }
+                const result = await services.graphService.createRelationship({
+                    from: { id: options.from },
+                    to: { id: options.to },
+                    type: options.type,
+                    properties: options.properties,
+                });
+                return result.relationship;
+            },
+            async traverse(options) {
+                if (!services.graphService) {
+                    throw new Error('GraphService not available. Cannot traverse graph.');
+                }
+                const result = await services.graphService.traverse({
+                    startNodeId: options.startNodeId,
+                    direction: options.direction,
+                    relationshipTypes: options.relationshipTypes,
+                    maxDepth: options.maxDepth,
+                });
+                return result;
+            },
+            async query(options) {
+                if (!services.graphService) {
+                    throw new Error('GraphService not available. Cannot query graph.');
+                }
+                const result = await services.graphService.execute({
+                    product: services.config.product,
+                    env: services.config.env,
+                    graph: options.graph,
+                    action: options.action,
+                    input: options.params || {},
+                });
+                return result.data;
+            },
+        };
+    }
+    createNotificationContext() {
+        const services = this._services;
+        return {
+            async send(options) {
+                if (!services.processorService) {
+                    throw new Error('ProcessorService not available. Cannot send notifications.');
+                }
+                await services.processorService.processNotification({
+                    product: services.config.product,
+                    env: services.config.env,
+                    notification: options.notification,
+                    event: options.event,
+                    input: options.input,
+                    retries: options.retries || 0,
+                });
+            },
+            async email(options) {
+                if (!services.processorService) {
+                    throw new Error('ProcessorService not available. Cannot send emails.');
+                }
+                await services.processorService.processNotification({
+                    product: services.config.product,
+                    env: services.config.env,
+                    notification: options.notification,
+                    event: options.event,
+                    input: {
+                        recipients: options.recipients,
+                        subject: options.subject,
+                        template: options.template,
+                    },
+                });
+            },
+            async push(options) {
+                if (!services.processorService) {
+                    throw new Error('ProcessorService not available. Cannot send push notifications.');
+                }
+                await services.processorService.processNotification({
+                    product: services.config.product,
+                    env: services.config.env,
+                    notification: options.notification,
+                    event: options.event,
+                    input: {
+                        tokens: options.tokens,
+                        title: options.title,
+                        body: options.body,
+                        data: options.data,
+                    },
+                });
+            },
+            async sms(options) {
+                if (!services.processorService) {
+                    throw new Error('ProcessorService not available. Cannot send SMS.');
+                }
+                await services.processorService.processNotification({
+                    product: services.config.product,
+                    env: services.config.env,
+                    notification: options.notification,
+                    event: options.event,
+                    input: {
+                        phones: options.phones,
+                        message: options.message,
+                    },
+                });
+            },
+        };
+    }
+    createStorageContext() {
+        const services = this._services;
+        return {
+            async upload(options) {
+                if (!services.storageService) {
+                    throw new Error('StorageService not available. Cannot upload files.');
+                }
+                const result = await services.storageService.upload({
+                    product: services.config.product,
+                    env: services.config.env,
+                    storage: options.storage,
+                    event: options.event,
+                    input: options.input,
+                });
+                return result;
+            },
+            async download(options) {
+                if (!services.storageService) {
+                    throw new Error('StorageService not available. Cannot download files.');
+                }
+                const result = await services.storageService.download({
+                    product: services.config.product,
+                    env: services.config.env,
+                    storage: options.storage,
+                    event: options.event,
+                    input: options.input,
+                });
+                return result;
+            },
+            async delete(options) {
+                if (!services.storageService) {
+                    throw new Error('StorageService not available. Cannot delete files.');
+                }
+                await services.storageService.delete({
+                    product: services.config.product,
+                    env: services.config.env,
+                    storage: options.storage,
+                    event: options.event,
+                    input: options.input,
+                });
+            },
+        };
+    }
+    createPublishContext() {
+        const services = this._services;
+        return {
+            async send(options) {
+                if (!services.brokersService) {
+                    throw new Error('BrokersService not available. Cannot publish messages.');
+                }
+                await services.brokersService.publish({
+                    product: services.config.product,
+                    env: services.config.env,
+                    broker: options.broker,
+                    event: options.event,
+                    input: options.input,
+                });
+            },
+        };
+    }
+    createFeatureContext() {
+        const services = this._services;
+        return {
+            async run(options) {
+                if (!services.processorService) {
+                    throw new Error('ProcessorService not available. Cannot run features.');
+                }
+                const result = await services.processorService.processFeature({
+                    product: services.config.product,
+                    env: services.config.env,
+                    feature: options.feature,
+                    input: options.input,
+                    retries: options.retries || 0,
+                });
+                return result;
+            },
+        };
+    }
+    createResilienceContext() {
+        const services = this._services;
+        const resilienceConfig = services.resilienceConfig;
+        // Collect all referenced healthcheck tags from the agent config
+        const getReferencedHealthchecks = () => {
+            var _a;
+            const tags = new Set();
+            // Add default healthcheck
+            if ((_a = resilienceConfig === null || resilienceConfig === void 0 ? void 0 : resilienceConfig.defaults) === null || _a === void 0 ? void 0 : _a.healthcheck) {
+                tags.add(resilienceConfig.defaults.healthcheck);
+            }
+            // Add healthchecks from tool overrides
+            if (resilienceConfig === null || resilienceConfig === void 0 ? void 0 : resilienceConfig.toolOverrides) {
+                Object.values(resilienceConfig.toolOverrides).forEach((override) => {
+                    if (override.healthcheck) {
+                        tags.add(override.healthcheck);
+                    }
+                });
+            }
+            return Array.from(tags);
+        };
+        // Create quota context
+        const quotaContext = {
+            async run(options) {
+                if (!services.resilienceService) {
+                    throw new Error('ResilienceService not available. Cannot run quota operations.');
+                }
+                const result = await services.resilienceService.runQuota({
+                    product: services.config.product,
+                    env: services.config.env,
+                    tag: options.tag,
+                    input: options.input,
+                    session: options.session,
+                });
+                return result;
+            },
+            async status(options) {
+                if (!services.resilienceService) {
+                    throw new Error('ResilienceService not available. Cannot get quota status.');
+                }
+                const result = await services.resilienceService.getQuotaStatus({
+                    product: services.config.product,
+                    env: services.config.env,
+                    tag: options.tag,
+                });
+                return {
+                    tag: options.tag,
+                    totalQuota: result.totalQuota,
+                    usedQuota: result.usedQuota,
+                    remainingQuota: result.remainingQuota,
+                    providers: result.providers || [],
+                };
+            },
+        };
+        // Create fallback context
+        const fallbackContext = {
+            async run(options) {
+                if (!services.resilienceService) {
+                    throw new Error('ResilienceService not available. Cannot run fallback operations.');
+                }
+                const result = await services.resilienceService.runFallback({
+                    product: services.config.product,
+                    env: services.config.env,
+                    tag: options.tag,
+                    input: options.input,
+                    session: options.session,
+                });
+                return result;
+            },
+        };
+        // Create healthcheck context
+        const healthcheckContext = {
+            async check(options) {
+                if (!services.resilienceService) {
+                    throw new Error('ResilienceService not available. Cannot check health.');
+                }
+                const result = await services.resilienceService.checkHealth({
+                    product: services.config.product,
+                    env: options.env || services.config.env,
+                    tag: options.tag,
+                });
+                return {
+                    tag: options.tag,
+                    status: result.status || 'unknown',
+                    lastChecked: result.lastChecked,
+                    lastAvailable: result.lastAvailable,
+                    lastLatency: result.lastLatency,
+                    averageLatency: result.averageLatency,
+                    error: result.error,
+                };
+            },
+            async status() {
+                if (!services.resilienceService) {
+                    throw new Error('ResilienceService not available. Cannot get health status.');
+                }
+                const healthcheckTags = getReferencedHealthchecks();
+                const results = {};
+                for (const tag of healthcheckTags) {
+                    try {
+                        const result = await services.resilienceService.checkHealth({
+                            product: services.config.product,
+                            env: services.config.env,
+                            tag,
+                        });
+                        results[tag] = {
+                            tag,
+                            status: result.status || 'unknown',
+                            lastChecked: result.lastChecked,
+                            lastAvailable: result.lastAvailable,
+                            lastLatency: result.lastLatency,
+                            averageLatency: result.averageLatency,
+                            error: result.error,
+                        };
+                    }
+                    catch (error) {
+                        results[tag] = {
+                            tag,
+                            status: 'unknown',
+                            error: error instanceof Error ? error.message : 'Unknown error',
+                        };
+                    }
+                }
+                return results;
+            },
+        };
+        return {
+            quota: quotaContext,
+            fallback: fallbackContext,
+            healthcheck: healthcheckContext,
+        };
+    }
+    createLogger() {
+        const ctx = this;
+        return {
+            debug(message, data) {
+                console.debug(`[Agent:${ctx.agent_tag}:${ctx.execution_id}] ${message}`, data || '');
+            },
+            info(message, data) {
+                console.info(`[Agent:${ctx.agent_tag}:${ctx.execution_id}] ${message}`, data || '');
+            },
+            warn(message, data) {
+                console.warn(`[Agent:${ctx.agent_tag}:${ctx.execution_id}] ${message}`, data || '');
+            },
+            error(message, data) {
+                console.error(`[Agent:${ctx.agent_tag}:${ctx.execution_id}] ${message}`, data || '');
+            },
+        };
+    }
+    // ==================== STATE UPDATE ====================
+    /**
+     * Update internal state (called by AgentExecutor)
+     */
+    updateState(updates) {
+        this._state = Object.assign(Object.assign({}, this._state), updates);
+    }
+    /**
+     * Get current state snapshot
+     */
+    getStateSnapshot() {
+        return Object.assign({}, this._state);
+    }
+}
+exports.AgentContext = AgentContext;
+exports.default = AgentContext;
+//# sourceMappingURL=agent-context.js.map