@lobu/core 3.0.5 → 3.0.6

package/src/agent-store.ts

@@ -0,0 +1,220 @@
+/**
+ * AgentStore — unified interface for agent configuration storage.
+ *
+ * Implementations:
+ *   - InMemoryAgentStore (default, populated from files or API)
+ *   - Host-provided store (embedded mode, e.g. PostgresAgentStore in Owletto)
+ */
+
+import type { PluginsConfig } from "./plugin-types";
+import type {
+  AuthProfile,
+  InstalledProvider,
+  McpServerConfig,
+  NetworkConfig,
+  NixConfig,
+  SkillsConfig,
+  ToolsConfig,
+} from "./types";
+
+// ── Agent Settings ──────────────────────────────────────────────────────────
+
+export interface AgentSettings {
+  model?: string;
+  modelSelection?: { mode: "auto" | "pinned"; pinnedModel?: string };
+  providerModelPreferences?: Record<string, string>;
+  networkConfig?: NetworkConfig;
+  nixConfig?: NixConfig;
+  mcpServers?: Record<string, McpServerConfig>;
+  mcpInstallNotified?: Record<string, number>;
+  soulMd?: string;
+  userMd?: string;
+  identityMd?: string;
+  skillsConfig?: SkillsConfig;
+  toolsConfig?: ToolsConfig;
+  pluginsConfig?: PluginsConfig;
+  authProfiles?: AuthProfile[];
+  installedProviders?: InstalledProvider[];
+  verboseLogging?: boolean;
+  templateAgentId?: string;
+  updatedAt: number;
+}
+
+// ── Agent Metadata ──────────────────────────────────────────────────────────
+
+export interface AgentMetadata {
+  agentId: string;
+  name: string;
+  description?: string;
+  owner: { platform: string; userId: string };
+  isWorkspaceAgent?: boolean;
+  workspaceId?: string;
+  parentConnectionId?: string;
+  createdAt: number;
+  lastUsedAt?: number;
+}
+
+// ── Connections ─────────────────────────────────────────────────────────────
+
+export interface ConnectionSettings {
+  allowFrom?: string[];
+  allowGroups?: boolean;
+  userConfigScopes?: string[];
+}
+
+export interface StoredConnection {
+  id: string;
+  platform: string;
+  templateAgentId?: string;
+  config: Record<string, any>;
+  settings: ConnectionSettings;
+  metadata: Record<string, any>;
+  status: "active" | "stopped" | "error";
+  errorMessage?: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ── Grants ──────────────────────────────────────────────────────────────────
+
+export interface Grant {
+  pattern: string;
+  expiresAt: number | null;
+  grantedAt: number;
+  denied?: boolean;
+}
+
+// ── Channel Bindings ────────────────────────────────────────────────────────
+
+export interface ChannelBinding {
+  agentId: string;
+  platform: string;
+  channelId: string;
+  teamId?: string;
+  createdAt: number;
+}
+
+// ── Sub-Store Interfaces ──────────────────────────────────────────────────
+
+/**
+ * Agent identity & configuration storage.
+ * Settings (model, skills, providers, etc.) + metadata (name, owner, etc.)
+ */
+export interface AgentConfigStore {
+  getSettings(agentId: string): Promise<AgentSettings | null>;
+  saveSettings(agentId: string, settings: AgentSettings): Promise<void>;
+  updateSettings(
+    agentId: string,
+    updates: Partial<AgentSettings>
+  ): Promise<void>;
+  deleteSettings(agentId: string): Promise<void>;
+  hasSettings(agentId: string): Promise<boolean>;
+
+  getMetadata(agentId: string): Promise<AgentMetadata | null>;
+  saveMetadata(agentId: string, metadata: AgentMetadata): Promise<void>;
+  updateMetadata(
+    agentId: string,
+    updates: Partial<AgentMetadata>
+  ): Promise<void>;
+  deleteMetadata(agentId: string): Promise<void>;
+  hasAgent(agentId: string): Promise<boolean>;
+  listAgents(): Promise<AgentMetadata[]>;
+  listSandboxes(connectionId: string): Promise<AgentMetadata[]>;
+}
+
+/**
+ * Find the first non-sandbox agent with installed providers configured.
+ * Used to pick a default template agent when creating ephemeral/API agents.
+ */
+export async function findTemplateAgentId(
+  store: Pick<AgentConfigStore, "listAgents" | "getSettings">
+): Promise<string | null> {
+  const agents = await store.listAgents();
+
+  for (const agent of agents) {
+    if (agent.parentConnectionId) continue;
+    const settings = await store.getSettings(agent.agentId);
+    if (settings?.installedProviders?.length) {
+      return agent.agentId;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Platform wiring storage.
+ * Connections (Telegram, Slack, etc.) + channel bindings.
+ */
+export interface AgentConnectionStore {
+  getConnection(connectionId: string): Promise<StoredConnection | null>;
+  listConnections(filter?: {
+    templateAgentId?: string;
+    platform?: string;
+  }): Promise<StoredConnection[]>;
+  saveConnection(connection: StoredConnection): Promise<void>;
+  updateConnection(
+    connectionId: string,
+    updates: Partial<StoredConnection>
+  ): Promise<void>;
+  deleteConnection(connectionId: string): Promise<void>;
+
+  getChannelBinding(
+    platform: string,
+    channelId: string,
+    teamId?: string
+  ): Promise<ChannelBinding | null>;
+  createChannelBinding(binding: ChannelBinding): Promise<void>;
+  deleteChannelBinding(
+    platform: string,
+    channelId: string,
+    teamId?: string
+  ): Promise<void>;
+  listChannelBindings(agentId: string): Promise<ChannelBinding[]>;
+  deleteAllChannelBindings(agentId: string): Promise<number>;
+}
+
+/**
+ * Permissions & ownership storage.
+ * Grants (skill/domain access) + user-agent associations.
+ */
+export interface AgentAccessStore {
+  grant(
+    agentId: string,
+    pattern: string,
+    expiresAt: number | null,
+    denied?: boolean
+  ): Promise<void>;
+  hasGrant(agentId: string, pattern: string): Promise<boolean>;
+  isDenied(agentId: string, pattern: string): Promise<boolean>;
+  listGrants(agentId: string): Promise<Grant[]>;
+  revokeGrant(agentId: string, pattern: string): Promise<void>;
+
+  addUserAgent(
+    platform: string,
+    userId: string,
+    agentId: string
+  ): Promise<void>;
+  removeUserAgent(
+    platform: string,
+    userId: string,
+    agentId: string
+  ): Promise<void>;
+  listUserAgents(platform: string, userId: string): Promise<string[]>;
+  ownsAgent(
+    platform: string,
+    userId: string,
+    agentId: string
+  ): Promise<boolean>;
+}
+
+// ── AgentStore (full intersection) ────────────────────────────────────────
+
+/**
+ * Full storage interface — intersection of all sub-stores.
+ * Implementations (InMemoryAgentStore, etc.) satisfy all 3.
+ * Hosts can provide individual sub-stores via GatewayOptions instead.
+ */
+export type AgentStore = AgentConfigStore &
+  AgentConnectionStore &
+  AgentAccessStore;

package/src/api-types.ts

@@ -0,0 +1,256 @@
+/**
+ * Agent Settings API response types.
+ * These mirror the gateway API response shapes used by UI consumers.
+ */
+
+import type { RegistryEntry } from "./types";
+
+export type { RegistryEntry };
+
+export interface ProviderInfo {
+  name: string;
+  authType: "oauth" | "device-code" | "api-key";
+  supportedAuthTypes: ("oauth" | "device-code" | "api-key")[];
+  apiKeyInstructions: string;
+  apiKeyPlaceholder: string;
+  capabilities: (
+    | "text"
+    | "image-generation"
+    | "speech-to-text"
+    | "text-to-speech"
+  )[];
+}
+
+export interface CatalogProvider {
+  id: string;
+  name: string;
+  iconUrl: string;
+  authType: "oauth" | "device-code" | "api-key";
+  supportedAuthTypes: ("oauth" | "device-code" | "api-key")[];
+  apiKeyInstructions: string;
+  apiKeyPlaceholder: string;
+  capabilities: (
+    | "text"
+    | "image-generation"
+    | "speech-to-text"
+    | "text-to-speech"
+  )[];
+}
+
+export interface ModelOption {
+  label: string;
+  value: string;
+}
+
+export type SettingsScope = "agent" | "sandbox";
+export type SettingsSource = "local" | "inherited" | "mixed";
+export type SettingsSectionKey =
+  | "model"
+  | "system-prompt"
+  | "skills"
+  | "packages"
+  | "permissions"
+  | "schedules"
+  | "logging";
+
+export interface SectionView {
+  source: SettingsSource;
+  editable: boolean;
+  canReset: boolean;
+  hasLocalOverride: boolean;
+}
+
+export interface ProviderView {
+  id: string;
+  source: SettingsSource;
+  canEdit: boolean;
+  canReset: boolean;
+  hasLocalOverride: boolean;
+}
+
+export interface ModelSelectionState {
+  mode: "auto" | "pinned";
+  pinnedModel?: string;
+}
+
+export interface SkillMcpServerInfo {
+  id: string;
+  name?: string;
+  url?: string;
+  type?: "sse" | "stdio";
+  command?: string;
+  args?: string[];
+}
+
+export interface Skill {
+  repo: string;
+  name: string;
+  description: string;
+  enabled: boolean;
+  system?: boolean;
+  content?: string;
+  contentFetchedAt?: number;
+  mcpServers?: SkillMcpServerInfo[];
+  nixPackages?: string[];
+  permissions?: string[];
+  providers?: string[];
+  modelPreference?: string;
+  thinkingLevel?: string;
+}
+
+export interface McpConfig {
+  enabled?: boolean;
+  url?: string;
+  command?: string;
+  args?: string[];
+  type?: string;
+  description?: string;
+}
+
+export interface Schedule {
+  scheduleId: string;
+  task: string;
+  scheduledFor: string;
+  status: "pending" | "triggered" | "cancelled";
+  isRecurring?: boolean;
+  cron?: string;
+  iteration?: number;
+  maxIterations?: number;
+}
+
+export interface PrefillSkill {
+  repo: string;
+  name?: string;
+  description?: string;
+}
+
+export interface PrefillMcp {
+  id: string;
+  name?: string;
+  url?: string;
+  type?: string;
+  command?: string;
+  args?: string[];
+  envVars?: string[];
+}
+
+export interface ProviderState {
+  status: string;
+  connected: boolean;
+  userConnected: boolean;
+  systemConnected: boolean;
+  showAuthFlow: boolean;
+  showCodeInput: boolean;
+  showDeviceCode: boolean;
+  showApiKeyInput: boolean;
+  activeAuthTab: string;
+  activeAuthType?: string | null;
+  authMethods?: string[];
+  code: string;
+  apiKey: string;
+  userCode: string;
+  verificationUrl: string;
+  pollStatus: string;
+  deviceAuthId: string;
+  selectedModel: string;
+  modelQuery: string;
+  showModelDropdown: boolean;
+}
+
+export interface PermissionGrant {
+  pattern: string;
+  expiresAt: number | null;
+  denied?: boolean;
+  grantedAt?: number;
+}
+
+export interface AgentInfo {
+  agentId: string;
+  name: string;
+  isWorkspaceAgent?: boolean;
+  channelCount: number;
+  description?: string;
+}
+
+export interface SettingsSnapshot {
+  identityMd: string;
+  soulMd: string;
+  userMd: string;
+  verboseLogging: boolean;
+  primaryProvider: string;
+  providerOrder: string;
+  nixPackages: string;
+  skills: string;
+  mcpServers: string;
+  permissions: string;
+  providerModelPreferences: string;
+  registries: string;
+}
+
+export interface Connection {
+  id: string;
+  platform: string;
+  templateAgentId?: string;
+  config: Record<string, unknown>;
+  settings: {
+    allowFrom?: string[];
+    allowGroups?: boolean;
+    userConfigScopes?: string[];
+  };
+  metadata: Record<string, unknown>;
+  status: "active" | "stopped" | "error";
+  errorMessage?: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface ProviderStatus {
+  connected: boolean;
+  userConnected: boolean;
+  systemConnected: boolean;
+  activeAuthType?: "oauth" | "device-code" | "api-key";
+  authMethods?: string[];
+}
+
+export interface AgentConfigResponse {
+  agentId: string;
+  scope: SettingsScope;
+  templateAgentId?: string;
+  templateAgentName?: string;
+  sections: Record<SettingsSectionKey, SectionView>;
+  providerViews: Record<string, ProviderView>;
+
+  instructions: {
+    identity: string;
+    soul: string;
+    user: string;
+  };
+
+  providers: {
+    order: string[];
+    status: Record<string, ProviderStatus>;
+    catalog: CatalogProvider[];
+    meta: Record<string, ProviderInfo>;
+    models: Record<string, ModelOption[]>;
+    preferences: Record<string, string>;
+    icons: Record<string, string>;
+    modelSelection: ModelSelectionState;
+    configManaged: string[];
+  };
+
+  skills: Skill[];
+  mcpServers: Record<string, McpConfig>;
+
+  tools: {
+    nixPackages: string[];
+    permissions: PermissionGrant[];
+    schedules: Schedule[];
+    registries: RegistryEntry[];
+    globalRegistries: RegistryEntry[];
+  };
+
+  settings: {
+    verboseLogging: boolean;
+    memoryEnabled: boolean;
+  };
+}

package/src/command-registry.ts

@@ -0,0 +1,73 @@
+import { createLogger } from "./logger";
+
+const logger = createLogger("command-registry");
+
+/**
+ * Context passed to command handlers.
+ * Shaped to match OpenClaw's registerCommand() API for future migration.
+ */
+export interface CommandContext {
+  userId: string;
+  channelId: string;
+  conversationId?: string;
+  connectionId?: string;
+  agentId?: string;
+  args: string;
+  reply: (
+    text: string,
+    options?: { url?: string; urlLabel?: string; webApp?: boolean }
+  ) => Promise<void>;
+  platform: string;
+}
+
+/**
+ * A registered command definition.
+ */
+export interface CommandDefinition {
+  name: string;
+  description: string;
+  handler: (ctx: CommandContext) => Promise<void>;
+}
+
+/**
+ * Shared command registry used by all platform adapters.
+ * Matches OpenClaw's registerCommand() shape so migration is a simple swap.
+ */
+export class CommandRegistry {
+  private commands = new Map<string, CommandDefinition>();
+
+  register(cmd: CommandDefinition): void {
+    this.commands.set(cmd.name, cmd);
+    logger.debug({ command: cmd.name }, "Command registered");
+  }
+
+  get(name: string): CommandDefinition | undefined {
+    return this.commands.get(name);
+  }
+
+  getAll(): CommandDefinition[] {
+    return Array.from(this.commands.values());
+  }
+
+  /**
+   * Try to handle a command by name. Returns true if handled.
+   */
+  async tryHandle(name: string, ctx: CommandContext): Promise<boolean> {
+    const cmd = this.commands.get(name);
+    if (!cmd) return false;
+
+    try {
+      await cmd.handler(ctx);
+      return true;
+    } catch (error) {
+      logger.error(
+        { command: name, error: String(error) },
+        "Command handler failed"
+      );
+      await ctx.reply(
+        "Sorry, something went wrong executing that command. Please try again."
+      );
+      return true;
+    }
+  }
+}

package/src/constants.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env bun
+
+/**
+ * Shared constants across all packages
+ * These are platform-agnostic and used by core, gateway, and platform adapters
+ */
+
+// Time constants (milliseconds)
+export const TIME = {
+  /** One hour in milliseconds */
+  HOUR_MS: 60 * 60 * 1000,
+  /** One day in milliseconds */
+  DAY_MS: 24 * 60 * 60 * 1000,
+  /** One hour in seconds */
+  HOUR_SECONDS: 3600,
+  /** One day in seconds */
+  DAY_SECONDS: 24 * 60 * 60,
+  /** One minute in milliseconds */
+  MINUTE_MS: 60 * 1000,
+  /** Five seconds in milliseconds */
+  FIVE_SECONDS_MS: 5000,
+  /** Thirty seconds */
+  THIRTY_SECONDS: 30,
+  /** Three hours in milliseconds (for interaction timeout) */
+  THREE_HOURS_MS: 3 * 60 * 60 * 1000,
+  /** Three hours in seconds (for Redis TTL) */
+  THREE_HOURS_SECONDS: 3 * 60 * 60,
+} as const;
+
+// Redis key prefixes
+export const REDIS_KEYS = {
+  /** Prefix for bot message timestamps */
+  BOT_MESSAGES: "bot_messages:",
+  /** Prefix for session data */
+  SESSION: "session:",
+  /** Prefix for thread ownership */
+  THREAD_OWNER: "thread_owner:",
+  /** Prefix for MCP credentials */
+  MCP_CREDENTIAL: "mcp:credential:",
+  /** Prefix for MCP OAuth state */
+  MCP_OAUTH_STATE: "mcp:oauth:state:",
+  /** Prefix for MCP inputs */
+  MCP_INPUT: "mcp:input:",
+} as const;
+
+// Default configuration values
+export const DEFAULTS = {
+  /** Default session TTL in milliseconds */
+  SESSION_TTL_MS: TIME.DAY_MS,
+  /** Default session TTL in seconds */
+  SESSION_TTL_SECONDS: TIME.DAY_SECONDS,
+  /** Default queue expiration in hours */
+  QUEUE_EXPIRE_HOURS: 24,
+  /** Default retry limit for queue operations */
+  QUEUE_RETRY_LIMIT: 3,
+  /** Default retry delay in seconds */
+  QUEUE_RETRY_DELAY_SECONDS: TIME.THIRTY_SECONDS,
+  /** Default session timeout in minutes */
+  SESSION_TIMEOUT_MINUTES: 5,
+} as const;