@inkeep/agents-api 0.0.1

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

@@ -0,0 +1,193 @@
+import { ErrorEvent, OperationEvent } from "./agent-operations.js";
+import { SummaryEvent } from "@inkeep/agents-core";
+
+//#region src/domains/run/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 static readonly MAX_BUFFER_SIZE;
+  private isCompleted;
+  private isTextStreaming;
+  private queuedEvents;
+  private lastTextEndTimestamp;
+  private connectionDropTimer?;
+  constructor(writer: VercelUIWriter);
+  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;
+  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 };

package/dist/domains/run/utils/stream-helpers.js

@@ -0,0 +1,510 @@
+import { STREAM_BUFFER_MAX_SIZE_BYTES, STREAM_MAX_LIFETIME_MS, STREAM_TEXT_GAP_THRESHOLD_MS } from "../constants/execution-limits/index.js";
+import { parsePartialJson } from "ai";
+
+//#region src/domains/run/utils/stream-helpers.ts
+var SSEStreamHelper = class {
+	isTextStreaming = false;
+	queuedEvents = [];
+	constructor(stream, requestId, timestamp) {
+		this.stream = stream;
+		this.requestId = requestId;
+		this.timestamp = timestamp;
+	}
+	/**
+	* Write the initial role message
+	*/
+	async writeRole(role = "assistant") {
+		await this.stream.writeSSE({ data: JSON.stringify({
+			id: this.requestId,
+			object: "chat.completion.chunk",
+			created: this.timestamp,
+			choices: [{
+				index: 0,
+				delta: { role },
+				finish_reason: null
+			}]
+		}) });
+	}
+	/**
+	* Write content chunk
+	*/
+	async writeContent(content) {
+		await this.stream.writeSSE({ data: JSON.stringify({
+			id: this.requestId,
+			object: "chat.completion.chunk",
+			created: this.timestamp,
+			choices: [{
+				index: 0,
+				delta: { content },
+				finish_reason: null
+			}]
+		}) });
+	}
+	/**
+	* Stream text word by word with optional delay
+	*/
+	async streamText(text, delayMs = 100) {
+		const words = text.split(" ");
+		this.isTextStreaming = true;
+		try {
+			for (let i = 0; i < words.length; i++) {
+				await this.stream.sleep(delayMs);
+				const content = i === 0 ? words[i] : ` ${words[i]}`;
+				await this.writeContent(content);
+			}
+		} finally {
+			this.isTextStreaming = false;
+			await this.flushQueuedOperations();
+		}
+	}
+	async streamData(data) {
+		await this.writeContent(JSON.stringify(data));
+	}
+	/**
+	* Write error message or error event
+	*/
+	async writeError(error) {
+		const errorMessage = typeof error === "string" ? error : error.message;
+		await this.writeContent(`\n\n${errorMessage}`);
+	}
+	/**
+	* Write the final completion message
+	*/
+	async writeCompletion(finishReason = "stop") {
+		await this.stream.writeSSE({ data: JSON.stringify({
+			id: this.requestId,
+			object: "chat.completion.chunk",
+			created: this.timestamp,
+			choices: [{
+				index: 0,
+				delta: {},
+				finish_reason: finishReason
+			}]
+		}) });
+	}
+	async writeData(type, data) {
+		await this.stream.writeSSE({ data: JSON.stringify({
+			id: this.requestId,
+			object: "chat.completion.chunk",
+			created: this.timestamp,
+			choices: [{
+				index: 0,
+				delta: { content: JSON.stringify({
+					type,
+					data
+				}) },
+				finish_reason: null
+			}]
+		}) });
+	}
+	async writeSummary(summary) {
+		if (this.isTextStreaming) {
+			this.queuedEvents.push({
+				type: "data-summary",
+				event: summary
+			});
+			return;
+		}
+		await this.flushQueuedOperations();
+		await this.writeData("data-summary", summary);
+	}
+	async writeOperation(operation) {
+		if (this.isTextStreaming) {
+			this.queuedEvents.push({
+				type: "data-operation",
+				event: operation
+			});
+			return;
+		}
+		await this.flushQueuedOperations();
+		await this.writeData("data-operation", operation);
+	}
+	/**
+	* Flush all queued operations in order after text streaming completes
+	*/
+	async flushQueuedOperations() {
+		if (this.queuedEvents.length === 0) return;
+		const eventsToFlush = [...this.queuedEvents];
+		this.queuedEvents = [];
+		for (const event of eventsToFlush) await this.writeData(event.type, event.event);
+	}
+	/**
+	* Write the final [DONE] message
+	*/
+	async writeDone() {
+		await this.stream.writeSSE({ data: "[DONE]" });
+	}
+	/**
+	* Complete the stream with finish reason and done message
+	*/
+	async complete(finishReason = "stop") {
+		await this.flushQueuedOperations();
+		await this.writeCompletion(finishReason);
+		await this.writeDone();
+	}
+};
+/**
+* Factory function to create SSE stream helper
+*/
+function createSSEStreamHelper(stream, requestId, timestamp) {
+	return new SSEStreamHelper(stream, requestId, timestamp);
+}
+var VercelDataStreamHelper = class VercelDataStreamHelper {
+	textId = null;
+	jsonBuffer = "";
+	sentItems = /* @__PURE__ */ new Map();
+	completedItems = /* @__PURE__ */ new Set();
+	static MAX_BUFFER_SIZE = STREAM_BUFFER_MAX_SIZE_BYTES;
+	isCompleted = false;
+	isTextStreaming = false;
+	queuedEvents = [];
+	lastTextEndTimestamp = 0;
+	connectionDropTimer;
+	constructor(writer) {
+		this.writer = writer;
+		this.connectionDropTimer = setTimeout(() => {
+			this.forceCleanup("Connection lifetime exceeded");
+		}, STREAM_MAX_LIFETIME_MS);
+	}
+	async writeRole(_ = "assistant") {}
+	async writeContent(content) {
+		if (this.isCompleted) {
+			console.warn("Attempted to write content to completed stream");
+			return;
+		}
+		if (!this.textId) this.textId = `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+		if (this.jsonBuffer.length + content.length > VercelDataStreamHelper.MAX_BUFFER_SIZE) {
+			const newBuffer = this.truncateJsonBufferSafely(this.jsonBuffer);
+			if (newBuffer.length === this.jsonBuffer.length) {
+				console.warn("VercelDataStreamHelper: Could not find safe JSON truncation point, clearing buffer");
+				this.jsonBuffer = "";
+				this.sentItems.clear();
+			} else {
+				this.jsonBuffer = newBuffer;
+				this.reindexSentItems();
+			}
+		}
+		this.jsonBuffer += content;
+		const { value, state } = await parsePartialJson(this.jsonBuffer);
+		if (!["repaired-parse", "successful-parse"].includes(state)) return;
+		if (!Array.isArray(value)) return;
+		for (let i = 0; i < value.length; i++) {
+			const { type, ...data } = value[i];
+			const currentContent = JSON.stringify(data);
+			if (currentContent !== this.sentItems.get(i)) {
+				const chunk = {
+					type: "data-component",
+					id: `${this.textId}-${i}`,
+					data: {
+						type,
+						...data
+					}
+				};
+				this.writer.write(chunk);
+				this.sentItems.set(i, currentContent);
+			}
+		}
+	}
+	async streamText(text, delayMs = 100) {
+		if (this.isCompleted) {
+			console.warn("Attempted to stream text to completed stream");
+			return;
+		}
+		if (!this.textId) this.textId = `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+		const id = this.textId;
+		const startTime = Date.now();
+		if ((this.lastTextEndTimestamp > 0 ? startTime - this.lastTextEndTimestamp : Number.MAX_SAFE_INTEGER) >= STREAM_TEXT_GAP_THRESHOLD_MS) await this.flushQueuedOperations();
+		this.isTextStreaming = true;
+		try {
+			this.writer.write({
+				type: "text-start",
+				id
+			});
+			if (delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+			this.writer.write({
+				type: "text-delta",
+				id,
+				delta: text
+			});
+			this.writer.write({
+				type: "text-end",
+				id
+			});
+			this.lastTextEndTimestamp = Date.now();
+		} finally {
+			this.isTextStreaming = false;
+		}
+	}
+	async writeData(type, data) {
+		if (this.isCompleted) {
+			console.warn("Attempted to write data to completed stream");
+			return;
+		}
+		if (type === "data-artifact") {
+			const now = Date.now();
+			const gapFromLastTextEnd = this.lastTextEndTimestamp > 0 ? now - this.lastTextEndTimestamp : Number.MAX_SAFE_INTEGER;
+			if (this.isTextStreaming || gapFromLastTextEnd < STREAM_TEXT_GAP_THRESHOLD_MS) {
+				this.writer.write({
+					type: `${type}`,
+					data
+				});
+				return;
+			}
+		}
+		this.writer.write({
+			type: `${type}`,
+			data
+		});
+	}
+	async writeError(error) {
+		if (this.isCompleted) {
+			console.warn("Attempted to write error to completed stream");
+			return;
+		}
+		if (typeof error === "string") this.writer.write({
+			type: "error",
+			message: error,
+			severity: "error",
+			timestamp: Date.now()
+		});
+		else this.writer.write({
+			...error,
+			type: "error"
+		});
+	}
+	async streamData(data) {
+		await this.writeContent(JSON.stringify(data));
+	}
+	async mergeStream(stream) {
+		if (this.isCompleted) {
+			console.warn("Attempted to merge stream to completed stream");
+			return;
+		}
+		this.writer.merge(stream);
+	}
+	/**
+	* Clean up all memory allocations
+	* Should be called when the stream helper is no longer needed
+	*/
+	cleanup() {
+		if (this.connectionDropTimer) {
+			clearTimeout(this.connectionDropTimer);
+			this.connectionDropTimer = void 0;
+		}
+		this.jsonBuffer = "";
+		this.sentItems.clear();
+		this.completedItems.clear();
+		this.textId = null;
+		this.queuedEvents = [];
+		this.isTextStreaming = false;
+	}
+	/**
+	* JSON-aware buffer truncation that preserves complete JSON structures
+	*/
+	truncateJsonBufferSafely(buffer) {
+		const keepSize = Math.floor(VercelDataStreamHelper.MAX_BUFFER_SIZE * .6);
+		if (buffer.length <= keepSize) return buffer;
+		let depth = 0;
+		let inString = false;
+		let escaping = false;
+		let lastCompleteStructureEnd = -1;
+		for (let i = Math.min(keepSize + 1e3, buffer.length - 1); i >= keepSize; i--) {
+			const char = buffer[i];
+			if (escaping) {
+				escaping = false;
+				continue;
+			}
+			if (char === "\\") {
+				escaping = true;
+				continue;
+			}
+			if (char === "\"") {
+				inString = !inString;
+				continue;
+			}
+			if (inString) continue;
+			if (char === "}" || char === "]") depth++;
+			else if (char === "{" || char === "[") {
+				depth--;
+				if (depth === 0) {
+					lastCompleteStructureEnd = i - 1;
+					break;
+				}
+			}
+		}
+		if (lastCompleteStructureEnd > 0) return buffer.slice(lastCompleteStructureEnd + 1);
+		for (let i = keepSize; i < Math.min(keepSize + 500, buffer.length); i++) if (buffer[i] === "\n" && buffer[i + 1] && buffer[i + 1].match(/[{[]]/)) return buffer.slice(i + 1);
+		return buffer;
+	}
+	/**
+	* Reindex sent items after buffer truncation
+	*/
+	reindexSentItems() {
+		this.sentItems.clear();
+		this.completedItems.clear();
+	}
+	/**
+	* Force cleanup on connection drop or timeout
+	*/
+	forceCleanup(reason) {
+		console.warn(`VercelDataStreamHelper: Forcing cleanup - ${reason}`);
+		this.isCompleted = true;
+		this.cleanup();
+		try {
+			if (this.writer && !this.isCompleted) this.writer.write({
+				type: "error",
+				message: `Stream terminated: ${reason}`,
+				severity: "error",
+				timestamp: Date.now()
+			});
+		} catch (_e) {}
+	}
+	/**
+	* Check if the stream has been completed and cleaned up
+	*/
+	isStreamCompleted() {
+		return this.isCompleted;
+	}
+	/**
+	* Get current memory usage stats (for debugging/monitoring)
+	*/
+	getMemoryStats() {
+		return {
+			bufferSize: this.jsonBuffer.length,
+			sentItemsCount: this.sentItems.size,
+			completedItemsCount: this.completedItems.size,
+			isCompleted: this.isCompleted
+		};
+	}
+	async writeSummary(summary) {
+		if (this.isCompleted) {
+			console.warn("Attempted to write summary to completed stream");
+			return;
+		}
+		const now = Date.now();
+		const gapFromLastTextEnd = this.lastTextEndTimestamp > 0 ? now - this.lastTextEndTimestamp : Number.MAX_SAFE_INTEGER;
+		if (this.isTextStreaming || gapFromLastTextEnd < STREAM_TEXT_GAP_THRESHOLD_MS) {
+			this.queuedEvents.push({
+				type: "data-summary",
+				event: summary
+			});
+			return;
+		}
+		await this.flushQueuedOperations();
+		await this.writer.write({
+			id: "id" in summary ? summary.id : void 0,
+			type: "data-summary",
+			data: summary
+		});
+	}
+	async writeOperation(operation) {
+		if (this.isCompleted) {
+			console.warn("Attempted to write operation to completed stream");
+			return;
+		}
+		const now = Date.now();
+		const gapFromLastTextEnd = this.lastTextEndTimestamp > 0 ? now - this.lastTextEndTimestamp : Number.MAX_SAFE_INTEGER;
+		if (operation.type !== "tool_call" && operation.type !== "tool_result" && (this.isTextStreaming || gapFromLastTextEnd < STREAM_TEXT_GAP_THRESHOLD_MS)) {
+			this.queuedEvents.push({
+				type: "data-operation",
+				event: operation
+			});
+			return;
+		}
+		await this.flushQueuedOperations();
+		this.writer.write({
+			id: "id" in operation ? operation.id : void 0,
+			type: "data-operation",
+			data: operation
+		});
+	}
+	/**
+	* Flush all queued operations in order after text streaming completes
+	*/
+	async flushQueuedOperations() {
+		if (this.queuedEvents.length === 0) return;
+		const eventsToFlush = [...this.queuedEvents];
+		this.queuedEvents = [];
+		for (const event of eventsToFlush) this.writer.write({
+			id: "id" in event.event ? event.event.id : void 0,
+			type: event.type,
+			data: event.event
+		});
+	}
+	async writeCompletion(_finishReason = "stop") {}
+	async writeDone() {}
+	/**
+	* Complete the stream and clean up all memory
+	* This is the primary cleanup point to prevent memory leaks between requests
+	*/
+	async complete() {
+		if (this.isCompleted) return;
+		await this.flushQueuedOperations();
+		this.isCompleted = true;
+		this.cleanup();
+	}
+};
+function createVercelStreamHelper(writer) {
+	return new VercelDataStreamHelper(writer);
+}
+/**
+* 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
+*/
+var BufferingStreamHelper = class {
+	capturedText = "";
+	capturedData = [];
+	capturedOperations = [];
+	capturedSummaries = [];
+	hasError = false;
+	errorMessage = "";
+	async writeRole(_role) {}
+	async writeContent(content) {
+		this.capturedText += content;
+	}
+	async streamText(text, _delayMs) {
+		this.capturedText += text;
+	}
+	async streamData(data) {
+		this.capturedData.push(data);
+	}
+	async streamSummary(summary) {
+		this.capturedSummaries.push(summary);
+	}
+	async streamOperation(operation) {
+		this.capturedOperations.push(operation);
+	}
+	async writeData(_type, data) {
+		this.capturedData.push(data);
+	}
+	async writeSummary(summary) {
+		this.capturedSummaries.push(summary);
+	}
+	async writeOperation(operation) {
+		this.capturedOperations.push(operation);
+	}
+	async writeError(error) {
+		this.hasError = true;
+		this.errorMessage = typeof error === "string" ? error : error.message;
+	}
+	async complete() {}
+	/**
+	* Get the captured response for non-streaming output
+	*/
+	getCapturedResponse() {
+		return {
+			text: this.capturedText,
+			data: this.capturedData,
+			operations: this.capturedOperations,
+			hasError: this.hasError,
+			errorMessage: this.errorMessage
+		};
+	}
+};
+function createBufferingStreamHelper() {
+	return new BufferingStreamHelper();
+}
+const createMCPStreamHelper = createBufferingStreamHelper;
+
+//#endregion
+export { BufferingStreamHelper, SSEStreamHelper, VercelDataStreamHelper, createBufferingStreamHelper, createMCPStreamHelper, createSSEStreamHelper, createVercelStreamHelper };