@inkeep/agents-run-api 0.1.0

package/dist/utils/incremental-stream-parser.d.ts

@@ -0,0 +1,57 @@
+import { type StreamPart } from './artifact-parser.js';
+import type { StreamHelper } from './stream-helpers.js';
+/**
+ * Incremental parser that processes streaming text and formats artifacts/objects as they become complete
+ * Uses the unified ArtifactParser to eliminate redundancy
+ */
+export declare class IncrementalStreamParser {
+    private buffer;
+    private pendingTextBuffer;
+    private streamHelper;
+    private artifactParser;
+    private contextId;
+    private hasStartedRole;
+    private collectedParts;
+    constructor(streamHelper: StreamHelper, tenantId: string, contextId: string);
+    /**
+     * Process a new text chunk for text streaming (handles artifact markers)
+     */
+    processTextChunk(chunk: string): Promise<void>;
+    /**
+     * Process a new object chunk for object streaming (handles JSON objects with artifact references)
+     */
+    processObjectChunk(chunk: string): Promise<void>;
+    /**
+     * Process tool call stream for structured output, streaming components as they complete
+     */
+    processToolCallStream(stream: AsyncIterable<any>, targetToolName: string): Promise<void>;
+    /**
+     * Legacy method for backward compatibility - defaults to text processing
+     */
+    processChunk(chunk: string): Promise<void>;
+    /**
+     * Process any remaining buffer content at the end of stream
+     */
+    finalize(): Promise<void>;
+    /**
+     * Get all collected parts for building the final response
+     */
+    getCollectedParts(): StreamPart[];
+    /**
+     * Parse buffer for complete artifacts and text parts (for text streaming)
+     */
+    private parseTextBuffer;
+    /**
+     * Parse buffer for complete JSON objects with artifact references (for object streaming)
+     */
+    private parseObjectBuffer;
+    /**
+     * Check if text might be the start of an artifact marker
+     */
+    private mightBeArtifactStart;
+    /**
+     * Stream a formatted part (text or data) with smart buffering
+     */
+    private streamPart;
+}
+//# sourceMappingURL=incremental-stream-parser.d.ts.map

package/dist/utils/incremental-stream-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"incremental-stream-parser.d.ts","sourceRoot":"","sources":["../../src/utils/incremental-stream-parser.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AASxD;;;GAGG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,iBAAiB,CAAM;IAC/B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,cAAc,CAAoB;gBAE9B,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAM3E;;OAEG;IACG,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcpD;;OAEG;IACG,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IActD;;OAEG;IACG,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsE9F;;OAEG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAgC/B;;OAEG;IACH,iBAAiB,IAAI,UAAU,EAAE;IAIjC;;OAEG;YACW,eAAe;IAoD7B;;OAEG;YACW,iBAAiB;IA4B/B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAK5B;;OAEG;YACW,UAAU;CAqDzB"}

package/dist/utils/incremental-stream-parser.js

@@ -0,0 +1,287 @@
+import { getLogger } from '../logger.js';
+import { ArtifactParser } from './artifact-parser.js';
+const logger = getLogger('IncrementalStreamParser');
+/**
+ * Incremental parser that processes streaming text and formats artifacts/objects as they become complete
+ * Uses the unified ArtifactParser to eliminate redundancy
+ */
+export class IncrementalStreamParser {
+    buffer = '';
+    pendingTextBuffer = '';
+    streamHelper;
+    artifactParser;
+    contextId;
+    hasStartedRole = false;
+    collectedParts = [];
+    constructor(streamHelper, tenantId, contextId) {
+        this.streamHelper = streamHelper;
+        this.contextId = contextId;
+        this.artifactParser = new ArtifactParser(tenantId);
+    }
+    /**
+     * Process a new text chunk for text streaming (handles artifact markers)
+     */
+    async processTextChunk(chunk) {
+        this.buffer += chunk;
+        const parseResult = await this.parseTextBuffer();
+        // Stream complete parts
+        for (const part of parseResult.completeParts) {
+            await this.streamPart(part);
+        }
+        // Update buffer with remaining content
+        this.buffer = parseResult.remainingBuffer;
+    }
+    /**
+     * Process a new object chunk for object streaming (handles JSON objects with artifact references)
+     */
+    async processObjectChunk(chunk) {
+        this.buffer += chunk;
+        const parseResult = await this.parseObjectBuffer();
+        // Stream complete parts
+        for (const part of parseResult.completeParts) {
+            await this.streamPart(part);
+        }
+        // Update buffer with remaining content
+        this.buffer = parseResult.remainingBuffer;
+    }
+    /**
+     * Process tool call stream for structured output, streaming components as they complete
+     */
+    async processToolCallStream(stream, targetToolName) {
+        let jsonBuffer = '';
+        let componentBuffer = '';
+        let depth = 0;
+        let inDataComponents = false;
+        let componentsStreamed = 0;
+        for await (const part of stream) {
+            // Look for tool call deltas with incremental JSON
+            if (part.type === 'tool-call-delta' && part.toolName === targetToolName) {
+                const delta = part.argsTextDelta || '';
+                jsonBuffer += delta;
+                // Parse character by character to detect complete components
+                for (const char of delta) {
+                    componentBuffer += char;
+                    // Track JSON depth
+                    if (char === '{') {
+                        depth++;
+                    }
+                    else if (char === '}') {
+                        depth--;
+                        // At depth 2, we're inside the dataComponents array
+                        // When we return to depth 2, we have a complete component
+                        if (depth === 2 && componentBuffer.includes('"id"')) {
+                            // Extract just the component object
+                            const componentMatch = componentBuffer.match(/\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}/);
+                            if (componentMatch) {
+                                try {
+                                    const component = JSON.parse(componentMatch[0]);
+                                    // Stream this individual component
+                                    const parts = await this.artifactParser.parseObject({ dataComponents: [component] });
+                                    for (const part of parts) {
+                                        await this.streamPart(part);
+                                    }
+                                    componentsStreamed++;
+                                    componentBuffer = ''; // Reset for next component
+                                }
+                                catch (e) {
+                                    // Not valid JSON yet, keep accumulating
+                                    logger.debug({ error: e }, 'Failed to parse component, continuing to accumulate');
+                                }
+                            }
+                        }
+                    }
+                    // Detect when we enter dataComponents array
+                    if (componentBuffer.includes('"dataComponents"') && componentBuffer.includes('[')) {
+                        inDataComponents = true;
+                    }
+                }
+            }
+            // Alternative: if the SDK provides complete tool calls (not deltas)
+            else if (part.type === 'tool-call' && part.toolName === targetToolName) {
+                // Process the complete args at once
+                if (part.args?.dataComponents) {
+                    const parts = await this.artifactParser.parseObject(part.args);
+                    for (const part of parts) {
+                        await this.streamPart(part);
+                    }
+                }
+                break; // Tool call complete
+            }
+        }
+        logger.debug({ componentsStreamed }, 'Finished streaming components');
+    }
+    /**
+     * Legacy method for backward compatibility - defaults to text processing
+     */
+    async processChunk(chunk) {
+        await this.processTextChunk(chunk);
+    }
+    /**
+     * Process any remaining buffer content at the end of stream
+     */
+    async finalize() {
+        if (this.buffer.trim()) {
+            // Process remaining buffer as final text
+            const part = {
+                kind: 'text',
+                text: this.buffer.trim(),
+            };
+            await this.streamPart(part);
+        }
+        // Flush any remaining buffered text
+        if (this.pendingTextBuffer.trim()) {
+            // Clean up any artifact-related tags or remnants before final flush
+            const cleanedText = this.pendingTextBuffer
+                .replace(/<\/?artifact:ref[^>]*>/g, '') // Remove all artifact:ref tags (opening and closing)
+                .replace(/<\/?artifact[^>]*>/g, '') // Remove all artifact tags
+                .replace(/<\/[^>]*artifact[^>]*>/g, '') // Remove closing tags with artifact in the name
+                .replace(/<[^>]*artifact[^>]*\/?>/g, '') // Remove any remaining artifact-related tags
+                .trim();
+            if (cleanedText) {
+                this.collectedParts.push({
+                    kind: 'text',
+                    text: cleanedText,
+                });
+                await this.streamHelper.streamText(cleanedText, 50);
+            }
+            this.pendingTextBuffer = '';
+        }
+    }
+    /**
+     * Get all collected parts for building the final response
+     */
+    getCollectedParts() {
+        return [...this.collectedParts];
+    }
+    /**
+     * Parse buffer for complete artifacts and text parts (for text streaming)
+     */
+    async parseTextBuffer() {
+        const completeParts = [];
+        const workingBuffer = this.buffer;
+        // Check if we have incomplete artifact markers
+        if (this.artifactParser.hasIncompleteArtifact(workingBuffer)) {
+            // Find safe boundary to stream text before incomplete artifact
+            const safeEnd = this.artifactParser.findSafeTextBoundary(workingBuffer);
+            if (safeEnd > 0) {
+                const safeText = workingBuffer.slice(0, safeEnd);
+                // Parse the safe portion for complete artifacts
+                const parts = await this.artifactParser.parseText(safeText);
+                completeParts.push(...parts);
+                return {
+                    completeParts,
+                    remainingBuffer: workingBuffer.slice(safeEnd),
+                };
+            }
+            // Buffer contains only incomplete artifact
+            return {
+                completeParts: [],
+                remainingBuffer: workingBuffer,
+            };
+        }
+        // No incomplete artifacts, parse the entire buffer
+        const parts = await this.artifactParser.parseText(workingBuffer);
+        // Check last part - if it's text, it might be incomplete
+        if (parts.length > 0 && parts[parts.length - 1].kind === 'text') {
+            const lastPart = parts[parts.length - 1];
+            const lastText = lastPart.text || '';
+            // Keep some text in buffer if it might be start of artifact
+            if (this.mightBeArtifactStart(lastText)) {
+                parts.pop(); // Remove last text part
+                return {
+                    completeParts: parts,
+                    remainingBuffer: lastText,
+                };
+            }
+        }
+        return {
+            completeParts: parts,
+            remainingBuffer: '',
+        };
+    }
+    /**
+     * Parse buffer for complete JSON objects with artifact references (for object streaming)
+     */
+    async parseObjectBuffer() {
+        const completeParts = [];
+        try {
+            // Try to parse as complete JSON
+            const parsed = JSON.parse(this.buffer);
+            const parts = await this.artifactParser.parseObject(parsed);
+            return {
+                completeParts: parts,
+                remainingBuffer: '',
+            };
+        }
+        catch {
+            // JSON is incomplete, try partial parsing
+            const { complete, remaining } = this.artifactParser.parsePartialJSON(this.buffer);
+            for (const obj of complete) {
+                const parts = await this.artifactParser.parseObject(obj);
+                completeParts.push(...parts);
+            }
+            return {
+                completeParts,
+                remainingBuffer: remaining,
+            };
+        }
+    }
+    /**
+     * Check if text might be the start of an artifact marker
+     */
+    mightBeArtifactStart(text) {
+        const lastChars = text.slice(-20); // Check last 20 chars
+        return lastChars.includes('<') && !lastChars.includes('/>');
+    }
+    /**
+     * Stream a formatted part (text or data) with smart buffering
+     */
+    async streamPart(part) {
+        // Collect for final response
+        this.collectedParts.push({ ...part });
+        if (!this.hasStartedRole) {
+            await this.streamHelper.writeRole('assistant');
+            this.hasStartedRole = true;
+        }
+        if (part.kind === 'text' && part.text) {
+            // Add to pending buffer
+            this.pendingTextBuffer += part.text;
+            // Flush if safe to do so
+            if (!this.artifactParser.hasIncompleteArtifact(this.pendingTextBuffer)) {
+                // Clean up any artifact-related tags or remnants before flushing
+                const cleanedText = this.pendingTextBuffer
+                    .replace(/<\/?artifact:ref[^>]*>/g, '') // Remove all artifact:ref tags (opening and closing)
+                    .replace(/<\/?artifact[^>]*>/g, '') // Remove all artifact tags
+                    .replace(/<\/[^>]*artifact[^>]*>/g, '') // Remove closing tags with artifact in the name
+                    .replace(/<[^>]*artifact[^>]*\/?>/g, ''); // Remove any remaining artifact-related tags
+                if (cleanedText.trim()) {
+                    await this.streamHelper.streamText(cleanedText, 50);
+                }
+                this.pendingTextBuffer = '';
+            }
+        }
+        else if (part.kind === 'data' && part.data) {
+            // Flush any pending text before streaming data
+            if (this.pendingTextBuffer) {
+                // Clean up any artifact-related tags or remnants before flushing
+                const cleanedText = this.pendingTextBuffer
+                    .replace(/<\/?artifact:ref[^>]*>/g, '') // Remove all artifact:ref tags (opening and closing)
+                    .replace(/<\/?artifact[^>]*>/g, '') // Remove all artifact tags
+                    .replace(/<\/[^>]*artifact[^>]*>/g, '') // Remove closing tags with artifact in the name
+                    .replace(/<[^>]*artifact[^>]*\/?>/g, ''); // Remove any remaining artifact-related tags
+                if (cleanedText.trim()) {
+                    await this.streamHelper.streamText(cleanedText, 50);
+                }
+                this.pendingTextBuffer = '';
+            }
+            // Determine if this is an artifact or regular data component
+            const isArtifact = part.data.artifactId && part.data.taskId;
+            if (isArtifact) {
+                await this.streamHelper.writeData('data-artifact', part.data);
+            }
+            else {
+                await this.streamHelper.writeData('data-component', part.data);
+            }
+        }
+    }
+}

package/dist/utils/response-formatter.d.ts

@@ -0,0 +1,27 @@
+import type { MessageContent } from '@inkeep/agents-core';
+/**
+ * Response formatter that uses the unified ArtifactParser to convert artifact markers
+ * into data parts for consistent artifact handling across all agent responses
+ */
+export declare class ResponseFormatter {
+    private tenantId;
+    private artifactParser;
+    constructor(tenantId: string);
+    /**
+     * Process structured object response and replace artifact markers with actual artifacts
+     */
+    formatObjectResponse(responseObject: any, contextId: string): Promise<MessageContent>;
+    /**
+     * Process agent response and convert artifact markers to data parts
+     */
+    formatResponse(responseText: string, contextId: string): Promise<MessageContent>;
+    /**
+     * Count unique artifacts in parts array
+     */
+    private countUniqueArtifacts;
+    /**
+     * Log artifacts found in parts to span
+     */
+    private logArtifacts;
+}
+//# sourceMappingURL=response-formatter.d.ts.map

package/dist/utils/response-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-formatter.d.ts","sourceRoot":"","sources":["../../src/utils/response-formatter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAe1D;;;GAGG;AACH,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ;IAF5B,OAAO,CAAC,cAAc,CAAiB;gBAEnB,QAAQ,EAAE,MAAM;IAIpC;;OAEG;IACG,oBAAoB,CAAC,cAAc,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA0C3F;;OAEG;IACG,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAgEtF;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAgB5B;;OAEG;IACH,OAAO,CAAC,YAAY;CAwBrB"}

package/dist/utils/response-formatter.js

@@ -0,0 +1,160 @@
+import { trace } from '@opentelemetry/api';
+import { getLogger } from '../logger.js';
+import { SERVICE_VERSION } from '../tracer.js';
+import { ArtifactParser } from './artifact-parser.js';
+const logger = getLogger('ResponseFormatter');
+// Service name for response formatter tracer
+const RESPONSE_FORMATTER_SERVICE = 'responseFormatter';
+function getResponseFormatterTracer() {
+    const tracerProvider = trace.getTracerProvider();
+    return tracerProvider.getTracer(RESPONSE_FORMATTER_SERVICE, SERVICE_VERSION);
+}
+/**
+ * Response formatter that uses the unified ArtifactParser to convert artifact markers
+ * into data parts for consistent artifact handling across all agent responses
+ */
+export class ResponseFormatter {
+    tenantId;
+    artifactParser;
+    constructor(tenantId) {
+        this.tenantId = tenantId;
+        this.artifactParser = new ArtifactParser(tenantId);
+    }
+    /**
+     * Process structured object response and replace artifact markers with actual artifacts
+     */
+    async formatObjectResponse(responseObject, contextId) {
+        const tracer = getResponseFormatterTracer();
+        return tracer.startActiveSpan('response.formatObject', async (span) => {
+            try {
+                // Get all artifacts available in this context
+                const artifactMap = await this.artifactParser.getContextArtifacts(contextId);
+                span.setAttributes({
+                    'response.type': 'object',
+                    'response.availableArtifacts': artifactMap.size,
+                });
+                // Parse the object using unified parser
+                const parts = await this.artifactParser.parseObject(responseObject, artifactMap);
+                // Count and log metrics
+                const uniqueArtifacts = this.countUniqueArtifacts(parts);
+                span.setAttributes({
+                    'response.dataPartsCount': parts.length,
+                    'response.artifactsCount': uniqueArtifacts,
+                    'response.totalPartsCount': parts.length,
+                });
+                this.logArtifacts(span, parts);
+                span.addEvent('response.parts.final_output', {
+                    final_parts_array: JSON.stringify(parts, null, 2),
+                });
+                return { parts };
+            }
+            catch (error) {
+                span.recordException(error);
+                logger.error({ error, responseObject }, 'Error formatting object response');
+                return {
+                    parts: [{ kind: 'data', data: responseObject }],
+                };
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    /**
+     * Process agent response and convert artifact markers to data parts
+     */
+    async formatResponse(responseText, contextId) {
+        const tracer = getResponseFormatterTracer();
+        return tracer.startActiveSpan('response.format', async (span) => {
+            try {
+                span.setAttributes({
+                    'response.hasArtifactMarkers': this.artifactParser.hasArtifactMarkers(responseText),
+                    'response.contextId': contextId,
+                    'response.textLength': responseText.length,
+                });
+                // Check if the response contains artifact markers
+                if (!this.artifactParser.hasArtifactMarkers(responseText)) {
+                    span.setAttributes({
+                        'response.result': 'no_markers_found',
+                    });
+                    return { parts: [{ kind: 'text', text: responseText }] };
+                }
+                // Get all artifacts available in this context
+                const artifactMap = await this.artifactParser.getContextArtifacts(contextId);
+                span.setAttributes({
+                    'response.type': 'text',
+                    'response.availableArtifacts': artifactMap.size,
+                });
+                // Parse text using unified parser
+                const parts = await this.artifactParser.parseText(responseText, artifactMap);
+                // If only one text part, return as plain text
+                if (parts.length === 1 && parts[0].kind === 'text') {
+                    return { text: parts[0].text };
+                }
+                // Count and log metrics
+                const textParts = parts.filter((p) => p.kind === 'text').length;
+                const dataParts = parts.filter((p) => p.kind === 'data').length;
+                const uniqueArtifacts = this.countUniqueArtifacts(parts);
+                span.setAttributes({
+                    'response.textPartsCount': textParts,
+                    'response.dataPartsCount': dataParts,
+                    'response.artifactsCount': uniqueArtifacts,
+                    'response.totalPartsCount': parts.length,
+                });
+                this.logArtifacts(span, parts);
+                span.addEvent('response.parts.final_output', {
+                    final_parts_array: JSON.stringify(parts, null, 2),
+                });
+                return { parts };
+            }
+            catch (error) {
+                span.recordException(error);
+                span.setStatus({ code: 2, message: error.message });
+                logger.error({ error, responseText }, 'Error formatting response');
+                return { text: responseText };
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    /**
+     * Count unique artifacts in parts array
+     */
+    countUniqueArtifacts(parts) {
+        const uniqueKeys = new Set(parts
+            .filter((p) => p.kind === 'data')
+            .map((p) => {
+            const data = p.data;
+            if (data?.artifactId && data?.taskId) {
+                return `${data.artifactId}:${data.taskId}`;
+            }
+            return null;
+        })
+            .filter((key) => key !== null));
+        return uniqueKeys.size;
+    }
+    /**
+     * Log artifacts found in parts to span
+     */
+    logArtifacts(span, parts) {
+        const artifacts = parts
+            .filter((p) => p.kind === 'data')
+            .map((p) => {
+            const data = p.data;
+            return {
+                artifactId: data?.artifactId,
+                name: data?.name,
+                taskId: data?.taskId,
+            };
+        })
+            .filter((art) => art.artifactId && art.taskId);
+        if (artifacts.length > 0) {
+            const uniqueArtifactsList = Array.from(new Map(artifacts.map((art) => [`${art.artifactId}:${art.taskId}`, art])).values());
+            span.addEvent('artifacts.found', {
+                'artifacts.count': uniqueArtifactsList.length,
+                'artifacts.list': JSON.stringify(uniqueArtifactsList),
+            });
+        }
+    }
+}