@inkeep/agents-run-api 0.0.0-dev-20250910232631

package/dist/types/execution-context.js

@@ -0,0 +1,14 @@
+/**
+ * Create execution context from middleware values
+ */
+export function createExecutionContext(params) {
+    return {
+        apiKey: params.apiKey,
+        tenantId: params.tenantId,
+        projectId: params.projectId,
+        graphId: params.graphId,
+        baseUrl: params.baseUrl || process.env.API_URL || 'http://localhost:3003',
+        apiKeyId: params.apiKeyId,
+        agentId: params.agentId,
+    };
+}

package/dist/utils/agent-operations.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Agent initialization operation event
+ */
+export interface AgentInitializingEvent {
+    type: 'agent_initializing';
+    ctx: {
+        sessionId: string;
+        graphId: string;
+    };
+}
+/**
+ * Agent ready operation event
+ */
+export interface AgentReadyEvent {
+    type: 'agent_ready';
+    ctx: {
+        sessionId: string;
+        graphId: string;
+    };
+}
+/**
+ * Completion operation event
+ */
+export interface CompletionEvent {
+    type: 'completion';
+    ctx: {
+        agent: string;
+        iteration: number;
+    };
+}
+/**
+ * Error operation event
+ */
+export interface ErrorEvent {
+    type: 'error';
+    ctx: {
+        error: string;
+        agent?: string;
+    };
+}
+/**
+ * Agent thinking operation event
+ */
+export interface AgentThinkingEvent {
+    type: 'agent_thinking';
+    ctx: {
+        agent: string;
+    };
+}
+/**
+ * Status update operation event with flexible structured/unstructured data
+ */
+export interface StatusUpdateEvent {
+    type: 'status_update';
+    label?: string;
+    ctx: {
+        summary?: string;
+        [key: string]: any;
+    };
+}
+/**
+ * Discriminated union of all operation events
+ */
+export type OperationEvent = AgentInitializingEvent | AgentReadyEvent | AgentThinkingEvent | CompletionEvent | ErrorEvent | StatusUpdateEvent;
+/**
+ * Creates an agent initializing operation
+ */
+export declare function agentInitializingOp(sessionId: string, graphId: string): AgentInitializingEvent;
+/**
+ * Creates an agent ready operation
+ */
+export declare function agentReadyOp(sessionId: string, graphId: string): AgentReadyEvent;
+/**
+ * Creates an agent thinking operation
+ */
+export declare function agentThinkingOp(agent: string): AgentThinkingEvent;
+/**
+ * Creates a completion operation
+ */
+export declare function completionOp(agentId: string, iterations: number): CompletionEvent;
+/**
+ * Creates an error operation
+ */
+export declare function errorOp(error: string, agentId?: string): ErrorEvent;
+/**
+ * Generate a unique tool execution ID for lifecycle tracking
+ */
+export declare function generateToolId(): string;
+/**
+ * Creates a status update operation with flexible data
+ */
+export declare function statusUpdateOp(ctx: Record<string, any>): StatusUpdateEvent;
+//# sourceMappingURL=agent-operations.d.ts.map

package/dist/utils/agent-operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-operations.d.ts","sourceRoot":"","sources":["../../src/utils/agent-operations.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,GAAG,EAAE;QACH,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,GAAG,EAAE;QACH,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IACnB,GAAG,EAAE;QACH,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE;QACH,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAC;IACvB,GAAG,EAAE;QACH,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,EAAE;QACH,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB,sBAAsB,GACtB,eAAe,GACf,kBAAkB,GAClB,eAAe,GACf,UAAU,GACV,iBAAiB,CAAC;AAMtB;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,sBAAsB,CAQ9F;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,CAQhF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAOjE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,eAAe,CAQjF;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,CAQnE;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,iBAAiB,CAK1E"}

package/dist/utils/agent-operations.js

@@ -0,0 +1,78 @@
+import { nanoid } from 'nanoid';
+// =============================================================================
+// OPERATION FUNCTIONS
+// =============================================================================
+/**
+ * Creates an agent initializing operation
+ */
+export function agentInitializingOp(sessionId, graphId) {
+    return {
+        type: 'agent_initializing',
+        ctx: {
+            sessionId,
+            graphId,
+        },
+    };
+}
+/**
+ * Creates an agent ready operation
+ */
+export function agentReadyOp(sessionId, graphId) {
+    return {
+        type: 'agent_ready',
+        ctx: {
+            sessionId,
+            graphId,
+        },
+    };
+}
+/**
+ * Creates an agent thinking operation
+ */
+export function agentThinkingOp(agent) {
+    return {
+        type: 'agent_thinking',
+        ctx: {
+            agent,
+        },
+    };
+}
+/**
+ * Creates a completion operation
+ */
+export function completionOp(agentId, iterations) {
+    return {
+        type: 'completion',
+        ctx: {
+            agent: agentId,
+            iteration: iterations,
+        },
+    };
+}
+/**
+ * Creates an error operation
+ */
+export function errorOp(error, agentId) {
+    return {
+        type: 'error',
+        ctx: {
+            error,
+            agent: agentId,
+        },
+    };
+}
+/**
+ * Generate a unique tool execution ID for lifecycle tracking
+ */
+export function generateToolId() {
+    return `tool_${nanoid(8)}`;
+}
+/**
+ * Creates a status update operation with flexible data
+ */
+export function statusUpdateOp(ctx) {
+    return {
+        type: 'status_update',
+        ctx,
+    };
+}

package/dist/utils/artifact-component-schema.d.ts

@@ -0,0 +1,29 @@
+import type { ArtifactComponentApiSelect, DataComponentInsert } from '@inkeep/agents-core';
+import { z } from 'zod';
+/**
+ * Converts artifact component configurations to Zod schema for structured generation
+ */
+export declare function createArtifactComponentsSchema(artifactComponents?: ArtifactComponentApiSelect[]): z.ZodObject<{}, z.core.$strip> | z.ZodUnion<any>;
+/**
+ * Create schema for artifact component summary props only (for quick display)
+ */
+export declare function createArtifactComponentsSummarySchema(artifactComponents?: ArtifactComponentApiSelect[]): z.ZodUnion<any> | z.ZodObject<{}, z.core.$strip>;
+/**
+ * Create schema for artifact component full props only (for detailed display)
+ */
+export declare function createArtifactComponentsFullSchema(artifactComponents?: ArtifactComponentApiSelect[]): z.ZodUnion<any> | z.ZodObject<{}, z.core.$strip>;
+/**
+ * Standard artifact reference component schema for tool responses
+ */
+export declare class ArtifactReferenceSchema {
+    private static readonly ARTIFACT_PROPS_SCHEMA;
+    /**
+     * Get the standard Zod schema for artifact reference components
+     */
+    static getSchema(): z.ZodType<any>;
+    /**
+     * Get complete DataComponent by adding missing fields to base definition
+     */
+    static getDataComponent(tenantId: string, projectId?: string): DataComponentInsert;
+}
+//# sourceMappingURL=artifact-component-schema.d.ts.map

package/dist/utils/artifact-component-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-component-schema.d.ts","sourceRoot":"","sources":["../../src/utils/artifact-component-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC3F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,kBAAkB,CAAC,EAAE,0BAA0B,EAAE,oDA2B/F;AAED;;GAEG;AACH,wBAAgB,qCAAqC,CACnD,kBAAkB,CAAC,EAAE,0BAA0B,EAAE,oDAsBlD;AAED;;GAEG;AACH,wBAAgB,kCAAkC,CAChD,kBAAkB,CAAC,EAAE,0BAA0B,EAAE,oDAsBlD;AAED;;GAEG;AACH,qBAAa,uBAAuB;IAElC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAe3C;IAEF;;OAEG;IACH,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;IAQlC;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAW,GAAG,mBAAmB;CAWvF"}

package/dist/utils/artifact-component-schema.js

@@ -0,0 +1,119 @@
+import { z } from 'zod';
+import { getLogger } from '../logger';
+import { jsonSchemaToZod } from './data-component-schema';
+const _logger = getLogger('ArtifactComponentSchema');
+/**
+ * Converts artifact component configurations to Zod schema for structured generation
+ */
+export function createArtifactComponentsSchema(artifactComponents) {
+    // Convert artifact component configs to a union schema
+    const componentSchemas = artifactComponents?.map((component) => {
+        // Convert the JSON Schema props to Zod - handle both summaryProps and fullProps
+        const summaryPropsSchema = jsonSchemaToZod(component.summaryProps);
+        const fullPropsSchema = jsonSchemaToZod(component.fullProps);
+        // Return schema with both summary and full props
+        return z
+            .object({
+            id: z.string().describe(component.id),
+            name: z.literal(component.name).describe(component.name),
+            summaryProps: summaryPropsSchema,
+            fullProps: fullPropsSchema,
+        })
+            .describe(`${component.name}: ${component.description}`);
+    }) || [];
+    // Return union of all component schemas - z.union requires at least 2 schemas
+    if (componentSchemas.length === 0) {
+        return z.object({}); // Empty object for no components
+    }
+    if (componentSchemas.length === 1) {
+        return componentSchemas[0]; // Single schema doesn't need union
+    }
+    return z.union(componentSchemas); // Safe union with 2+ schemas
+}
+/**
+ * Create schema for artifact component summary props only (for quick display)
+ */
+export function createArtifactComponentsSummarySchema(artifactComponents) {
+    const componentSchemas = artifactComponents?.map((component) => {
+        const summaryPropsSchema = jsonSchemaToZod(component.summaryProps);
+        return z
+            .object({
+            id: z.string().describe(component.id),
+            name: z.literal(component.name).describe(component.name),
+            summaryProps: summaryPropsSchema,
+        })
+            .describe(`${component.name} Summary: ${component.description}`);
+    }) || [];
+    if (componentSchemas.length === 0) {
+        return z.object({});
+    }
+    if (componentSchemas.length === 1) {
+        return componentSchemas[0];
+    }
+    return z.union(componentSchemas);
+}
+/**
+ * Create schema for artifact component full props only (for detailed display)
+ */
+export function createArtifactComponentsFullSchema(artifactComponents) {
+    const componentSchemas = artifactComponents?.map((component) => {
+        const fullPropsSchema = jsonSchemaToZod(component.fullProps);
+        return z
+            .object({
+            id: z.string().describe(component.id),
+            name: z.literal(component.name).describe(component.name),
+            fullProps: fullPropsSchema,
+        })
+            .describe(`${component.name} Full: ${component.description}`);
+    }) || [];
+    if (componentSchemas.length === 0) {
+        return z.object({});
+    }
+    if (componentSchemas.length === 1) {
+        return componentSchemas[0];
+    }
+    return z.union(componentSchemas);
+}
+/**
+ * Standard artifact reference component schema for tool responses
+ */
+export class ArtifactReferenceSchema {
+    // Standard artifact props schema - single source of truth
+    static ARTIFACT_PROPS_SCHEMA = {
+        type: 'object',
+        properties: {
+            artifact_id: {
+                type: 'string',
+                description: 'The EXACT artifact_id from save_tool_result tool output. NEVER invent or make up IDs.',
+            },
+            task_id: {
+                type: 'string',
+                description: 'The EXACT task_id from save_tool_result tool output. NEVER invent or make up IDs.',
+            },
+        },
+        required: ['artifact_id', 'task_id'],
+    };
+    /**
+     * Get the standard Zod schema for artifact reference components
+     */
+    static getSchema() {
+        return z.object({
+            id: z.string(),
+            name: z.literal('Artifact'),
+            props: jsonSchemaToZod(ArtifactReferenceSchema.ARTIFACT_PROPS_SCHEMA),
+        });
+    }
+    /**
+     * Get complete DataComponent by adding missing fields to base definition
+     */
+    static getDataComponent(tenantId, projectId = '') {
+        return {
+            id: 'The EXACT artifact_id from save_tool_result tool output. NEVER invent or make up IDs.',
+            tenantId: tenantId,
+            projectId: projectId,
+            name: 'Artifact',
+            description: 'Reference to saved content from tool results that grounds information in verifiable sources.',
+            props: ArtifactReferenceSchema.ARTIFACT_PROPS_SCHEMA,
+        };
+    }
+}

package/dist/utils/artifact-parser.d.ts

@@ -0,0 +1,71 @@
+export interface StreamPart {
+    kind: 'text' | 'data';
+    text?: string;
+    data?: any;
+}
+export interface ArtifactData {
+    artifactId: string;
+    taskId: string;
+    name: string;
+    description: string;
+    artifactType?: string;
+    artifactSummary: any;
+}
+/**
+ * Unified artifact parser that handles all artifact-related parsing and formatting
+ * Used by both ResponseFormatter and IncrementalStreamParser to eliminate redundancy
+ */
+export declare class ArtifactParser {
+    private tenantId;
+    private static readonly ARTIFACT_REGEX;
+    private static readonly ARTIFACT_CHECK_REGEX;
+    private static readonly INCOMPLETE_ARTIFACT_REGEX;
+    constructor(tenantId: string);
+    /**
+     * Check if text contains complete artifact markers
+     */
+    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 (with caching opportunity)
+     */
+    getContextArtifacts(contextId: string): Promise<Map<string, any>>;
+    /**
+     * Convert raw artifact to standardized data format
+     */
+    private formatArtifactData;
+    /**
+     * Parse text with artifact markers into parts array
+     * Can work with or without pre-fetched artifact map
+     */
+    parseText(text: string, artifactMap?: Map<string, any>): Promise<StreamPart[]>;
+    /**
+     * Process object/dataComponents for artifact components
+     */
+    parseObject(obj: any, artifactMap?: Map<string, any>): Promise<StreamPart[]>;
+    /**
+     * Check if object is an artifact component
+     */
+    private isArtifactComponent;
+    /**
+     * Get artifact data from map or fetch directly
+     */
+    private getArtifactData;
+    /**
+     * Parse partial JSON buffer (for streaming)
+     */
+    parsePartialJSON(buffer: string): {
+        complete: any[];
+        remaining: string;
+    };
+}
+//# sourceMappingURL=artifact-parser.d.ts.map

package/dist/utils/artifact-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-parser.d.ts","sourceRoot":"","sources":["../../src/utils/artifact-parser.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,GAAG,CAAC;CACZ;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,GAAG,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,cAAc;IAWb,OAAO,CAAC,QAAQ;IAT5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CACsB;IAC5D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CACmB;IAG/D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,yBAAyB,CACQ;gBAErC,QAAQ,EAAE,MAAM;IAEpC;;OAEG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIzC;;;OAGG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAU5C;;;OAGG;IACH,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAqC1C;;OAEG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAqCvE;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;;OAGG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IA2CpF;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAoClF;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;YACW,eAAe;IAwC7B;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;CA2BzE"}

package/dist/utils/artifact-parser.js

@@ -0,0 +1,253 @@
+import { getLedgerArtifacts, getTask, listTaskIdsByContextId } from '@inkeep/agents-core';
+import dbClient from '../data/db/dbClient';
+import { getLogger } from '../logger';
+const logger = getLogger('ArtifactParser');
+/**
+ * Unified artifact parser that handles all artifact-related parsing and formatting
+ * Used by both ResponseFormatter and IncrementalStreamParser to eliminate redundancy
+ */
+export class ArtifactParser {
+    tenantId;
+    // Shared regex patterns
+    static ARTIFACT_REGEX = /<artifact:ref\s+id="([^"]*?)"\s+task="([^"]*?)"\s*\/>/gs;
+    static ARTIFACT_CHECK_REGEX = /<artifact:ref\s+(?=.*id="[^"]+")(?=.*task="[^"]+")[^>]*\/>/;
+    // Regex for catching any partial artifact pattern (< + any prefix of "artifact:ref")
+    static INCOMPLETE_ARTIFACT_REGEX = /<(a(r(t(i(f(a(c(t(:(r(e(f?)?)?)?)?)?)?)?)?)?)?)?)?$/g;
+    constructor(tenantId) {
+        this.tenantId = tenantId;
+    }
+    /**
+     * Check if text contains complete artifact markers
+     */
+    hasArtifactMarkers(text) {
+        return ArtifactParser.ARTIFACT_CHECK_REGEX.test(text);
+    }
+    /**
+     * Check if text has incomplete artifact marker (for streaming)
+     * More robust detection that handles streaming fragments
+     */
+    hasIncompleteArtifact(text) {
+        // Use safe, non-backtracking patterns to prevent ReDoS attacks
+        // Check if text ends with any partial artifact pattern
+        return (/^.*<(?:artifact(?::ref)?|a(?:r(?:t(?:i(?:f(?:a(?:c(?:t(?::(?:r(?:e(?:f)?)?)?)?)?)?)?)?)?)?)?)?$/.test(text) ||
+            /^.*<artifact:ref(?:[^>]*)$/.test(text) || // Incomplete artifact:ref at end
+            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) {
+        // First check for incomplete artifact patterns at the end
+        // Use safe patterns that don't cause exponential backtracking
+        const endPatterns = [
+            /^.*<artifact:ref(?:[^/>]+(?:[^>]*[^/])?)?$/, // artifact:ref that doesn't end with />
+            /^.*<(?:artifact(?::ref)?|a(?:r(?:t(?:i(?:f(?:a(?:c(?:t(?::(?:r(?:e(?:f)?)?)?)?)?)?)?)?)?)?)?)?$/, // Safe partial artifact pattern
+        ];
+        for (const pattern of endPatterns) {
+            const match = text.match(pattern);
+            if (match && match.index !== undefined) {
+                return match.index;
+            }
+        }
+        // Look for incomplete artifact patterns anywhere in text
+        const matches = [...text.matchAll(ArtifactParser.INCOMPLETE_ARTIFACT_REGEX)];
+        if (matches.length === 0) {
+            return text.length;
+        }
+        // Check each match from the end to find an incomplete artifact
+        for (let i = matches.length - 1; i >= 0; i--) {
+            const match = matches[i];
+            const startIdx = match.index;
+            const textAfterMatch = text.slice(startIdx);
+            // If the text after this match doesn't contain a closing '/>', it's incomplete
+            if (!textAfterMatch.includes('/>')) {
+                return startIdx;
+            }
+        }
+        return text.length;
+    }
+    /**
+     * Get all artifacts for a context (with caching opportunity)
+     */
+    async getContextArtifacts(contextId) {
+        const artifacts = new Map();
+        try {
+            const taskIds = await listTaskIdsByContextId(dbClient)({
+                contextId: contextId,
+            });
+            for (const taskId of taskIds) {
+                // Get task to retrieve projectId
+                const task = await getTask(dbClient)({
+                    id: taskId,
+                });
+                if (!task) {
+                    logger.warn({ taskId }, 'Task not found when fetching artifacts');
+                    continue;
+                }
+                const taskArtifacts = await getLedgerArtifacts(dbClient)({
+                    scopes: { tenantId: this.tenantId, projectId: task.projectId },
+                    taskId,
+                });
+                for (const artifact of taskArtifacts) {
+                    const key = `${artifact.artifactId}:${artifact.taskId}`;
+                    artifacts.set(key, artifact);
+                }
+            }
+            logger.debug({ contextId, count: artifacts.size }, 'Loaded context artifacts');
+        }
+        catch (error) {
+            logger.error({ error, contextId }, 'Error loading context artifacts');
+        }
+        return artifacts;
+    }
+    /**
+     * Convert raw artifact to standardized data format
+     */
+    formatArtifactData(artifact, artifactId, taskId) {
+        return {
+            artifactId,
+            taskId,
+            name: artifact.name || 'Processing...',
+            description: artifact.description || 'Name and description being generated...',
+            artifactType: artifact.metadata?.artifactType,
+            artifactSummary: artifact.parts?.[0]?.data?.summary || {},
+        };
+    }
+    /**
+     * Parse text with artifact markers into parts array
+     * Can work with or without pre-fetched artifact map
+     */
+    async parseText(text, artifactMap) {
+        const parts = [];
+        const matches = [...text.matchAll(ArtifactParser.ARTIFACT_REGEX)];
+        if (matches.length === 0) {
+            return [{ kind: 'text', text }];
+        }
+        let lastIndex = 0;
+        for (const match of matches) {
+            const [fullMatch, artifactId, taskId] = match;
+            const matchStart = match.index;
+            // Add text before artifact
+            if (matchStart > lastIndex) {
+                const textBefore = text.slice(lastIndex, matchStart);
+                if (textBefore.trim()) {
+                    parts.push({ kind: 'text', text: textBefore });
+                }
+            }
+            // Get artifact data
+            const artifactData = await this.getArtifactData(artifactId, taskId, artifactMap);
+            if (artifactData) {
+                parts.push({ kind: 'data', data: artifactData });
+            }
+            // If no artifact found, marker is simply removed
+            lastIndex = matchStart + fullMatch.length;
+        }
+        // Add remaining text
+        if (lastIndex < text.length) {
+            const remainingText = text.slice(lastIndex);
+            if (remainingText.trim()) {
+                parts.push({ kind: 'text', text: remainingText });
+            }
+        }
+        return parts;
+    }
+    /**
+     * Process object/dataComponents for artifact components
+     */
+    async parseObject(obj, artifactMap) {
+        // Handle dataComponents array
+        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.task_id, artifactMap);
+                    if (artifactData) {
+                        parts.push({ kind: 'data', data: artifactData });
+                    }
+                }
+                else {
+                    parts.push({ kind: 'data', data: component });
+                }
+            }
+            return parts;
+        }
+        // Handle single object
+        if (this.isArtifactComponent(obj)) {
+            const artifactData = await this.getArtifactData(obj.props.artifact_id, obj.props.task_id, artifactMap);
+            return artifactData ? [{ kind: 'data', data: artifactData }] : [];
+        }
+        return [{ kind: 'data', data: obj }];
+    }
+    /**
+     * Check if object is an artifact component
+     */
+    isArtifactComponent(obj) {
+        return obj?.props?.artifact_id && obj?.props?.task_id;
+    }
+    /**
+     * Get artifact data from map or fetch directly
+     */
+    async getArtifactData(artifactId, taskId, artifactMap) {
+        const key = `${artifactId}:${taskId}`;
+        // Try map first
+        if (artifactMap?.has(key)) {
+            const artifact = artifactMap.get(key);
+            return this.formatArtifactData(artifact, artifactId, taskId);
+        }
+        // Fetch directly if no map
+        try {
+            // Get task to retrieve projectId
+            const task = await getTask(dbClient)({
+                id: taskId,
+            });
+            if (!task) {
+                logger.warn({ taskId }, 'Task not found when fetching artifact');
+                return null;
+            }
+            const artifacts = await getLedgerArtifacts(dbClient)({
+                scopes: { tenantId: this.tenantId, projectId: task.projectId },
+                artifactId,
+                taskId,
+            });
+            if (artifacts.length > 0) {
+                return this.formatArtifactData(artifacts[0], artifactId, taskId);
+            }
+        }
+        catch (error) {
+            logger.warn({ artifactId, taskId, error }, 'Failed to fetch artifact');
+        }
+        return null;
+    }
+    /**
+     * Parse partial JSON buffer (for streaming)
+     */
+    parsePartialJSON(buffer) {
+        const complete = [];
+        let remaining = buffer;
+        let braceCount = 0;
+        let start = -1;
+        for (let i = 0; i < buffer.length; i++) {
+            if (buffer[i] === '{') {
+                if (braceCount === 0)
+                    start = i;
+                braceCount++;
+            }
+            else if (buffer[i] === '}') {
+                braceCount--;
+                if (braceCount === 0 && start !== -1) {
+                    const jsonStr = buffer.slice(start, i + 1);
+                    try {
+                        complete.push(JSON.parse(jsonStr));
+                        remaining = buffer.slice(i + 1);
+                        start = -1;
+                    }
+                    catch {
+                        // Invalid JSON, continue
+                    }
+                }
+            }
+        }
+        return { complete, remaining };
+    }
+}