@lobu/core 3.0.10 → 3.0.12

package/src/types.ts

@@ -1,440 +0,0 @@
-// ============================================================================
-// Provider Catalog Types
-// ============================================================================
-
-/**
- * Represents a provider installed for a specific agent.
- * Stored in AgentSettings.installedProviders as an ordered array (index 0 = primary).
- */
-export interface InstalledProvider {
-  providerId: string; // "claude", "chatgpt", "gemini", "z-ai"
-  installedAt: number;
-  config?: {
-    baseUrl?: string; // override upstream (e.g. z.ai proxy)
-    [key: string]: unknown;
-  };
-}
-
-/**
- * CLI backend configuration for pi-agent integration.
- * Providers can ship CLI tools that pi-agent invokes as backends.
- */
-export interface CliBackendConfig {
-  name: string; // "claude-code", "codex"
-  command: string; // "/usr/local/bin/claude"
-  args?: string[];
-  env?: Record<string, string>;
-  modelArg?: string; // "--model"
-  sessionArg?: string; // "--session"
-}
-
-// ============================================================================
-// Auth Profile Types
-// ============================================================================
-
-/**
- * Unified authentication profile for any model provider.
- * Stored in AgentSettings.authProfiles as an ordered array (index 0 = primary).
- */
-export interface AuthProfile {
-  id: string; // UUID
-  provider: string; // "anthropic", "openai-codex", "gemini", "nvidia"
-  model: string; // Full model ref: "openai-codex/gpt-5.2-codex"
-  credential: string; // API key or OAuth access token
-  label: string; // "user@gmail.com", "sk-ant-...1234"
-  authType: "oauth" | "device-code" | "api-key";
-  metadata?: {
-    email?: string;
-    expiresAt?: number;
-    refreshToken?: string;
-    accountId?: string;
-  };
-  createdAt: number;
-}
-
-export interface SessionContext {
-  // Core identifiers
-  platform: string; // Platform identifier (e.g., "slack", "discord", "teams")
-  channelId: string;
-  userId: string;
-  messageId: string; // Required - always needed for tracking
-
-  // Optional context
-  conversationId?: string;
-  teamId?: string; // Platform workspace/team identifier
-  userDisplayName?: string; // For logging/display purposes
-  workingDirectory?: string;
-  customInstructions?: string;
-  conversationHistory?: ConversationMessage[];
-}
-
-export interface ConversationMessage {
-  role: "system" | "user" | "assistant";
-  content: string;
-  timestamp: number;
-}
-
-// ============================================================================
-// Conversation History Types
-// ============================================================================
-
-// ============================================================================
-// Skills Configuration Types
-// ============================================================================
-
-/**
- * Per-skill thinking budget level.
- * Controls how much reasoning the model applies when executing a skill.
- */
-export type ThinkingLevel = "off" | "low" | "medium" | "high";
-
-/**
- * MCP server declared by a skill manifest.
- */
-export interface McpOAuthConfig {
-  /** Authorization endpoint (user verification page for device-code flow). */
-  authUrl?: string;
-  /** Token endpoint. Falls back to `{origin}/oauth/token`. */
-  tokenUrl?: string;
-  /** Pre-registered client ID. When provided, dynamic client registration is skipped. */
-  clientId?: string;
-  /** Client secret for confidential clients. */
-  clientSecret?: string;
-  /** OAuth scopes. Falls back to `mcp:read mcp:write profile:read`. */
-  scopes?: string[];
-  /** Device authorization endpoint. Falls back to `{origin}/oauth/device_authorization`. */
-  deviceAuthorizationUrl?: string;
-  /** Dynamic client registration endpoint. Falls back to `{origin}/oauth/register`. */
-  registrationUrl?: string;
-  /** RFC 8707 resource indicator included in token requests. */
-  resource?: string;
-}
-
-export interface SkillMcpServer {
-  id: string;
-  name?: string;
-  url?: string;
-  type?: "sse" | "stdio";
-  command?: string;
-  args?: string[];
-  oauth?: McpOAuthConfig;
-  inputs?: Array<{ id: string; label?: string; type?: string }>;
-  headers?: Record<string, string>;
-}
-
-/**
- * Individual skill configuration.
- * Skills are SKILL.md files from GitHub repos that provide instructions to Claude.
- */
-export interface SkillConfig {
-  /** Skill repository in owner/repo format (e.g., "anthropics/skills/pdf") */
-  repo: string;
-  /** Skill name derived from SKILL.md frontmatter or folder name */
-  name: string;
-  /** Optional description from SKILL.md frontmatter */
-  description?: string;
-  /** Short always-inlined instruction block for critical rules */
-  instructions?: string;
-  /** Whether this skill is currently enabled */
-  enabled: boolean;
-  /** True for system-defined skills (from system-skills.json). Cannot be removed by users. */
-  system?: boolean;
-  /** Cached SKILL.md content (fetched from GitHub) */
-  content?: string;
-  /** When the content was last fetched (timestamp ms) */
-  contentFetchedAt?: number;
-  /** MCP servers declared by the skill */
-  mcpServers?: SkillMcpServer[];
-  /** System packages declared by the skill (nix) */
-  nixPackages?: string[];
-  /** Network domains the skill needs access to (legacy flat list) */
-  permissions?: string[];
-  /** Network access policy declared by the skill */
-  networkConfig?: { allowedDomains?: string[]; deniedDomains?: string[] };
-  /** Tool permission policy declared by the skill */
-  toolPermissions?: { allow?: string[]; deny?: string[] };
-  /** AI providers the skill requires */
-  providers?: string[];
-  /** Preferred model for this skill (e.g., "anthropic/claude-opus-4") */
-  modelPreference?: string;
-  /** Thinking level budget for this skill */
-  thinkingLevel?: ThinkingLevel;
-}
-
-/**
- * Skills configuration for agent settings.
- * Contains list of configured skills that can be enabled/disabled.
- */
-export interface SkillsConfig {
-  /** List of configured skills */
-  skills: SkillConfig[];
-}
-
-/**
- * Platform-agnostic history message format.
- * Used to pass conversation history to workers.
- */
-export interface HistoryMessage {
-  role: "user" | "assistant";
-  content: string;
-  timestamp: number;
-  /** Display name of the message sender */
-  userName?: string;
-  /** Platform-specific message ID for deduplication */
-  messageId?: string;
-}
-
-/**
- * Network configuration for worker sandbox isolation.
- * Controls which domains the worker can access via HTTP proxy.
- *
- * Filtering rules:
- * - deniedDomains are checked first (take precedence)
- * - allowedDomains are checked second
- * - If neither matches, request is denied
- *
- * Domain pattern format:
- * - "example.com" - exact match
- * - ".example.com" or "*.example.com" - matches subdomains
- */
-export interface NetworkConfig {
-  /** Domains the worker is allowed to access. Empty array = no network access. */
-  allowedDomains?: string[];
-  /** Domains explicitly blocked (takes precedence over allowedDomains). */
-  deniedDomains?: string[];
-}
-
-/**
- * Nix environment configuration for agent workspace.
- * Allows agents to run with specific Nix packages or flakes.
- *
- * Resolution priority:
- * 1. API-provided flakeUrl (highest)
- * 2. API-provided packages
- * 3. flake.nix in git repo
- * 4. shell.nix in git repo
- * 5. .nix-packages file in git repo
- */
-export interface NixConfig {
-  /** Nix flake URL (e.g., "github:user/repo#devShell") */
-  flakeUrl?: string;
-  /** Nixpkgs packages to install (e.g., ["python311", "ffmpeg"]) */
-  packages?: string[];
-}
-
-// ============================================================================
-// Tools Configuration Types
-// ============================================================================
-
-/**
- * Tool permission configuration for agent settings.
- * Follows Claude Code's permission patterns for consistency.
- *
- * Pattern formats (Claude Code compatible):
- * - "Read" - exact tool match
- * - "Bash(git:*)" - Bash with command filter (only git commands)
- * - "Bash(npm:*)" - Bash with npm commands only
- * - "mcp__servername__*" - all tools from an MCP server
- * - "*" - wildcard (all tools)
- *
- * Filtering rules:
- * - deniedTools are checked first (take precedence)
- * - allowedTools are checked second
- * - If strictMode=true, only allowedTools are permitted
- * - If strictMode=false, defaults + allowedTools are permitted
- */
-export interface ToolsConfig {
-  /**
-   * Tools to auto-allow (in addition to defaults unless strictMode=true).
-   * Supports patterns like "Bash(git:*)" or "mcp__github__*".
-   */
-  allowedTools?: string[];
-
-  /**
-   * Tools to always deny (takes precedence over allowedTools).
-   * Use to block specific tools even if they're in defaults.
-   */
-  deniedTools?: string[];
-
-  /**
-   * If true, ONLY allowedTools are permitted (ignores defaults).
-   * If false (default), allowedTools are ADDED to default permissions.
-   */
-  strictMode?: boolean;
-}
-
-/**
- * MCP server configuration for per-agent MCP servers.
- * Supports both HTTP/SSE and stdio MCP servers.
- */
-export interface McpServerConfig {
-  /** For HTTP/SSE MCPs: upstream URL */
-  url?: string;
-  /** Server type: "sse" for HTTP MCPs, "stdio" for command-based */
-  type?: "sse" | "stdio";
-  /** For stdio MCPs: command to execute */
-  command?: string;
-  /** For stdio MCPs: command arguments */
-  args?: string[];
-  /** For stdio MCPs: environment variables */
-  env?: Record<string, string>;
-  /** Additional headers for HTTP MCPs */
-  headers?: Record<string, string>;
-  /** Optional description for the MCP */
-  description?: string;
-}
-
-/**
- * Per-agent MCP configuration.
- * These MCPs are ADDED to global MCPs (not replacing).
- */
-export interface AgentMcpConfig {
-  /** Additional MCP servers for this agent */
-  mcpServers: Record<string, McpServerConfig>;
-}
-
-export interface MemoryFlushOptions {
-  enabled?: boolean;
-  softThresholdTokens?: number;
-  systemPrompt?: string;
-  prompt?: string;
-}
-
-export interface AgentCompactionOptions {
-  memoryFlush?: MemoryFlushOptions;
-}
-
-/**
- * Platform-agnostic execution hints passed through gateway → worker.
- * Flexible types (string | string[]) and index signature allow forward
- * compatibility for different agent implementations.
- */
-export interface AgentOptions {
-  runtime?: string;
-  model?: string;
-  maxTokens?: number;
-  temperature?: number;
-  allowedTools?: string | string[];
-  disallowedTools?: string | string[];
-  timeoutMinutes?: number | string;
-  compaction?: AgentCompactionOptions;
-  // Additional settings passed through from gateway (can be nested objects)
-  networkConfig?: Record<string, unknown>;
-  envVars?: Record<string, string>;
-  [key: string]: unknown;
-}
-
-/**
- * Platform-agnostic log level type
- * Maps to common logging levels used across different platforms
- */
-export type LogLevel = "debug" | "info" | "warn" | "error";
-
-// ============================================================================
-// Instruction Provider Types
-// ============================================================================
-
-/**
- * Context information passed to instruction providers
- */
-export interface InstructionContext {
-  userId: string;
-  agentId: string;
-  sessionKey: string;
-  workingDirectory: string;
-  availableProjects?: string[];
-  userPrompt?: string;
-}
-
-/**
- * Interface for components that contribute custom instructions
- */
-export interface InstructionProvider {
-  /** Unique identifier for this provider */
-  name: string;
-
-  /** Priority for ordering (lower = earlier in output) */
-  priority: number;
-
-  /**
-   * Generate instruction text for this provider
-   * @param context - Context information for instruction generation
-   * @returns Instruction text or empty string if none
-   */
-  getInstructions(context: InstructionContext): Promise<string> | string;
-}
-
-// ============================================================================
-// Thread Response Types
-// ============================================================================
-
-/**
- * Shared payload contract for worker → platform thread responses.
- * Ensures gateway consumers and workers stay type-aligned.
- */
-export interface ThreadResponsePayload {
-  messageId: string;
-  channelId: string;
-  conversationId: string;
-  userId: string;
-  teamId: string;
-  platform?: string; // Platform identifier (slack, whatsapp, api, etc.) for routing
-  content?: string; // Used only for ephemeral messages (OAuth/auth flows)
-  delta?: string;
-  isFullReplacement?: boolean;
-  processedMessageIds?: string[];
-  error?: string;
-  errorCode?: string;
-  timestamp: number;
-  originalMessageId?: string;
-  moduleData?: Record<string, unknown>;
-  botResponseId?: string;
-  ephemeral?: boolean; // If true, message should be sent as ephemeral (only visible to user)
-  platformMetadata?: Record<string, unknown>;
-  statusUpdate?: {
-    elapsedSeconds: number;
-    state: string; // e.g., "is running" or "is scheduling"
-  };
-
-  // Exec-specific response fields (for jobType === "exec")
-  execId?: string; // Exec job ID for response routing
-  execStream?: "stdout" | "stderr"; // Which stream this delta is from
-  execExitCode?: number; // Process exit code (sent on completion)
-}
-
-// ============================================================================
-// User Interaction Types
-// ============================================================================
-
-/**
- * Suggested prompt for user
- */
-export interface SuggestedPrompt {
-  title: string; // Short label shown as chip
-  message: string; // Full message sent when clicked
-}
-
-/**
- * Skill registry entry (global or per-agent).
- */
-export interface RegistryEntry {
-  id: string;
-  type: string;
-  apiUrl: string;
-}
-
-/**
- * Non-blocking suggestions - agent continues immediately
- * Used for optional next steps
- */
-export interface UserSuggestion {
-  id: string;
-  userId: string;
-  conversationId: string;
-  channelId: string;
-  teamId?: string;
-
-  blocking: false; // Always false - distinguishes from interactions
-
-  prompts: SuggestedPrompt[];
-}

package/src/utils/encryption.ts

@@ -1,78 +0,0 @@
-import * as crypto from "node:crypto";
-import { createLogger } from "../logger";
-
-const IV_LENGTH = 12; // 96-bit nonce for AES-GCM
-const logger = createLogger("encryption");
-
-/**
- * Get encryption key from environment with validation
- *
- * IMPORTANT: The ENCRYPTION_KEY must be exactly 32 bytes (256 bits) for AES-256.
- * Generate a secure key using: `openssl rand -base64 32` or `openssl rand -hex 32`
- */
-function getEncryptionKey(): Buffer {
-  const key = process.env.ENCRYPTION_KEY || "";
-  if (!key) {
-    throw new Error(
-      "ENCRYPTION_KEY environment variable is required for secure operation"
-    );
-  }
-
-  // Try to decode as base64 first (most common format)
-  let keyBuffer: Buffer;
-  try {
-    keyBuffer = Buffer.from(key, "base64");
-    if (keyBuffer.length === 32) {
-      return keyBuffer;
-    }
-  } catch (err) {
-    logger.debug("ENCRYPTION_KEY is not valid base64, trying hex format", err);
-  }
-
-  // Try as hex (must be exactly 64 hex characters for 32 bytes)
-  if (/^[0-9a-fA-F]{64}$/.test(key)) {
-    keyBuffer = Buffer.from(key, "hex");
-    if (keyBuffer.length === 32) {
-      return keyBuffer;
-    }
-  }
-
-  throw new Error(
-    "ENCRYPTION_KEY must be a base64 or hex encoded 32-byte key. " +
-      "Generate a valid key with: openssl rand -base64 32"
-  );
-}
-
-/**
- * Encrypt a string using AES-256-GCM
- */
-export function encrypt(text: string): string {
-  const encryptionKey = getEncryptionKey();
-  const iv = crypto.randomBytes(IV_LENGTH);
-  const cipher = crypto.createCipheriv("aes-256-gcm", encryptionKey, iv);
-  const encrypted = Buffer.concat([
-    cipher.update(text, "utf8"),
-    cipher.final(),
-  ]);
-  const tag = cipher.getAuthTag();
-  return `${iv.toString("hex")}:${tag.toString("hex")}:${encrypted.toString("hex")}`;
-}
-
-/**
- * Decrypt a string encrypted with AES-256-GCM
- */
-export function decrypt(text: string): string {
-  const encryptionKey = getEncryptionKey();
-  const parts = text.split(":");
-  if (parts.length !== 3) throw new Error("Invalid encrypted format");
-  const iv = Buffer.from(parts[0]!, "hex");
-  const tag = Buffer.from(parts[1]!, "hex");
-  const encryptedText = Buffer.from(parts[2]!, "hex");
-  const decipher = crypto.createDecipheriv("aes-256-gcm", encryptionKey, iv);
-  decipher.setAuthTag(tag);
-  const decrypted = Buffer.concat([
-    decipher.update(encryptedText),
-    decipher.final(),
-  ]);
-  return decrypted.toString("utf8");
-}

package/src/utils/env.ts

@@ -1,50 +0,0 @@
-import { ConfigError } from "../errors";
-
-/**
- * Get required environment variable
- * Throws ConfigError if not set
- */
-export function getRequiredEnv(name: string): string {
-  const value = process.env[name];
-  if (!value) {
-    throw new ConfigError(`Missing required environment variable: ${name}`);
-  }
-  return value;
-}
-
-/**
- * Get optional environment variable with default
- */
-export function getOptionalEnv(name: string, defaultValue: string): string {
-  return process.env[name] || defaultValue;
-}
-
-/**
- * Get optional number environment variable with default
- * Throws ConfigError if value is not a valid number
- */
-export function getOptionalNumber(name: string, defaultValue: number): number {
-  const value = process.env[name];
-  if (!value) return defaultValue;
-  const parsed = parseInt(value, 10);
-  if (Number.isNaN(parsed)) {
-    throw new ConfigError(
-      `Invalid number for ${name}: ${value} (expected integer)`
-    );
-  }
-  return parsed;
-}
-
-/**
- * Get optional boolean environment variable with default
- * Accepts "true", "1", "yes" as truthy values
- */
-export function getOptionalBoolean(
-  name: string,
-  defaultValue: boolean
-): boolean {
-  const value = process.env[name];
-  if (!value) return defaultValue;
-  const lower = value.toLowerCase();
-  return lower === "true" || lower === "1" || lower === "yes";
-}

package/src/utils/json.ts

@@ -1,37 +0,0 @@
-import { createLogger } from "../logger";
-
-const logger = createLogger("json-utils");
-
-/**
- * Safely parse JSON string
- * Returns null on parse failure instead of throwing
- */
-export function safeJsonParse<T = unknown>(
-  data: string,
-  fallback: T | null = null
-): T | null {
-  try {
-    return JSON.parse(data) as T;
-  } catch (error) {
-    logger.debug("JSON parse failed", {
-      error: error instanceof Error ? error.message : String(error),
-      dataPreview: data.substring(0, 100),
-    });
-    return fallback;
-  }
-}
-
-/**
- * Safely stringify value to JSON
- * Returns null on stringify failure instead of throwing
- */
-export function safeJsonStringify(value: unknown): string | null {
-  try {
-    return JSON.stringify(value);
-  } catch (error) {
-    logger.error("JSON stringify failed", {
-      error: error instanceof Error ? error.message : String(error),
-    });
-    return null;
-  }
-}

package/src/utils/lock.ts

@@ -1,75 +0,0 @@
-/**
- * Async lock for serializing concurrent operations
- * Prevents race conditions in async code by ensuring only one operation runs at a time
- *
- * @example
- * ```typescript
- * class StreamSession {
- *   private streamLock = new AsyncLock();
- *
- *   async appendDelta(delta: string) {
- *     return this.streamLock.acquire(() => this.appendDeltaUnsafe(delta));
- *   }
- *
- *   private async appendDeltaUnsafe(delta: string) {
- *     // Critical section - only one execution at a time
- *   }
- * }
- * ```
- */
-export class AsyncLock {
-  private lock: Promise<void> = Promise.resolve();
-  private lockContext: string;
-
-  constructor(context: string = "unknown") {
-    this.lockContext = context;
-  }
-
-  /**
-   * Acquire lock and execute function exclusively
-   *
-   * @param fn - The async function to execute with exclusive access
-   * @param timeoutMs - Maximum time to wait for lock acquisition (default: 30s)
-   * @returns The result of the function
-   * @throws Error if lock acquisition times out
-   */
-  async acquire<T>(
-    fn: () => Promise<T>,
-    timeoutMs: number = 30000
-  ): Promise<T> {
-    const currentLock = this.lock;
-    let releaseLock: (() => void) | undefined;
-
-    // Create new lock that will be released when fn completes
-    this.lock = new Promise<void>((resolve) => {
-      releaseLock = resolve;
-    });
-
-    let timeoutId: ReturnType<typeof setTimeout> | undefined;
-
-    try {
-      // Wait for previous operation with timeout to prevent deadlock
-      const lockTimeout = new Promise<never>((_, reject) => {
-        timeoutId = setTimeout(() => {
-          reject(
-            new Error(
-              `Lock acquisition timeout after ${timeoutMs}ms - possible deadlock in ${this.lockContext}`
-            )
-          );
-        }, timeoutMs);
-      });
-
-      await Promise.race([currentLock, lockTimeout]);
-
-      // Execute function with exclusive access
-      return await fn();
-    } finally {
-      // Clear the timeout to prevent leak
-      if (timeoutId !== undefined) {
-        clearTimeout(timeoutId);
-      }
-      // Always release lock, even on error
-      releaseLock?.();
-    }
-  }
-}

package/src/utils/mcp-tool-instructions.ts

@@ -1,5 +0,0 @@
-export interface McpToolDef {
-  name: string;
-  description?: string;
-  inputSchema?: Record<string, unknown>;
-}