@soleri/forge 4.2.1 → 5.0.0

package/dist/templates/intelligence-loader.js

@@ -0,0 +1,43 @@
+export function generateIntelligenceLoader() {
+    return `import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { IntelligenceBundle, IntelligenceEntry } from './types.js';
+
+export function loadIntelligenceData(dataDir: string): IntelligenceEntry[] {
+  const entries: IntelligenceEntry[] = [];
+  let files: string[];
+  try {
+    files = readdirSync(dataDir).filter((f) => f.endsWith('.json'));
+  } catch {
+    console.warn('Intelligence data directory not found: ' + dataDir);
+    return entries;
+  }
+
+  for (const file of files) {
+    try {
+      const raw = readFileSync(join(dataDir, file), 'utf-8');
+      const bundle = JSON.parse(raw) as IntelligenceBundle;
+      if (!bundle.entries || !Array.isArray(bundle.entries)) continue;
+      for (const entry of bundle.entries) {
+        if (validateEntry(entry)) entries.push(entry);
+      }
+    } catch (err) {
+      console.warn('Failed to load ' + file + ': ' + (err instanceof Error ? err.message : err));
+    }
+  }
+  return entries;
+}
+
+function validateEntry(entry: IntelligenceEntry): boolean {
+  return (
+    typeof entry.id === 'string' && entry.id.length > 0 &&
+    ['pattern', 'anti-pattern', 'rule'].includes(entry.type) &&
+    typeof entry.title === 'string' && entry.title.length > 0 &&
+    typeof entry.description === 'string' && entry.description.length > 0 &&
+    ['critical', 'warning', 'suggestion'].includes(entry.severity) &&
+    Array.isArray(entry.tags)
+  );
+}
+`;
+}
+//# sourceMappingURL=intelligence-loader.js.map

package/dist/templates/intelligence-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intelligence-loader.js","sourceRoot":"","sources":["../../src/templates/intelligence-loader.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,0BAA0B;IACxC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCR,CAAC;AACF,CAAC"}

package/dist/templates/intelligence-types.d.ts

@@ -0,0 +1 @@
+export declare function generateIntelligenceTypes(): string;

package/dist/templates/intelligence-types.js

@@ -0,0 +1,24 @@
+export function generateIntelligenceTypes() {
+    return `export interface IntelligenceEntry {
+  id: string;
+  type: 'pattern' | 'anti-pattern' | 'rule';
+  domain: string;
+  title: string;
+  severity: 'critical' | 'warning' | 'suggestion';
+  description: string;
+  context?: string;
+  example?: string;
+  counterExample?: string;
+  why?: string;
+  tags: string[];
+  appliesTo?: string[];
+}
+
+export interface IntelligenceBundle {
+  domain: string;
+  version: string;
+  entries: IntelligenceEntry[];
+}
+`;
+}
+//# sourceMappingURL=intelligence-types.js.map

package/dist/templates/intelligence-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intelligence-types.js","sourceRoot":"","sources":["../../src/templates/intelligence-types.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,yBAAyB;IACvC,OAAO;;;;;;;;;;;;;;;;;;;;CAoBR,CAAC;AACF,CAAC"}

package/dist/templates/llm-key-pool.d.ts

@@ -0,0 +1,7 @@
+import type { AgentConfig } from '../types.js';
+/**
+ * Generate the LLM key pool file for a new agent.
+ * KeyPool manages multiple API keys with per-key circuit breakers.
+ * Uses config.id to resolve ~/.{agentId}/keys.json.
+ */
+export declare function generateLLMKeyPool(config: AgentConfig): string;

package/dist/templates/llm-key-pool.js

@@ -0,0 +1,211 @@
+/**
+ * Generate the LLM key pool file for a new agent.
+ * KeyPool manages multiple API keys with per-key circuit breakers.
+ * Uses config.id to resolve ~/.{agentId}/keys.json.
+ */
+export function generateLLMKeyPool(config) {
+    return `/**
+ * Key Pool — Multi-key management with auto-rotation
+ * Generated by Soleri — do not edit manually.
+ *
+ * Key loading priority:
+ * 1. ~/.${config.id}/keys.json → { "openai": ["sk-..."], "anthropic": ["sk-ant-..."] }
+ * 2. Fallback: OPENAI_API_KEY / ANTHROPIC_API_KEY env vars
+ * 3. Empty pool → graceful degradation
+ */
+
+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
+// =============================================================================
+
+class RateLimitRotationError extends Error {
+  retryable = true;
+  constructor() {
+    super('Rate limit rotation');
+    this.name = 'RateLimitRotationError';
+  }
+}
+
+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 {
+    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;
+}
+
+export function loadKeyPoolConfig(): KeyPoolFiles {
+  const keysFilePath = path.join(
+    homedir(),
+    '.${config.id}',
+    '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 },
+  };
+}
+`;
+}
+//# sourceMappingURL=llm-key-pool.js.map

package/dist/templates/llm-key-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-key-pool.js","sourceRoot":"","sources":["../../src/templates/llm-key-pool.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAmB;IACpD,OAAO;;;;;WAKE,MAAM,CAAC,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAiKZ,MAAM,CAAC,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoChB,CAAC;AACF,CAAC"}

package/dist/templates/llm-types.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generate the LLM types file for a new agent.
+ * Contains all types, LLMError class, and SecretString class.
+ */
+export declare function generateLLMTypes(): string;

package/dist/templates/llm-types.js

@@ -0,0 +1,161 @@
+/**
+ * Generate the LLM types file for a new agent.
+ * Contains all types, LLMError class, and SecretString class.
+ */
+export function generateLLMTypes() {
+    return `/**
+ * LLM Module Types
+ * Generated by Soleri — do not edit manually.
+ */
+
+// =============================================================================
+// SECRET STRING
+// =============================================================================
+
+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;
+  }
+}
+
+// =============================================================================
+// LLM ERROR
+// =============================================================================
+
+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);
+  }
+}
+
+// =============================================================================
+// LLM CALL TYPES
+// =============================================================================
+
+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;
+}
+
+// =============================================================================
+// CIRCUIT BREAKER TYPES
+// =============================================================================
+
+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;
+}
+
+// =============================================================================
+// KEY POOL TYPES
+// =============================================================================
+
+export interface KeyPoolConfig {
+  keys: string[];
+  preemptiveThreshold?: number;
+}
+
+export interface KeyStatus {
+  index: number;
+  circuitState: CircuitBreakerSnapshot;
+  remainingQuota: number | null;
+}
+
+// =============================================================================
+// ROUTING TYPES
+// =============================================================================
+
+export interface RouteEntry {
+  caller: string;
+  task?: string;
+  model: string;
+  provider: 'openai' | 'anthropic';
+}
+
+export interface RoutingConfig {
+  routes: RouteEntry[];
+  defaultOpenAIModel: string;
+  defaultAnthropicModel: string;
+}
+
+// =============================================================================
+// RATE LIMIT TYPES
+// =============================================================================
+
+export interface RateLimitInfo {
+  remaining: number | null;
+  resetMs: number | null;
+  retryAfterMs: number | null;
+}
+
+// =============================================================================
+// RETRY TYPES
+// =============================================================================
+
+export interface RetryConfig {
+  maxAttempts: number;
+  baseDelayMs: number;
+  maxDelayMs: number;
+  jitter: number;
+  shouldRetry?: (error: unknown) => boolean;
+  onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+}
+`;
+}
+//# sourceMappingURL=llm-types.js.map

package/dist/templates/llm-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-types.js","sourceRoot":"","sources":["../../src/templates/llm-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyJR,CAAC;AACF,CAAC"}

package/dist/templates/llm-utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generate the LLM utils file for a new agent.
+ * Contains CircuitBreaker, retry with backoff+jitter, and rate limit header parser.
+ */
+export declare function generateLLMUtils(): string;