skyloom 1.4.0

package/src/core/cache.ts

@@ -0,0 +1,153 @@
+/**
+ * Lightweight LRU cache for LLM responses.
+ *
+ * Deduplicates identical requests within a configurable time window.
+ * Keyed by (model, messages_json) hash.
+ */
+
+import crypto from 'crypto';
+
+/**
+ * Cache entry containing timestamp and response.
+ */
+interface CacheEntry {
+  timestamp: number;
+  response: string;
+}
+
+/**
+ * LRU cache for LLM completions with TTL expiration.
+ */
+export class LLMCache {
+  private maxSize: number;
+  private ttlSeconds: number;
+  private cache: Map<string, CacheEntry> = new Map();
+
+  constructor(maxSize: number = 128, ttlSeconds: number = 60) {
+    this.maxSize = maxSize;
+    this.ttlSeconds = ttlSeconds;
+  }
+
+  /**
+   * Generate a cache key from model, messages, and parameters.
+   *
+   * Uses SHA256 hash for deterministic, compact keys. Parameters are sorted
+   * to ensure consistent keys regardless of key order.
+   */
+  private makeKey(
+    model: string,
+    messages: Record<string, any>[],
+    params?: Record<string, any>
+  ): string {
+    const raw = JSON.stringify([model, messages, params || {}], this.jsonReplacer);
+    return crypto.createHash('sha256').update(raw).digest('hex').slice(0, 32);
+  }
+
+  /**
+   * JSON replacer for consistent serialization.
+   */
+  private jsonReplacer(_key: string, value: any): any {
+    if (typeof value === 'function') {
+      return undefined;
+    }
+    return value;
+  }
+
+  /**
+   * Get a cached response if it exists and hasn't expired.
+   *
+   * @param model - LLM model name
+   * @param messages - Conversation messages
+   * @param params - Optional parameters
+   * @returns Cached response or null if miss/expired
+   */
+  get(
+    model: string,
+    messages: Record<string, any>[],
+    params?: Record<string, any>
+  ): string | null {
+    const key = this.makeKey(model, messages, params);
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      return null;
+    }
+
+    // Check if expired
+    const now = Date.now();
+    const ageSeconds = (now - entry.timestamp) / 1000;
+
+    if (ageSeconds >= this.ttlSeconds) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    // Move to end (LRU)
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+
+    return entry.response;
+  }
+
+  /**
+   * Cache a response.
+   *
+   * Refuses to cache empty or very short content to avoid bloat.
+   * Also performs LRU eviction if cache exceeds max_size.
+   *
+   * @param model - LLM model name
+   * @param messages - Conversation messages
+   * @param response - LLM response to cache
+   * @param params - Optional parameters
+   */
+  set(
+    model: string,
+    messages: Record<string, any>[],
+    response: string,
+    params?: Record<string, any>
+  ): void {
+    // Don't cache empty or very short responses
+    if (!response || response.length < 10) {
+      return;
+    }
+
+    const key = this.makeKey(model, messages, params);
+    const entry: CacheEntry = {
+      timestamp: Date.now(),
+      response,
+    };
+
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+
+    // Evict oldest entries if over capacity
+    while (this.cache.size > this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) this.cache.delete(firstKey);
+    }
+  }
+
+  /**
+   * Clear all cache entries.
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get current cache size.
+   */
+  get size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Get cache hit rate statistics.
+   */
+  getStats(): { size: number; maxSize: number } {
+    return {
+      size: this.cache.size,
+      maxSize: this.maxSize,
+    };
+  }
+}

package/src/core/checkpoint.ts

@@ -0,0 +1,94 @@
+/**
+ * Orchestration checkpoint — save/restore task state.
+ *
+ * Writes ~/.skyloom/task_checkpoint.json so a long-running orchestration
+ * interrupted by Ctrl-C can be resumed.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { USER_CONFIG_DIR } from './config';
+
+function checkpointPath(): string {
+  return path.join(USER_CONFIG_DIR, 'task_checkpoint.json');
+}
+
+/**
+ * Save current orchestration state so it can be resumed later.
+ */
+export function save(
+  goal: string,
+  tasks: any[],
+  results: any[],
+  completedIds?: Set<string>
+): void {
+  const cids = completedIds || new Set(results.map((r: any) => r.id));
+  const payload = {
+    goal,
+    tasks: tasks.map(serializeTask),
+    results: results.map(serializeResult),
+    completed_ids: Array.from(cids).sort(),
+  };
+
+  const p = checkpointPath();
+  const dir = path.dirname(p);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const tmp = p + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf-8');
+  fs.renameSync(tmp, p);
+}
+
+/**
+ * Return the last saved checkpoint dict, or null if none / unreadable.
+ */
+export function load(): Record<string, any> | null {
+  const p = checkpointPath();
+  if (!fs.existsSync(p)) {
+    return null;
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    return typeof data === 'object' && data !== null ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Delete the checkpoint file.
+ */
+export function clear(): void {
+  try {
+    const p = checkpointPath();
+    if (fs.existsSync(p)) {
+      fs.unlinkSync(p);
+    }
+  } catch {
+    // Ignore cleanup errors
+  }
+}
+
+// ── Serialization helpers ──
+
+function serializeTask(t: any): Record<string, any> {
+  return {
+    id: t.id,
+    description: t.description,
+    assigned_to: t.assignedTo ?? t.assigned_to,
+    all_deps: t.allDeps ?? t.all_deps ?? [],
+    status: t.status?.value ?? t.status ?? 'unknown',
+  };
+}
+
+function serializeResult(r: any): Record<string, any> {
+  return {
+    id: r.id,
+    agent: r.agent,
+    description: r.description,
+    success: r.success,
+    content: r.content,
+  };
+}

package/src/core/circuit_breaker.ts

@@ -0,0 +1,119 @@
+/**
+ * Circuit breaker pattern for fault tolerance
+ */
+
+export interface CircuitBreakerConfig {
+  name: string;
+  failureThreshold?: number;
+  successThreshold?: number;
+  resetTimeout?: number;
+}
+
+export type CircuitBreakerState = "closed" | "open" | "half_open";
+
+/**
+ * Circuit breaker implementation
+ */
+export class CircuitBreaker {
+  private state: CircuitBreakerState = "closed";
+  private failureCount = 0;
+  private successCount = 0;
+  private lastFailureTime = 0;
+  private failureThreshold: number;
+  private successThreshold: number;
+  private resetTimeout: number;
+
+  constructor(config: CircuitBreakerConfig) {
+    this.failureThreshold = config.failureThreshold ?? 5;
+    this.successThreshold = config.successThreshold ?? 3;
+    this.resetTimeout = config.resetTimeout ?? 60000; // 60 seconds
+  }
+
+  /**
+   * Check if execution is allowed
+   */
+  canExecute(): boolean {
+    if (this.state === "closed") {
+      return true;
+    }
+
+    if (this.state === "open") {
+      const timeSinceLastFailure = Date.now() - this.lastFailureTime;
+      if (timeSinceLastFailure > this.resetTimeout) {
+        this.state = "half_open";
+        this.successCount = 0;
+        return true;
+      }
+      return false;
+    }
+
+    // half_open state allows attempts
+    return true;
+  }
+
+  /**
+   * Record a successful execution
+   */
+  recordSuccess(): void {
+    this.failureCount = 0;
+
+    if (this.state === "half_open") {
+      this.successCount++;
+      if (this.successCount >= this.successThreshold) {
+        this.state = "closed";
+        this.successCount = 0;
+      }
+    }
+  }
+
+  /**
+   * Record a failed execution
+   */
+  recordFailure(): void {
+    this.lastFailureTime = Date.now();
+    this.failureCount++;
+
+    if (this.failureCount >= this.failureThreshold) {
+      this.state = "open";
+      this.failureCount = 0;
+    }
+
+    if (this.state === "half_open") {
+      this.state = "open";
+      this.failureCount = 0;
+    }
+  }
+
+  /**
+   * Get current state
+   */
+  getState(): CircuitBreakerState {
+    return this.state;
+  }
+
+  /**
+   * Reset the circuit breaker
+   */
+  reset(): void {
+    this.state = "closed";
+    this.failureCount = 0;
+    this.successCount = 0;
+    this.lastFailureTime = 0;
+  }
+}
+
+/**
+ * Get or create a circuit breaker for a service
+ */
+const breakers = new Map<string, CircuitBreaker>();
+
+export function getBreaker(name: string, config?: CircuitBreakerConfig): CircuitBreaker {
+  if (!breakers.has(name)) {
+    breakers.set(name, new CircuitBreaker(config ?? { name }));
+  }
+  return breakers.get(name)!;
+}
+
+export function clearBreakers(): void {
+  breakers.clear();
+}

package/src/core/config.ts

@@ -0,0 +1,341 @@
+/**
+ * Configuration management for Skyloom
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import * as yaml from "yaml";
+import { getLogger } from "./logger";
+
+const log = getLogger("config");
+
+/**
+ * Configuration directory paths
+ */
+const LEGACY_CONFIG_DIR = path.join(os.homedir(), ".weather-agents");
+
+/**
+ * Resolve the user configuration directory
+ * Migrates from legacy ~/.weather-agents to ~/.skyloom if needed
+ */
+function resolveUserConfigDir(): string {
+  const newDir = path.join(os.homedir(), ".skyloom");
+
+  if (!fs.existsSync(newDir) && fs.existsSync(LEGACY_CONFIG_DIR)) {
+    try {
+      fs.renameSync(LEGACY_CONFIG_DIR, newDir);
+      log.info("Migrated config directory", {
+        from: LEGACY_CONFIG_DIR,
+        to: newDir,
+      });
+    } catch (error) {
+      log.warn("Failed to migrate config directory", {
+        error: (error as Error).message,
+      });
+      return LEGACY_CONFIG_DIR;
+    }
+  }
+
+  return newDir;
+}
+
+export const USER_CONFIG_DIR = resolveUserConfigDir();
+
+/**
+ * Find the config directory (bundled or user-provided)
+ */
+function findConfigDir(): string {
+  // Try bundled config directory (relative to src or dist)
+  const possiblePaths = [
+    path.join(__dirname, "..", "..", "..", "config"),
+    path.join(__dirname, "..", "config"),
+    path.join(process.cwd(), "config"),
+  ];
+
+  for (const configPath of possiblePaths) {
+    if (fs.existsSync(path.join(configPath, "default.yaml"))) {
+      return configPath;
+    }
+  }
+
+  // Fall back to user config directory
+  return path.join(USER_CONFIG_DIR, "config");
+}
+
+export const CONFIG_DIR = findConfigDir();
+
+/**
+ * Memory configuration
+ */
+export interface MemoryConfig {
+  dbPath: string;
+  shortTermLimit: number;
+  maxPersistedMessages?: number;
+}
+
+/**
+ * All agent names — single source of truth
+ */
+export const AGENT_NAMES = ["fog", "rain", "frost", "snow", "dew", "fair"] as const;
+
+/**
+ * Load a YAML file safely
+ */
+function loadYaml(filePath: string): Record<string, unknown> | null {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+
+    const content = fs.readFileSync(filePath, "utf-8");
+    const data = yaml.parse(content);
+
+    return typeof data === "object" && data !== null ? (data as Record<string, unknown>) : {};
+  } catch (error) {
+    log.error("Failed to load YAML file", {
+      file: filePath,
+      error: (error as Error).message,
+    });
+    return null;
+  }
+}
+
+/**
+ * Model catalog entry
+ */
+export interface ModelEntry {
+  name: string;
+  provider?: string;
+  context_window?: number;
+  max_output?: number;
+  input_cost_per_1k?: number;
+  output_cost_per_1k?: number;
+  fallback?: string[];
+}
+
+/**
+ * Load available models from models.yaml
+ */
+export function loadModelCatalog(): Record<string, ModelEntry[]> {
+  const modelPath = path.join(CONFIG_DIR, "models.yaml");
+  const data = loadYaml(modelPath);
+
+  if (!data) {
+    return {};
+  }
+
+  const catalog: Record<string, ModelEntry[]> = {};
+
+  for (const [provider, models] of Object.entries(data)) {
+    if (typeof models === "object" && models !== null) {
+      catalog[provider] = [];
+
+      for (const [name, info] of Object.entries(models as Record<string, unknown>)) {
+        const entry: ModelEntry = { name };
+
+        if (typeof info === "object" && info !== null) {
+          Object.assign(entry, info);
+        } else if (typeof info === "string") {
+          entry.provider = info;
+        }
+
+        catalog[provider].push(entry);
+      }
+    }
+  }
+
+  return catalog;
+}
+
+/**
+ * Provider catalog entry
+ */
+export interface ProviderEntry {
+  env_var?: string;
+  region?: string;
+  docs_url?: string;
+  base_url?: string;
+  aliases?: string[];
+  [key: string]: unknown;
+}
+
+let providerCatalogCache: Record<string, ProviderEntry> | null = null;
+
+/**
+ * Load provider catalog from providers.yaml
+ */
+export function loadProviderCatalog(): Record<string, ProviderEntry> {
+  if (providerCatalogCache) {
+    return providerCatalogCache;
+  }
+
+  const catalog: Record<string, ProviderEntry> = {};
+
+  // Load bundled providers
+  const bundledPath = path.join(CONFIG_DIR, "providers.yaml");
+  const bundledData = loadYaml(bundledPath);
+
+  if (bundledData) {
+    for (const [key, value] of Object.entries(bundledData)) {
+      if (typeof value === "object" && value !== null) {
+        catalog[key] = { ...value } as ProviderEntry;
+      }
+    }
+  }
+
+  // Load user overrides
+  const userPath = path.join(USER_CONFIG_DIR, "providers.yaml");
+  const userData = loadYaml(userPath);
+
+  if (userData) {
+    for (const [key, value] of Object.entries(userData)) {
+      if (typeof value === "object" && value !== null) {
+        catalog[key] = {
+          ...catalog[key],
+          ...value,
+        } as ProviderEntry;
+      }
+    }
+  }
+
+  providerCatalogCache = catalog;
+  return catalog;
+}
+
+/**
+ * Agent configuration
+ */
+export interface AgentConfig {
+  model: string;
+  provider: string;
+  temperature?: number;
+  top_p?: number;
+  max_tokens?: number;
+  system_prompt?: string;
+  tools?: string[];
+}
+
+/**
+ * Skyloom configuration
+ */
+export interface SkyloomConfig {
+  agents: Record<string, AgentConfig>;
+  providers?: Record<string, ProviderEntry>;
+  models?: Record<string, ModelEntry[]>;
+}
+
+/**
+ * Load default configuration
+ */
+export function loadDefaultConfig(): SkyloomConfig {
+  const defaultPath = path.join(CONFIG_DIR, "default.yaml");
+  const data = loadYaml(defaultPath);
+
+  if (!data) {
+    return { agents: {} };
+  }
+
+  return data as unknown as SkyloomConfig;
+}
+
+/**
+ * Load user configuration (from ~/.skyloom/config.yaml)
+ */
+export function loadUserConfig(): SkyloomConfig | null {
+  const userPath = path.join(USER_CONFIG_DIR, "config.yaml");
+  const data = loadYaml(userPath);
+
+  if (!data) {
+    return null;
+  }
+
+  return data as unknown as SkyloomConfig;
+}
+
+/**
+ * Merge user config on top of default config
+ */
+export function mergeConfigs(defaultCfg: SkyloomConfig, userCfg: SkyloomConfig | null): SkyloomConfig {
+  if (!userCfg) {
+    return defaultCfg;
+  }
+
+  return {
+    agents: {
+      ...defaultCfg.agents,
+      ...userCfg.agents,
+    },
+    providers: {
+      ...defaultCfg.providers,
+      ...userCfg.providers,
+    },
+    models: {
+      ...defaultCfg.models,
+      ...userCfg.models,
+    },
+  };
+}
+
+/**
+ * Load the complete configuration
+ */
+export function loadConfig(): SkyloomConfig {
+  const defaultCfg = loadDefaultConfig();
+  const userCfg = loadUserConfig();
+  return mergeConfigs(defaultCfg, userCfg);
+}
+
+/**
+ * Save user configuration
+ */
+export function saveUserConfig(config: SkyloomConfig): void {
+  // Ensure user config directory exists
+  if (!fs.existsSync(USER_CONFIG_DIR)) {
+    fs.mkdirSync(USER_CONFIG_DIR, { recursive: true });
+  }
+
+  const userPath = path.join(USER_CONFIG_DIR, "config.yaml");
+  const content = yaml.stringify(config);
+
+  fs.writeFileSync(userPath, content, "utf-8");
+  log.info("Saved user configuration", { path: userPath });
+}
+
+/**
+ * Get an agent configuration
+ */
+export function getAgentConfig(config: SkyloomConfig, agentName: string): AgentConfig | null {
+  return config.agents[agentName] || null;
+}
+
+/**
+ * Format models for display
+ */
+export function formatModelsForDisplay(catalog: Record<string, ModelEntry[]>): string {
+  const lines: string[] = [];
+
+  for (const [provider, models] of Object.entries(catalog)) {
+    lines.push(`  [${provider.toUpperCase()}]`);
+
+    for (const m of models) {
+      const costParts: string[] = [];
+      if (m.input_cost_per_1k) {
+        costParts.push(`$${m.input_cost_per_1k.toFixed(4)}/1k in`);
+      }
+      if (m.output_cost_per_1k) {
+        costParts.push(`$${m.output_cost_per_1k.toFixed(4)}/1k out`);
+      }
+
+      const costStr = costParts.length > 0 ? `  cost=(${costParts.join(", ")})` : "";
+      const fallbackStr =
+        m.fallback && m.fallback.length > 0 ? `  fallback->${m.fallback.join(" > ")}` : "";
+
+      lines.push(
+        `    ${m.name}  (ctx=${m.context_window || "?"}, max=${m.max_output || "?"})${costStr}${fallbackStr}`
+      );
+    }
+  }
+
+  return lines.join("\n");
+}