@soleri/core 0.0.1 → 2.0.0

package/src/llm/key-pool.ts

@@ -0,0 +1,190 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { homedir } from 'node:os';
+import { SecretString } from './types.js';
+import type { KeyPoolConfig, KeyStatus } from './types.js';
+import { CircuitBreaker } from './utils.js';
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const DEFAULT_PREEMPTIVE_THRESHOLD = 50;
+
+// =============================================================================
+// KEY POOL
+// =============================================================================
+
+export class KeyPool {
+  private keys: SecretString[];
+  private activeIndex: number = 0;
+  private keyBreakers: Map<number, CircuitBreaker> = new Map();
+  private remainingQuota: Map<number, number> = new Map();
+  private readonly preemptiveThreshold: number;
+
+  constructor(config: KeyPoolConfig) {
+    this.keys = config.keys.filter((k) => k.length > 0).map((k) => new SecretString(k));
+    this.preemptiveThreshold = config.preemptiveThreshold ?? DEFAULT_PREEMPTIVE_THRESHOLD;
+
+    for (let i = 0; i < this.keys.length; i++) {
+      this.keyBreakers.set(
+        i,
+        new CircuitBreaker({
+          name: `key-pool-${i}`,
+          failureThreshold: 3,
+          resetTimeoutMs: 30_000,
+        }),
+      );
+    }
+
+    if (this.keys.length > 1) {
+      console.error(`[LLM] KeyPool initialized with ${this.keys.length} keys`);
+    }
+  }
+
+  get hasKeys(): boolean {
+    return this.keys.length > 0;
+  }
+
+  getActiveKey(): SecretString {
+    if (this.keys.length === 0) {
+      throw new Error('KeyPool has no keys — cannot get active key');
+    }
+    return this.keys[this.activeIndex];
+  }
+
+  get activeKeyIndex(): number {
+    return this.activeIndex;
+  }
+
+  get poolSize(): number {
+    return this.keys.length;
+  }
+
+  get exhausted(): boolean {
+    if (this.keys.length === 0) return true;
+    for (let i = 0; i < this.keys.length; i++) {
+      const breaker = this.keyBreakers.get(i)!;
+      if (!breaker.isOpen()) return false;
+    }
+    return true;
+  }
+
+  rotateOnError(): SecretString | null {
+    const breaker = this.keyBreakers.get(this.activeIndex);
+    if (breaker) {
+      breaker.recordFailure();
+    }
+    return this.findNextHealthyKey();
+  }
+
+  rotatePreemptive(): boolean {
+    const previousIndex = this.activeIndex;
+    const remaining = this.remainingQuota.get(previousIndex);
+    if (remaining !== undefined && remaining < this.preemptiveThreshold) {
+      const next = this.findNextHealthyKey();
+      if (next) {
+        console.error(
+          `[LLM] KeyPool preemptive rotation: key ${previousIndex} remaining=${remaining} < threshold=${this.preemptiveThreshold}`,
+        );
+        return true;
+      }
+    }
+    return false;
+  }
+
+  updateQuota(keyIndex: number, remaining: number): void {
+    this.remainingQuota.set(keyIndex, remaining);
+  }
+
+  getStatus(): {
+    poolSize: number;
+    activeKeyIndex: number;
+    exhausted: boolean;
+    perKeyStatus: KeyStatus[];
+  } {
+    const perKeyStatus: KeyStatus[] = [];
+    for (let i = 0; i < this.keys.length; i++) {
+      perKeyStatus.push({
+        index: i,
+        circuitState: this.keyBreakers.get(i)!.getState(),
+        remainingQuota: this.remainingQuota.get(i) ?? null,
+      });
+    }
+    return {
+      poolSize: this.poolSize,
+      activeKeyIndex: this.activeIndex,
+      exhausted: this.exhausted,
+      perKeyStatus,
+    };
+  }
+
+  private findNextHealthyKey(): SecretString | null {
+    const startIndex = this.activeIndex;
+    for (let offset = 1; offset <= this.keys.length; offset++) {
+      const candidateIndex = (startIndex + offset) % this.keys.length;
+      const breaker = this.keyBreakers.get(candidateIndex)!;
+      if (!breaker.isOpen()) {
+        this.activeIndex = candidateIndex;
+        return this.keys[candidateIndex];
+      }
+    }
+    console.error('[LLM] KeyPool: all keys exhausted — no healthy key available');
+    return null;
+  }
+}
+
+// =============================================================================
+// KEY LOADING
+// =============================================================================
+
+export interface KeyPoolFiles {
+  openai: KeyPoolConfig;
+  anthropic: KeyPoolConfig;
+}
+
+/**
+ * Load key pool configuration for an agent.
+ * Key loading priority:
+ * 1. ~/.{agentId}/keys.json
+ * 2. Fallback: OPENAI_API_KEY / ANTHROPIC_API_KEY env vars
+ * 3. Empty pool
+ */
+export function loadKeyPoolConfig(agentId: string): KeyPoolFiles {
+  if (!agentId || /[/\\]/.test(agentId) || agentId.includes('..')) {
+    throw new Error(`Invalid agentId: ${agentId}`);
+  }
+  const keysFilePath = path.join(homedir(), `.${agentId}`, 'keys.json');
+
+  let openaiKeys: string[] = [];
+  let anthropicKeys: string[] = [];
+
+  try {
+    if (fs.existsSync(keysFilePath)) {
+      const data = JSON.parse(fs.readFileSync(keysFilePath, 'utf-8'));
+      if (data?.openai && Array.isArray(data.openai)) {
+        openaiKeys = data.openai;
+      }
+      if (data?.anthropic && Array.isArray(data.anthropic)) {
+        anthropicKeys = data.anthropic;
+      }
+    }
+  } catch {
+    console.error('[LLM] Could not read keys.json, falling back to env vars');
+  }
+
+  // Fallback: environment variables
+  if (openaiKeys.length === 0) {
+    const envKey = process.env.OPENAI_API_KEY || '';
+    if (envKey) openaiKeys = [envKey];
+  }
+  if (anthropicKeys.length === 0) {
+    const envKey = process.env.ANTHROPIC_API_KEY || '';
+    if (envKey) anthropicKeys = [envKey];
+  }
+
+  return {
+    openai: { keys: openaiKeys },
+    anthropic: { keys: anthropicKeys },
+  };
+}

package/src/llm/types.ts

@@ -0,0 +1,116 @@
+const REDACTED = '[REDACTED]';
+
+export class SecretString {
+  #value: string;
+
+  constructor(value: string) {
+    this.#value = value;
+  }
+
+  expose(): string {
+    return this.#value;
+  }
+
+  get isSet(): boolean {
+    return this.#value.length > 0;
+  }
+
+  toString(): string {
+    return REDACTED;
+  }
+  toJSON(): string {
+    return REDACTED;
+  }
+  [Symbol.toPrimitive](): string {
+    return REDACTED;
+  }
+  [Symbol.for('nodejs.util.inspect.custom')](): string {
+    return REDACTED;
+  }
+}
+
+export class LLMError extends Error {
+  retryable: boolean;
+  statusCode?: number;
+
+  constructor(message: string, options?: { retryable?: boolean; statusCode?: number }) {
+    super(message);
+    this.name = 'LLMError';
+    this.retryable = options?.retryable ?? false;
+    this.statusCode = options?.statusCode;
+    Object.setPrototypeOf(this, LLMError.prototype);
+  }
+}
+
+export interface LLMCallOptions {
+  provider: 'openai' | 'anthropic';
+  model: string;
+  systemPrompt: string;
+  userPrompt: string;
+  temperature?: number;
+  maxTokens?: number;
+  caller: string;
+  task?: string;
+}
+
+export interface LLMCallResult {
+  text: string;
+  model: string;
+  provider: 'openai' | 'anthropic';
+  inputTokens?: number;
+  outputTokens?: number;
+  durationMs: number;
+}
+
+export type CircuitState = 'closed' | 'open' | 'half-open';
+
+export interface CircuitBreakerConfig {
+  failureThreshold: number;
+  resetTimeoutMs: number;
+  name: string;
+}
+
+export interface CircuitBreakerSnapshot {
+  state: CircuitState;
+  failureCount: number;
+  lastFailureAt: number | null;
+}
+
+export interface KeyPoolConfig {
+  keys: string[];
+  preemptiveThreshold?: number;
+}
+
+export interface KeyStatus {
+  index: number;
+  circuitState: CircuitBreakerSnapshot;
+  remainingQuota: number | null;
+}
+
+export interface RouteEntry {
+  caller: string;
+  task?: string;
+  model: string;
+  provider: 'openai' | 'anthropic';
+}
+
+export interface RoutingConfig {
+  routes: RouteEntry[];
+  defaultOpenAIModel: string;
+  defaultAnthropicModel: string;
+}
+
+export interface RateLimitInfo {
+  remaining: number | null;
+  resetMs: number | null;
+  retryAfterMs: number | null;
+}
+
+export interface RetryConfig {
+  maxAttempts: number;
+  baseDelayMs: number;
+  maxDelayMs: number;
+  jitter: number;
+  shouldRetry?: (error: unknown) => boolean;
+  onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+}

package/src/llm/utils.ts

@@ -0,0 +1,248 @@
+import type {
+  CircuitBreakerConfig,
+  CircuitBreakerSnapshot,
+  CircuitState,
+  LLMError,
+  RateLimitInfo,
+  RetryConfig,
+} from './types.js';
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+function isRetryable(error: unknown): boolean {
+  if (error && typeof error === 'object' && 'retryable' in error) {
+    return (error as { retryable: boolean }).retryable === true;
+  }
+  return false;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// =============================================================================
+// CIRCUIT BREAKER
+// =============================================================================
+
+const DEFAULT_CB_CONFIG: CircuitBreakerConfig = {
+  failureThreshold: 5,
+  resetTimeoutMs: 60_000,
+  name: 'default',
+};
+
+export class CircuitOpenError extends Error {
+  retryable = false;
+  constructor(name: string) {
+    super(`${name} circuit breaker is open — calls are being rejected`);
+    this.name = 'CircuitOpenError';
+    Object.setPrototypeOf(this, CircuitOpenError.prototype);
+  }
+}
+
+export class CircuitBreaker {
+  private state: CircuitState = 'closed';
+  private failureCount = 0;
+  private lastFailureAt: number | null = null;
+  private readonly config: CircuitBreakerConfig;
+
+  constructor(config?: Partial<CircuitBreakerConfig>) {
+    this.config = { ...DEFAULT_CB_CONFIG, ...config };
+  }
+
+  async call<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === 'open') {
+      if (this.shouldProbe()) {
+        this.transitionTo('half-open');
+      } else {
+        throw new CircuitOpenError(this.config.name);
+      }
+    }
+
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure(error);
+      throw error;
+    }
+  }
+
+  getState(): CircuitBreakerSnapshot {
+    if (this.state === 'open' && this.shouldProbe()) {
+      this.transitionTo('half-open');
+    }
+    return {
+      state: this.state,
+      failureCount: this.failureCount,
+      lastFailureAt: this.lastFailureAt,
+    };
+  }
+
+  isOpen(): boolean {
+    return this.state === 'open' && !this.shouldProbe();
+  }
+
+  reset(): void {
+    this.transitionTo('closed');
+    this.failureCount = 0;
+    this.lastFailureAt = null;
+  }
+
+  /** Synchronously record a failure (used by KeyPool to trip breaker without async) */
+  recordFailure(): void {
+    this.failureCount++;
+    this.lastFailureAt = Date.now();
+    if (this.state === 'half-open') {
+      this.transitionTo('open');
+      return;
+    }
+    if (this.failureCount >= this.config.failureThreshold) {
+      console.error(
+        `[LLM] CircuitBreaker:${this.config.name} threshold reached (${this.failureCount}/${this.config.failureThreshold}) — opening`,
+      );
+      this.transitionTo('open');
+    }
+  }
+
+  private onSuccess(): void {
+    this.failureCount = 0;
+    this.transitionTo('closed');
+  }
+
+  private onFailure(error: unknown): void {
+    if (!isRetryable(error)) {
+      return;
+    }
+
+    this.failureCount++;
+    this.lastFailureAt = Date.now();
+
+    if (this.state === 'half-open') {
+      this.transitionTo('open');
+      return;
+    }
+
+    if (this.failureCount >= this.config.failureThreshold) {
+      console.error(
+        `[LLM] CircuitBreaker:${this.config.name} threshold reached (${this.failureCount}/${this.config.failureThreshold}) — opening`,
+      );
+      this.transitionTo('open');
+    }
+  }
+
+  private shouldProbe(): boolean {
+    if (this.lastFailureAt === null) return false;
+    return Date.now() - this.lastFailureAt >= this.config.resetTimeoutMs;
+  }
+
+  private transitionTo(newState: CircuitState): void {
+    if (this.state !== newState) {
+      this.state = newState;
+    }
+  }
+}
+
+// =============================================================================
+// RETRY
+// =============================================================================
+
+const DEFAULT_RETRY_CONFIG: RetryConfig = {
+  maxAttempts: 3,
+  baseDelayMs: 1000,
+  maxDelayMs: 30000,
+  jitter: 0.1,
+};
+
+export function computeDelay(error: unknown, attempt: number, config: RetryConfig): number {
+  const retryAfterMs = (error as Partial<LLMError> & { retryAfterMs?: number })?.retryAfterMs;
+  if (retryAfterMs !== undefined && retryAfterMs > 0) {
+    return Math.min(retryAfterMs, config.maxDelayMs);
+  }
+
+  const exponential = config.baseDelayMs * Math.pow(2, attempt);
+  const capped = Math.min(exponential, config.maxDelayMs);
+
+  const jitterRange = capped * config.jitter;
+  const jitterOffset = (Math.random() * 2 - 1) * jitterRange;
+
+  return Math.max(0, Math.round(capped + jitterOffset));
+}
+
+export async function retry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>): Promise<T> {
+  const resolved: RetryConfig = { ...DEFAULT_RETRY_CONFIG, ...config };
+  if (resolved.maxAttempts < 1) {
+    throw new Error(`retry maxAttempts must be >= 1, got ${resolved.maxAttempts}`);
+  }
+  const shouldRetry = resolved.shouldRetry ?? isRetryable;
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt < resolved.maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      if (attempt >= resolved.maxAttempts - 1 || !shouldRetry(error)) {
+        throw error;
+      }
+
+      const delay = computeDelay(error, attempt, resolved);
+      resolved.onRetry?.(error, attempt + 1, delay);
+
+      await sleep(delay);
+    }
+  }
+
+  throw lastError;
+}
+
+// =============================================================================
+// RATE LIMIT HEADER PARSER
+// =============================================================================
+
+export function parseRateLimitHeaders(headers: Headers): RateLimitInfo {
+  const remaining = headers.get('x-ratelimit-remaining-requests');
+  const reset = headers.get('x-ratelimit-reset-requests');
+  const retryAfter = headers.get('retry-after');
+
+  return {
+    remaining:
+      remaining !== null ? (isNaN(parseInt(remaining, 10)) ? null : parseInt(remaining, 10)) : null,
+    resetMs: reset !== null ? parseResetDuration(reset) : null,
+    retryAfterMs: retryAfter !== null ? parseRetryAfter(retryAfter) : null,
+  };
+}
+
+function parseResetDuration(value: string): number | null {
+  let totalMs = 0;
+  let matched = false;
+
+  const minMatch = value.match(/(\d+)m(?!\s*s)/);
+  if (minMatch) {
+    totalMs += parseInt(minMatch[1], 10) * 60_000;
+    matched = true;
+  }
+
+  const msMatch = value.match(/(\d+)ms/);
+  if (msMatch) {
+    totalMs += parseInt(msMatch[1], 10);
+    matched = true;
+  }
+
+  const secMatch = value.match(/(\d+)(?<!m)s/);
+  if (secMatch) {
+    totalMs += parseInt(secMatch[1], 10) * 1000;
+    matched = true;
+  }
+
+  return matched ? totalMs : null;
+}
+
+function parseRetryAfter(value: string): number | null {
+  const seconds = parseFloat(value);
+  return isNaN(seconds) ? null : Math.ceil(seconds * 1000);
+}

package/src/planning/planner.ts

@@ -0,0 +1,151 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export type PlanStatus = 'draft' | 'approved' | 'executing' | 'completed';
+export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'skipped' | 'failed';
+
+export interface PlanTask {
+  id: string;
+  title: string;
+  description: string;
+  status: TaskStatus;
+  updatedAt: number;
+}
+
+export interface Plan {
+  id: string;
+  objective: string;
+  scope: string;
+  status: PlanStatus;
+  decisions: string[];
+  tasks: PlanTask[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface PlanStore {
+  version: string;
+  plans: Plan[];
+}
+
+export class Planner {
+  private filePath: string;
+  private store: PlanStore;
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+    this.store = this.load();
+  }
+
+  private load(): PlanStore {
+    if (!existsSync(this.filePath)) {
+      return { version: '1.0', plans: [] };
+    }
+    try {
+      const data = readFileSync(this.filePath, 'utf-8');
+      return JSON.parse(data) as PlanStore;
+    } catch {
+      return { version: '1.0', plans: [] };
+    }
+  }
+
+  private save(): void {
+    mkdirSync(dirname(this.filePath), { recursive: true });
+    writeFileSync(this.filePath, JSON.stringify(this.store, null, 2), 'utf-8');
+  }
+
+  create(params: {
+    objective: string;
+    scope: string;
+    decisions?: string[];
+    tasks?: Array<{ title: string; description: string }>;
+  }): Plan {
+    const now = Date.now();
+    const plan: Plan = {
+      id: `plan-${now}-${Math.random().toString(36).slice(2, 8)}`,
+      objective: params.objective,
+      scope: params.scope,
+      status: 'draft',
+      decisions: params.decisions ?? [],
+      tasks: (params.tasks ?? []).map((t, i) => ({
+        id: `task-${i + 1}`,
+        title: t.title,
+        description: t.description,
+        status: 'pending' as TaskStatus,
+        updatedAt: now,
+      })),
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.store.plans.push(plan);
+    this.save();
+    return plan;
+  }
+
+  get(planId: string): Plan | null {
+    return this.store.plans.find((p) => p.id === planId) ?? null;
+  }
+
+  list(): Plan[] {
+    return [...this.store.plans];
+  }
+
+  approve(planId: string): Plan {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+    if (plan.status !== 'draft')
+      throw new Error(`Cannot approve plan in '${plan.status}' status — must be 'draft'`);
+    plan.status = 'approved';
+    plan.updatedAt = Date.now();
+    this.save();
+    return plan;
+  }
+
+  startExecution(planId: string): Plan {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+    if (plan.status !== 'approved')
+      throw new Error(`Cannot execute plan in '${plan.status}' status — must be 'approved'`);
+    plan.status = 'executing';
+    plan.updatedAt = Date.now();
+    this.save();
+    return plan;
+  }
+
+  updateTask(planId: string, taskId: string, status: TaskStatus): Plan {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+    if (plan.status !== 'executing')
+      throw new Error(
+        `Cannot update tasks on plan in '${plan.status}' status — must be 'executing'`,
+      );
+    const task = plan.tasks.find((t) => t.id === taskId);
+    if (!task) throw new Error(`Task not found: ${taskId}`);
+    task.status = status;
+    task.updatedAt = Date.now();
+    plan.updatedAt = Date.now();
+    this.save();
+    return plan;
+  }
+
+  complete(planId: string): Plan {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+    if (plan.status !== 'executing')
+      throw new Error(`Cannot complete plan in '${plan.status}' status — must be 'executing'`);
+    plan.status = 'completed';
+    plan.updatedAt = Date.now();
+    this.save();
+    return plan;
+  }
+
+  getExecuting(): Plan[] {
+    return this.store.plans.filter((p) => p.status === 'executing');
+  }
+
+  getActive(): Plan[] {
+    return this.store.plans.filter(
+      (p) => p.status === 'draft' || p.status === 'approved' || p.status === 'executing',
+    );
+  }
+}