@orka-js/devtools 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,300 @@
+/**
+ * DevTools Types
+ */
+interface DevToolsConfig {
+    port?: number;
+    host?: string;
+    open?: boolean;
+    cors?: boolean;
+    maxTraces?: number;
+    retentionMs?: number;
+}
+interface TraceRun {
+    id: string;
+    parentId?: string;
+    type: TraceRunType;
+    name: string;
+    startTime: number;
+    endTime?: number;
+    latencyMs?: number;
+    status: 'running' | 'success' | 'error';
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    metadata?: TraceMetadata;
+    children: TraceRun[];
+}
+type TraceRunType = 'agent' | 'llm' | 'tool' | 'retrieval' | 'chain' | 'workflow' | 'graph' | 'node' | 'embedding' | 'custom';
+interface TraceMetadata {
+    model?: string;
+    provider?: string;
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    cost?: number;
+    temperature?: number;
+    maxTokens?: number;
+    toolName?: string;
+    toolArgs?: Record<string, unknown>;
+    nodeId?: string;
+    threadId?: string;
+    [key: string]: unknown;
+}
+interface TraceSession {
+    id: string;
+    name?: string;
+    startTime: number;
+    endTime?: number;
+    runs: TraceRun[];
+    metadata?: Record<string, unknown>;
+}
+interface TraceMetrics {
+    totalRuns: number;
+    totalLatencyMs: number;
+    avgLatencyMs: number;
+    totalTokens: number;
+    totalCost: number;
+    errorRate: number;
+    runsByType: Record<TraceRunType, number>;
+    tokensByModel: Record<string, number>;
+    costByModel: Record<string, number>;
+}
+interface DevToolsState {
+    sessions: TraceSession[];
+    activeSessionId?: string;
+    metrics: TraceMetrics;
+    isRecording: boolean;
+}
+interface TraceEvent {
+    type: 'run:start' | 'run:end' | 'run:error' | 'session:start' | 'session:end';
+    timestamp: number;
+    sessionId: string;
+    run?: TraceRun;
+    error?: string;
+}
+interface ReplayOptions {
+    runId: string;
+    sessionId: string;
+    modifyInput?: (input: unknown) => unknown;
+}
+interface ReplayResult {
+    originalRun: TraceRun;
+    replayedRun: TraceRun;
+    diff: {
+        inputChanged: boolean;
+        outputChanged: boolean;
+        latencyDiff: number;
+    };
+}
+
+/**
+ * TraceCollector - Collects and manages trace data for DevTools
+ */
+declare class TraceCollector {
+    private sessions;
+    private activeSessionId?;
+    private runStack;
+    private maxTraces;
+    private retentionMs;
+    private listeners;
+    constructor(config?: DevToolsConfig);
+    /**
+     * Start a new trace session
+     */
+    startSession(name?: string): string;
+    /**
+     * End the current session
+     */
+    endSession(sessionId?: string): void;
+    /**
+     * Start a new trace run
+     */
+    startRun(type: TraceRunType, name: string, input?: unknown, metadata?: TraceMetadata): string;
+    /**
+     * End a trace run
+     */
+    endRun(runId: string, output?: unknown, metadata?: TraceMetadata): void;
+    /**
+     * Mark a run as errored
+     */
+    errorRun(runId: string, error: Error | string): void;
+    /**
+     * Get all sessions
+     */
+    getSessions(): TraceSession[];
+    /**
+     * Get a specific session
+     */
+    getSession(sessionId: string): TraceSession | undefined;
+    /**
+     * Get metrics for a session or all sessions
+     */
+    getMetrics(sessionId?: string): TraceMetrics;
+    /**
+     * Find a run by ID
+     */
+    findRun(runId: string, sessionId?: string): TraceRun | undefined;
+    /**
+     * Subscribe to trace events
+     */
+    subscribe(listener: (event: TraceEvent) => void): () => void;
+    /**
+     * Emit an event to all listeners
+     */
+    private emit;
+    /**
+     * Cleanup old sessions
+     */
+    private cleanup;
+    /**
+     * Clear all traces
+     */
+    clear(): void;
+    /**
+     * Export traces as JSON
+     */
+    export(): string;
+    /**
+     * Import traces from JSON
+     */
+    import(json: string): void;
+}
+declare function getCollector(config?: DevToolsConfig): TraceCollector;
+declare function resetCollector(): void;
+
+/**
+ * DevTools Server - Express server for the DevTools dashboard
+ */
+declare class DevToolsServer {
+    private collector;
+    private config;
+    private server?;
+    private clients;
+    constructor(collector: TraceCollector, config?: DevToolsConfig);
+    /**
+     * Start the DevTools server
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the server
+     */
+    stop(): Promise<void>;
+    /**
+     * Setup API routes
+     */
+    private setupRoutes;
+    /**
+     * Broadcast event to all SSE clients
+     */
+    private broadcastEvent;
+    /**
+     * Get embedded dashboard HTML
+     */
+    private getDashboardHTML;
+}
+
+/**
+ * Hook interface matching @orka-js/observability
+ */
+interface ObservabilityHook {
+    onTraceStart?: (trace: TracerTrace) => void;
+    onTraceEnd?: (trace: TracerTrace) => void;
+    onEvent?: (event: TracerEvent) => void;
+    onError?: (error: Error, context?: Record<string, unknown>) => void;
+}
+interface TracerTrace {
+    id: string;
+    name: string;
+    startTime: number;
+    endTime?: number;
+    totalLatencyMs?: number;
+    totalTokens?: number;
+    events: TracerEvent[];
+    metadata?: Record<string, unknown>;
+}
+interface TracerEvent {
+    id: string;
+    traceId: string;
+    type: string;
+    name: string;
+    startTime?: number;
+    endTime?: number;
+    latencyMs?: number;
+    input?: unknown;
+    output?: unknown;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    };
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Create a DevTools hook for the Tracer
+ *
+ * Usage:
+ * ```ts
+ * import { Tracer } from '@orka-js/observability';
+ * import { createDevToolsHook, devtools } from '@orka-js/devtools';
+ *
+ * await devtools();
+ *
+ * const tracer = new Tracer({
+ *   hooks: [createDevToolsHook()]
+ * });
+ * ```
+ */
+declare function createDevToolsHook(): ObservabilityHook;
+/**
+ * Convenience function to create a Tracer with DevTools integration
+ */
+declare function createTracerWithDevTools(options?: {
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    maxTraces?: number;
+    traceTtlMs?: number;
+}): {
+    hook: ObservabilityHook;
+    config: typeof options & {
+        hooks: ObservabilityHook[];
+    };
+};
+
+/**
+ * Start the DevTools dashboard
+ */
+declare function devtools(config?: DevToolsConfig): Promise<{
+    collector: TraceCollector;
+    server: DevToolsServer;
+    stop: () => Promise<void>;
+}>;
+/**
+ * Create a trace wrapper for any function
+ */
+declare function withTrace<T extends (...args: unknown[]) => unknown>(fn: T, options?: {
+    name?: string;
+    type?: TraceRunType;
+    collector?: TraceCollector;
+}): T;
+/**
+ * Decorator for tracing class methods
+ */
+declare function Trace(options?: {
+    name?: string;
+    type?: TraceRunType;
+}): (_target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Manual tracing helpers
+ */
+declare const trace: {
+    start(type: TraceRunType, name: string, input?: unknown, metadata?: TraceMetadata): string;
+    end(runId: string, output?: unknown, metadata?: TraceMetadata): void;
+    error(runId: string, error: Error | string): void;
+    session(name?: string): string;
+    endSession(sessionId?: string): void;
+    /**
+     * Wrap an async function with tracing
+     */
+    wrap<T>(type: TraceRunType, name: string, fn: () => Promise<T>, metadata?: TraceMetadata): Promise<T>;
+};
+
+export { type DevToolsConfig, DevToolsServer, type DevToolsState, type ReplayOptions, type ReplayResult, Trace, TraceCollector, type TraceEvent, type TraceMetadata, type TraceMetrics, type TraceRun, type TraceRunType, type TraceSession, createDevToolsHook, createTracerWithDevTools, devtools, getCollector, resetCollector, trace, withTrace };