@inkeep/agents-run-api 0.39.5 → 0.40.0

package/dist/services/ArtifactParser.d.ts

@@ -0,0 +1,105 @@
+import { ArtifactFullData, ArtifactService, ArtifactSummaryData } from "./ArtifactService.js";
+import { ArtifactComponentApiInsert } from "@inkeep/agents-core";
+
+//#region src/services/ArtifactParser.d.ts
+interface StreamPart {
+  kind: 'text' | 'data';
+  text?: string;
+  data?: any;
+}
+type ArtifactData = {
+  artifactId: string;
+  toolCallId: string;
+  name: string;
+  description: string;
+  type: string;
+  summary: Record<string, any>;
+};
+interface ArtifactCreateAnnotation {
+  artifactId: string;
+  toolCallId: string;
+  type: string;
+  baseSelector: string;
+  detailsSelector?: Record<string, string>;
+  raw?: string;
+}
+/**
+ * Artifact parser focused on parsing and text processing responsibilities
+ * Delegates business logic operations to ArtifactService
+ * Handles artifact tag detection, parsing, and text boundary detection
+ */
+declare class ArtifactParser {
+  private static readonly ARTIFACT_CHECK_REGEX;
+  private static readonly ATTR_REGEX;
+  private static readonly ARTIFACT_PATTERNS;
+  private static readonly INCOMPLETE_CREATE_REGEX;
+  private artifactService;
+  constructor(tenantId: string, options?: {
+    sessionId?: string;
+    taskId?: string;
+    projectId?: string;
+    contextId?: string;
+    artifactComponents?: ArtifactComponentApiInsert[];
+    streamRequestId?: string;
+    subAgentId?: string;
+    artifactService?: ArtifactService;
+  });
+  /**
+   * Check if text contains complete artifact markers (ref or create)
+   */
+  hasArtifactMarkers(text: string): boolean;
+  /**
+   * Check if text has incomplete artifact marker (for streaming)
+   * More robust detection that handles streaming fragments
+   */
+  hasIncompleteArtifact(text: string): boolean;
+  /**
+   * Find safe text boundary before incomplete artifacts (for streaming)
+   * Enhanced to handle streaming chunks that split in the middle of artifacts
+   */
+  findSafeTextBoundary(text: string): number;
+  /**
+   * Get all artifacts for a context - delegates to service
+   */
+  getContextArtifacts(contextId: string): Promise<Map<string, any>>;
+  /**
+   * Parse attributes from the artifact:create tag
+   */
+  private parseCreateAttributes;
+  /**
+   * Parse artifact creation annotations from text
+   */
+  private parseCreateAnnotations;
+  /**
+   * Extract artifact data from a create annotation - delegates to service
+   */
+  private extractFromCreateAnnotation;
+  /**
+   * Parse text with artifact markers into parts array
+   * Handles both artifact:ref and artifact:create tags
+   * Can work with or without pre-fetched artifact map
+   */
+  parseText(text: string, artifactMap?: Map<string, any>, subAgentId?: string): Promise<StreamPart[]>;
+  /**
+   * Process object/dataComponents for artifact components
+   */
+  parseObject(obj: any, artifactMap?: Map<string, any>, subAgentId?: string): Promise<StreamPart[]>;
+  /**
+   * Check if object is an artifact component
+   */
+  private isArtifactComponent;
+  /**
+   * Check if object is an artifact create component
+   */
+  private isArtifactCreateComponent;
+  /**
+   * Extract artifact from ArtifactCreate component
+   */
+  private extractFromArtifactCreateComponent;
+  /**
+   * Get artifact data - delegates to service
+   */
+  private getArtifactData;
+}
+//#endregion
+export { ArtifactCreateAnnotation, ArtifactData, type ArtifactFullData, ArtifactParser, type ArtifactSummaryData, StreamPart };

package/dist/services/ArtifactParser.js

@@ -0,0 +1,338 @@
+import { getLogger } from "../logger.js";
+import { ArtifactService } from "./ArtifactService.js";
+
+//#region src/services/ArtifactParser.ts
+const logger = getLogger("ArtifactParser");
+/**
+* Artifact parser focused on parsing and text processing responsibilities
+* Delegates business logic operations to ArtifactService
+* Handles artifact tag detection, parsing, and text boundary detection
+*/
+var ArtifactParser = class ArtifactParser {
+	static ARTIFACT_CHECK_REGEX = /<artifact:ref\s+(?=.*id=['"][^'"]+['"])(?=.*tool=['"][^'"]+['"])[^>]*\/>/;
+	static ATTR_REGEX = /(\w+)="([^"]*)"|(\w+)='([^']*)'|(\w+)=({[^}]+})/g;
+	static ARTIFACT_PATTERNS = [
+		"<a",
+		"<ar",
+		"<art",
+		"<arti",
+		"<artif",
+		"<artifa",
+		"<artifac",
+		"<artifact",
+		"<artifact:",
+		"<artifact:r",
+		"<artifact:re",
+		"<artifact:ref",
+		"<artifact:c",
+		"<artifact:cr",
+		"<artifact:cre",
+		"<artifact:crea",
+		"<artifact:creat",
+		"<artifact:create"
+	];
+	static INCOMPLETE_CREATE_REGEX = /<artifact:create(?![^>]*(?:\/>|<\/artifact:create>))/;
+	artifactService;
+	constructor(tenantId, options) {
+		if (options?.artifactService) this.artifactService = options.artifactService;
+		else this.artifactService = new ArtifactService({
+			tenantId,
+			...options
+		});
+	}
+	/**
+	* Check if text contains complete artifact markers (ref or create)
+	*/
+	hasArtifactMarkers(text) {
+		const refMatch = ArtifactParser.ARTIFACT_CHECK_REGEX.test(text);
+		const createMatch = /<artifact:create\s+([^>]+?)(?:\s*\/)?>(?:(.*?)<\/artifact:create>)?/gs.test(text);
+		return refMatch || createMatch;
+	}
+	/**
+	* Check if text has incomplete artifact marker (for streaming)
+	* More robust detection that handles streaming fragments
+	*/
+	hasIncompleteArtifact(text) {
+		return ArtifactParser.ARTIFACT_PATTERNS.some((pattern) => text.endsWith(pattern)) || /<artifact:ref[^>]+$/.test(text) || /<artifact:create[^>]*$/.test(text) || ArtifactParser.INCOMPLETE_CREATE_REGEX.test(text) && !text.includes("</artifact:create>") || this.findSafeTextBoundary(text) < text.length;
+	}
+	/**
+	* Find safe text boundary before incomplete artifacts (for streaming)
+	* Enhanced to handle streaming chunks that split in the middle of artifacts
+	*/
+	findSafeTextBoundary(text) {
+		for (const pattern of [/<artifact:ref(?![^>]*\/>).*$/, /<artifact:create(?![^>]*(?:\/>|<\/artifact:create>)).*$/]) {
+			const match = text.match(pattern);
+			if (match && match.index !== void 0) return match.index;
+		}
+		for (const pattern of ArtifactParser.ARTIFACT_PATTERNS) {
+			const lastIndex = text.lastIndexOf(pattern);
+			if (lastIndex !== -1) {
+				const textAfterPattern = text.slice(lastIndex);
+				if (!textAfterPattern.includes("/>") && !textAfterPattern.includes("</artifact:")) return lastIndex;
+			}
+		}
+		return text.length;
+	}
+	/**
+	* Get all artifacts for a context - delegates to service
+	*/
+	async getContextArtifacts(contextId) {
+		return this.artifactService.getContextArtifacts(contextId);
+	}
+	/**
+	* Parse attributes from the artifact:create tag
+	*/
+	parseCreateAttributes(attrString) {
+		const attrs = {};
+		let match;
+		ArtifactParser.ATTR_REGEX.lastIndex = 0;
+		while ((match = ArtifactParser.ATTR_REGEX.exec(attrString)) !== null) {
+			const key = match[1] || match[3] || match[5];
+			let value = match[2] || match[4] || match[6];
+			if (value?.startsWith("{")) try {
+				value = JSON.parse(value);
+			} catch {}
+			attrs[key] = value;
+		}
+		if (!attrs.id || !attrs.tool || !attrs.type || !attrs.base) {
+			logger.warn({
+				attrs,
+				attrString
+			}, "Missing required attributes in artifact annotation");
+			return null;
+		}
+		return {
+			artifactId: attrs.id,
+			toolCallId: attrs.tool,
+			type: attrs.type,
+			baseSelector: attrs.base,
+			detailsSelector: attrs.details || {}
+		};
+	}
+	/**
+	* Parse artifact creation annotations from text
+	*/
+	parseCreateAnnotations(text) {
+		const annotations = [];
+		const matches = [...text.matchAll(/<artifact:create\s+([^>]+?)(?:\s*\/)?>(?:(.*?)<\/artifact:create>)?/gs)];
+		for (const match of matches) {
+			const [fullMatch, attributes] = match;
+			const annotation = this.parseCreateAttributes(attributes);
+			if (annotation) {
+				annotation.raw = fullMatch;
+				annotations.push(annotation);
+			}
+		}
+		return annotations;
+	}
+	/**
+	* Extract artifact data from a create annotation - delegates to service
+	*/
+	async extractFromCreateAnnotation(annotation, subAgentId) {
+		const request = {
+			artifactId: annotation.artifactId,
+			toolCallId: annotation.toolCallId,
+			type: annotation.type,
+			baseSelector: annotation.baseSelector,
+			detailsSelector: annotation.detailsSelector
+		};
+		return this.artifactService.createArtifact(request, subAgentId);
+	}
+	/**
+	* Parse text with artifact markers into parts array
+	* Handles both artifact:ref and artifact:create tags
+	* Can work with or without pre-fetched artifact map
+	*/
+	async parseText(text, artifactMap, subAgentId) {
+		let processedText = text;
+		const createAnnotations = this.parseCreateAnnotations(text);
+		const createdArtifactData = /* @__PURE__ */ new Map();
+		const failedAnnotations = [];
+		for (const annotation of createAnnotations) try {
+			const artifactData = await this.extractFromCreateAnnotation(annotation, subAgentId);
+			if (artifactData && annotation.raw) createdArtifactData.set(annotation.raw, artifactData);
+			else if (annotation.raw) {
+				failedAnnotations.push(`Failed to create artifact "${annotation.artifactId}": Missing or invalid data`);
+				processedText = processedText.replace(annotation.raw, "");
+				logger.warn({
+					annotation,
+					artifactData
+				}, "Removed failed artifact:create annotation from output");
+			}
+		} catch (error) {
+			const errorMsg = error instanceof Error ? error.message : "Unknown error";
+			failedAnnotations.push(`Failed to create artifact "${annotation.artifactId}": ${errorMsg}`);
+			if (annotation.raw) processedText = processedText.replace(annotation.raw, "");
+			logger.error({
+				annotation,
+				error
+			}, "Failed to extract artifact from create annotation");
+		}
+		if (failedAnnotations.length > 0) logger.warn({
+			failedCount: failedAnnotations.length,
+			failures: failedAnnotations
+		}, "Some artifact creation attempts failed");
+		const parts = [];
+		const createRegex = /<artifact:create\s+([^>]+?)(?:\s*\/)?>(?:(.*?)<\/artifact:create>)?/gs;
+		const refRegex = /<artifact:ref\s+id=(["'])([^"']*?)\1\s+tool=(["'])([^"']*?)\3\s*\/>/gs;
+		const createMatches = [...text.matchAll(createRegex)];
+		const refMatches = [...processedText.matchAll(refRegex)];
+		const allMatches = [...createMatches.map((match) => ({
+			match,
+			type: "create"
+		})), ...refMatches.map((match) => ({
+			match,
+			type: "ref"
+		}))].sort((a, b) => (a.match.index || 0) - (b.match.index || 0));
+		if (allMatches.length === 0) return [{
+			kind: "text",
+			text: processedText
+		}];
+		let lastIndex = 0;
+		for (const { match, type } of allMatches) {
+			if (match.index === void 0) continue;
+			const matchStart = match.index;
+			const fullMatch = match[0];
+			if (matchStart > lastIndex) {
+				const textBefore = text.slice(lastIndex, matchStart);
+				if (textBefore) parts.push({
+					kind: "text",
+					text: textBefore
+				});
+			}
+			let artifactData = null;
+			if (type === "create") artifactData = createdArtifactData.get(fullMatch) || null;
+			else {
+				const [, , artifactId, , toolCallId] = match;
+				artifactData = await this.getArtifactData(artifactId, toolCallId, artifactMap);
+			}
+			if (artifactData) parts.push({
+				kind: "data",
+				data: {
+					artifactId: artifactData.artifactId,
+					toolCallId: artifactData.toolCallId,
+					name: artifactData.name,
+					description: artifactData.description,
+					type: artifactData.type,
+					artifactSummary: artifactData.data
+				}
+			});
+			lastIndex = matchStart + fullMatch.length;
+		}
+		if (lastIndex < text.length) {
+			const remainingText = text.slice(lastIndex);
+			if (remainingText) parts.push({
+				kind: "text",
+				text: remainingText
+			});
+		}
+		return parts;
+	}
+	/**
+	* Process object/dataComponents for artifact components
+	*/
+	async parseObject(obj, artifactMap, subAgentId) {
+		if (obj?.dataComponents && Array.isArray(obj.dataComponents)) {
+			const parts = [];
+			for (const component of obj.dataComponents) if (this.isArtifactComponent(component)) {
+				const artifactData = await this.getArtifactData(component.props.artifact_id, component.props.tool_call_id, artifactMap);
+				if (artifactData) parts.push({
+					kind: "data",
+					data: {
+						artifactId: artifactData.artifactId,
+						toolCallId: artifactData.toolCallId,
+						name: artifactData.name,
+						description: artifactData.description,
+						type: artifactData.type,
+						artifactSummary: artifactData.data
+					}
+				});
+			} else if (this.isArtifactCreateComponent(component)) {
+				const createData = await this.extractFromArtifactCreateComponent(component, subAgentId);
+				if (createData) parts.push({
+					kind: "data",
+					data: {
+						artifactId: createData.artifactId,
+						toolCallId: createData.toolCallId,
+						name: createData.name,
+						description: createData.description,
+						type: createData.type,
+						artifactSummary: createData.data
+					}
+				});
+			} else parts.push({
+				kind: "data",
+				data: component
+			});
+			return parts;
+		}
+		if (this.isArtifactComponent(obj)) {
+			const artifactData = await this.getArtifactData(obj.props.artifact_id, obj.props.tool_call_id, artifactMap);
+			return artifactData ? [{
+				kind: "data",
+				data: {
+					artifactId: artifactData.artifactId,
+					toolCallId: artifactData.toolCallId,
+					name: artifactData.name,
+					description: artifactData.description,
+					type: artifactData.type,
+					artifactSummary: artifactData.data
+				}
+			}] : [];
+		}
+		if (this.isArtifactCreateComponent(obj)) {
+			const createData = await this.extractFromArtifactCreateComponent(obj, subAgentId);
+			return createData ? [{
+				kind: "data",
+				data: {
+					artifactId: createData.artifactId,
+					toolCallId: createData.toolCallId,
+					name: createData.name,
+					description: createData.description,
+					type: createData.type,
+					artifactSummary: createData.data
+				}
+			}] : [];
+		}
+		return [{
+			kind: "data",
+			data: obj
+		}];
+	}
+	/**
+	* Check if object is an artifact component
+	*/
+	isArtifactComponent(obj) {
+		return obj?.name === "Artifact" && obj?.props?.artifact_id && obj?.props?.tool_call_id;
+	}
+	/**
+	* Check if object is an artifact create component
+	*/
+	isArtifactCreateComponent(obj) {
+		return obj?.name?.startsWith("ArtifactCreate_") && obj?.props?.id && obj?.props?.tool_call_id;
+	}
+	/**
+	* Extract artifact from ArtifactCreate component
+	*/
+	async extractFromArtifactCreateComponent(component, subAgentId) {
+		const props = component.props;
+		if (!props) return null;
+		const annotation = {
+			artifactId: props.id,
+			toolCallId: props.tool_call_id,
+			type: props.type,
+			baseSelector: props.base_selector,
+			detailsSelector: props.details_selector || {}
+		};
+		return await this.extractFromCreateAnnotation(annotation, subAgentId);
+	}
+	/**
+	* Get artifact data - delegates to service
+	*/
+	async getArtifactData(artifactId, toolCallId, artifactMap) {
+		return await this.artifactService.getArtifactSummary(artifactId, toolCallId, artifactMap);
+	}
+};
+
+//#endregion
+export { ArtifactParser };

package/dist/services/ArtifactService.d.ts

@@ -0,0 +1,123 @@
+import { ArtifactComponentApiInsert } from "@inkeep/agents-core";
+
+//#region src/services/ArtifactService.d.ts
+interface ArtifactSummaryData {
+  artifactId: string;
+  toolCallId: string;
+  name: string;
+  description: string;
+  type?: string;
+  data: any;
+}
+interface ArtifactFullData {
+  artifactId: string;
+  toolCallId: string;
+  name: string;
+  description: string;
+  type?: string;
+  data: any;
+}
+interface ArtifactCreateRequest {
+  artifactId: string;
+  toolCallId: string;
+  type: string;
+  baseSelector: string;
+  detailsSelector?: Record<string, string>;
+}
+interface ArtifactServiceContext {
+  tenantId: string;
+  sessionId?: string;
+  taskId?: string;
+  projectId?: string;
+  contextId?: string;
+  artifactComponents?: ArtifactComponentApiInsert[];
+  streamRequestId?: string;
+  subAgentId?: string;
+}
+/**
+ * Service class responsible for artifact business logic operations
+ * Handles database persistence, tool result extraction, and artifact management
+ * Separated from parsing concerns for better architecture
+ */
+declare class ArtifactService {
+  private context;
+  private createdArtifacts;
+  private static selectorCache;
+  constructor(context: ArtifactServiceContext);
+  /**
+   * Clear static caches to prevent memory leaks between sessions
+   */
+  static clearCaches(): void;
+  /**
+   * Update artifact components in the context
+   */
+  updateArtifactComponents(artifactComponents: ArtifactComponentApiInsert[]): void;
+  /**
+   * Get all artifacts for a context from database
+   */
+  getContextArtifacts(contextId: string): Promise<Map<string, any>>;
+  /**
+   * Create artifact from tool result and request data
+   */
+  createArtifact(request: ArtifactCreateRequest, subAgentId?: string): Promise<ArtifactSummaryData | null>;
+  /**
+   * Get artifact summary data by ID and tool call ID
+   */
+  getArtifactSummary(artifactId: string, toolCallId: string, artifactMap?: Map<string, any>): Promise<ArtifactSummaryData | null>;
+  /**
+   * Get artifact full data by ID and tool call ID
+   */
+  getArtifactFull(artifactId: string, toolCallId: string, artifactMap?: Map<string, any>): Promise<ArtifactFullData | null>;
+  /**
+   * Format raw artifact to standardized summary data format
+   */
+  private formatArtifactSummaryData;
+  /**
+   * Format raw artifact to standardized full data format
+   */
+  private formatArtifactFullData;
+  /**
+   * Validate extracted data against the schemas used for extraction
+   */
+  private validateExtractedData;
+  /**
+   * Persist artifact to database vian agent session
+   */
+  private persistArtifact;
+  /**
+   * Cache artifact for immediate access
+   */
+  private cacheArtifact;
+  /**
+   * Sanitize JMESPath selector to fix common syntax issues (with caching)
+   */
+  private sanitizeJMESPathSelector;
+  /**
+   * Save an already-created artifact directly to the database
+   * Used by AgentSession to save artifacts after name/description generation
+   */
+  saveArtifact(artifact: {
+    artifactId: string;
+    name: string;
+    description: string;
+    type: string;
+    data: Record<string, any>;
+    summaryData?: Record<string, any>;
+    metadata?: Record<string, any>;
+    toolCallId?: string;
+  }): Promise<void>;
+  /**
+   * Clean up over-escaped strings that have been through multiple JSON serialization cycles
+   */
+  cleanEscapedContent(value: any): any;
+  /**
+   * Extract properties from data using schema-defined fields and custom selectors
+   */
+  private extractPropsFromSchema;
+  /**
+   * Filter extracted props based on schema
+   */
+  private filterBySchema;
+}
+//#endregion
+export { ArtifactCreateRequest, ArtifactFullData, ArtifactService, ArtifactServiceContext, ArtifactSummaryData };