@inkeep/agents-run-api 0.39.5 → 0.40.0

package/dist/services/AgentSession.d.ts

@@ -0,0 +1,356 @@
+import { DelegationReturnedData, DelegationSentData, ModelSettings, StatusUpdateSettings, TransferData } from "@inkeep/agents-core";
+
+//#region src/services/AgentSession.d.ts
+type AgentSessionEventType = 'agent_generate' | 'agent_reasoning' | 'transfer' | 'delegation_sent' | 'delegation_returned' | 'artifact_saved' | 'tool_call' | 'tool_result' | 'compression' | 'error';
+interface BaseAgentSessionEvent {
+  timestamp: number;
+  subAgentId: string;
+}
+type AgentSessionEvent = (BaseAgentSessionEvent & {
+  eventType: 'agent_generate';
+  data: AgentGenerateData;
+}) | (BaseAgentSessionEvent & {
+  eventType: 'agent_reasoning';
+  data: AgentReasoningData;
+}) | (BaseAgentSessionEvent & {
+  eventType: 'transfer';
+  data: TransferData;
+}) | (BaseAgentSessionEvent & {
+  eventType: 'delegation_sent';
+  data: DelegationSentData;
+}) | (BaseAgentSessionEvent & {
+  eventType: 'delegation_returned';
+  data: DelegationReturnedData;
+}) | (BaseAgentSessionEvent & {
+  eventType: 'artifact_saved';
+  data: ArtifactSavedData;
+}) | (BaseAgentSessionEvent & {
+  eventType: 'tool_call';
+  data: ToolCallData;
+}) | (BaseAgentSessionEvent & {
+  eventType: 'tool_result';
+  data: ToolResultData;
+}) | (BaseAgentSessionEvent & {
+  eventType: 'compression';
+  data: CompressionEventData;
+}) | (BaseAgentSessionEvent & {
+  eventType: 'error';
+  data: ErrorEventData;
+});
+type EventData = AgentGenerateData | AgentReasoningData | TransferData | DelegationSentData | DelegationReturnedData | ArtifactSavedData | ToolCallData | ToolResultData | CompressionEventData | ErrorEventData;
+type EventDataMap = {
+  agent_generate: AgentGenerateData;
+  agent_reasoning: AgentReasoningData;
+  transfer: TransferData;
+  delegation_sent: DelegationSentData;
+  delegation_returned: DelegationReturnedData;
+  artifact_saved: ArtifactSavedData;
+  tool_call: ToolCallData;
+  tool_result: ToolResultData;
+  compression: CompressionEventData;
+  error: ErrorEventData;
+};
+interface AgentGenerateData {
+  parts: Array<{
+    type: 'text' | 'tool_call' | 'tool_result';
+    content?: string;
+    toolName?: string;
+    args?: any;
+    result?: any;
+  }>;
+  generationType: 'text_generation' | 'object_generation';
+}
+interface AgentReasoningData {
+  parts: Array<{
+    type: 'text' | 'tool_call' | 'tool_result';
+    content?: string;
+    toolName?: string;
+    args?: any;
+    result?: any;
+  }>;
+}
+interface ArtifactSavedData {
+  artifactId: string;
+  taskId: string;
+  toolCallId?: string;
+  artifactType: string;
+  pendingGeneration?: boolean;
+  tenantId?: string;
+  projectId?: string;
+  contextId?: string;
+  subAgentId?: string;
+  subAgentName?: string;
+  metadata?: Record<string, any>;
+  summaryData?: Record<string, any>;
+  data?: Record<string, any>;
+  schemaValidation?: {
+    summary: {
+      hasExpectedFields: boolean;
+      missingFields: string[];
+      extraFields: string[];
+      expectedFields: string[];
+      actualFields: string[];
+      hasRequiredFields: boolean;
+      missingRequired: string[];
+    };
+    full: {
+      hasExpectedFields: boolean;
+      missingFields: string[];
+      extraFields: string[];
+      expectedFields: string[];
+      actualFields: string[];
+      hasRequiredFields: boolean;
+      missingRequired: string[];
+    };
+    schemaFound: boolean;
+  };
+}
+interface ToolCallData {
+  toolName: string;
+  input: any;
+  toolCallId: string;
+  relationshipId?: string;
+  needsApproval?: boolean;
+  conversationId?: string;
+}
+interface ToolResultData {
+  toolName: string;
+  toolCallId: string;
+  output: any;
+  duration?: number;
+  error?: string;
+  relationshipId?: string;
+  needsApproval?: boolean;
+}
+interface CompressionEventData {
+  reason: 'manual' | 'automatic';
+  messageCount: number;
+  artifactCount: number;
+  contextSizeBefore: number;
+  contextSizeAfter: number;
+  compressionType: 'mid_generation' | 'conversation_level';
+}
+interface ErrorEventData {
+  message: string;
+  code?: string;
+  severity?: 'error' | 'warning' | 'info';
+  context?: any;
+}
+/**
+ * Tracks all agent operations and interactions for a single message
+ * Now includes intelligent status update functionality
+ */
+declare class AgentSession {
+  readonly sessionId: string;
+  readonly messageId: string;
+  readonly agentId?: string | undefined;
+  readonly tenantId?: string | undefined;
+  readonly projectId?: string | undefined;
+  readonly contextId?: 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?;
+  private artifactCache;
+  private artifactService?;
+  private artifactParser?;
+  private isEmitOperations;
+  constructor(sessionId: string, messageId: string, agentId?: string | undefined, tenantId?: string | undefined, projectId?: string | undefined, contextId?: string | undefined);
+  /**
+   * Enable emit operations to send data operations
+   */
+  enableEmitOperations(): void;
+  /**
+   * Send data operation to stream when emit operations is enabled
+   */
+  private sendDataOperation;
+  /**
+   * Generate human-readable labels for events
+   */
+  private generateEventLabel;
+  /**
+   * Initialize status updates for this session
+   */
+  initializeStatusUpdates(config: StatusUpdateSettings, summarizerModel?: ModelSettings, baseModel?: ModelSettings): void;
+  /**
+   * Record an event in the session and trigger status updates if configured
+   * Generic type parameter T ensures eventType and data are correctly paired
+   */
+  recordEvent<T extends AgentSessionEventType>(eventType: T, subAgentId: string, data: EventDataMap[T]): 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(): AgentSessionEvent[];
+  /**
+   * Get events filtered by type
+   */
+  getEventsByType(eventType: AgentSessionEventType): AgentSessionEvent[];
+  /**
+   * Get events filtered by agent
+   */
+  getEventsByAgent(subAgentId: string): AgentSessionEvent[];
+  /**
+   * Get summary of session activity
+   */
+  getSummary(): {
+    sessionId: string;
+    messageId: string;
+    agentId: string | undefined;
+    totalEvents: number;
+    eventCounts: Record<AgentSessionEventType, 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(): Promise<void>;
+  /**
+   * Generate and send a status update using agent-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 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;
+  /**
+   * Process a single artifact to generate name and description using conversation context
+   */
+  private processArtifact;
+  /**
+   * Cache an artifact in this session for immediate access
+   */
+  setArtifactCache(key: string, artifact: any): void;
+  /**
+   * Get session-scoped ArtifactService instance
+   */
+  getArtifactService(): any | null;
+  /**
+   * Get session-scoped ArtifactParser instance
+   */
+  getArtifactParser(): any | null;
+  /**
+   * Get an artifact from this session cache
+   */
+  getArtifactCache(key: string): any | null;
+  /**
+   * Update artifact components in the shared ArtifactService
+   */
+  updateArtifactComponents(artifactComponents: any[]): void;
+}
+/**
+ * Manages AgentSession instances for message-level tracking
+ */
+declare class AgentSessionManager {
+  private sessions;
+  /**
+   * Create a new session for a message
+   */
+  createSession(messageId: string, agentId?: string, tenantId?: string, projectId?: string, contextId?: string): string;
+  /**
+   * Initialize status updates for a session
+   */
+  initializeStatusUpdates(sessionId: string, config: StatusUpdateSettings, summarizerModel?: ModelSettings, baseModel?: ModelSettings): void;
+  /**
+   * Enable emit operations for a session to send data operations
+   */
+  enableEmitOperations(sessionId: string): void;
+  /**
+   * Get an existing session
+   */
+  getSession(sessionId: string): AgentSession | null;
+  /**
+   * Record an event in a session
+   * Generic type parameter T ensures eventType and data are correctly paired
+   */
+  recordEvent<T extends AgentSessionEventType>(sessionId: string, eventType: T, subAgentId: string, data: EventDataMap[T]): void;
+  /**
+   * End a session and return the final event data
+   */
+  endSession(sessionId: string): Promise<AgentSessionEvent[]>;
+  /**
+   * 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;
+  }>;
+  /**
+   * Cache an artifact in the specified session
+   */
+  setArtifactCache(sessionId: string, key: string, artifact: any): Promise<void>;
+  /**
+   * Get an artifact from the specified session cache
+   */
+  getArtifactCache(sessionId: string, key: string): Promise<any | null>;
+  /**
+   * Get session-scoped ArtifactService instance
+   */
+  getArtifactService(sessionId: string): any | null;
+  /**
+   * Get session-scoped ArtifactParser instance
+   */
+  getArtifactParser(sessionId: string): any | null;
+  /**
+   * Update artifact components for a session
+   */
+  updateArtifactComponents(sessionId: string, artifactComponents: any[]): void;
+}
+declare const agentSessionManager: AgentSessionManager;
+//#endregion
+export { AgentGenerateData, AgentReasoningData, AgentSession, AgentSessionEvent, AgentSessionEventType, AgentSessionManager, ArtifactSavedData, CompressionEventData, ErrorEventData, EventData, EventDataMap, ToolCallData, ToolResultData, agentSessionManager };