@lobu/core 3.0.5 → 3.0.6

package/src/modules.ts

@@ -0,0 +1,184 @@
+import { createLogger } from "./logger";
+
+const logger = createLogger("modules");
+
+// ============================================================================
+// Module Type Definitions
+// ============================================================================
+
+export interface ModuleInterface<_TModuleData = unknown> {
+  /** Module identifier */
+  name: string;
+
+  /** Check if module should be enabled based on environment */
+  isEnabled(): boolean;
+
+  /** Initialize module - called once at startup */
+  init(): Promise<void>;
+
+  /** Register HTTP endpoints with Express app */
+  registerEndpoints(app: any): void;
+}
+
+export interface WorkerContext {
+  workspaceDir: string;
+  userId: string;
+  conversationId: string;
+}
+
+export interface WorkerModule<TModuleData = unknown>
+  extends ModuleInterface<TModuleData> {
+  /** Initialize workspace - called when worker starts session */
+  initWorkspace(config: any): Promise<void>;
+
+  /** Called at session start - can modify system prompt */
+  onSessionStart(context: ModuleSessionContext): Promise<ModuleSessionContext>;
+
+  /** Called at session end - can add action buttons */
+  onSessionEnd(context: ModuleSessionContext): Promise<ActionButton[]>;
+
+  /** Collect module-specific data before sending response. Return null if no data. */
+  onBeforeResponse(context: WorkerContext): Promise<TModuleData | null>;
+}
+
+export interface ModuleSessionContext {
+  userId: string;
+  conversationId: string;
+  systemPrompt: string;
+  workspace?: any;
+}
+
+export interface ActionButton {
+  text: string;
+  action_id: string;
+  style?: "primary" | "danger";
+  value?: string;
+  url?: string;
+}
+
+// ============================================================================
+// Module Registry
+// ============================================================================
+
+export interface IModuleRegistry {
+  register(module: ModuleInterface): void;
+  getWorkerModules(): WorkerModule[];
+  registerAvailableModules(modulePackages?: string[]): Promise<void>;
+  initAll(): Promise<void>;
+  registerEndpoints(app: any): void;
+  /** Return all registered modules as base ModuleInterface array. */
+  getModules(): ModuleInterface[];
+}
+
+/**
+ * Module registry for managing plugin modules across the application.
+ *
+ * Modules must be explicitly registered by calling `register()` before use.
+ * This allows each package (dispatcher, worker) to load only the modules it needs.
+ *
+ * For production: use the global `moduleRegistry` instance
+ * For testing: create a new instance to avoid shared state
+ *
+ * @example
+ * // In gateway/worker
+ * import { MyModule } from './my-module';
+ * moduleRegistry.register(new MyModule());
+ * await moduleRegistry.initAll();
+ *
+ * @example
+ * // In tests
+ * const testRegistry = new ModuleRegistry();
+ * testRegistry.register(mockModule);
+ */
+export class ModuleRegistry implements IModuleRegistry {
+  private modules: Map<string, ModuleInterface> = new Map();
+
+  register(module: ModuleInterface): void {
+    if (module.isEnabled()) {
+      this.modules.set(module.name, module);
+    }
+  }
+
+  /**
+   * Automatically discover and register available modules.
+   * Tries to import module packages and registers them if available.
+   *
+   * @param modulePackages - List of module package names to try loading.
+   *                         Users can provide custom modules to register.
+   *
+   * @example
+   * // Register custom modules
+   * await moduleRegistry.registerAvailableModules([
+   *   '@mycompany/slack-module',
+   *   '@mycompany/jira-module'
+   * ]);
+   */
+  async registerAvailableModules(modulePackages: string[] = []): Promise<void> {
+    for (const packageName of modulePackages) {
+      try {
+        // Dynamic import to avoid build-time dependencies
+        const moduleExports = await import(packageName);
+
+        // Try common export patterns
+        const ModuleClass =
+          moduleExports.default ||
+          Object.values(moduleExports).find(
+            (exp) => typeof exp === "function" && exp.name.endsWith("Module")
+          );
+
+        if (ModuleClass && typeof ModuleClass === "function") {
+          const moduleInstance = new (ModuleClass as any)();
+          if (!this.modules.has(moduleInstance.name)) {
+            this.register(moduleInstance);
+            logger.debug(`${packageName} registered`);
+          }
+        } else {
+          logger.debug(`${packageName}: No module class found in exports`);
+        }
+      } catch {
+        logger.debug(`${packageName} not available`);
+      }
+    }
+  }
+
+  async initAll(): Promise<void> {
+    for (const module of this.modules.values()) {
+      if (module.init) {
+        logger.debug(`Initializing module: ${module.name}`);
+        await module.init();
+        logger.debug(`Module ${module.name} initialized`);
+      }
+    }
+  }
+
+  registerEndpoints(app: any): void {
+    for (const module of this.modules.values()) {
+      if (module.registerEndpoints) {
+        try {
+          module.registerEndpoints(app);
+        } catch (error) {
+          logger.error(
+            `Failed to register endpoints for module ${module.name}:`,
+            error
+          );
+        }
+      }
+    }
+  }
+
+  getWorkerModules(): WorkerModule[] {
+    return Array.from(this.modules.values()).filter(
+      (m): m is WorkerModule => "onBeforeResponse" in m
+    );
+  }
+
+  getModules(): ModuleInterface[] {
+    return Array.from(this.modules.values());
+  }
+}
+
+/**
+ * Global registry instance for production use.
+ * For testing, create separate instances: `new ModuleRegistry()`
+ */
+export const moduleRegistry = new ModuleRegistry();

package/src/otel.ts

@@ -0,0 +1,306 @@
+/**
+ * OpenTelemetry tracing setup for distributed tracing with Grafana Tempo.
+ * Provides Chrome DevTools-style waterfall visualization in Grafana.
+ */
+
+import type { Span, Tracer } from "@opentelemetry/api";
+import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+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;
+  tempoEndpoint?: string; // e.g., "http://tempo:4318/v1/traces"
+  enabled?: boolean;
+}
+
+/**
+ * Initialize OpenTelemetry tracing.
+ * Call this once at application startup.
+ *
+ * @example
+ * initTracing({
+ *   serviceName: "lobu-gateway",
+ *   tempoEndpoint: "http://lobu-tempo:4318/v1/traces",
+ * });
+ */
+export function initTracing(config: OtelConfig): void {
+  if (provider) {
+    return; // Already initialized
+  }
+
+  const enabled = config.enabled ?? !!config.tempoEndpoint;
+  if (!enabled) {
+    logger.debug("Tracing disabled (no TEMPO_ENDPOINT configured)");
+    return;
+  }
+
+  const resource = new Resource({
+    [ATTR_SERVICE_NAME]: config.serviceName,
+    [ATTR_SERVICE_VERSION]: config.serviceVersion || "1.0.0",
+  });
+
+  provider = new NodeTracerProvider({ resource });
+
+  // Configure OTLP exporter to send traces to Tempo
+  const exporter = new OTLPTraceExporter({
+    url: config.tempoEndpoint,
+    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.tempoEndpoint}`
+  );
+}
+
+/**
+ * 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`;
+}
+
+// Re-export OpenTelemetry types for convenience
+export { SpanKind, SpanStatusCode };
+export type { Span, Tracer };

package/src/plugin-types.ts

@@ -0,0 +1,46 @@
+/**
+ * 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

@@ -0,0 +1,54 @@
+/**
+ * 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;
+}