@inkeep/agents-run-api 0.0.0-dev-20250910232631

package/dist/utils/cleanup.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cleanup utilities for gracefully shutting down resources
+ * Helps prevent Node.js processes from hanging
+ */
+/**
+ * Gracefully exit the process after cleaning up resources
+ */
+export declare function gracefulExit(code?: number, delayMs?: number, message?: string): void;
+/**
+ * Setup signal handlers for graceful shutdown
+ */
+export declare function setupGracefulShutdown(cleanupFn?: () => Promise<void> | void, exitDelayMs?: number): void;
+/**
+ * Stop all tools associated with agents
+ */
+export declare function stopAllAgentTools(agents: Array<{
+    getTools: () => Record<string, any>;
+}>): Promise<void>;
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/utils/cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../src/utils/cleanup.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,MAAU,EAAE,OAAO,GAAE,MAAa,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAS7F;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EACtC,WAAW,GAAE,MAAa,GACzB,IAAI,CAyBN;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAC,GACrD,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/utils/cleanup.js

@@ -0,0 +1,66 @@
+/**
+ * Cleanup utilities for gracefully shutting down resources
+ * Helps prevent Node.js processes from hanging
+ */
+import { getLogger } from '../logger';
+const logger = getLogger('cleanup');
+/**
+ * Gracefully exit the process after cleaning up resources
+ */
+export function gracefulExit(code = 0, delayMs = 1000, message) {
+    if (message) {
+        logger.info(message);
+    }
+    setTimeout(() => {
+        logger.debug('Forcing process exit after cleanup delay');
+        process.exit(code);
+    }, delayMs);
+}
+/**
+ * Setup signal handlers for graceful shutdown
+ */
+export function setupGracefulShutdown(cleanupFn, exitDelayMs = 2000) {
+    const signals = ['SIGTERM', 'SIGINT'];
+    let isShuttingDown = false;
+    for (const signal of signals) {
+        process.on(signal, async () => {
+            if (isShuttingDown) {
+                logger.warn(`Received ${signal} during shutdown, forcing exit`);
+                process.exit(1);
+            }
+            logger.info(`Received ${signal}, starting graceful shutdown`);
+            isShuttingDown = true;
+            try {
+                if (cleanupFn) {
+                    await cleanupFn();
+                }
+            }
+            catch (error) {
+                logger.error({ error }, 'Error during cleanup');
+            }
+            gracefulExit(0, exitDelayMs, '🚪 Graceful shutdown complete');
+        });
+    }
+}
+/**
+ * Stop all tools associated with agents
+ */
+export async function stopAllAgentTools(agents) {
+    logger.info('Stopping all agent tools...');
+    for (const agent of agents) {
+        const tools = agent.getTools();
+        for (const toolInstance of Object.values(tools)) {
+            if (toolInstance && typeof toolInstance.stop === 'function') {
+                try {
+                    await toolInstance.stop();
+                    const toolName = toolInstance.config?.name || 'unknown';
+                    logger.debug(`Stopped tool: ${toolName}`);
+                }
+                catch (error) {
+                    logger.warn(`Failed to stop tool: ${error instanceof Error ? error.message : 'Unknown error'}`);
+                }
+            }
+        }
+    }
+    logger.info('All agent tools stopped');
+}

package/dist/utils/data-component-schema.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+/**
+ * Converts JSON Schema objects to Zod schema types
+ */
+export declare function jsonSchemaToZod(jsonSchema: any): z.ZodType<any>;
+//# sourceMappingURL=data-component-schema.d.ts.map

package/dist/utils/data-component-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-component-schema.d.ts","sourceRoot":"","sources":["../../src/utils/data-component-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;GAEG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CA8C/D"}

package/dist/utils/data-component-schema.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { getLogger } from '../logger';
+const logger = getLogger('DataComponentSchema');
+/**
+ * Converts JSON Schema objects to Zod schema types
+ */
+export function jsonSchemaToZod(jsonSchema) {
+    if (!jsonSchema || typeof jsonSchema !== 'object') {
+        logger.warn({ jsonSchema }, 'Invalid JSON schema provided, using string fallback');
+        return z.string();
+    }
+    switch (jsonSchema.type) {
+        case 'object':
+            if (jsonSchema.properties) {
+                const shape = {};
+                for (const [key, prop] of Object.entries(jsonSchema.properties)) {
+                    shape[key] = jsonSchemaToZod(prop);
+                }
+                return z.object(shape);
+            }
+            return z.record(z.string(), z.unknown());
+        case 'array': {
+            const itemSchema = jsonSchema.items ? jsonSchemaToZod(jsonSchema.items) : z.unknown();
+            return z.array(itemSchema);
+        }
+        case 'string':
+            return z.string();
+        case 'number':
+        case 'integer':
+            return z.number();
+        case 'boolean':
+            return z.boolean();
+        case 'null':
+            return z.null();
+        default:
+            // Log unsupported types for monitoring
+            logger.warn({
+                unsupportedType: jsonSchema.type,
+                schema: jsonSchema,
+            }, 'Unsupported JSON schema type, using unknown validation');
+            return z.unknown();
+    }
+}

package/dist/utils/graph-session.d.ts

@@ -0,0 +1,230 @@
+import type { ModelSettings, StatusUpdateSettings } from '@inkeep/agents-core';
+export type GraphSessionEventType = 'agent_generate' | 'agent_reasoning' | 'transfer' | 'delegation_sent' | 'delegation_returned' | 'artifact_saved' | 'tool_execution';
+export interface GraphSessionEvent {
+    timestamp: number;
+    eventType: GraphSessionEventType;
+    agentId: string;
+    data: EventData;
+}
+export type EventData = AgentGenerateData | AgentReasoningData | TransferData | DelegationSentData | DelegationReturnedData | ArtifactSavedData | ToolExecutionData;
+export interface AgentGenerateData {
+    parts: Array<{
+        type: 'text' | 'tool_call' | 'tool_result';
+        content?: string;
+        toolName?: string;
+        args?: any;
+        result?: any;
+    }>;
+    generationType: 'text_generation' | 'object_generation';
+}
+export interface AgentReasoningData {
+    parts: Array<{
+        type: 'text' | 'tool_call' | 'tool_result';
+        content?: string;
+        toolName?: string;
+        args?: any;
+        result?: any;
+    }>;
+}
+export interface TransferData {
+    fromAgent: string;
+    targetAgent: string;
+    reason?: string;
+    context?: any;
+}
+export interface DelegationSentData {
+    delegationId: string;
+    fromAgent: string;
+    targetAgent: string;
+    taskDescription: string;
+    context?: any;
+}
+export interface DelegationReturnedData {
+    delegationId: string;
+    fromAgent: string;
+    targetAgent: string;
+    result?: any;
+}
+export interface ArtifactSavedData {
+    artifactId: string;
+    taskId: string;
+    artifactType: string;
+    summaryData?: Record<string, any>;
+    fullData?: Record<string, any>;
+    pendingGeneration?: boolean;
+    tenantId?: string;
+    projectId?: string;
+    contextId?: string;
+    metadata?: Record<string, any>;
+    summaryProps?: Record<string, any>;
+    fullProps?: Record<string, any>;
+}
+export interface ToolExecutionData {
+    toolName: string;
+    args: any;
+    result: any;
+    toolId?: string;
+    duration?: number;
+}
+/**
+ * Tracks all agent operations and interactions for a single message
+ * Now includes intelligent status update functionality
+ */
+export declare class GraphSession {
+    readonly sessionId: string;
+    readonly messageId: string;
+    readonly graphId?: string | undefined;
+    readonly tenantId?: string | undefined;
+    readonly projectId?: string | undefined;
+    private events;
+    private statusUpdateState?;
+    private statusUpdateTimer?;
+    private previousSummaries;
+    private isEnded;
+    private isTextStreaming;
+    private isGeneratingUpdate;
+    private pendingArtifacts;
+    private artifactProcessingErrors;
+    private readonly MAX_ARTIFACT_RETRIES;
+    private readonly MAX_PENDING_ARTIFACTS;
+    private scheduledTimeouts?;
+    constructor(sessionId: string, messageId: string, graphId?: string | undefined, tenantId?: string | undefined, projectId?: string | undefined);
+    /**
+     * Initialize status updates for this session
+     */
+    initializeStatusUpdates(config: StatusUpdateSettings, summarizerModel?: ModelSettings): void;
+    /**
+     * Record an event in the session and trigger status updates if configured
+     */
+    recordEvent(eventType: GraphSessionEventType, agentId: string, data: EventData): void;
+    /**
+     * Check and send status updates if configured (async, non-blocking)
+     */
+    private checkStatusUpdates;
+    /**
+     * Check and send time-based status updates
+     */
+    private checkAndSendTimeBasedUpdate;
+    /**
+     * Get all events in chronological order
+     */
+    getEvents(): GraphSessionEvent[];
+    /**
+     * Get events filtered by type
+     */
+    getEventsByType(eventType: GraphSessionEventType): GraphSessionEvent[];
+    /**
+     * Get events filtered by agent
+     */
+    getEventsByAgent(agentId: string): GraphSessionEvent[];
+    /**
+     * Get summary of session activity
+     */
+    getSummary(): {
+        sessionId: string;
+        messageId: string;
+        graphId: string | undefined;
+        totalEvents: number;
+        eventCounts: Record<GraphSessionEventType, number>;
+        agentCounts: Record<string, number>;
+        startTime: number;
+        endTime: number;
+        duration: number;
+    };
+    /**
+     * Mark that text streaming has started (to suppress status updates)
+     */
+    setTextStreaming(isStreaming: boolean): void;
+    /**
+     * Check if text is currently being streamed
+     */
+    isCurrentlyStreaming(): boolean;
+    /**
+     * Clean up status update resources when session ends
+     */
+    cleanup(): void;
+    /**
+     * Generate and send a status update using graph-level summarizer
+     */
+    private generateAndSendUpdate;
+    /**
+     * Schedule status update check without setImmediate race conditions
+     */
+    private scheduleStatusUpdateCheck;
+    /**
+     * Acquire update lock with atomic check
+     */
+    private acquireUpdateLock;
+    /**
+     * Release update lock
+     */
+    private releaseUpdateLock;
+    /**
+     * Generate user-focused progress summary hiding internal operations
+     */
+    private generateProgressSummary;
+    /**
+     * Generate structured status update using configured data components
+     */
+    private generateStructuredStatusUpdate;
+    /**
+     * Build Zod schema from JSON schema configuration or use pre-defined schemas
+     */
+    private getComponentSchema;
+    /**
+     * Build Zod schema from JSON schema with improved type handling
+     */
+    private buildZodSchemaFromJson;
+    /**
+     * Extract user-visible activities with rich formatting and complete information
+     */
+    private extractUserVisibleActivities;
+    /**
+     * Generate fallback summary when LLM fails
+     */
+    private generateFallbackSummary;
+    /**
+     * Process a single artifact to generate name and description using conversation context
+     */
+    private processArtifact;
+}
+/**
+ * Manages GraphSession instances for message-level tracking
+ */
+export declare class GraphSessionManager {
+    private sessions;
+    /**
+     * Create a new session for a message
+     */
+    createSession(messageId: string, graphId?: string, tenantId?: string, projectId?: string): string;
+    /**
+     * Initialize status updates for a session
+     */
+    initializeStatusUpdates(sessionId: string, config: StatusUpdateSettings, summarizerModel?: ModelSettings): void;
+    /**
+     * Get an existing session
+     */
+    getSession(sessionId: string): GraphSession | null;
+    /**
+     * Record an event in a session
+     */
+    recordEvent(sessionId: string, eventType: GraphSessionEventType, agentId: string, data: EventData): void;
+    /**
+     * End a session and return the final event data
+     */
+    endSession(sessionId: string): GraphSessionEvent[];
+    /**
+     * Set text streaming state for a session
+     */
+    setTextStreaming(sessionId: string, isStreaming: boolean): void;
+    /**
+     * Get summary of all active sessions
+     */
+    getActiveSessions(): Array<{
+        sessionId: string;
+        messageId: string;
+        eventCount: number;
+    }>;
+}
+export declare const graphSessionManager: GraphSessionManager;
+//# sourceMappingURL=graph-session.d.ts.map

package/dist/utils/graph-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-session.d.ts","sourceRoot":"","sources":["../../src/utils/graph-session.ts"],"names":[],"mappings":"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"}