@inkeep/agents-run-api 0.1.0

package/dist/tracer.d.ts

@@ -0,0 +1,24 @@
+import { type Span, type Tracer } from '@opentelemetry/api';
+export declare const BASE = "inkeep-chat";
+export declare const SERVICE_NAME = "inkeep-chat";
+export declare const SERVICE_VERSION = "1.0.0";
+export declare const createSpanName: (suffix: string) => string;
+/**
+ * Helper function to handle span errors consistently
+ * Records the exception, sets error status, and optionally logs
+ */
+export declare function handleSpanError(span: Span, error: unknown, logger?: {
+    error: (obj: any, msg?: string) => void;
+}, logMessage?: string): void;
+/**
+ * Get the global tracer instance
+ * This creates a single tracer for the entire application
+ */
+export declare function getGlobalTracer(): Tracer;
+/**
+ * Force flush the tracer provider to ensure critical spans are sent immediately
+ * This is useful for critical operations where we want to ensure telemetry data
+ * is sent before the operation completes or fails
+ */
+export declare function forceFlushTracer(): Promise<void>;
+//# sourceMappingURL=tracer.d.ts.map

package/dist/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../src/tracer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,IAAI,EAGT,KAAK,MAAM,EAEZ,MAAM,oBAAoB,CAAC;AAM5B,eAAO,MAAM,IAAI,gBAAgB,CAAC;AAGlC,eAAO,MAAM,YAAY,gBAAgB,CAAC;AAC1C,eAAO,MAAM,eAAe,UAAU,CAAC;AAGvC,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,WAAwB,CAAC;AAyCtE;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE;IAAE,KAAK,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,EACpD,UAAU,CAAC,EAAE,MAAM,GAClB,IAAI,CAgBN;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAUxC;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAatD"}

package/dist/tracer.js

@@ -0,0 +1,97 @@
+import { SpanStatusCode, trace, } from '@opentelemetry/api';
+import { getLogger } from './logger.js';
+const logger = getLogger('tracer');
+// Base prefix for all span names - export this to use in other files
+export const BASE = 'inkeep-chat';
+// Service name and version constants for consistent tracer identification
+export const SERVICE_NAME = 'inkeep-chat';
+export const SERVICE_VERSION = '1.0.0';
+// Helper function to create prefixed span names
+export const createSpanName = (suffix) => `${BASE}.${suffix}`;
+// No-op span implementation for when OpenTelemetry is not available
+const createNoOpSpan = () => ({
+    setAttributes: () => ({}),
+    recordException: () => ({}),
+    setStatus: () => ({}),
+    addEvent: () => ({}),
+    end: () => { },
+    isRecording: () => false,
+    setAttribute: () => ({}),
+    updateName: () => ({}),
+    spanContext: () => ({
+        traceId: '00000000000000000000000000000000',
+        spanId: '0000000000000000',
+        traceFlags: 0,
+    }),
+    addLink: () => ({}),
+    addLinks: () => ({}),
+});
+// No-op tracer implementation for when OpenTelemetry is not available
+const noopTracer = {
+    startActiveSpan(name, arg1, arg2, arg3) {
+        const fn = typeof arg1 === 'function' ? arg1 : typeof arg2 === 'function' ? arg2 : arg3;
+        if (!fn)
+            throw new Error('No callback function provided');
+        return fn(createNoOpSpan());
+    },
+    startSpan(name, options) {
+        return createNoOpSpan();
+    },
+};
+// Global tracer instance - singleton pattern
+let globalTracerInstance = null;
+/**
+ * Helper function to handle span errors consistently
+ * Records the exception, sets error status, and optionally logs
+ */
+export function handleSpanError(span, error, logger, logMessage) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    // Record the exception in the span
+    span.recordException(error);
+    // Set error status
+    span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: errorMessage,
+    });
+    // Optionally log the error
+    if (logger && logMessage) {
+        logger.error({ error: errorMessage }, logMessage);
+    }
+}
+/**
+ * Get the global tracer instance
+ * This creates a single tracer for the entire application
+ */
+export function getGlobalTracer() {
+    if (!globalTracerInstance) {
+        try {
+            globalTracerInstance = trace.getTracer(SERVICE_NAME, SERVICE_VERSION);
+        }
+        catch (error) {
+            logger.debug('OpenTelemetry tracer not available, using no-op tracer');
+            globalTracerInstance = noopTracer;
+        }
+    }
+    return globalTracerInstance;
+}
+/**
+ * Force flush the tracer provider to ensure critical spans are sent immediately
+ * This is useful for critical operations where we want to ensure telemetry data
+ * is sent before the operation completes or fails
+ */
+export async function forceFlushTracer() {
+    try {
+        // Import the span processor from instrumentation
+        const { spanProcessor } = await import('./instrumentation.js');
+        if (spanProcessor && typeof spanProcessor.forceFlush === 'function') {
+            await spanProcessor.forceFlush();
+            logger.debug('Span processor force flush completed');
+        }
+        else {
+            logger.debug('Span processor does not support force flush or is not available');
+        }
+    }
+    catch (error) {
+        logger.warn({ error }, 'Failed to force flush tracer');
+    }
+}

package/dist/types/chat.d.ts

@@ -0,0 +1,25 @@
+export type ContentItem = {
+    type: string;
+    text?: string;
+};
+export type Message = {
+    role: 'system' | 'user' | 'assistant' | 'function' | 'tool';
+    content: string | ContentItem[];
+    name?: string;
+};
+export type ChatCompletionRequest = {
+    model: string;
+    messages: Message[];
+    temperature?: number;
+    top_p?: number;
+    n?: number;
+    stream?: boolean;
+    max_tokens?: number;
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    logit_bias?: Record<string, number>;
+    user?: string;
+    tools?: Record<string, unknown>;
+    runConfig?: Record<string, unknown>;
+};
+//# sourceMappingURL=chat.d.ts.map

package/dist/types/chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../src/types/chat.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC;IAC5D,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC,CAAC"}

package/dist/types/chat.js

@@ -0,0 +1 @@
+export {};

package/dist/types/execution-context.d.ts

@@ -0,0 +1,14 @@
+import type { ExecutionContext } from '@inkeep/agents-core';
+/**
+ * Create execution context from middleware values
+ */
+export declare function createExecutionContext(params: {
+    apiKey: string;
+    tenantId: string;
+    projectId: string;
+    graphId: string;
+    apiKeyId: string;
+    agentId?: string;
+    baseUrl?: string;
+}): ExecutionContext;
+//# sourceMappingURL=execution-context.d.ts.map

package/dist/types/execution-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-context.d.ts","sourceRoot":"","sources":["../../src/types/execution-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,gBAAgB,CAUnB"}

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,79 @@
+/**
+ * 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;
+    };
+}
+/**
+ * Status update operation event with flexible structured/unstructured data
+ */
+export interface StatusUpdateEvent {
+    type: 'status_update';
+    ctx: {
+        summary?: string;
+        [key: string]: any;
+    };
+}
+/**
+ * Discriminated union of all operation events
+ */
+export type OperationEvent = AgentInitializingEvent | AgentReadyEvent | 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 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,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,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,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,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,67 @@
+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 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 { z } from 'zod';
+import type { ArtifactComponentApiSelect, DataComponentInsert } from '@inkeep/agents-core';
+/**
+ * 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,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAM3F;;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.js';
+import { jsonSchemaToZod } from './data-component-schema.js';
+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(this.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: this.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;IAS5C;;;OAGG;IACH,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAoC1C;;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"}