@looopy-ai/core 1.0.1

package/dist/events/utils.js

@@ -0,0 +1,263 @@
+export function generateEventId() {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+}
+export function createTaskCreatedEvent(options) {
+    return {
+        kind: 'task-created',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        parentTaskId: options.parentTaskId,
+        initiator: options.initiator,
+        timestamp: new Date().toISOString(),
+        metadata: options.metadata,
+    };
+}
+export function createTaskStatusEvent(options) {
+    return {
+        kind: 'task-status',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        status: options.status,
+        message: options.message,
+        timestamp: new Date().toISOString(),
+        metadata: options.metadata,
+    };
+}
+export function createTaskCompleteEvent(options) {
+    return {
+        kind: 'task-complete',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        content: options.content,
+        artifacts: options.artifacts,
+        timestamp: new Date().toISOString(),
+        metadata: options.metadata,
+    };
+}
+export function createContentDeltaEvent(options) {
+    return {
+        kind: 'content-delta',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        delta: options.delta,
+        index: options.index,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function createContentCompleteEvent(options) {
+    return {
+        kind: 'content-complete',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        content: options.content,
+        finishReason: options.finishReason || 'stop',
+        timestamp: new Date().toISOString(),
+    };
+}
+export function createToolStartEvent(options) {
+    return {
+        kind: 'tool-start',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        toolCallId: options.toolCallId,
+        toolName: options.toolName,
+        arguments: options.arguments,
+        timestamp: new Date().toISOString(),
+        metadata: options.metadata,
+    };
+}
+export function createToolProgressEvent(options) {
+    return {
+        kind: 'tool-progress',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        toolCallId: options.toolCallId,
+        progress: options.progress,
+        message: options.message,
+        timestamp: new Date().toISOString(),
+        metadata: options.metadata,
+    };
+}
+export function createToolCompleteEvent(options) {
+    return {
+        kind: 'tool-complete',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        toolCallId: options.toolCallId,
+        toolName: options.toolName,
+        success: options.success,
+        result: options.result,
+        error: options.error,
+        timestamp: new Date().toISOString(),
+        metadata: options.metadata,
+    };
+}
+export function createInputRequiredEvent(options) {
+    return {
+        kind: 'input-required',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        inputId: options.inputId,
+        requireUser: options.requireUser,
+        inputType: options.inputType,
+        prompt: options.prompt,
+        schema: options.schema,
+        options: options.options,
+        timestamp: new Date().toISOString(),
+        metadata: options.metadata,
+    };
+}
+export function createInputReceivedEvent(options) {
+    return {
+        kind: 'input-received',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        inputId: options.inputId,
+        providedBy: options.providedBy,
+        userId: options.userId,
+        agentId: options.agentId,
+        timestamp: new Date().toISOString(),
+        metadata: options.metadata,
+    };
+}
+export function createAuthRequiredEvent(options) {
+    return {
+        kind: 'auth-required',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        authId: options.authId,
+        authType: options.authType,
+        provider: options.provider,
+        scopes: options.scopes,
+        prompt: options.prompt,
+        authUrl: options.authUrl,
+        timestamp: new Date().toISOString(),
+        metadata: options.metadata,
+    };
+}
+export function createAuthCompletedEvent(options) {
+    return {
+        kind: 'auth-completed',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        authId: options.authId,
+        userId: options.userId,
+        timestamp: new Date().toISOString(),
+        metadata: options.metadata,
+    };
+}
+export function createFileWriteEvent(options) {
+    return {
+        kind: 'file-write',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        artifactId: options.artifactId,
+        data: options.data,
+        index: options.index,
+        complete: options.complete,
+        timestamp: new Date().toISOString(),
+        name: options.name,
+        description: options.description,
+        mimeType: options.mimeType,
+        encoding: options.encoding,
+        metadata: options.metadata,
+    };
+}
+export function createDataWriteEvent(options) {
+    return {
+        kind: 'data-write',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        artifactId: options.artifactId,
+        data: options.data,
+        name: options.name,
+        description: options.description,
+        timestamp: new Date().toISOString(),
+        metadata: options.metadata,
+    };
+}
+export function createDatasetWriteEvent(options) {
+    return {
+        kind: 'dataset-write',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        artifactId: options.artifactId,
+        rows: options.rows,
+        index: options.index,
+        complete: options.complete,
+        timestamp: new Date().toISOString(),
+        name: options.name,
+        description: options.description,
+        schema: options.schema,
+        metadata: options.metadata,
+    };
+}
+export function createSubtaskCreatedEvent(options) {
+    return {
+        kind: 'subtask-created',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        subtaskId: options.subtaskId,
+        agentId: options.agentId,
+        prompt: options.prompt,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function createThoughtStreamEvent(options) {
+    return {
+        kind: 'thought-stream',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        thoughtId: options.thoughtId,
+        thoughtType: options.thoughtType,
+        verbosity: options.verbosity,
+        content: options.content,
+        index: options.index,
+        timestamp: new Date().toISOString(),
+        metadata: options.metadata,
+    };
+}
+export function createInternalThoughtProcessEvent(options) {
+    return {
+        kind: 'internal:thought-process',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        iteration: options.iteration,
+        stage: options.stage,
+        reasoning: options.reasoning,
+        state: options.state,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function createInternalLLMCallEvent(options) {
+    return {
+        kind: 'internal:llm-call',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        iteration: options.iteration,
+        messageCount: options.messageCount,
+        toolCount: options.toolCount,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function createInternalCheckpointEvent(options) {
+    return {
+        kind: 'internal:checkpoint',
+        contextId: options.contextId,
+        taskId: options.taskId,
+        iteration: options.iteration,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function filterExternalEvents(events) {
+    return events.filter((event) => !event.kind.startsWith('internal:'));
+}
+export function filterByTaskId(events, taskId) {
+    return events.filter((event) => event.taskId === taskId);
+}
+export function filterByContextId(events, contextId) {
+    return events.filter((event) => event.contextId === contextId);
+}
+export function filterByKind(events, kind) {
+    return events.filter((event) => event.kind === kind);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './core';
+export * from './events';
+export * from './observability';
+export * from './providers';
+export * from './server';
+export * from './stores';
+export * from './tools';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './core';
+export * from './events';
+export * from './observability';
+export * from './providers';
+export * from './server';
+export * from './stores';
+export * from './tools';
+export * from './types';

package/dist/observability/index.d.ts

@@ -0,0 +1 @@
+export { getTracer, initializeTracing, SpanAttributes, SpanNames, shutdownTracing, type TelemetryConfig, type TraceContext, } from './tracing';

package/dist/observability/index.js

@@ -0,0 +1 @@
+export { getTracer, initializeTracing, SpanAttributes, SpanNames, shutdownTracing, } from './tracing';

package/dist/observability/spans/agent-turn.d.ts

@@ -0,0 +1,31 @@
+import { type Context, type Span } from '@opentelemetry/api';
+import type { AnyEvent } from '../../types/event';
+export interface AgentTurnSpanParams {
+    agentId: string;
+    taskId: string;
+    contextId: string;
+    turnNumber: number;
+    userMessage: string | null;
+}
+export declare const startAgentTurnSpan: (params: AgentTurnSpanParams) => {
+    span: Span;
+    traceContext: Context;
+    tapFinish: import("rxjs").MonoTypeOperatorFunction<AnyEvent>;
+};
+export declare function addMessagesLoadedEvent(span: Span, count: number): void;
+export declare function addMessagesCompactedEvent(span: Span): void;
+export declare function setTurnOutputAttribute(span: Span, output: string): void;
+export declare function setTurnCountAttribute(span: Span, turnCount: number): void;
+export declare function completeAgentTurnSpan(span: Span): void;
+export declare function failAgentTurnSpan(span: Span, error: Error): void;
+export declare const startAgentInitializeSpan: (params: {
+    agentId: string;
+    contextId: string;
+    parentContext: Context;
+}) => {
+    span: Span;
+    traceContext: Context;
+};
+export declare function setResumeAttributes(span: Span, existingMessageCount: number): void;
+export declare function completeAgentInitializeSpan(span: Span): void;
+export declare function failAgentInitializeSpan(span: Span, error: Error): void;

package/dist/observability/spans/agent-turn.js

@@ -0,0 +1,94 @@
+import { context, SpanStatusCode, trace } from '@opentelemetry/api';
+import { tap } from 'rxjs/internal/operators/tap';
+import { SpanAttributes } from '../tracing';
+const safeName = (name) => name.replace(/[^a-zA-Z0-9_-]+/g, '-');
+export const startAgentTurnSpan = (params) => {
+    const tracer = trace.getTracer('looopy-agent');
+    const span = tracer.startSpan(`agent[${safeName(params.agentId)}]`, {
+        attributes: {
+            [SpanAttributes.SESSION_ID]: params.contextId,
+            [SpanAttributes.AGENT_ID]: params.agentId,
+            [SpanAttributes.TASK_ID]: params.taskId,
+            'agent.turn.number': params.turnNumber,
+            [SpanAttributes.LANGFUSE_OBSERVATION_TYPE]: 'agent',
+            ...(params.userMessage ? { input: params.userMessage } : {}),
+        },
+    });
+    const traceContext = trace.setSpan(context.active(), span);
+    return {
+        span,
+        traceContext,
+        tapFinish: tap({
+            next: (event) => {
+                switch (event.kind) {
+                    case 'task-complete':
+                        if (event.content) {
+                            span.setAttribute(SpanAttributes.OUTPUT, event.content);
+                        }
+                        span.setStatus({ code: SpanStatusCode.OK });
+                        break;
+                    default:
+                        break;
+                }
+            },
+            complete: () => span.end(),
+            error: (err) => {
+                span.recordException(err);
+                span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+                span.end();
+            },
+        }),
+    };
+};
+export function addMessagesLoadedEvent(span, count) {
+    span.addEvent('messages.loaded', { count });
+}
+export function addMessagesCompactedEvent(span) {
+    span.addEvent('messages.compacted');
+}
+export function setTurnOutputAttribute(span, output) {
+    span.setAttribute('output', output);
+}
+export function setTurnCountAttribute(span, turnCount) {
+    span.setAttribute('agent.turn.count', turnCount);
+}
+export function completeAgentTurnSpan(span) {
+    span.setStatus({ code: 1 });
+    span.end();
+}
+export function failAgentTurnSpan(span, error) {
+    span.setStatus({
+        code: 2,
+        message: error.message,
+    });
+    span.recordException(error);
+    span.end();
+}
+export const startAgentInitializeSpan = (params) => {
+    const tracer = trace.getTracer('looopy-agent');
+    const spanOptions = {
+        attributes: {
+            [SpanAttributes.SESSION_ID]: params.contextId,
+            [SpanAttributes.AGENT_ID]: params.agentId,
+        },
+    };
+    const span = tracer.startSpan(`agent.initialize`, spanOptions, params.parentContext);
+    const traceContext = trace.setSpan(params.parentContext, span);
+    return { span, traceContext };
+};
+export function setResumeAttributes(span, existingMessageCount) {
+    span.setAttribute('agent.resumed', true);
+    span.setAttribute('agent.existingMessages', existingMessageCount);
+}
+export function completeAgentInitializeSpan(span) {
+    span.setStatus({ code: 1 });
+    span.end();
+}
+export function failAgentInitializeSpan(span, error) {
+    span.setStatus({
+        code: 2,
+        message: error.message,
+    });
+    span.recordException(error);
+    span.end();
+}

package/dist/observability/spans/index.d.ts

@@ -0,0 +1,5 @@
+export * from './agent-turn';
+export * from './iteration';
+export * from './llm-call';
+export * from './loop';
+export * from './tool';

package/dist/observability/spans/index.js

@@ -0,0 +1,5 @@
+export * from './agent-turn';
+export * from './iteration';
+export * from './llm-call';
+export * from './loop';
+export * from './tool';

package/dist/observability/spans/iteration.d.ts

@@ -0,0 +1,14 @@
+import type { LoopContext } from '../../core/types';
+import type { AnyEvent } from '../../types/event';
+export interface LoopIterationSpanParams {
+    agentId: string;
+    contextId: string;
+    taskId: string;
+    iteration: number;
+    parentContext: import('@opentelemetry/api').Context;
+}
+export declare const startLoopIterationSpan: (context: LoopContext, iteration: number) => {
+    span: import("@opentelemetry/api").Span;
+    traceContext: import("@opentelemetry/api").Context;
+    tapFinish: import("rxjs").MonoTypeOperatorFunction<AnyEvent>;
+};

package/dist/observability/spans/iteration.js

@@ -0,0 +1,41 @@
+import { SpanStatusCode, trace } from '@opentelemetry/api';
+import { tap } from 'rxjs/internal/operators/tap';
+import { SpanAttributes, SpanNames } from '../tracing';
+export const startLoopIterationSpan = (context, iteration) => {
+    const logger = context.logger;
+    logger.info('Starting iteration');
+    const tracer = trace.getTracer('looopy');
+    const span = tracer.startSpan(SpanNames.LOOP_ITERATION, {
+        attributes: {
+            [SpanAttributes.SESSION_ID]: context.contextId,
+            [SpanAttributes.AGENT_ID]: context.agentId,
+            [SpanAttributes.TASK_ID]: context.taskId,
+            [SpanAttributes.ITERATION]: iteration,
+            [SpanAttributes.LANGFUSE_OBSERVATION_TYPE]: 'chain',
+        },
+    }, context.parentContext);
+    const traceContext = trace.setSpan(context.parentContext, span);
+    return {
+        span,
+        traceContext,
+        tapFinish: tap({
+            next: (event) => {
+                if (event.kind === 'content-complete') {
+                    if (event.content) {
+                        span.setAttribute(SpanAttributes.OUTPUT, event.content);
+                        span.setAttribute(SpanAttributes.LLM_FINISH_REASON, event.finishReason);
+                        span.setStatus({ code: SpanStatusCode.OK });
+                    }
+                    logger.debug({ finishReason: event.finishReason }, 'Iteration completed successfully');
+                }
+            },
+            complete: () => span.end(),
+            error: (err) => {
+                span.recordException(err);
+                span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+                span.end();
+                logger.error({ error: err.message }, 'Iteration failed');
+            },
+        }),
+    };
+};

package/dist/observability/spans/llm-call.d.ts

@@ -0,0 +1,14 @@
+import type { LoopContext } from '../../core/types';
+import type { AnyEvent } from '../../types/event';
+import type { Message } from '../../types/message';
+export interface LLMCallSpanParams {
+    agentId: string;
+    taskId: string;
+    messages: Message[];
+    parentContext: import('@opentelemetry/api').Context;
+}
+export declare const startLLMCallSpan: (context: LoopContext, messages: Message[]) => {
+    span: import("@opentelemetry/api").Span;
+    traceContext: import("@opentelemetry/api").Context;
+    tapFinish: import("rxjs").MonoTypeOperatorFunction<AnyEvent>;
+};

package/dist/observability/spans/llm-call.js

@@ -0,0 +1,50 @@
+import { SpanStatusCode, trace } from '@opentelemetry/api';
+import { tap } from 'rxjs/internal/operators/tap';
+import { SpanAttributes, SpanNames } from '../tracing';
+export const startLLMCallSpan = (context, messages) => {
+    const tracer = trace.getTracer('looopy');
+    const span = tracer.startSpan(SpanNames.LLM_CALL, {
+        attributes: {
+            [SpanAttributes.AGENT_ID]: context.agentId,
+            [SpanAttributes.TASK_ID]: context.taskId,
+            [SpanAttributes.GEN_AI_PROMPT]: JSON.stringify(messages),
+            [SpanAttributes.LANGFUSE_OBSERVATION_TYPE]: 'generation',
+        },
+    }, context.parentContext);
+    const traceContext = trace.setSpan(context.parentContext, span);
+    return {
+        span,
+        traceContext,
+        tapFinish: tap({
+            next: (event) => {
+                switch (event.kind) {
+                    case 'content-complete':
+                        if (event.content) {
+                            span.setAttribute(SpanAttributes.GEN_AI_COMPLETION, event.content);
+                        }
+                        span.setAttribute(SpanAttributes.LLM_FINISH_REASON, event.finishReason || 'unknown');
+                        span.setStatus({ code: SpanStatusCode.OK });
+                        break;
+                    case 'llm-usage':
+                        span.setAttribute(SpanAttributes.GEN_AI_RESPONSE_MODEL, event.model);
+                        span.setAttribute(SpanAttributes.GEN_AI_USAGE_PROMPT_TOKENS, event.prompt_tokens || 0);
+                        span.setAttribute(SpanAttributes.GEN_AI_USAGE_COMPLETION_TOKENS, event.completion_tokens || 0);
+                        span.setAttribute(SpanAttributes.GEN_AI_USAGE_TOTAL_TOKENS, event.total_tokens || 0);
+                        span.setAttribute(SpanAttributes.GEN_AI_USAGE_COMPLETION_TOKENS_DETAILS, JSON.stringify(event.completion_tokens_details || {}));
+                        span.setAttribute(SpanAttributes.GEN_AI_USAGE_PROMPT_TOKENS_DETAILS, JSON.stringify(event.prompt_tokens_details || {}));
+                        span.setAttribute(SpanAttributes.GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS, event.cache_creation_input_tokens || 0);
+                        span.setAttribute(SpanAttributes.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS, event.cache_read_input_tokens || 0);
+                        break;
+                    default:
+                        break;
+                }
+            },
+            complete: () => span.end(),
+            error: (err) => {
+                span.recordException(err);
+                span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+                span.end();
+            },
+        }),
+    };
+};

package/dist/observability/spans/loop.d.ts

@@ -0,0 +1,14 @@
+import { type Context } from '@opentelemetry/api';
+import type { AnyEvent } from '../../types/event';
+export interface AgentLoopSpanParams {
+    agentId: string;
+    taskId: string;
+    contextId: string;
+    prompt?: string;
+    parentContext: Context;
+}
+export declare const startAgentLoopSpan: (params: AgentLoopSpanParams) => {
+    span: import("@opentelemetry/api").Span;
+    traceContext: Context;
+    tapFinish: import("rxjs").MonoTypeOperatorFunction<AnyEvent>;
+};

package/dist/observability/spans/loop.js

@@ -0,0 +1,40 @@
+import { SpanStatusCode, trace } from '@opentelemetry/api';
+import { tap } from 'rxjs/internal/operators/tap';
+import { SpanAttributes, SpanNames } from '../tracing';
+export const startAgentLoopSpan = (params) => {
+    const tracer = trace.getTracer('looopy');
+    const span = tracer.startSpan(SpanNames.LOOP_START, {
+        attributes: {
+            [SpanAttributes.SESSION_ID]: params.contextId,
+            [SpanAttributes.AGENT_ID]: params.agentId,
+            [SpanAttributes.TASK_ID]: params.taskId,
+            input: params.prompt,
+            [SpanAttributes.LANGFUSE_OBSERVATION_TYPE]: 'event',
+        },
+    }, params.parentContext);
+    const traceContext = trace.setSpan(params.parentContext, span);
+    return {
+        span,
+        traceContext,
+        tapFinish: tap({
+            next: (event) => {
+                switch (event.kind) {
+                    case 'content-complete':
+                        if (event.content) {
+                            span.setAttribute(SpanAttributes.OUTPUT, event.content);
+                        }
+                        span.setStatus({ code: SpanStatusCode.OK });
+                        break;
+                    default:
+                        break;
+                }
+            },
+            complete: () => span.end(),
+            error: (err) => {
+                span.recordException(err);
+                span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+                span.end();
+            },
+        }),
+    };
+};

package/dist/observability/spans/tool.d.ts

@@ -0,0 +1,14 @@
+import type { IterationContext } from '../../core/types';
+import type { ToolExecutionEvent, ToolStartEvent } from '../../types/event';
+import type { ToolCall } from '../../types/tools';
+export interface ToolExecutionSpanParams {
+    agentId: string;
+    taskId: string;
+    toolCall: ToolCall;
+    parentContext?: import('@opentelemetry/api').Context;
+}
+export declare const startToolExecuteSpan: (context: IterationContext, toolStart: ToolStartEvent) => {
+    span: import("@opentelemetry/api").Span;
+    traceContext: import("@opentelemetry/api").Context;
+    tapFinish: import("rxjs").MonoTypeOperatorFunction<ToolExecutionEvent>;
+};

package/dist/observability/spans/tool.js

@@ -0,0 +1,44 @@
+import { context as otelContext, SpanStatusCode, trace } from '@opentelemetry/api';
+import { tap } from 'rxjs/internal/operators/tap';
+import { SpanAttributes, SpanNames } from '../tracing';
+export const startToolExecuteSpan = (context, toolStart) => {
+    const tracer = trace.getTracer('looopy');
+    const span = tracer.startSpan(SpanNames.TOOL_EXECUTE, {
+        attributes: {
+            [SpanAttributes.AGENT_ID]: context.agentId,
+            [SpanAttributes.TASK_ID]: context.taskId,
+            [SpanAttributes.TOOL_NAME]: toolStart.toolName,
+            [SpanAttributes.TOOL_CALL_ID]: toolStart.toolCallId,
+            [SpanAttributes.LANGFUSE_OBSERVATION_TYPE]: 'tool',
+            input: JSON.stringify(toolStart.arguments),
+        },
+    }, context.parentContext);
+    const traceContext = trace.setSpan(context.parentContext || otelContext.active(), span);
+    return {
+        span,
+        traceContext,
+        tapFinish: tap({
+            next: (event) => {
+                if (event.kind === 'tool-complete') {
+                    if (event.success) {
+                        span.setAttribute('output', JSON.stringify(event.result));
+                        span.setStatus({ code: SpanStatusCode.OK });
+                    }
+                    else {
+                        span.setAttribute('output', event.error || 'Tool execution failed');
+                        span.setStatus({ code: SpanStatusCode.ERROR });
+                        if (event.error) {
+                            span.setAttribute('error.message', event.error);
+                        }
+                    }
+                }
+            },
+            complete: () => span.end(),
+            error: (err) => {
+                span.recordException(err);
+                span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+                span.end();
+            },
+        }),
+    };
+};