@inkeep/agents-run-api 0.39.5 → 0.40.0

package/dist/utils/schema-validation.d.ts

@@ -0,0 +1,44 @@
+//#region src/utils/schema-validation.d.ts
+/**
+ * Clear the validator cache to free memory
+ * Useful for testing or when memory usage becomes a concern
+ */
+declare function clearValidatorCache(): void;
+/**
+ * Get the current cache size for monitoring
+ */
+declare function getValidatorCacheSize(): number;
+/**
+ * Extended JSON Schema that includes preview field indicators
+ */
+interface ExtendedJsonSchema {
+  type: string;
+  properties?: Record<string, ExtendedJsonSchemaProperty>;
+  required?: string[];
+  [key: string]: any;
+}
+interface ExtendedJsonSchemaProperty {
+  type: string;
+  description?: string;
+  inPreview?: boolean;
+  [key: string]: any;
+}
+/**
+ * Validate that a schema is valid (either JSON Schema or Zod)
+ * Following the same pattern as context validation
+ */
+declare function validateComponentSchema(schema: any, componentName: string): {
+  isValid: boolean;
+  error?: string;
+  validatedSchema?: ExtendedJsonSchema;
+};
+/**
+ * Extract preview fields from a schema (fields marked with inPreview: true)
+ */
+declare function extractPreviewFields(schema: ExtendedJsonSchema): Record<string, any>;
+/**
+ * Extract full fields from a schema (all fields, with inPreview flags removed)
+ */
+declare function extractFullFields(schema: ExtendedJsonSchema): Record<string, any>;
+//#endregion
+export { ExtendedJsonSchema, ExtendedJsonSchemaProperty, clearValidatorCache, extractFullFields, extractPreviewFields, getValidatorCacheSize, validateComponentSchema };

package/dist/utils/schema-validation.js

@@ -0,0 +1,97 @@
+import { getLogger } from "../logger.js";
+import { z } from "@hono/zod-openapi";
+import { convertZodToJsonSchemaWithPreview } from "@inkeep/agents-core/utils/schema-conversion";
+import Ajv from "ajv";
+
+//#region src/utils/schema-validation.ts
+const logger = getLogger("SchemaValidation");
+const ajv = new Ajv({
+	allErrors: true,
+	strict: false
+});
+const validatorCache = /* @__PURE__ */ new Map();
+/**
+* Clear the validator cache to free memory
+* Useful for testing or when memory usage becomes a concern
+*/
+function clearValidatorCache() {
+	validatorCache.clear();
+}
+/**
+* Get the current cache size for monitoring
+*/
+function getValidatorCacheSize() {
+	return validatorCache.size;
+}
+/**
+* Validate that a schema is valid (either JSON Schema or Zod)
+* Following the same pattern as context validation
+*/
+function validateComponentSchema(schema, componentName) {
+	try {
+		if (schema instanceof z.ZodType) return {
+			isValid: true,
+			validatedSchema: convertZodToJsonSchemaWithPreview(schema)
+		};
+		if (!schema || typeof schema !== "object" || Array.isArray(schema)) return {
+			isValid: false,
+			error: "Schema must be a valid JSON Schema object or Zod schema"
+		};
+		const schemaKey = JSON.stringify(schema);
+		let validator = validatorCache.get(schemaKey);
+		if (!validator) {
+			validator = ajv.compile(schema);
+			validatorCache.set(schemaKey, validator);
+		}
+		return {
+			isValid: true,
+			validatedSchema: schema
+		};
+	} catch (error) {
+		logger.error({
+			componentName,
+			error: error instanceof Error ? error.message : "Unknown error"
+		}, "Invalid component schema");
+		return {
+			isValid: false,
+			error: error instanceof Error ? error.message : "Invalid JSON Schema"
+		};
+	}
+}
+/**
+* Extract preview fields from a schema (fields marked with inPreview: true)
+*/
+function extractPreviewFields(schema) {
+	const previewProperties = {};
+	if (schema.properties) {
+		for (const [key, prop] of Object.entries(schema.properties)) if (prop.inPreview === true) {
+			const cleanProp = { ...prop };
+			delete cleanProp.inPreview;
+			previewProperties[key] = cleanProp;
+		}
+	}
+	return {
+		type: "object",
+		properties: previewProperties,
+		required: schema.required?.filter((field) => previewProperties[field])
+	};
+}
+/**
+* Extract full fields from a schema (all fields, with inPreview flags removed)
+*/
+function extractFullFields(schema) {
+	const fullProperties = {};
+	if (schema.properties) for (const [key, prop] of Object.entries(schema.properties)) {
+		const cleanProp = { ...prop };
+		delete cleanProp.inPreview;
+		fullProperties[key] = cleanProp;
+	}
+	return {
+		type: "object",
+		properties: fullProperties,
+		required: schema.required
+	};
+}
+
+//#endregion
+export { clearValidatorCache, extractFullFields, extractPreviewFields, getValidatorCacheSize, validateComponentSchema };

package/dist/utils/stream-helpers.d.ts

@@ -0,0 +1,197 @@
+import { ErrorEvent, OperationEvent } from "./agent-operations.js";
+import { SummaryEvent } from "@inkeep/agents-core";
+
+//#region src/utils/stream-helpers.d.ts
+interface StreamHelper {
+  writeRole(role?: string): Promise<void>;
+  writeContent(content: string): Promise<void>;
+  streamData(data: any): Promise<void>;
+  streamText(text: string, delayMs?: number): Promise<void>;
+  writeError(error: string | ErrorEvent): Promise<void>;
+  complete(): Promise<void>;
+  writeData(type: string, data: any): Promise<void>;
+  writeOperation(operation: OperationEvent): Promise<void>;
+  writeSummary(summary: SummaryEvent): Promise<void>;
+}
+interface HonoSSEStream {
+  writeSSE(message: {
+    data: string;
+    event?: string;
+    id?: string;
+  }): Promise<void>;
+  sleep(ms: number): Promise<unknown>;
+}
+interface ChatCompletionChunk {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    delta: {
+      role?: string;
+      content?: string;
+    };
+    finish_reason: string | null;
+  }>;
+}
+declare class SSEStreamHelper implements StreamHelper {
+  private stream;
+  private requestId;
+  private timestamp;
+  private isTextStreaming;
+  private queuedEvents;
+  constructor(stream: HonoSSEStream, requestId: string, timestamp: number);
+  /**
+   * Write the initial role message
+   */
+  writeRole(role?: string): Promise<void>;
+  /**
+   * Write content chunk
+   */
+  writeContent(content: string): Promise<void>;
+  /**
+   * Stream text word by word with optional delay
+   */
+  streamText(text: string, delayMs?: number): Promise<void>;
+  streamData(data: any): Promise<void>;
+  /**
+   * Write error message or error event
+   */
+  writeError(error: string | ErrorEvent): Promise<void>;
+  /**
+   * Write the final completion message
+   */
+  writeCompletion(finishReason?: string): Promise<void>;
+  writeData(type: string, data: any): Promise<void>;
+  writeSummary(summary: SummaryEvent): Promise<void>;
+  writeOperation(operation: OperationEvent): Promise<void>;
+  /**
+   * Flush all queued operations in order after text streaming completes
+   */
+  private flushQueuedOperations;
+  /**
+   * Write the final [DONE] message
+   */
+  writeDone(): Promise<void>;
+  /**
+   * Complete the stream with finish reason and done message
+   */
+  complete(finishReason?: string): Promise<void>;
+}
+/**
+ * Factory function to create SSE stream helper
+ */
+declare function createSSEStreamHelper(stream: HonoSSEStream, requestId: string, timestamp: number): SSEStreamHelper;
+interface VercelUIWriter {
+  write(chunk: any): void;
+  merge(stream: any): void;
+  onError?: (error: Error) => void;
+}
+declare class VercelDataStreamHelper implements StreamHelper {
+  private writer;
+  private textId;
+  private jsonBuffer;
+  private sentItems;
+  private completedItems;
+  private sessionId?;
+  private static readonly MAX_BUFFER_SIZE;
+  private isCompleted;
+  private isTextStreaming;
+  private queuedEvents;
+  private lastTextEndTimestamp;
+  private connectionDropTimer?;
+  constructor(writer: VercelUIWriter);
+  setSessionId(sessionId: string): void;
+  writeRole(_?: string): Promise<void>;
+  writeContent(content: string): Promise<void>;
+  streamText(text: string, delayMs?: number): Promise<void>;
+  writeData(type: string, data: any): Promise<void>;
+  writeError(error: string | ErrorEvent): Promise<void>;
+  streamData(data: any): Promise<void>;
+  mergeStream(stream: any): Promise<void>;
+  /**
+   * Clean up all memory allocations
+   * Should be called when the stream helper is no longer needed
+   */
+  cleanup(): void;
+  /**
+   * JSON-aware buffer truncation that preserves complete JSON structures
+   */
+  private truncateJsonBufferSafely;
+  /**
+   * Reindex sent items after buffer truncation
+   */
+  private reindexSentItems;
+  /**
+   * Force cleanup on connection drop or timeout
+   */
+  private forceCleanup;
+  /**
+   * Check if the stream has been completed and cleaned up
+   */
+  isStreamCompleted(): boolean;
+  /**
+   * Get current memory usage stats (for debugging/monitoring)
+   */
+  getMemoryStats(): {
+    bufferSize: number;
+    sentItemsCount: number;
+    completedItemsCount: number;
+    isCompleted: boolean;
+  };
+  writeSummary(summary: SummaryEvent): Promise<void>;
+  writeOperation(operation: OperationEvent): Promise<void>;
+  /**
+   * Flush all queued operations in order after text streaming completes
+   */
+  private flushQueuedOperations;
+  writeCompletion(_finishReason?: string): Promise<void>;
+  writeDone(): Promise<void>;
+  /**
+   * Complete the stream and clean up all memory
+   * This is the primary cleanup point to prevent memory leaks between requests
+   */
+  complete(): Promise<void>;
+}
+declare function createVercelStreamHelper(writer: VercelUIWriter): VercelDataStreamHelper;
+/**
+ * Buffering Stream Helper that captures content instead of streaming
+ * Used for MCP tool responses and non-streaming API responses that require a single complete message
+ */
+declare class BufferingStreamHelper implements StreamHelper {
+  private capturedText;
+  private capturedData;
+  private capturedOperations;
+  private capturedSummaries;
+  private hasError;
+  private errorMessage;
+  private sessionId?;
+  setSessionId(sessionId: string): void;
+  writeRole(_role?: string): Promise<void>;
+  writeContent(content: string): Promise<void>;
+  streamText(text: string, _delayMs?: number): Promise<void>;
+  streamData(data: any): Promise<void>;
+  streamSummary(summary: SummaryEvent): Promise<void>;
+  streamOperation(operation: OperationEvent): Promise<void>;
+  writeData(_type: string, data: any): Promise<void>;
+  writeSummary(summary: SummaryEvent): Promise<void>;
+  writeOperation(operation: OperationEvent): Promise<void>;
+  writeError(error: string | ErrorEvent): Promise<void>;
+  complete(): Promise<void>;
+  /**
+   * Get the captured response for non-streaming output
+   */
+  getCapturedResponse(): {
+    text: string;
+    data: any[];
+    operations: OperationEvent[];
+    hasError: boolean;
+    errorMessage: string;
+  };
+}
+declare function createBufferingStreamHelper(): BufferingStreamHelper;
+declare const createMCPStreamHelper: typeof createBufferingStreamHelper;
+type MCPStreamHelper = BufferingStreamHelper;
+//#endregion
+export { BufferingStreamHelper, ChatCompletionChunk, HonoSSEStream, MCPStreamHelper, SSEStreamHelper, StreamHelper, VercelDataStreamHelper, VercelUIWriter, createBufferingStreamHelper, createMCPStreamHelper, createSSEStreamHelper, createVercelStreamHelper };