@lobu/core 3.0.13 → 3.0.19

package/src/otel.ts

@@ -1,307 +0,0 @@
-/**
- * OpenTelemetry tracing setup for distributed tracing.
- * Ships traces via OTLP gRPC to any compatible collector (Tempo, Jaeger, Datadog, etc.).
- */
-
-import type { Span, Tracer } from "@opentelemetry/api";
-import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
-import { Resource } from "@opentelemetry/resources";
-import {
-  NodeTracerProvider,
-  SimpleSpanProcessor,
-} from "@opentelemetry/sdk-trace-node";
-import {
-  ATTR_SERVICE_NAME,
-  ATTR_SERVICE_VERSION,
-} from "@opentelemetry/semantic-conventions";
-import { createLogger } from "./logger";
-
-const logger = createLogger("otel");
-
-let provider: NodeTracerProvider | null = null;
-let tracer: Tracer | null = null;
-
-export interface OtelConfig {
-  serviceName: string;
-  serviceVersion?: string;
-  otlpEndpoint?: string; // e.g., "http://collector:4317"
-  enabled?: boolean;
-}
-
-/**
- * Initialize OpenTelemetry tracing.
- * Call this once at application startup.
- *
- * @example
- * initTracing({
- *   serviceName: "lobu-gateway",
- *   otlpEndpoint: "http://collector:4317",
- * });
- */
-export function initTracing(config: OtelConfig): void {
-  if (provider) {
-    return; // Already initialized
-  }
-
-  const enabled = config.enabled ?? !!config.otlpEndpoint;
-  if (!enabled) {
-    logger.debug(
-      "Tracing disabled (no OTEL_EXPORTER_OTLP_ENDPOINT configured)"
-    );
-    return;
-  }
-
-  const resource = new Resource({
-    [ATTR_SERVICE_NAME]: config.serviceName,
-    [ATTR_SERVICE_VERSION]: config.serviceVersion || "1.0.0",
-  });
-
-  provider = new NodeTracerProvider({ resource });
-
-  const exporter = new OTLPTraceExporter({
-    url: config.otlpEndpoint,
-    timeoutMillis: 30000, // 30 second timeout for reliability
-  });
-
-  // Use SimpleSpanProcessor for immediate export (better for short-lived workers)
-  provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
-  provider.register();
-
-  tracer = trace.getTracer(config.serviceName, config.serviceVersion);
-
-  logger.info(
-    `Tracing initialized: ${config.serviceName} -> ${config.otlpEndpoint}`
-  );
-}
-
-/**
- * Get the configured tracer. Returns null if not initialized.
- */
-export function getTracer(): Tracer | null {
-  return tracer;
-}
-
-/**
- * Shutdown tracing gracefully.
- */
-export async function shutdownTracing(): Promise<void> {
-  if (provider) {
-    await provider.shutdown();
-    provider = null;
-    tracer = null;
-  }
-}
-
-/**
- * Force flush all pending spans to the exporter.
- * Call this after processing a message to ensure spans are exported promptly.
- */
-export async function flushTracing(): Promise<void> {
-  if (provider) {
-    await provider.forceFlush();
-  }
-}
-
-/**
- * Create a new span for tracing.
- * If tracing is not initialized, returns a no-op span.
- *
- * @param name Span name (e.g., "queue_processing", "agent_execution")
- * @param attributes Optional attributes to add to the span
- * @param parentContext Optional parent context for trace correlation
- */
-export function createSpan(
-  name: string,
-  attributes?: Record<string, string | number | boolean>,
-  kind: SpanKind = SpanKind.INTERNAL
-): Span | null {
-  if (!tracer) {
-    return null;
-  }
-
-  const span = tracer.startSpan(name, {
-    kind,
-    attributes,
-  });
-
-  return span;
-}
-
-/**
- * Execute a function within a span context.
- * Automatically handles span lifecycle (start, end, error recording).
- *
- * @example
- * const result = await withSpan("process_message", async (span) => {
- *   span?.setAttribute("messageId", messageId);
- *   return await processMessage();
- * });
- */
-export async function withSpan<T>(
-  name: string,
-  fn: (span: Span | null) => Promise<T>,
-  attributes?: Record<string, string | number | boolean>
-): Promise<T> {
-  const span = createSpan(name, attributes);
-
-  try {
-    const result = await fn(span);
-    span?.setStatus({ code: SpanStatusCode.OK });
-    return result;
-  } catch (error) {
-    if (span) {
-      span.setStatus({
-        code: SpanStatusCode.ERROR,
-        message: error instanceof Error ? error.message : String(error),
-      });
-      span.recordException(error as Error);
-    }
-    throw error;
-  } finally {
-    span?.end();
-  }
-}
-
-/**
- * Get current active span from context.
- */
-export function getCurrentSpan(): Span | undefined {
-  return trace.getActiveSpan();
-}
-
-/**
- * Run a function within a span context, propagating the span.
- */
-export function runInSpanContext<T>(span: Span, fn: () => T): T {
-  const ctx = trace.setSpan(context.active(), span);
-  return context.with(ctx, fn);
-}
-
-/**
- * Create a root span and return traceparent header for propagation.
- * Use this at the entry point (message ingestion) to start a trace.
- *
- * @example
- * const { span, traceparent } = createRootSpan("message_received", { messageId });
- * // Store traceparent in message metadata for downstream propagation
- * await queueProducer.enqueueMessage({ ...data, platformMetadata: { traceparent } });
- * span.end();
- */
-export function createRootSpan(
-  name: string,
-  attributes?: Record<string, string | number | boolean>
-): { span: Span | null; traceparent: string | null } {
-  if (!tracer) {
-    return { span: null, traceparent: null };
-  }
-
-  const span = tracer.startSpan(name, {
-    kind: SpanKind.SERVER,
-    attributes,
-  });
-
-  // Extract W3C traceparent header from span context
-  const spanContext = span.spanContext();
-  const traceparent = `00-${spanContext.traceId}-${spanContext.spanId}-01`;
-
-  return { span, traceparent };
-}
-
-/**
- * Create a child span from a traceparent header.
- * Use this to continue a trace in downstream services (queue consumer, worker).
- *
- * @example
- * const traceparent = data.platformMetadata?.traceparent;
- * const span = createChildSpan("queue_processing", traceparent, { jobId });
- * // ... do work ...
- * span?.end();
- */
-export function createChildSpan(
-  name: string,
-  traceparent: string | null | undefined,
-  attributes?: Record<string, string | number | boolean>
-): Span | null {
-  if (!tracer) {
-    return null;
-  }
-
-  if (!traceparent) {
-    // No parent context - create independent span
-    return createSpan(name, attributes);
-  }
-
-  // Parse W3C traceparent: 00-traceId-parentSpanId-flags
-  const parts = traceparent.split("-");
-  if (parts.length !== 4) {
-    return createSpan(name, attributes);
-  }
-
-  const traceId = parts[1]!;
-  const parentSpanId = parts[2]!;
-
-  // Create span context from traceparent
-  const parentContext = trace.setSpanContext(context.active(), {
-    traceId,
-    spanId: parentSpanId,
-    traceFlags: 1, // sampled
-    isRemote: true,
-  });
-
-  // Start span as child of the propagated context
-  return tracer.startSpan(
-    name,
-    { kind: SpanKind.INTERNAL, attributes },
-    parentContext
-  );
-}
-
-/**
- * Run a function within a child span context.
- * Automatically handles span lifecycle and error recording.
- *
- * @example
- * const result = await withChildSpan("process_job", traceparent, async (span) => {
- *   span?.setAttribute("jobId", jobId);
- *   return await processJob();
- * });
- */
-export async function withChildSpan<T>(
-  name: string,
-  traceparent: string | null | undefined,
-  fn: (span: Span | null) => Promise<T>,
-  attributes?: Record<string, string | number | boolean>
-): Promise<T> {
-  const span = createChildSpan(name, traceparent, attributes);
-
-  try {
-    const result = await fn(span);
-    span?.setStatus({ code: SpanStatusCode.OK });
-    return result;
-  } catch (error) {
-    if (span) {
-      span.setStatus({
-        code: SpanStatusCode.ERROR,
-        message: error instanceof Error ? error.message : String(error),
-      });
-      span.recordException(error as Error);
-    }
-    throw error;
-  } finally {
-    span?.end();
-  }
-}
-
-/**
- * Extract traceparent from span for propagation to downstream services.
- */
-export function getTraceparent(span: Span | null): string | null {
-  if (!span) return null;
-  const ctx = span.spanContext();
-  return `00-${ctx.traceId}-${ctx.spanId}-01`;
-}
-
-export type { Span, Tracer };
-// Re-export OpenTelemetry types for convenience
-export { SpanKind, SpanStatusCode };

package/src/plugin-types.ts

@@ -1,46 +0,0 @@
-/**
- * OpenClaw plugin types for Lobu.
- *
- * Supports loading existing OpenClaw community plugins.
- */
-
-/** Supported plugin slots */
-export type PluginSlot = "tool" | "provider" | "memory";
-
-/** Configuration for a single plugin */
-export interface PluginConfig {
-  /** npm package name or local path (e.g., "@openclaw/voice-call", "./my-plugin") */
-  source: string;
-  /** Which slot this plugin fills */
-  slot: PluginSlot;
-  /** Whether this plugin is enabled (default: true) */
-  enabled?: boolean;
-  /** Plugin-specific configuration passed through to the plugin runtime */
-  config?: Record<string, unknown>;
-}
-
-/** Top-level plugins configuration stored in agent settings */
-export interface PluginsConfig {
-  plugins: PluginConfig[];
-}
-
-/** Metadata about a loaded plugin */
-export interface PluginManifest {
-  /** Source identifier (package name or path) */
-  source: string;
-  /** Plugin slot */
-  slot: PluginSlot;
-  /** Display name (from package or source) */
-  name: string;
-}
-
-/**
- * A provider registration captured from pi.registerProvider().
- * The config is opaque here — it's passed directly to ModelRegistry.registerProvider().
- */
-export interface ProviderRegistration {
-  /** Provider name (e.g., "corporate-ai", "my-proxy") */
-  name: string;
-  /** Provider config (ProviderConfigInput from pi-coding-agent) */
-  config: Record<string, unknown>;
-}

package/src/provider-config-types.ts

@@ -1,54 +0,0 @@
-/**
- * Shared types for config-driven LLM providers.
- * Loaded from the `providers` section of system skills config.
- */
-
-export interface ProviderConfigEntry {
-  /** Display name in settings page (e.g. "Groq") */
-  displayName: string;
-  /** Provider icon URL */
-  iconUrl: string;
-  /** Env var name for API key (e.g. "GROQ_API_KEY") */
-  envVarName: string;
-  /** Provider's API base URL (e.g. "https://api.groq.com/openai") */
-  upstreamBaseUrl: string;
-  /** HTML help text for the settings page API key input */
-  apiKeyInstructions: string;
-  /** Placeholder text for the API key input */
-  apiKeyPlaceholder: string;
-  /** SDK compatibility hint — "openai" means OpenAI-compatible API format */
-  sdkCompat?: "openai";
-  /** Default model ID when none is configured */
-  defaultModel?: string;
-  /** Relative path to fetch model list (e.g. "/v1/models") */
-  modelsEndpoint?: string;
-  /** Override provider name for model registry lookup */
-  registryAlias?: string;
-  /** Whether to show in "Add Provider" catalog (default: true) */
-  catalogVisible?: boolean;
-  /**
-   * Optional speech-to-text configuration.
-   * If omitted and sdkCompat is "openai", STT is enabled with default endpoint/model.
-   * Use this block to override endpoint/model or disable STT for a provider.
-   */
-  stt?: {
-    /** Set false to disable STT even when this block exists. */
-    enabled?: boolean;
-    /** STT protocol compatibility; currently only OpenAI-compatible is supported here. */
-    sdkCompat?: "openai";
-    /** Optional upstream base URL override for STT requests. */
-    baseUrl?: string;
-    /** Relative or absolute transcription endpoint path/URL. */
-    transcriptionPath?: string;
-    /** STT model ID (for OpenAI-compatible endpoints). */
-    model?: string;
-  };
-}
-
-/** Metadata passed from gateway to worker for config-driven providers. */
-export interface ConfigProviderMeta {
-  sdkCompat?: "openai";
-  defaultModel?: string;
-  registryAlias?: string;
-  baseUrlEnvVar: string;
-}

package/src/redis/base-store.ts

@@ -1,200 +0,0 @@
-import type Redis from "ioredis";
-import { createLogger, type Logger } from "../logger";
-import { safeJsonParse, safeJsonStringify } from "../utils/json";
-
-function errMsg(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-export interface RedisStoreConfig {
-  redis: Redis;
-  keyPrefix: string;
-  loggerName: string;
-}
-
-/**
- * Base class for all Redis-backed stores
- * Provides common CRUD operations with JSON serialization
- *
- * Consolidates:
- * - packages/gateway/src/auth/credential-store.ts (BaseCredentialStore)
- * - packages/gateway/src/infrastructure/redis/store.ts (BaseRedisStore)
- */
-export abstract class BaseRedisStore<T> {
-  protected logger: Logger;
-  protected redis: Redis;
-  protected keyPrefix: string;
-
-  constructor(config: RedisStoreConfig) {
-    this.redis = config.redis;
-    this.keyPrefix = config.keyPrefix;
-    this.logger = createLogger(config.loggerName);
-  }
-
-  /**
-   * Build Redis key from parts
-   */
-  protected buildKey(...parts: string[]): string {
-    return [this.keyPrefix, ...parts].join(":");
-  }
-
-  /**
-   * Get value from Redis
-   * Returns null if not found or validation fails
-   */
-  protected async get(key: string): Promise<T | null> {
-    try {
-      const data = await this.redis.get(key);
-      if (!data) {
-        return null;
-      }
-
-      const value = this.deserialize(data);
-
-      // Validate after deserialization
-      if (!this.validate(value)) {
-        this.logger.warn("Invalid data after deserialization", { key });
-        return null;
-      }
-
-      return value;
-    } catch (error) {
-      this.logger.error("Failed to get from Redis", {
-        error: errMsg(error),
-        key,
-      });
-      return null;
-    }
-  }
-
-  /**
-   * Set value in Redis
-   */
-  protected async set(
-    key: string,
-    value: T,
-    ttlSeconds?: number
-  ): Promise<void> {
-    try {
-      const data = this.serialize(value);
-      if (ttlSeconds) {
-        await this.redis.setex(key, ttlSeconds, data);
-      } else {
-        await this.redis.set(key, data);
-      }
-    } catch (error) {
-      this.logger.error("Failed to set in Redis", {
-        error: errMsg(error),
-        key,
-      });
-      throw error;
-    }
-  }
-
-  /**
-   * Delete value from Redis
-   */
-  protected async delete(key: string): Promise<void> {
-    try {
-      await this.redis.del(key);
-    } catch (error) {
-      this.logger.error("Failed to delete from Redis", {
-        error: errMsg(error),
-        key,
-      });
-    }
-  }
-
-  /**
-   * Scan for all keys matching a prefix (cursor-based, production-safe).
-   * Returns full key strings matching `{prefix}*`.
-   */
-  protected async scanByPrefix(prefix: string): Promise<string[]> {
-    const results: string[] = [];
-    let cursor = "0";
-    try {
-      do {
-        const [nextCursor, keys] = await this.redis.scan(
-          cursor,
-          "MATCH",
-          `${prefix}*`,
-          "COUNT",
-          100
-        );
-        cursor = nextCursor;
-        results.push(...keys);
-      } while (cursor !== "0");
-    } catch (error) {
-      this.logger.error("Failed to scan by prefix", {
-        error: errMsg(error),
-        prefix,
-      });
-    }
-    return results;
-  }
-
-  /**
-   * Check if key exists in Redis
-   */
-  protected async exists(key: string): Promise<boolean> {
-    try {
-      const result = await this.redis.exists(key);
-      return result === 1;
-    } catch (error) {
-      this.logger.error("Failed to check existence in Redis", {
-        error: errMsg(error),
-        key,
-      });
-      return false;
-    }
-  }
-
-  /**
-   * Serialize value to string
-   * Override for custom serialization
-   */
-  protected serialize(value: T): string {
-    const result = safeJsonStringify(value);
-    if (result === null) {
-      throw new Error("Failed to serialize value to JSON");
-    }
-    return result;
-  }
-
-  /**
-   * Deserialize string to value
-   * Override for custom deserialization
-   */
-  protected deserialize(data: string): T {
-    const result = safeJsonParse<T>(data);
-    if (result === null) {
-      throw new Error("Failed to deserialize JSON data");
-    }
-    return result;
-  }
-
-  /**
-   * Validate value after deserialization
-   * Override to add custom validation logic
-   * Return false to reject invalid data
-   */
-  protected validate(_value: T): boolean {
-    return true;
-  }
-}
-
-/**
- * Specialized base for credential stores
- * Validates that accessToken field exists
- */
-export abstract class BaseCredentialStore<
-  T extends { accessToken: string },
-> extends BaseRedisStore<T> {
-  protected override validate(value: T): boolean {
-    if (!value.accessToken) {
-      this.logger.warn("Invalid credentials: missing accessToken");
-      return false;
-    }
-    return true;
-  }
-}

package/src/sentry.ts

@@ -1,56 +0,0 @@
-import { createLogger, type Logger } from "./logger";
-
-// Lazy logger initialization to avoid circular dependency
-let _logger: Logger | null = null;
-function getLogger(): Logger {
-  if (!_logger) {
-    _logger = createLogger("sentry");
-  }
-  return _logger;
-}
-
-let sentryInstance: typeof import("@sentry/node") | null = null;
-
-/**
- * Initialize Sentry with configuration from environment variables.
- * Only initializes if SENTRY_DSN is set — no implicit error reporting.
- * Uses dynamic import to avoid module resolution issues in dev mode.
- */
-export async function initSentry() {
-  const sentryDsn = process.env.SENTRY_DSN;
-  if (!sentryDsn) {
-    getLogger().debug("Sentry disabled (no SENTRY_DSN configured)");
-    return;
-  }
-
-  try {
-    const Sentry = await import("@sentry/node");
-    sentryInstance = Sentry;
-
-    Sentry.init({
-      dsn: sentryDsn,
-      sendDefaultPii: true,
-      profileSessionSampleRate: 1.0,
-      tracesSampleRate: 1.0, // Capture 100% of traces for better visibility
-      integrations: [
-        Sentry.consoleLoggingIntegration({ levels: ["log", "warn", "error"] }),
-        Sentry.redisIntegration(),
-      ],
-    });
-
-    getLogger().debug("Sentry monitoring initialized");
-  } catch (error) {
-    getLogger().warn(
-      "Sentry initialization failed (continuing without monitoring):",
-      error
-    );
-  }
-}
-
-/**
- * Get the initialized Sentry instance
- * @returns Sentry instance or null if not initialized
- */
-export function getSentry(): typeof import("@sentry/node") | null {
-  return sentryInstance;
-}

package/src/trace.ts

@@ -1,32 +0,0 @@
-/**
- * Trace ID utilities for end-to-end message lifecycle observability.
- * Trace IDs propagate through the entire pipeline:
- * [WhatsApp Message] -> [Queue] -> [Worker Creation] -> [PVC Setup] -> [Agent Runtime] -> [Response]
- *
- * When OpenTelemetry is initialized, spans are sent to Tempo for waterfall visualization.
- * Use createSpan/createChildSpan from ./otel.ts for actual span creation.
- */
-
-/**
- * Generate a trace ID from a message ID.
- * Format: tr-{messageId prefix}-{timestamp base36}-{random}
- * Example: tr-abc12345-lx4k-a3b2
- */
-export function generateTraceId(messageId: string): string {
-  const timestamp = Date.now().toString(36);
-  const random = Math.random().toString(36).substring(2, 6);
-  // Take first 8 chars of messageId, sanitize for safe logging
-  const shortMessageId = messageId.replace(/[^a-zA-Z0-9]/g, "").substring(0, 8);
-  return `tr-${shortMessageId}-${timestamp}-${random}`;
-}
-
-/**
- * Extract trace ID from various payload formats.
- * Checks both top-level and nested platformMetadata.
- */
-export function extractTraceId(payload: {
-  traceId?: string;
-  platformMetadata?: { traceId?: string };
-}): string | undefined {
-  return payload?.traceId || payload?.platformMetadata?.traceId;
-}