@lobu/core 3.0.5 → 3.0.7

package/src/errors.ts

@@ -0,0 +1,220 @@
+/**
+ * Base error class for all lobu errors
+ */
+export abstract class BaseError extends Error {
+  abstract readonly name: string;
+  public operation?: string;
+
+  constructor(
+    message: string,
+    public cause?: Error
+  ) {
+    super(message);
+
+    // Maintain proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  /**
+   * Get the full error chain as a string
+   */
+  getFullMessage(): string {
+    let message = `${this.name}: ${this.message}`;
+    if (this.cause) {
+      if (this.cause instanceof BaseError) {
+        message += `\nCaused by: ${this.cause.getFullMessage()}`;
+      } else {
+        message += `\nCaused by: ${this.cause.message}`;
+      }
+    }
+    return message;
+  }
+
+  /**
+   * Convert error to JSON for logging/serialization
+   */
+  toJSON(): Record<string, any> {
+    return {
+      name: this.name,
+      message: this.message,
+      ...(this.operation && { operation: this.operation }),
+      cause:
+        this.cause instanceof BaseError
+          ? this.cause.toJSON()
+          : this.cause?.message,
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * Error class for worker-related operations
+ */
+export class WorkerError extends BaseError {
+  override readonly name = "WorkerError";
+
+  constructor(operation: string, message: string, cause?: Error) {
+    super(message, cause);
+    this.operation = operation;
+  }
+}
+
+/**
+ * Error class for workspace-related operations
+ */
+export class WorkspaceError extends BaseError {
+  override readonly name = "WorkspaceError";
+
+  constructor(operation: string, message: string, cause?: Error) {
+    super(message, cause);
+    this.operation = operation;
+  }
+}
+
+/**
+ * Error class for platform-related operations (Slack, WhatsApp, etc.)
+ */
+export class PlatformError extends BaseError {
+  override readonly name = "PlatformError";
+
+  constructor(
+    public platform: string,
+    operation: string,
+    message: string,
+    cause?: Error
+  ) {
+    super(message, cause);
+    this.operation = operation;
+  }
+
+  override toJSON(): Record<string, any> {
+    return {
+      ...super.toJSON(),
+      platform: this.platform,
+    };
+  }
+}
+
+/**
+ * Error class for session-related operations
+ */
+export class SessionError extends BaseError {
+  readonly name = "SessionError";
+
+  constructor(
+    public sessionKey: string,
+    public code: string,
+    message: string,
+    cause?: Error
+  ) {
+    super(message, cause);
+  }
+
+  toJSON(): Record<string, any> {
+    return {
+      ...super.toJSON(),
+      sessionKey: this.sessionKey,
+      code: this.code,
+    };
+  }
+}
+
+/**
+ * Worker error variant with workerId for core operations
+ */
+export class CoreWorkerError extends WorkerError {
+  constructor(
+    public workerId: string,
+    operation: string,
+    message: string,
+    cause?: Error
+  ) {
+    super(operation, message, cause);
+  }
+
+  override toJSON(): Record<string, any> {
+    return {
+      ...super.toJSON(),
+      workerId: this.workerId,
+    };
+  }
+}
+
+/**
+ * Error class for dispatcher-related operations
+ */
+export class DispatcherError extends BaseError {
+  override readonly name = "DispatcherError";
+
+  constructor(operation: string, message: string, cause?: Error) {
+    super(message, cause);
+    this.operation = operation;
+  }
+}
+
+// ErrorCode enum for orchestration operations
+export enum ErrorCode {
+  DATABASE_CONNECTION_FAILED = "DATABASE_CONNECTION_FAILED",
+  KUBERNETES_API_ERROR = "KUBERNETES_API_ERROR",
+  DEPLOYMENT_SCALE_FAILED = "DEPLOYMENT_SCALE_FAILED",
+  DEPLOYMENT_CREATE_FAILED = "DEPLOYMENT_CREATE_FAILED",
+  DEPLOYMENT_DELETE_FAILED = "DEPLOYMENT_DELETE_FAILED",
+  QUEUE_JOB_PROCESSING_FAILED = "QUEUE_JOB_PROCESSING_FAILED",
+  USER_CREDENTIALS_CREATE_FAILED = "USER_CREDENTIALS_CREATE_FAILED",
+  INVALID_CONFIGURATION = "INVALID_CONFIGURATION",
+  THREAD_DEPLOYMENT_NOT_FOUND = "THREAD_DEPLOYMENT_NOT_FOUND",
+  USER_QUEUE_NOT_FOUND = "USER_QUEUE_NOT_FOUND",
+}
+
+/**
+ * Error class for orchestrator-related operations
+ */
+export class OrchestratorError extends BaseError {
+  readonly name = "OrchestratorError";
+
+  constructor(
+    public code: ErrorCode,
+    message: string,
+    public details?: any,
+    public shouldRetry: boolean = false,
+    cause?: Error
+  ) {
+    super(message, cause);
+  }
+
+  static fromDatabaseError(error: any): OrchestratorError {
+    return new OrchestratorError(
+      ErrorCode.DATABASE_CONNECTION_FAILED,
+      `Database error: ${error instanceof Error ? error.message : String(error)}`,
+      { code: error.code, detail: error.detail },
+      true,
+      error
+    );
+  }
+
+  static fromKubernetesError(error: any): OrchestratorError {
+    return new OrchestratorError(
+      ErrorCode.KUBERNETES_API_ERROR,
+      `Kubernetes operation failed: ${error.message}`,
+      error,
+      true,
+      error
+    );
+  }
+
+  toJSON(): Record<string, any> {
+    return {
+      ...super.toJSON(),
+      code: this.code,
+      details: this.details,
+      shouldRetry: this.shouldRetry,
+    };
+  }
+}
+
+/**
+ * Error class for configuration-related operations
+ */
+export class ConfigError extends BaseError {
+  readonly name = "ConfigError";
+}

package/src/index.ts

@@ -0,0 +1,131 @@
+#!/usr/bin/env bun
+
+// Shared exports for @lobu/core consumers (gateway, worker, external tools)
+
+export * from "./agent-policy";
+// Agent store interface (unified storage abstraction)
+export type {
+  AgentAccessStore,
+  AgentConfigStore,
+  AgentConnectionStore,
+  AgentMetadata,
+  AgentSettings,
+  AgentStore,
+  ChannelBinding,
+  ConnectionSettings,
+  Grant,
+  StoredConnection,
+} from "./agent-store";
+export { findTemplateAgentId } from "./agent-store";
+export type { CommandContext, CommandDefinition } from "./command-registry";
+// Command registry
+export { CommandRegistry } from "./command-registry";
+export * from "./constants";
+// Errors & logging
+export * from "./errors";
+// Integration types
+export type {
+  SystemSkillEntry,
+  SystemSkillsConfigFile,
+} from "./integration-types";
+export * from "./logger";
+// Module system
+export type { ActionButton, ModuleSessionContext } from "./modules";
+export * from "./modules";
+export type { OtelConfig, Span, Tracer } from "./otel";
+// OpenTelemetry tracing (Tempo integration)
+export {
+  createChildSpan,
+  createRootSpan,
+  createSpan,
+  flushTracing,
+  getCurrentSpan,
+  getTraceparent,
+  getTracer,
+  initTracing,
+  runInSpanContext,
+  SpanKind,
+  SpanStatusCode,
+  shutdownTracing,
+  withChildSpan,
+  withSpan,
+} from "./otel";
+// Plugin types
+export type {
+  PluginConfig,
+  PluginManifest,
+  PluginSlot,
+  PluginsConfig,
+  ProviderRegistration,
+} from "./plugin-types";
+// Config-driven provider types
+export type {
+  ConfigProviderMeta,
+  ProviderConfigEntry,
+} from "./provider-config-types";
+// Redis & worker helpers
+export * from "./redis/base-store";
+// Observability
+export { getSentry, initSentry } from "./sentry";
+export { extractTraceId, generateTraceId } from "./trace";
+// Core types
+export type {
+  AgentMcpConfig,
+  AgentOptions,
+  AuthProfile,
+  CliBackendConfig,
+  ConversationMessage,
+  HistoryMessage,
+  InstalledProvider,
+  InstructionContext,
+  InstructionProvider,
+  LogLevel,
+  McpServerConfig,
+  NetworkConfig,
+  NixConfig,
+  RegistryEntry,
+  SessionContext,
+  SkillConfig,
+  SkillMcpServer,
+  SkillsConfig,
+  SuggestedPrompt,
+  ThinkingLevel,
+  ThreadResponsePayload,
+  ToolsConfig,
+  UserSuggestion,
+} from "./types";
+
+// Agent Settings API response types (for UI consumers)
+export type {
+  AgentConfigResponse,
+  AgentInfo,
+  CatalogProvider,
+  Connection,
+  McpConfig,
+  ModelOption,
+  ModelSelectionState,
+  PermissionGrant,
+  PrefillMcp,
+  PrefillSkill,
+  ProviderInfo,
+  ProviderState,
+  ProviderStatus,
+  Schedule,
+  SettingsSnapshot,
+  Skill,
+  SkillMcpServerInfo,
+} from "./api-types";
+
+// Utilities
+export * from "./utils/encryption";
+export * from "./utils/env";
+export * from "./utils/json";
+export * from "./utils/lock";
+export type { McpToolDef } from "./utils/mcp-tool-instructions";
+export * from "./utils/retry";
+export * from "./utils/sanitize";
+export * from "./worker/auth";
+export type {
+  WorkerTransport,
+  WorkerTransportConfig,
+} from "./worker/transport";

package/src/integration-types.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared types for the integration system.
+ *
+ * OAuth credential management for third-party APIs (GitHub, Google, etc.)
+ * is handled by Owletto.
+ */
+
+import type { ProviderConfigEntry } from "./provider-config-types";
+
+// System Skills Config (config/system-skills.json)
+
+export interface SystemSkillEntry {
+  id: string;
+  name: string;
+  description?: string;
+  instructions?: string;
+  hidden?: boolean;
+  mcpServers?: import("./types").SkillMcpServer[];
+  providers?: ProviderConfigEntry[];
+  nixPackages?: string[];
+  permissions?: string[];
+}
+
+export interface SystemSkillsConfigFile {
+  skills: SystemSkillEntry[];
+}

package/src/logger.ts

@@ -0,0 +1,248 @@
+// Use simple console.log-based logger by default (unbuffered, 12-factor compliant)
+// Set USE_WINSTON_LOGGER=true only if you need Winston features (file rotation, multiple transports)
+const USE_WINSTON_LOGGER = process.env.USE_WINSTON_LOGGER === "true";
+// Use JSON format for structured logging (better for Loki parsing in production)
+const USE_JSON_FORMAT = process.env.LOG_FORMAT === "json";
+
+import winston from "winston";
+import { getSentry } from "./sentry";
+
+export interface Logger {
+  error: (message: any, ...args: any[]) => void;
+  warn: (message: any, ...args: any[]) => void;
+  info: (message: any, ...args: any[]) => void;
+  debug: (message: any, ...args: any[]) => void;
+}
+
+// Simple console logger fallback for environments where Winston doesn't work (Bun + Alpine)
+// Supports both formats: logger.info("message", data) AND pino-style logger.info({ data }, "message")
+function createConsoleLogger(serviceName: string): Logger {
+  const level = process.env.LOG_LEVEL || "info";
+  const levels: Record<string, number> = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    debug: 3,
+  };
+  const currentLevel = levels[level] ?? 2;
+
+  const formatMessage = (lvl: string, message: any, ...args: any[]): string => {
+    const timestamp = new Date().toISOString().replace("T", " ").slice(0, 19);
+    let msgStr: string;
+    let meta: any = null;
+
+    // Handle pino-style format: logger.info({ key: value }, "message")
+    if (
+      typeof message === "object" &&
+      message !== null &&
+      !Array.isArray(message) &&
+      !(message instanceof Error)
+    ) {
+      if (args.length > 0 && typeof args[0] === "string") {
+        // First arg is metadata object, second arg is the actual message
+        msgStr = args[0];
+        meta = message;
+        args = args.slice(1);
+      } else {
+        // Just an object, stringify it
+        try {
+          msgStr = JSON.stringify(message);
+        } catch {
+          msgStr = "[object]";
+        }
+      }
+    } else {
+      msgStr = String(message);
+    }
+
+    // Append remaining args
+    if (args.length > 0) {
+      try {
+        msgStr += ` ${JSON.stringify(args.length === 1 ? args[0] : args)}`;
+      } catch {
+        msgStr += " [unserializable]";
+      }
+    }
+
+    // Append metadata object
+    if (meta) {
+      try {
+        msgStr += ` ${JSON.stringify(meta)}`;
+      } catch {
+        msgStr += " [meta unserializable]";
+      }
+    }
+
+    return `[${timestamp}] [${lvl}] [${serviceName}] ${msgStr}`;
+  };
+
+  return {
+    error: (message: any, ...args: any[]) => {
+      if (currentLevel >= 0)
+        console.error(formatMessage("error", message, ...args));
+    },
+    warn: (message: any, ...args: any[]) => {
+      if (currentLevel >= 1)
+        console.warn(formatMessage("warn", message, ...args));
+    },
+    info: (message: any, ...args: any[]) => {
+      if (currentLevel >= 2)
+        console.log(formatMessage("info", message, ...args));
+    },
+    debug: (message: any, ...args: any[]) => {
+      if (currentLevel >= 3)
+        console.log(formatMessage("debug", message, ...args));
+    },
+  };
+}
+
+/**
+ * Custom Winston transport that sends errors to Sentry
+ */
+class SentryTransport extends winston.transports.Stream {
+  constructor() {
+    super({ stream: process.stdout });
+  }
+
+  log(info: any, callback: () => void) {
+    setImmediate(() => {
+      this.emit("logged", info);
+    });
+
+    // Only send errors and warnings to Sentry
+    if (info.level === "error" || info.level === "warn") {
+      const Sentry = getSentry();
+      if (Sentry) {
+        try {
+          // Extract error object if present
+          const errorObj =
+            info.error || (info.message instanceof Error ? info.message : null);
+
+          if (errorObj instanceof Error) {
+            Sentry.captureException(errorObj, {
+              level: info.level === "error" ? "error" : "warning",
+              tags: {
+                service: info.service,
+              },
+              extra: {
+                ...info,
+                message: info.message,
+              },
+            });
+          } else {
+            // Send as message if no Error object
+            Sentry.captureMessage(String(info.message), {
+              level: info.level === "error" ? "error" : "warning",
+              tags: {
+                service: info.service,
+              },
+              extra: info,
+            });
+          }
+        } catch (_err) {
+          // Ignore Sentry errors to avoid breaking logging
+        }
+      }
+    }
+
+    callback();
+  }
+}
+
+/**
+ * Creates a logger instance for a specific service
+ * Provides consistent logging format across all packages with level and timestamp
+ * @param serviceName The name of the service using the logger
+ * @returns A console logger by default, or Winston logger if USE_WINSTON_LOGGER=true
+ */
+export function createLogger(serviceName: string): Logger {
+  // Use simple console.log logger by default (unbuffered, 12-factor compliant)
+  // Set USE_WINSTON_LOGGER=true for Winston features (file rotation, multiple transports)
+  if (!USE_WINSTON_LOGGER) {
+    return createConsoleLogger(serviceName);
+  }
+
+  const isProduction = process.env.NODE_ENV === "production";
+  const level = process.env.LOG_LEVEL || "info";
+
+  // JSON format for structured logging (better for Loki/Grafana parsing)
+  const jsonFormat = winston.format.combine(
+    winston.format.timestamp({ format: "YYYY-MM-DDTHH:mm:ss.SSSZ" }),
+    winston.format.json()
+  );
+
+  // Human-readable format for development
+  const humanFormat = winston.format.combine(
+    ...(isProduction ? [] : [winston.format.colorize()]),
+    winston.format.printf(({ timestamp, level, message, service, ...meta }) => {
+      let metaStr = "";
+      if (Object.keys(meta).length) {
+        try {
+          metaStr = ` ${JSON.stringify(meta, null, 0)}`;
+        } catch (_err) {
+          // Handle circular structures with a safer approach
+          try {
+            const seen = new WeakSet();
+            metaStr = ` ${JSON.stringify(meta, (_key, value) => {
+              if (typeof value === "object" && value !== null) {
+                if (seen.has(value)) {
+                  return "[Circular Reference]";
+                }
+                seen.add(value);
+
+                if (value instanceof Error) {
+                  return {
+                    name: value.name,
+                    message: value.message,
+                    stack: value.stack?.split("\n")[0], // Only first line of stack
+                  };
+                }
+              }
+              return value;
+            })}`;
+          } catch (_err2) {
+            // Final fallback if even the circular handler fails
+            metaStr = " [Object too complex to serialize]";
+          }
+        }
+      }
+      return `[${timestamp}] [${level}] [${service}] ${message}${metaStr}`;
+    })
+  );
+
+  const transports: winston.transport[] = [
+    new winston.transports.Console({
+      format: USE_JSON_FORMAT ? jsonFormat : humanFormat,
+    }),
+  ];
+
+  const logger = winston.createLogger({
+    level,
+    format: winston.format.combine(
+      winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
+      winston.format.errors({ stack: true }),
+      winston.format.splat()
+    ),
+    defaultMeta: { service: serviceName },
+    transports,
+  });
+
+  // Add Sentry transport in production or if SENTRY_DSN is set
+  // Deferred to avoid circular dependency with sentry.ts
+  // The check is inside setImmediate to ensure SentryTransport class is fully initialized
+  setImmediate(() => {
+    if (isProduction || process.env.SENTRY_DSN) {
+      try {
+        const transport = new SentryTransport();
+        logger.add(transport);
+      } catch {
+        // Ignore errors during Sentry transport setup
+      }
+    }
+  });
+
+  return logger;
+}
+
+// Default logger instance for backward compatibility
+export const logger = createLogger("shared");