@inkeep/agents-run-api 0.39.4 → 0.40.0

package/dist/utils/stream-helpers.js

@@ -0,0 +1,518 @@
+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/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();
+	sessionId;
+	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);
+	}
+	setSessionId(sessionId) {
+		this.sessionId = sessionId;
+	}
+	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 = "";
+	sessionId;
+	setSessionId(sessionId) {
+		this.sessionId = sessionId;
+	}
+	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 };

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

@@ -0,0 +1,22 @@
+import { StreamHelper } from "./stream-helpers.js";
+
+//#region src/utils/stream-registry.d.ts
+
+/**
+ * Register a StreamHelper for a specific request ID
+ */
+declare function registerStreamHelper(requestId: string, streamHelper: StreamHelper): void;
+/**
+ * Get a StreamHelper by request ID
+ */
+declare function getStreamHelper(requestId: string): StreamHelper | undefined;
+/**
+ * Unregister a StreamHelper for a specific request ID
+ */
+declare function unregisterStreamHelper(requestId: string): void;
+/**
+ * Get registry size (for debugging)
+ */
+declare function getRegistrySize(): number;
+//#endregion
+export { getRegistrySize, getStreamHelper, registerStreamHelper, unregisterStreamHelper };

package/dist/utils/stream-registry.js

@@ -0,0 +1,34 @@
+//#region src/utils/stream-registry.ts
+/**
+* Global registry for StreamHelper instances
+* Allows agents to access streamHelper via requestId across A2A boundaries
+*/
+const streamHelperRegistry = /* @__PURE__ */ new Map();
+/**
+* Register a StreamHelper for a specific request ID
+*/
+function registerStreamHelper(requestId, streamHelper) {
+	streamHelperRegistry.set(requestId, streamHelper);
+	if ("setSessionId" in streamHelper && typeof streamHelper.setSessionId === "function") streamHelper.setSessionId(requestId);
+}
+/**
+* Get a StreamHelper by request ID
+*/
+function getStreamHelper(requestId) {
+	return streamHelperRegistry.get(requestId);
+}
+/**
+* Unregister a StreamHelper for a specific request ID
+*/
+function unregisterStreamHelper(requestId) {
+	streamHelperRegistry.delete(requestId);
+}
+/**
+* Get registry size (for debugging)
+*/
+function getRegistrySize() {
+	return streamHelperRegistry.size;
+}
+
+//#endregion
+export { getRegistrySize, getStreamHelper, registerStreamHelper, unregisterStreamHelper };

package/dist/utils/token-estimator.d.ts

@@ -0,0 +1,69 @@
+//#region src/utils/token-estimator.d.ts
+/**
+ * Token estimation utility for context tracking.
+ *
+ * Uses character-based approximation (~4 characters per token) which:
+ * - Works universally for all models (OpenAI, Anthropic, Gemini, custom)
+ * - Requires no external dependencies
+ * - Is fast (simple string length calculation)
+ * - Is accurate enough for relative comparisons between context components
+ */
+/**
+ * Breakdown of estimated token usage for each context component.
+ * All values are approximate token counts.
+ */
+interface ContextBreakdown {
+  /** Base system prompt template tokens */
+  systemPromptTemplate: number;
+  /** Core instructions (corePrompt) tokens */
+  coreInstructions: number;
+  /** Agent-level context (prompt) tokens */
+  agentPrompt: number;
+  /** Tools section (MCP, function, relation tools) tokens */
+  toolsSection: number;
+  /** Artifacts section tokens */
+  artifactsSection: number;
+  /** Data components section tokens (Phase 2) */
+  dataComponents: number;
+  /** Artifact component instructions tokens */
+  artifactComponents: number;
+  /** Transfer instructions tokens */
+  transferInstructions: number;
+  /** Delegation instructions tokens */
+  delegationInstructions: number;
+  /** Thinking preparation instructions tokens */
+  thinkingPreparation: number;
+  /** Conversation history tokens */
+  conversationHistory: number;
+  /** Total estimated tokens */
+  total: number;
+}
+/**
+ * Creates an empty context breakdown with all values set to 0.
+ */
+declare function createEmptyBreakdown(): ContextBreakdown;
+/**
+ * Estimates the number of tokens in a text string using character-based approximation.
+ *
+ * @param text - The text to estimate tokens for
+ * @returns Estimated token count (approximately text.length / 4)
+ */
+declare function estimateTokens(text: string | undefined | null): number;
+/**
+ * Calculates the total from all breakdown components and updates the total field.
+ *
+ * @param breakdown - The context breakdown to calculate total for
+ * @returns The breakdown with updated total
+ */
+declare function calculateBreakdownTotal(breakdown: ContextBreakdown): ContextBreakdown;
+/**
+ * Result from prompt assembly that includes both the prompt and token breakdown.
+ */
+interface AssembleResult {
+  /** The assembled prompt string */
+  prompt: string;
+  /** Token breakdown for each component */
+  breakdown: ContextBreakdown;
+}
+//#endregion
+export { AssembleResult, ContextBreakdown, calculateBreakdownTotal, createEmptyBreakdown, estimateTokens };

package/dist/utils/token-estimator.js

@@ -0,0 +1,53 @@
+//#region src/utils/token-estimator.ts
+/**
+* Token estimation utility for context tracking.
+*
+* Uses character-based approximation (~4 characters per token) which:
+* - Works universally for all models (OpenAI, Anthropic, Gemini, custom)
+* - Requires no external dependencies
+* - Is fast (simple string length calculation)
+* - Is accurate enough for relative comparisons between context components
+*/
+const CHARS_PER_TOKEN = 4;
+/**
+* Creates an empty context breakdown with all values set to 0.
+*/
+function createEmptyBreakdown() {
+	return {
+		systemPromptTemplate: 0,
+		coreInstructions: 0,
+		agentPrompt: 0,
+		toolsSection: 0,
+		artifactsSection: 0,
+		dataComponents: 0,
+		artifactComponents: 0,
+		transferInstructions: 0,
+		delegationInstructions: 0,
+		thinkingPreparation: 0,
+		conversationHistory: 0,
+		total: 0
+	};
+}
+/**
+* Estimates the number of tokens in a text string using character-based approximation.
+*
+* @param text - The text to estimate tokens for
+* @returns Estimated token count (approximately text.length / 4)
+*/
+function estimateTokens(text) {
+	if (!text) return 0;
+	return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+/**
+* Calculates the total from all breakdown components and updates the total field.
+*
+* @param breakdown - The context breakdown to calculate total for
+* @returns The breakdown with updated total
+*/
+function calculateBreakdownTotal(breakdown) {
+	breakdown.total = breakdown.systemPromptTemplate + breakdown.coreInstructions + breakdown.agentPrompt + breakdown.toolsSection + breakdown.artifactsSection + breakdown.dataComponents + breakdown.artifactComponents + breakdown.transferInstructions + breakdown.delegationInstructions + breakdown.thinkingPreparation + breakdown.conversationHistory;
+	return breakdown;
+}
+
+//#endregion
+export { calculateBreakdownTotal, createEmptyBreakdown, estimateTokens };

package/dist/utils/tracer.d.ts

@@ -0,0 +1,7 @@
+import { setSpanWithError } from "@inkeep/agents-core";
+import * as _opentelemetry_api0 from "@opentelemetry/api";
+
+//#region src/utils/tracer.d.ts
+declare const tracer: _opentelemetry_api0.Tracer;
+//#endregion
+export { setSpanWithError, tracer };