@lleverage-ai/agent-sdk 0.0.1

package/dist/observability/preset.js

@@ -0,0 +1,133 @@
+/**
+ * Observability Preset.
+ *
+ * Provides a convenience function for setting up complete observability
+ * in a single call, including logger, metrics, tracer, and hooks.
+ *
+ * @packageDocumentation
+ */
+import { createComprehensiveLoggingHooks } from "../hooks/logging.js";
+import { createConsoleTransport, createLogger, createPrettyFormatter, } from "./logger.js";
+import { createAgentMetrics, createMetricsRegistry, } from "./metrics.js";
+import { createConsoleSpanExporter, createTracer, } from "./tracing.js";
+/**
+ * Creates a complete observability setup with logger, metrics, tracer, and hooks.
+ *
+ * This function provides a convenient way to set up comprehensive observability
+ * for your agent in a single call. It returns configured observability primitives
+ * and hooks that can be passed directly to `createAgent()`.
+ *
+ * @param options - Configuration options
+ * @returns Observability preset with logger, metrics, tracer, and hooks
+ *
+ * @example
+ * ```typescript
+ * import { createAgent, createObservabilityPreset } from "@lleverage-ai/agent-sdk";
+ * import { anthropic } from "@ai-sdk/anthropic";
+ *
+ * // One-line observability setup
+ * const observability = createObservabilityPreset({
+ *   name: "my-agent",
+ * });
+ *
+ * // Create agent with full observability
+ * const agent = createAgent({
+ *   model: anthropic("claude-sonnet-4-20250514"),
+ *   hooks: observability.hooks,
+ * });
+ *
+ * // Access observability primitives
+ * observability.logger?.info("Agent started");
+ * observability.metrics?.requests.inc();
+ * const span = observability.tracer?.startSpan("custom-operation");
+ * ```
+ *
+ * @example
+
+ * ```typescript
+ * // Customize observability setup
+ * const observability = createObservabilityPreset({
+ *   name: "my-agent",
+ *   enableTracing: false, // Disable tracing
+ *   loggerOptions: {
+ *     level: "warn", // Only log warnings and errors
+ *   },
+ *   loggingHooksOptions: {
+ *     logTiming: true,
+ *     maxTextLength: 500,
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Export traces to OpenTelemetry collector
+ * import { createOTLPSpanExporter } from "@lleverage-ai/agent-sdk";
+ *
+ * const observability = createObservabilityPreset({
+ *   name: "production-agent",
+ *   spanExporters: [
+ *     createOTLPSpanExporter({
+ *       url: "http://localhost:4318/v1/traces",
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export function createObservabilityPreset(options = {}) {
+    const { name = "agent", enableLogging = true, enableMetrics = true, enableTracing = true, enableHooks = true, loggerOptions = {}, metricsOptions = {}, tracerOptions = {}, loggingHooksOptions = {}, spanExporters, } = options;
+    const preset = {};
+    // Create logger
+    if (enableLogging) {
+        preset.logger = createLogger({
+            name,
+            level: "info",
+            transports: [createConsoleTransport()],
+            formatter: createPrettyFormatter(),
+            ...loggerOptions,
+        });
+    }
+    // Create metrics
+    if (enableMetrics) {
+        preset.metricsRegistry = createMetricsRegistry(metricsOptions);
+        preset.metrics = createAgentMetrics(preset.metricsRegistry);
+    }
+    // Create tracer
+    if (enableTracing) {
+        const exporters = spanExporters ?? [createConsoleSpanExporter()];
+        preset.tracer = createTracer({
+            name,
+            exporters,
+            ...tracerOptions,
+        });
+    }
+    // Create hooks
+    if (enableHooks) {
+        let hooks;
+        // Add comprehensive logging hooks if logger is enabled
+        if (enableLogging && preset.logger) {
+            const logger = preset.logger;
+            const { generationHooks, toolHooks, compactionHooks } = createComprehensiveLoggingHooks({
+                log: (message) => logger.info(message),
+                prefix: `[${name}]`,
+                logTiming: true,
+                ...loggingHooksOptions,
+            });
+            hooks = {
+                PreGenerate: generationHooks[0] ? [generationHooks[0]] : undefined,
+                PostGenerate: generationHooks[1] ? [generationHooks[1]] : undefined,
+                PostGenerateFailure: generationHooks[2] ? [generationHooks[2]] : undefined,
+                PreToolUse: toolHooks[0] ? [{ hooks: [toolHooks[0]] }] : undefined,
+                PostToolUse: toolHooks[1] ? [{ hooks: [toolHooks[1]] }] : undefined,
+                PostToolUseFailure: toolHooks[2] ? [{ hooks: [toolHooks[2]] }] : undefined,
+                PreCompact: compactionHooks[0] ? [compactionHooks[0]] : undefined,
+                PostCompact: compactionHooks[1] ? [compactionHooks[1]] : undefined,
+            };
+        }
+        preset.hooks = hooks && Object.keys(hooks).length > 0 ? hooks : undefined;
+    }
+    return preset;
+}
+//# sourceMappingURL=preset.js.map

package/dist/observability/preset.js.map

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

package/dist/observability/streaming.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Streaming Observability Support.
+ *
+ * Provides transports and utilities for streaming observability data
+ * (logs, metrics, traces) to clients via the data stream.
+ *
+ * @packageDocumentation
+ */
+import type { UIMessageStreamWriter } from "ai";
+import type { LogFormatter, LogTransport } from "./logger.js";
+/**
+ * Options for creating a streaming log transport.
+ *
+ * @category Observability
+ */
+export interface StreamingLogTransportOptions {
+    /**
+     * The UI message stream writer to send logs to.
+     */
+    writer: UIMessageStreamWriter;
+    /**
+     * Optional formatter for converting log entries to data.
+     * If not provided, logs are sent as structured objects.
+     */
+    formatter?: LogFormatter;
+    /**
+     * The data type to use when sending logs.
+     * @default "log"
+     */
+    dataType?: string;
+    /**
+     * Whether to include the raw log entry object.
+     * @default true
+     */
+    includeRawEntry?: boolean;
+}
+/**
+ * Creates a log transport that streams logs to clients via the data stream.
+ *
+ * This transport is designed to be used with `streamDataResponse()` to send
+ * real-time log data to the frontend.
+ *
+ * @param options - Transport options
+ * @returns A log transport that writes to the data stream
+ *
+ * @example
+ * ```typescript
+ * import { createStreamingLogTransport } from "@lleverage-ai/agent-sdk";
+ *
+ * // In streamDataResponse execute function:
+ * const streamingContext: StreamingContext = { writer };
+ *
+ * const streamingTransport = createStreamingLogTransport({
+ *   writer: streamingContext.writer,
+ * });
+ *
+ * const logger = createLogger({
+ *   name: "agent",
+ *   transports: [streamingTransport],
+ * });
+ *
+ * // Logs will be streamed to the frontend
+ * logger.info("Agent started");
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createStreamingLogTransport(options: StreamingLogTransportOptions): LogTransport;
+/**
+ * Options for creating observability streaming support.
+ *
+ * @category Observability
+ */
+export interface StreamingObservabilityOptions {
+    /**
+     * The UI message stream writer.
+     */
+    writer: UIMessageStreamWriter;
+    /**
+     * Whether to stream logs.
+     * @default true
+     */
+    streamLogs?: boolean;
+    /**
+     * Log formatter to use.
+     */
+    logFormatter?: LogFormatter;
+}
+/**
+ * Creates a complete streaming observability setup.
+ *
+ * Returns transports configured to stream observability data to clients.
+ *
+ * @param options - Streaming options
+ * @returns An object with configured transports
+ *
+ * @example
+ * ```typescript
+ * const { logTransport } = createStreamingObservability({
+ *   writer: streamingContext.writer,
+ * });
+ *
+ * const logger = createLogger({
+ *   transports: [logTransport],
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createStreamingObservability(options: StreamingObservabilityOptions): {
+    logTransport: LogTransport | null;
+};
+//# sourceMappingURL=streaming.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../src/observability/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,IAAI,CAAC;AAChD,OAAO,KAAK,EAAY,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAExE;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;OAEG;IACH,MAAM,EAAE,qBAAqB,CAAC;IAE9B;;;OAGG;IACH,SAAS,CAAC,EAAE,YAAY,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,4BAA4B,GAAG,YAAY,CA6C/F;AAED;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;OAEG;IACH,MAAM,EAAE,qBAAqB,CAAC;IAE9B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,6BAA6B,GAAG;IACpF,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;CACnC,CAWA"}

package/dist/observability/streaming.js

@@ -0,0 +1,114 @@
+/**
+ * Streaming Observability Support.
+ *
+ * Provides transports and utilities for streaming observability data
+ * (logs, metrics, traces) to clients via the data stream.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Creates a log transport that streams logs to clients via the data stream.
+ *
+ * This transport is designed to be used with `streamDataResponse()` to send
+ * real-time log data to the frontend.
+ *
+ * @param options - Transport options
+ * @returns A log transport that writes to the data stream
+ *
+ * @example
+ * ```typescript
+ * import { createStreamingLogTransport } from "@lleverage-ai/agent-sdk";
+ *
+ * // In streamDataResponse execute function:
+ * const streamingContext: StreamingContext = { writer };
+ *
+ * const streamingTransport = createStreamingLogTransport({
+ *   writer: streamingContext.writer,
+ * });
+ *
+ * const logger = createLogger({
+ *   name: "agent",
+ *   transports: [streamingTransport],
+ * });
+ *
+ * // Logs will be streamed to the frontend
+ * logger.info("Agent started");
+ * ```
+ *
+ * @category Observability
+ */
+export function createStreamingLogTransport(options) {
+    const { writer, formatter, dataType = "log", includeRawEntry = true } = options;
+    return {
+        name: "streaming",
+        write(entry) {
+            // Build the data payload
+            const payload = {
+                type: dataType,
+            };
+            if (includeRawEntry) {
+                // Send the full entry for rich client-side handling
+                payload.entry = {
+                    level: entry.level,
+                    message: entry.message,
+                    timestamp: entry.timestamp,
+                    logger: entry.logger,
+                    context: entry.context,
+                    durationMs: entry.durationMs,
+                    // Serialize error if present
+                    error: entry.error
+                        ? {
+                            name: entry.error.name,
+                            message: entry.error.message,
+                            stack: entry.error.stack,
+                        }
+                        : undefined,
+                };
+            }
+            if (formatter) {
+                // Also include formatted text if a formatter is provided
+                payload.formatted = formatter.format(entry);
+            }
+            // Write to the data stream
+            // Use type assertion to bypass strict stream part type checking
+            // This follows the same pattern as task.ts for custom data streaming
+            writer.write({
+                type: "data-log",
+                data: payload,
+            });
+        },
+    };
+}
+/**
+ * Creates a complete streaming observability setup.
+ *
+ * Returns transports configured to stream observability data to clients.
+ *
+ * @param options - Streaming options
+ * @returns An object with configured transports
+ *
+ * @example
+ * ```typescript
+ * const { logTransport } = createStreamingObservability({
+ *   writer: streamingContext.writer,
+ * });
+ *
+ * const logger = createLogger({
+ *   transports: [logTransport],
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export function createStreamingObservability(options) {
+    const { writer, streamLogs = true, logFormatter } = options;
+    return {
+        logTransport: streamLogs
+            ? createStreamingLogTransport({
+                writer,
+                formatter: logFormatter,
+            })
+            : null,
+    };
+}
+//# sourceMappingURL=streaming.js.map

package/dist/observability/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../../src/observability/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmCH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAAqC;IAC/E,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,GAAG,KAAK,EAAE,eAAe,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAEhF,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,KAAK,CAAC,KAAe;YACnB,yBAAyB;YACzB,MAAM,OAAO,GAA4B;gBACvC,IAAI,EAAE,QAAQ;aACf,CAAC;YAEF,IAAI,eAAe,EAAE,CAAC;gBACpB,oDAAoD;gBACpD,OAAO,CAAC,KAAK,GAAG;oBACd,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,SAAS,EAAE,KAAK,CAAC,SAAS;oBAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,UAAU,EAAE,KAAK,CAAC,UAAU;oBAC5B,6BAA6B;oBAC7B,KAAK,EAAE,KAAK,CAAC,KAAK;wBAChB,CAAC,CAAC;4BACE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI;4BACtB,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO;4BAC5B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK;yBACzB;wBACH,CAAC,CAAC,SAAS;iBACd,CAAC;YACJ,CAAC;YAED,IAAI,SAAS,EAAE,CAAC;gBACd,yDAAyD;gBACzD,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC9C,CAAC;YAED,2BAA2B;YAC3B,gEAAgE;YAChE,qEAAqE;YACrE,MAAM,CAAC,KAAK,CAAC;gBACX,IAAI,EAAE,UAAU;gBAChB,IAAI,EAAE,OAAO;aACwB,CAAC,CAAC;QAC3C,CAAC;KACF,CAAC;AACJ,CAAC;AAyBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,4BAA4B,CAAC,OAAsC;IAGjF,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IAE5D,OAAO;QACL,YAAY,EAAE,UAAU;YACtB,CAAC,CAAC,2BAA2B,CAAC;gBAC1B,MAAM;gBACN,SAAS,EAAE,YAAY;aACxB,CAAC;YACJ,CAAC,CAAC,IAAI;KACT,CAAC;AACJ,CAAC"}