@cogitator-ai/workflows 0.1.0

package/dist/observability/span-attributes.js

@@ -0,0 +1,142 @@
+/**
+ * Standard span attributes for workflow tracing
+ * Based on OpenTelemetry semantic conventions + custom workflow attributes
+ */
+export const TRACE_PARENT_HEADER = 'traceparent';
+export const TRACE_STATE_HEADER = 'tracestate';
+export const BAGGAGE_HEADER = 'baggage';
+export const SERVICE_NAME = 'service.name';
+export const SERVICE_VERSION = 'service.version';
+export const SERVICE_INSTANCE_ID = 'service.instance.id';
+export const WORKFLOW_NAME = 'workflow.name';
+export const WORKFLOW_ID = 'workflow.id';
+export const WORKFLOW_RUN_ID = 'workflow.run.id';
+export const WORKFLOW_VERSION = 'workflow.version';
+export const WORKFLOW_ENTRY_POINT = 'workflow.entry_point';
+export const WORKFLOW_NODE_COUNT = 'workflow.node_count';
+export const WORKFLOW_STATUS = 'workflow.status';
+export const NODE_NAME = 'node.name';
+export const NODE_TYPE = 'node.type';
+export const NODE_INDEX = 'node.index';
+export const NODE_RETRY_COUNT = 'node.retry_count';
+export const NODE_TIMEOUT = 'node.timeout';
+export const NODE_DURATION = 'node.duration_ms';
+export const NODE_STATUS = 'node.status';
+export const LLM_SYSTEM = 'llm.system';
+export const LLM_REQUEST_MODEL = 'llm.request.model';
+export const LLM_RESPONSE_MODEL = 'llm.response.model';
+export const LLM_REQUEST_MAX_TOKENS = 'llm.request.max_tokens';
+export const LLM_REQUEST_TEMPERATURE = 'llm.request.temperature';
+export const LLM_REQUEST_TOP_P = 'llm.request.top_p';
+export const LLM_USAGE_INPUT_TOKENS = 'llm.usage.input_tokens';
+export const LLM_USAGE_OUTPUT_TOKENS = 'llm.usage.output_tokens';
+export const LLM_USAGE_TOTAL_TOKENS = 'llm.usage.total_tokens';
+export const LLM_USAGE_COST = 'llm.usage.cost';
+export const TOOL_NAME = 'tool.name';
+export const TOOL_PARAMETERS = 'tool.parameters';
+export const TOOL_RESULT = 'tool.result';
+export const TOOL_DURATION = 'tool.duration_ms';
+export const TOOL_SUCCESS = 'tool.success';
+export const ERROR_TYPE = 'error.type';
+export const ERROR_MESSAGE = 'error.message';
+export const ERROR_STACK = 'error.stack';
+export const ERROR_CODE = 'error.code';
+export const RETRY_ATTEMPT = 'retry.attempt';
+export const RETRY_MAX = 'retry.max';
+export const RETRY_DELAY = 'retry.delay_ms';
+export const CIRCUIT_BREAKER_STATE = 'circuit_breaker.state';
+export const COMPENSATION_TRIGGERED = 'compensation.triggered';
+export const COMPENSATION_NODE = 'compensation.node';
+export const DEAD_LETTER_QUEUE = 'dlq.added';
+export const APPROVAL_ID = 'approval.id';
+export const APPROVAL_TYPE = 'approval.type';
+export const APPROVAL_STATUS = 'approval.status';
+export const APPROVAL_TIMEOUT = 'approval.timeout_ms';
+export const APPROVAL_ASSIGNEE = 'approval.assignee';
+export const TIMER_TYPE = 'timer.type';
+export const TIMER_DELAY = 'timer.delay_ms';
+export const TIMER_CRON = 'timer.cron';
+export const TIMER_SCHEDULED_AT = 'timer.scheduled_at';
+export const TIMER_FIRED_AT = 'timer.fired_at';
+export const SUBWORKFLOW_NAME = 'subworkflow.name';
+export const SUBWORKFLOW_DEPTH = 'subworkflow.depth';
+export const SUBWORKFLOW_PARENT_ID = 'subworkflow.parent_id';
+export const TRIGGER_TYPE = 'trigger.type';
+export const TRIGGER_ID = 'trigger.id';
+export const TRIGGER_SOURCE = 'trigger.source';
+export const WEBHOOK_PATH = 'webhook.path';
+export const WEBHOOK_METHOD = 'webhook.method';
+export const CRON_EXPRESSION = 'cron.expression';
+export const CRON_NEXT_RUN = 'cron.next_run';
+/**
+ * Build standard workflow span attributes
+ */
+export function workflowSpanAttributes(workflowName, workflowId, runId, additionalAttrs) {
+    return {
+        [WORKFLOW_NAME]: workflowName,
+        [WORKFLOW_ID]: workflowId,
+        [WORKFLOW_RUN_ID]: runId,
+        ...additionalAttrs,
+    };
+}
+/**
+ * Build standard node span attributes
+ */
+export function nodeSpanAttributes(nodeName, nodeType, nodeIndex, additionalAttrs) {
+    return {
+        [NODE_NAME]: nodeName,
+        [NODE_TYPE]: nodeType,
+        [NODE_INDEX]: nodeIndex,
+        ...additionalAttrs,
+    };
+}
+/**
+ * Build LLM span attributes from token usage
+ */
+export function llmSpanAttributes(system, model, inputTokens, outputTokens, cost, additionalAttrs) {
+    const attrs = {
+        [LLM_SYSTEM]: system,
+        [LLM_REQUEST_MODEL]: model,
+        [LLM_USAGE_INPUT_TOKENS]: inputTokens,
+        [LLM_USAGE_OUTPUT_TOKENS]: outputTokens,
+        [LLM_USAGE_TOTAL_TOKENS]: inputTokens + outputTokens,
+    };
+    if (cost !== undefined) {
+        attrs[LLM_USAGE_COST] = cost;
+    }
+    return { ...attrs, ...additionalAttrs };
+}
+/**
+ * Build tool span attributes
+ */
+export function toolSpanAttributes(toolName, success, durationMs, additionalAttrs) {
+    return {
+        [TOOL_NAME]: toolName,
+        [TOOL_SUCCESS]: success,
+        [TOOL_DURATION]: durationMs,
+        ...additionalAttrs,
+    };
+}
+/**
+ * Build error span attributes
+ */
+export function errorSpanAttributes(error, additionalAttrs) {
+    return {
+        [ERROR_TYPE]: error.name,
+        [ERROR_MESSAGE]: error.message,
+        [ERROR_STACK]: error.stack,
+        ...additionalAttrs,
+    };
+}
+/**
+ * Build retry span attributes
+ */
+export function retrySpanAttributes(attempt, maxAttempts, delayMs, additionalAttrs) {
+    return {
+        [RETRY_ATTEMPT]: attempt,
+        [RETRY_MAX]: maxAttempts,
+        [RETRY_DELAY]: delayMs,
+        ...additionalAttrs,
+    };
+}
+//# sourceMappingURL=span-attributes.js.map

package/dist/observability/span-attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-attributes.js","sourceRoot":"","sources":["../../src/observability/span-attributes.ts"],"names":[],"mappings":"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"}

package/dist/observability/tracer.d.ts

@@ -0,0 +1,110 @@
+/**
+ * WorkflowTracer - Distributed tracing for workflow execution
+ *
+ * Features:
+ * - W3C Trace Context propagation
+ * - Hierarchical span creation (workflow → node → tool)
+ * - Automatic span lifecycle management
+ * - Context-aware span attributes
+ * - Multi-backend export support
+ */
+import type { TracingConfig, WorkflowSpan, SpanKind, SpanStatus, SpanLink, TraceContext } from '@cogitator-ai/types';
+/**
+ * Active span context for scoped operations
+ */
+interface SpanScope {
+    span: WorkflowSpan;
+    end: (status?: SpanStatus, message?: string) => void;
+    addEvent: (name: string, attributes?: Record<string, unknown>) => void;
+    setAttribute: (key: string, value: unknown) => void;
+    setAttributes: (attributes: Record<string, unknown>) => void;
+    recordException: (error: Error) => void;
+}
+/**
+ * WorkflowTracer - Main tracing class
+ */
+export declare class WorkflowTracer {
+    private config;
+    private exporter;
+    private spanStack;
+    private completedSpans;
+    private currentTraceContext;
+    private baggage;
+    private sampleDecision;
+    constructor(config?: Partial<TracingConfig>);
+    /**
+     * Check if this tracer is sampling
+     */
+    isSampled(): boolean;
+    /**
+     * Set trace context from incoming request headers
+     */
+    setContextFromHeaders(headers: Record<string, string>): void;
+    /**
+     * Get headers for outgoing request context propagation
+     */
+    getContextHeaders(): Record<string, string>;
+    /**
+     * Set a baggage value
+     */
+    setBaggage(key: string, value: string): void;
+    /**
+     * Get a baggage value
+     */
+    getBaggage(key: string): string | undefined;
+    /**
+     * Get current trace context
+     */
+    getTraceContext(): TraceContext | null;
+    /**
+     * Start a new workflow trace
+     */
+    startWorkflowSpan(workflowName: string, workflowId: string, runId: string, attributes?: Record<string, unknown>): SpanScope;
+    /**
+     * Start a node execution span
+     */
+    startNodeSpan(nodeName: string, nodeType: string, attributes?: Record<string, unknown>): SpanScope;
+    /**
+     * Start a tool execution span
+     */
+    startToolSpan(toolName: string, attributes?: Record<string, unknown>): SpanScope;
+    /**
+     * Start a custom span
+     */
+    startSpan(name: string, kind?: SpanKind, attributes?: Record<string, unknown>): SpanScope;
+    /**
+     * Create a span scope with lifecycle methods
+     */
+    private createSpanScope;
+    /**
+     * Add a link between spans
+     */
+    addLink(span: WorkflowSpan, link: SpanLink): void;
+    /**
+     * Get current active span
+     */
+    getCurrentSpan(): WorkflowSpan | undefined;
+    /**
+     * Flush completed spans to exporter
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown tracer and flush remaining spans
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Run a function with automatic span creation
+     */
+    trace<T>(name: string, fn: (scope: SpanScope) => Promise<T>, options?: {
+        kind?: SpanKind;
+        attributes?: Record<string, unknown>;
+    }): Promise<T>;
+}
+/**
+ * Create a tracer instance
+ */
+export declare function createTracer(config?: Partial<TracingConfig>): WorkflowTracer;
+export declare function getGlobalTracer(): WorkflowTracer;
+export declare function setGlobalTracer(tracer: WorkflowTracer): void;
+export {};
+//# sourceMappingURL=tracer.d.ts.map

package/dist/observability/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/observability/tracer.ts"],"names":[],"mappings":"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"}

package/dist/observability/tracer.js

@@ -0,0 +1,409 @@
+/**
+ * WorkflowTracer - Distributed tracing for workflow execution
+ *
+ * Features:
+ * - W3C Trace Context propagation
+ * - Hierarchical span creation (workflow → node → tool)
+ * - Automatic span lifecycle management
+ * - Context-aware span attributes
+ * - Multi-backend export support
+ */
+import { nanoid } from 'nanoid';
+import { createSpanExporter, NoopSpanExporter, } from './exporters';
+import { TRACE_PARENT_HEADER, TRACE_STATE_HEADER, BAGGAGE_HEADER, WORKFLOW_NAME, WORKFLOW_ID, WORKFLOW_RUN_ID, SERVICE_NAME, SERVICE_VERSION, } from './span-attributes';
+const TRACE_VERSION = '00';
+const DEFAULT_SAMPLE_RATE = 1.0;
+/**
+ * Generate a random trace ID (32 hex chars)
+ */
+function generateTraceId() {
+    return nanoid(16)
+        .split('')
+        .map((c) => c.charCodeAt(0).toString(16).padStart(2, '0'))
+        .join('')
+        .slice(0, 32);
+}
+/**
+ * Generate a random span ID (16 hex chars)
+ */
+function generateSpanId() {
+    return nanoid(8)
+        .split('')
+        .map((c) => c.charCodeAt(0).toString(16).padStart(2, '0'))
+        .join('')
+        .slice(0, 16);
+}
+/**
+ * Parse W3C traceparent header
+ * Format: {version}-{trace-id}-{parent-id}-{trace-flags}
+ */
+function parseTraceParent(header) {
+    const parts = header.split('-');
+    if (parts.length !== 4)
+        return null;
+    const [version, traceId, spanId, flags] = parts;
+    if (version !== TRACE_VERSION)
+        return null;
+    if (traceId.length !== 32 || spanId.length !== 16)
+        return null;
+    return {
+        traceId,
+        spanId,
+        traceFlags: parseInt(flags, 16),
+    };
+}
+/**
+ * Format TraceContext to W3C traceparent header
+ */
+function formatTraceParent(ctx) {
+    const flags = (ctx.traceFlags ?? 1).toString(16).padStart(2, '0');
+    return `${TRACE_VERSION}-${ctx.traceId}-${ctx.spanId}-${flags}`;
+}
+/**
+ * Parse W3C baggage header
+ * Format: key1=value1,key2=value2
+ */
+function parseBaggage(header) {
+    const baggage = {};
+    const pairs = header.split(',');
+    for (const pair of pairs) {
+        const [key, value] = pair.split('=');
+        if (key && value) {
+            baggage[key.trim()] = decodeURIComponent(value.trim());
+        }
+    }
+    return baggage;
+}
+/**
+ * Format Baggage to W3C baggage header
+ */
+function formatBaggage(baggage) {
+    return Object.entries(baggage)
+        .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+        .join(',');
+}
+/**
+ * WorkflowTracer - Main tracing class
+ */
+export class WorkflowTracer {
+    config;
+    exporter;
+    spanStack = [];
+    completedSpans = [];
+    currentTraceContext = null;
+    baggage = {};
+    sampleDecision = true;
+    constructor(config = {}) {
+        this.config = {
+            enabled: true,
+            serviceName: 'cogitator-workflow',
+            serviceVersion: '1.0.0',
+            sampleRate: DEFAULT_SAMPLE_RATE,
+            propagateContext: true,
+            exporter: 'console',
+            ...config,
+        };
+        if (!this.config.enabled) {
+            this.exporter = new NoopSpanExporter();
+            return;
+        }
+        this.exporter = createSpanExporter({
+            type: this.config.exporter ?? 'console',
+            endpoint: this.config.exporterEndpoint,
+            headers: this.config.exporterHeaders,
+            batchSize: this.config.batchSize,
+            flushInterval: this.config.flushInterval,
+        });
+        this.sampleDecision = Math.random() < (this.config.sampleRate ?? 1.0);
+    }
+    /**
+     * Check if this tracer is sampling
+     */
+    isSampled() {
+        return this.config.enabled && this.sampleDecision;
+    }
+    /**
+     * Set trace context from incoming request headers
+     */
+    setContextFromHeaders(headers) {
+        const traceparent = headers[TRACE_PARENT_HEADER];
+        if (traceparent) {
+            this.currentTraceContext = parseTraceParent(traceparent);
+        }
+        const tracestate = headers[TRACE_STATE_HEADER];
+        if (tracestate && this.currentTraceContext) {
+            this.currentTraceContext.traceState = tracestate;
+        }
+        const baggageHeader = headers[BAGGAGE_HEADER];
+        if (baggageHeader) {
+            this.baggage = { ...this.baggage, ...parseBaggage(baggageHeader) };
+        }
+    }
+    /**
+     * Get headers for outgoing request context propagation
+     */
+    getContextHeaders() {
+        const headers = {};
+        if (this.currentTraceContext && this.config.propagateContext) {
+            headers[TRACE_PARENT_HEADER] = formatTraceParent(this.currentTraceContext);
+            if (this.currentTraceContext.traceState) {
+                headers[TRACE_STATE_HEADER] = this.currentTraceContext.traceState;
+            }
+        }
+        if (Object.keys(this.baggage).length > 0) {
+            headers[BAGGAGE_HEADER] = formatBaggage(this.baggage);
+        }
+        return headers;
+    }
+    /**
+     * Set a baggage value
+     */
+    setBaggage(key, value) {
+        this.baggage[key] = value;
+    }
+    /**
+     * Get a baggage value
+     */
+    getBaggage(key) {
+        return this.baggage[key];
+    }
+    /**
+     * Get current trace context
+     */
+    getTraceContext() {
+        return this.currentTraceContext;
+    }
+    /**
+     * Start a new workflow trace
+     */
+    startWorkflowSpan(workflowName, workflowId, runId, attributes) {
+        const traceId = this.currentTraceContext?.traceId ?? generateTraceId();
+        const spanId = generateSpanId();
+        const parentSpanId = this.currentTraceContext?.spanId;
+        const span = {
+            traceId,
+            spanId,
+            parentSpanId,
+            name: `workflow:${workflowName}`,
+            kind: 'internal',
+            startTime: Date.now(),
+            attributes: {
+                [SERVICE_NAME]: this.config.serviceName,
+                [SERVICE_VERSION]: this.config.serviceVersion,
+                [WORKFLOW_NAME]: workflowName,
+                [WORKFLOW_ID]: workflowId,
+                [WORKFLOW_RUN_ID]: runId,
+                ...this.config.attributes,
+                ...attributes,
+            },
+            events: [],
+            links: [],
+            status: 'unset',
+        };
+        this.currentTraceContext = {
+            traceId,
+            spanId,
+            traceFlags: 1,
+        };
+        this.spanStack.push(span);
+        return this.createSpanScope(span);
+    }
+    /**
+     * Start a node execution span
+     */
+    startNodeSpan(nodeName, nodeType, attributes) {
+        const parentSpan = this.spanStack[this.spanStack.length - 1];
+        const traceId = parentSpan?.traceId ?? generateTraceId();
+        const spanId = generateSpanId();
+        const span = {
+            traceId,
+            spanId,
+            parentSpanId: parentSpan?.spanId,
+            name: `node:${nodeName}`,
+            kind: 'internal',
+            startTime: Date.now(),
+            attributes: {
+                'node.name': nodeName,
+                'node.type': nodeType,
+                ...attributes,
+            },
+            events: [],
+            links: [],
+            status: 'unset',
+        };
+        this.currentTraceContext = {
+            traceId,
+            spanId,
+            traceFlags: 1,
+        };
+        this.spanStack.push(span);
+        return this.createSpanScope(span);
+    }
+    /**
+     * Start a tool execution span
+     */
+    startToolSpan(toolName, attributes) {
+        const parentSpan = this.spanStack[this.spanStack.length - 1];
+        const traceId = parentSpan?.traceId ?? generateTraceId();
+        const spanId = generateSpanId();
+        const span = {
+            traceId,
+            spanId,
+            parentSpanId: parentSpan?.spanId,
+            name: `tool:${toolName}`,
+            kind: 'client',
+            startTime: Date.now(),
+            attributes: {
+                'tool.name': toolName,
+                ...attributes,
+            },
+            events: [],
+            links: [],
+            status: 'unset',
+        };
+        this.spanStack.push(span);
+        return this.createSpanScope(span);
+    }
+    /**
+     * Start a custom span
+     */
+    startSpan(name, kind = 'internal', attributes) {
+        const parentSpan = this.spanStack[this.spanStack.length - 1];
+        const traceId = parentSpan?.traceId ?? generateTraceId();
+        const spanId = generateSpanId();
+        const span = {
+            traceId,
+            spanId,
+            parentSpanId: parentSpan?.spanId,
+            name,
+            kind,
+            startTime: Date.now(),
+            attributes: { ...attributes },
+            events: [],
+            links: [],
+            status: 'unset',
+        };
+        this.spanStack.push(span);
+        return this.createSpanScope(span);
+    }
+    /**
+     * Create a span scope with lifecycle methods
+     */
+    createSpanScope(span) {
+        return {
+            span,
+            end: (status = 'ok', message) => {
+                span.endTime = Date.now();
+                span.status = status;
+                if (message) {
+                    span.statusMessage = message;
+                }
+                const idx = this.spanStack.indexOf(span);
+                if (idx !== -1) {
+                    this.spanStack.splice(idx, 1);
+                }
+                const parentSpan = this.spanStack[this.spanStack.length - 1];
+                if (parentSpan) {
+                    this.currentTraceContext = {
+                        traceId: parentSpan.traceId,
+                        spanId: parentSpan.spanId,
+                        traceFlags: 1,
+                    };
+                }
+                this.completedSpans.push(span);
+            },
+            addEvent: (name, attributes) => {
+                span.events.push({
+                    name,
+                    timestamp: Date.now(),
+                    attributes,
+                });
+            },
+            setAttribute: (key, value) => {
+                span.attributes[key] = value;
+            },
+            setAttributes: (attributes) => {
+                Object.assign(span.attributes, attributes);
+            },
+            recordException: (error) => {
+                span.events.push({
+                    name: 'exception',
+                    timestamp: Date.now(),
+                    attributes: {
+                        'exception.type': error.name,
+                        'exception.message': error.message,
+                        'exception.stacktrace': error.stack,
+                    },
+                });
+                span.status = 'error';
+                span.statusMessage = error.message;
+            },
+        };
+    }
+    /**
+     * Add a link between spans
+     */
+    addLink(span, link) {
+        span.links.push(link);
+    }
+    /**
+     * Get current active span
+     */
+    getCurrentSpan() {
+        return this.spanStack[this.spanStack.length - 1];
+    }
+    /**
+     * Flush completed spans to exporter
+     */
+    async flush() {
+        if (!this.isSampled() || this.completedSpans.length === 0) {
+            return;
+        }
+        const spansToExport = [...this.completedSpans];
+        this.completedSpans = [];
+        await this.exporter.export(spansToExport);
+    }
+    /**
+     * Shutdown tracer and flush remaining spans
+     */
+    async shutdown() {
+        await this.flush();
+        await this.exporter.shutdown();
+    }
+    /**
+     * Run a function with automatic span creation
+     */
+    async trace(name, fn, options) {
+        const scope = this.startSpan(name, options?.kind, options?.attributes);
+        try {
+            const result = await fn(scope);
+            scope.end('ok');
+            return result;
+        }
+        catch (error) {
+            scope.recordException(error);
+            scope.end('error', error.message);
+            throw error;
+        }
+    }
+}
+/**
+ * Create a tracer instance
+ */
+export function createTracer(config) {
+    return new WorkflowTracer(config);
+}
+/**
+ * Global tracer instance for convenience
+ */
+let globalTracer = null;
+export function getGlobalTracer() {
+    if (!globalTracer) {
+        globalTracer = new WorkflowTracer({ enabled: false });
+    }
+    return globalTracer;
+}
+export function setGlobalTracer(tracer) {
+    globalTracer = tracer;
+}
+//# sourceMappingURL=tracer.js.map