@sns-myagent/cli 0.2.0 → 0.3.0

package/src/agents/resilience.ts

@@ -0,0 +1,332 @@
+/**
+ * Error resilience — SNS-MyAgent Phase 5.4
+ *
+ * Retry with exponential backoff, per-task timeout, circuit breaker,
+ * and fallback model chain.
+ */
+
+import { EventEmitter } from "node:events";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface RetryOptions {
+  /** Max attempts (default: 3) */
+  maxAttempts: number;
+  /** Base delay in ms (default: 1000) */
+  baseDelayMs: number;
+  /** Max delay in ms (default: 30000) */
+  maxDelayMs: number;
+  /** Backoff multiplier (default: 2) */
+  backoffMultiplier: number;
+  /** Jitter factor 0-1 (default: 0.2) */
+  jitterFactor: number;
+}
+
+export interface CircuitBreakerOptions {
+  /** Failures before opening (default: 3) */
+  failureThreshold: number;
+  /** Time in ms before half-open (default: 60000) */
+  resetTimeoutMs: number;
+  /** Successes in half-open to close (default: 2) */
+  successThreshold: number;
+}
+
+export type CircuitState = "closed" | "open" | "half_open";
+
+export interface TaskResult<T> {
+  success: boolean;
+  result?: T;
+  error?: Error;
+  attempts: number;
+  totalTimeMs: number;
+  fromCache?: boolean;
+}
+
+// ─── Retry with Exponential Backoff ──────────────────────────────────────────
+
+const DEFAULT_RETRY: RetryOptions = {
+  maxAttempts: 3,
+  baseDelayMs: 1_000,
+  maxDelayMs: 30_000,
+  backoffMultiplier: 2,
+  jitterFactor: 0.2,
+};
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: Partial<RetryOptions> = {},
+): Promise<TaskResult<T>> {
+  const opts = { ...DEFAULT_RETRY, ...options };
+  const startTime = Date.now();
+  let lastError: Error | undefined;
+
+  for (let attempt = 1; attempt <= opts.maxAttempts; attempt++) {
+    try {
+      const result = await fn();
+      return {
+        success: true,
+        result,
+        attempts: attempt,
+        totalTimeMs: Date.now() - startTime,
+      };
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+
+      if (attempt < opts.maxAttempts) {
+        // Exponential backoff with jitter
+        const baseDelay = opts.baseDelayMs * Math.pow(opts.backoffMultiplier, attempt - 1);
+        const jitter = baseDelay * opts.jitterFactor * (Math.random() * 2 - 1);
+        const delay = Math.min(Math.max(0, baseDelay + jitter), opts.maxDelayMs);
+        await sleep(delay);
+      }
+    }
+  }
+
+  return {
+    success: false,
+    error: lastError,
+    attempts: opts.maxAttempts,
+    totalTimeMs: Date.now() - startTime,
+  };
+}
+
+// ─── Circuit Breaker ─────────────────────────────────────────────────────────
+
+const DEFAULT_CIRCUIT: CircuitBreakerOptions = {
+  failureThreshold: 3,
+  resetTimeoutMs: 60_000,
+  successThreshold: 2,
+};
+
+export class CircuitBreaker extends EventEmitter {
+  readonly #key: string;
+  readonly #options: CircuitBreakerOptions;
+  #state: CircuitState = "closed";
+  #failureCount = 0;
+  #successCount = 0;
+  #lastFailureTime = 0;
+  #nextAttemptTime = 0;
+
+  constructor(key: string, options: Partial<CircuitBreakerOptions> = {}) {
+    super();
+    this.#key = key;
+    this.#options = { ...DEFAULT_CIRCUIT, ...options };
+  }
+
+  get key(): string { return this.#key; }
+  get state(): CircuitState { return this.#state; }
+  get failureCount(): number { return this.#failureCount; }
+
+  /**
+   * Check if the circuit allows execution.
+   */
+  canExecute(): boolean {
+    if (this.#state === "closed") return true;
+
+    if (this.#state === "open") {
+      if (Date.now() >= this.#nextAttemptTime) {
+        this.#transitionTo("half_open");
+        return true;
+      }
+      return false;
+    }
+
+    // half_open: allow one attempt
+    return true;
+  }
+
+  /**
+   * Record a successful execution.
+   */
+  recordSuccess(): void {
+    if (this.#state === "half_open") {
+      this.#successCount++;
+      if (this.#successCount >= this.#options.successThreshold) {
+        this.#transitionTo("closed");
+      }
+    } else {
+      this.#failureCount = 0;
+    }
+  }
+
+  /**
+   * Record a failed execution.
+   */
+  recordFailure(): void {
+    this.#lastFailureTime = Date.now();
+
+    if (this.#state === "half_open") {
+      this.#transitionTo("open");
+      return;
+    }
+
+    this.#failureCount++;
+    if (this.#failureCount >= this.#options.failureThreshold) {
+      this.#transitionTo("open");
+    }
+  }
+
+  /**
+   * Execute a function through the circuit breaker.
+   */
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    if (!this.canExecute()) {
+      throw new CircuitBreakerOpenError(
+        `Circuit breaker [${this.#key}] is OPEN. Retry after ${new Date(this.#nextAttemptTime).toISOString()}`
+      );
+    }
+
+    try {
+      const result = await fn();
+      this.recordSuccess();
+      return result;
+    } catch (err) {
+      this.recordFailure();
+      throw err;
+    }
+  }
+
+  /**
+   * Reset circuit breaker to closed state.
+   */
+  reset(): void {
+    this.#state = "closed";
+    this.#failureCount = 0;
+    this.#successCount = 0;
+    this.#lastFailureTime = 0;
+    this.#nextAttemptTime = 0;
+  }
+
+  /** Get stats for display */
+  stats(): { key: string; state: CircuitState; failures: number; nextAttempt?: string } {
+    return {
+      key: this.#key,
+      state: this.#state,
+      failures: this.#failureCount,
+      nextAttempt: this.#state === "open" ? new Date(this.#nextAttemptTime).toISOString() : undefined,
+    };
+  }
+
+  #transitionTo(state: CircuitState): void {
+    const prev = this.#state;
+    this.#state = state;
+
+    if (state === "open") {
+      this.#nextAttemptTime = Date.now() + this.#options.resetTimeoutMs;
+      this.#successCount = 0;
+    }
+    if (state === "closed") {
+      this.#failureCount = 0;
+      this.#successCount = 0;
+      this.#nextAttemptTime = 0;
+    }
+    if (state === "half_open") {
+      this.#successCount = 0;
+    }
+
+    this.emit("state_change", { key: this.#key, from: prev, to: state });
+  }
+}
+
+// ─── Circuit Breaker Registry ────────────────────────────────────────────────
+
+const breakers = new Map<string, CircuitBreaker>();
+
+/**
+ * Get or create a circuit breaker for a provider/model key.
+ */
+export function getCircuitBreaker(key: string, options?: Partial<CircuitBreakerOptions>): CircuitBreaker {
+  if (!breakers.has(key)) {
+    breakers.set(key, new CircuitBreaker(key, options));
+  }
+  return breakers.get(key)!;
+}
+
+/**
+ * Get all circuit breaker stats.
+ */
+export function getAllCircuitBreakerStats(): Array<{ key: string; state: CircuitState; failures: number; nextAttempt?: string }> {
+  return [...breakers.values()].map(b => b.stats());
+}
+
+// ─── Task Timeout ────────────────────────────────────────────────────────────
+
+/**
+ * Execute with timeout. Rejects with TimeoutError if exceeded.
+ */
+export async function withTimeout<T>(
+  fn: () => Promise<T>,
+  timeoutMs: number,
+  label = "task",
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new TimeoutError(`[${label}] timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    fn().then(
+      (result) => { clearTimeout(timer); resolve(result); },
+      (err) => { clearTimeout(timer); reject(err); },
+    );
+  });
+}
+
+// ─── Fallback Chain ─────────────────────────────────────────────────────────
+
+/**
+ * Try primary fn first, then fallbacks in order.
+ * Returns first successful result.
+ */
+export async function withFallback<T>(
+  fns: Array<() => Promise<T>>,
+  options: Partial<RetryOptions> = {},
+): Promise<TaskResult<T>> {
+  const startTime = Date.now();
+  let lastError: Error | undefined;
+  let totalAttempts = 0;
+
+  for (const fn of fns) {
+    const result = await withRetry(fn, { ...options, maxAttempts: 1 });
+    totalAttempts += result.attempts;
+
+    if (result.success) {
+      return {
+        success: true,
+        result: result.result,
+        attempts: totalAttempts,
+        totalTimeMs: Date.now() - startTime,
+      };
+    }
+
+    lastError = result.error;
+  }
+
+  return {
+    success: false,
+    error: lastError,
+    attempts: totalAttempts,
+    totalTimeMs: Date.now() - startTime,
+  };
+}
+
+// ─── Errors ──────────────────────────────────────────────────────────────────
+
+export class CircuitBreakerOpenError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CircuitBreakerOpenError";
+  }
+}
+
+export class TimeoutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/agents/strategies/best-of-n.ts

@@ -0,0 +1,108 @@
+/**
+ * Best-of-N Strategy — SNS-MyAgent Phase 5.3d
+ *
+ * Generate N candidates from same agent/role → Rank by scoring agent → Pick best.
+ */
+
+import type { AgentResponse, EnsembleResult, EnsembleStrategy } from "./types.js";
+import { aggregateTokens } from "./types.js";
+
+export interface BestOfNOptions {
+  /** Number of candidates to generate (default: 4) */
+  n?: number;
+  /** Scorer agent role (default: same as first agent) */
+  scorerRole?: string;
+}
+
+export class BestOfNStrategy implements EnsembleStrategy {
+  readonly name = "best_of_n";
+  readonly #n: number;
+  readonly #scorerRole?: string;
+
+  constructor(options: BestOfNOptions = {}) {
+    this.#n = options.n ?? 4;
+    this.#scorerRole = options.scorerRole;
+  }
+
+  async execute(
+    prompt: string,
+    agents: string[],
+    executeAgent: (role: string, prompt: string) => Promise<AgentResponse>,
+  ): Promise<EnsembleResult> {
+    if (agents.length === 0) {
+      throw new Error("Best-of-N requires at least 1 agent");
+    }
+
+    const generatorRole = agents[0];
+    const scorerRole = this.#scorerRole ?? generatorRole;
+    const startTime = Date.now();
+    const allResponses: AgentResponse[] = [];
+
+    // Generate N candidates in parallel
+    const candidates = await Promise.all(
+      Array.from({ length: this.#n }, (_, i) =>
+        executeAgent(generatorRole, `${prompt}\n\n[Candidate ${i + 1}/${this.#n}]`),
+      ),
+    );
+    allResponses.push(...candidates);
+
+    // Score each candidate
+    const scoredCandidates = await this.#scoreCandidates(candidates, scorerRole, executeAgent, prompt);
+    allResponses.push(...scoredCandidates.scores);
+
+    // Pick highest scored
+    const bestIdx = scoredCandidates.ranking[0];
+    const winner = candidates[bestIdx];
+
+    return {
+      final: winner.content,
+      responses: allResponses,
+      strategy: this.name,
+      rounds: 2,
+      totalTimeMs: Date.now() - startTime,
+      totalTokens: aggregateTokens(allResponses),
+      winner: generatorRole,
+    };
+  }
+
+  async #scoreCandidates(
+    candidates: AgentResponse[],
+    scorerRole: string,
+    executeAgent: (role: string, prompt: string) => Promise<AgentResponse>,
+    originalPrompt: string,
+  ): Promise<{ scores: AgentResponse[]; ranking: number[] }> {
+    const scores: AgentResponse[] = [];
+    const ranking = Array.from({ length: candidates.length }, (_, i) => i);
+
+    for (let i = 0; i < candidates.length; i++) {
+      const scorePrompt = this.#buildScorePrompt(originalPrompt, candidates[i].content);
+      const scoreResponse = await executeAgent(scorerRole, scorePrompt);
+      scores.push(scoreResponse);
+      candidates[i].score = this.#extractScore(scoreResponse);
+    }
+
+    // Sort by score descending
+    ranking.sort((a, b) => (candidates[b].score ?? 0) - (candidates[a].score ?? 0));
+
+    return { scores, ranking };
+  }
+
+  #buildScorePrompt(originalPrompt: string, candidate: string): string {
+    return `Original task: ${originalPrompt}
+
+Candidate response to evaluate:
+${candidate}
+
+Rate this response 0-1 on: correctness, completeness, clarity, relevance.
+Output format:
+SCORE: <0-1>
+REASONING: <brief>`;
+  }
+
+  #extractScore(scoreResponse: AgentResponse): number {
+    const match = scoreResponse.content.match(/SCORE:\s*([0-9]*\.?[0-9]+)/i);
+    if (match) return Math.min(1, Math.max(0, Number.parseFloat(match[1])));
+    if (scoreResponse.score !== undefined) return scoreResponse.score;
+    return 0.5;
+  }
+}

package/src/agents/strategies/consensus.ts

@@ -0,0 +1,105 @@
+/**
+ * Consensus Strategy — SNS-MyAgent Phase 5.3b
+ *
+ * Spawn N agents with same prompt → Pick majority/best answer.
+ */
+
+import type { AgentResponse, EnsembleResult, EnsembleStrategy } from "./types.js";
+import { aggregateTokens } from "./types.js";
+
+export interface ConsensusOptions {
+  /** Number of agents to spawn (default: 3) */
+  n?: number;
+  /** Consensus threshold 0-1 (default: 0.6) */
+  threshold?: number;
+  /** Comparison function: "exact" | "semantic" (default: "exact") */
+  compareMode?: "exact" | "semantic";
+}
+
+export class ConsensusStrategy implements EnsembleStrategy {
+  readonly name = "consensus";
+  readonly #n: number;
+  readonly #threshold: number;
+  readonly #compareMode: "exact" | "semantic";
+
+  constructor(options: ConsensusOptions = {}) {
+    this.#n = options.n ?? 3;
+    this.#threshold = options.threshold ?? 0.6;
+    this.#compareMode = options.compareMode ?? "exact";
+  }
+
+  async execute(
+    prompt: string,
+    agents: string[],
+    executeAgent: (role: string, prompt: string) => Promise<AgentResponse>,
+  ): Promise<EnsembleResult> {
+    if (agents.length === 0) {
+      throw new Error("Consensus requires at least 1 agent");
+    }
+
+    const startTime = Date.now();
+    const allResponses: AgentResponse[] = [];
+
+    // Spawn N agents in parallel (cycle through available agents)
+    const candidates = await Promise.all(
+      Array.from({ length: this.#n }, async (_, i) => {
+        const role = agents[i % agents.length];
+        const response = await executeAgent(role, `${prompt}\n\n[Consensus attempt ${i + 1}/${this.#n}]`);
+        allResponses.push(response);
+        return response;
+      }),
+    );
+
+    // Find consensus
+    const { winner, agreement } = this.#findConsensus(candidates);
+
+    return {
+      final: winner.content,
+      responses: allResponses,
+      strategy: this.name,
+      rounds: 1,
+      totalTimeMs: Date.now() - startTime,
+      totalTokens: aggregateTokens(allResponses),
+      winner: winner.role,
+      metadata: { agreement, threshold: this.#threshold, met: agreement >= this.#threshold },
+    };
+  }
+
+  #findConsensus(candidates: AgentResponse[]): { winner: AgentResponse; agreement: number } {
+    if (candidates.length === 1) return { winner: candidates[0], agreement: 1 };
+
+    // Group similar responses
+    const groups: AgentResponse[][] = [];
+
+    for (const candidate of candidates) {
+      let placed = false;
+      for (const group of groups) {
+        if (this.#similar(candidate.content, group[0].content)) {
+          group.push(candidate);
+          placed = true;
+          break;
+        }
+      }
+      if (!placed) groups.push([candidate]);
+    }
+
+    // Pick largest group
+    groups.sort((a, b) => b.length - a.length);
+    const bestGroup = groups[0];
+    const agreement = bestGroup.length / candidates.length;
+
+    // Winner = first in best group
+    return { winner: bestGroup[0], agreement };
+  }
+
+  #similar(a: string, b: string): boolean {
+    if (this.#compareMode === "exact") return a.trim() === b.trim();
+
+    // Simple semantic: Jaccard similarity on words
+    const wordsA = new Set(a.toLowerCase().split(/\W+/).filter(Boolean));
+    const wordsB = new Set(b.toLowerCase().split(/\W+/).filter(Boolean));
+    const intersection = [...wordsA].filter(w => wordsB.has(w)).length;
+    const union = wordsA.size + wordsB.size - intersection;
+    return union > 0 ? intersection / union >= 0.7 : false;
+  }
+}

package/src/agents/strategies/critic.ts

@@ -0,0 +1,131 @@
+/**
+ * Critic Strategy — SNS-MyAgent Phase 5.3c
+ *
+ * Generator agent produces response → Critic agent reviews → Iterate up to max_rounds.
+ */
+
+import type { AgentResponse, EnsembleResult, EnsembleStrategy } from "./types.js";
+import { aggregateTokens } from "./types.js";
+
+export interface CriticOptions {
+  /** Max iteration rounds (default: 2) */
+  maxRounds?: number;
+}
+
+export class CriticStrategy implements EnsembleStrategy {
+  readonly name = "critic";
+  readonly #maxRounds: number;
+
+  constructor(options: CriticOptions = {}) {
+    this.#maxRounds = options.maxRounds ?? 2;
+  }
+
+  async execute(
+    prompt: string,
+    agents: string[],
+    executeAgent: (role: string, prompt: string) => Promise<AgentResponse>,
+  ): Promise<EnsembleResult> {
+    if (agents.length < 2) {
+      throw new Error("Critic strategy requires at least 2 agents: [generator, critic]");
+    }
+
+    const [generatorRole, criticRole] = agents;
+    const startTime = Date.now();
+    let currentPrompt = prompt;
+    const allResponses: AgentResponse[] = [];
+    let rounds = 0;
+
+    for (let round = 1; round <= this.#maxRounds; round++) {
+      rounds = round;
+
+      // Generator produces response
+      const genResponse = await executeAgent(generatorRole, currentPrompt);
+      allResponses.push(genResponse);
+
+      if (round === this.#maxRounds) {
+        // Last round: return generator's final response
+        return {
+          final: genResponse.content,
+          responses: allResponses,
+          strategy: this.name,
+          rounds,
+          totalTimeMs: Date.now() - startTime,
+          totalTokens: aggregateTokens(allResponses),
+          winner: generatorRole,
+        };
+      }
+
+      // Critic reviews generator's response
+      const criticPrompt = this.#buildCriticPrompt(prompt, genResponse.content);
+      const criticResponse = await executeAgent(criticRole, criticPrompt);
+      allResponses.push(criticResponse);
+
+      // Check if critic is satisfied (score >= 0.7 or explicit "approved")
+      const satisfied = this.#isSatisfied(criticResponse);
+      if (satisfied) {
+        return {
+          final: genResponse.content,
+          responses: allResponses,
+          strategy: this.name,
+          rounds,
+          totalTimeMs: Date.now() - startTime,
+          totalTokens: aggregateTokens(allResponses),
+          winner: generatorRole,
+        };
+      }
+
+      // Next iteration: improve based on critic feedback
+      currentPrompt = this.#buildImprovementPrompt(prompt, genResponse.content, criticResponse.content);
+    }
+
+    // Max rounds reached, return last generator response
+    const finalGenResponse = allResponses[allResponses.length - 2]!;
+    return {
+      final: finalGenResponse.content,
+      responses: allResponses,
+      strategy: this.name,
+      rounds,
+      totalTimeMs: Date.now() - startTime,
+      totalTokens: aggregateTokens(allResponses),
+      winner: generatorRole,
+    };
+  }
+
+  #buildCriticPrompt(originalPrompt: string, response: string): string {
+    return `Original task: ${originalPrompt}
+
+Candidate response:
+${response}
+
+Critique this response. Provide:
+1. Score 0-1 (1 = excellent, 0 = poor)
+2. Specific issues/weaknesses
+3. Suggested improvements
+4. Verdict: "APPROVED" if score >= 0.7, otherwise "NEEDS IMPROVEMENT"
+
+Format:
+SCORE: <number>
+ISSUES: <list>
+IMPROVEMENTS: <list>
+VERDICT: <APPROVED|NEEDS IMPROVEMENT>`;
+  }
+
+  #isSatisfied(criticResponse: AgentResponse): boolean {
+    const content = criticResponse.content.toUpperCase();
+    if (content.includes("APPROVED")) return true;
+    if (criticResponse.score !== undefined && criticResponse.score >= 0.7) return true;
+    return false;
+  }
+
+  #buildImprovementPrompt(originalPrompt: string, lastResponse: string, criticFeedback: string): string {
+    return `Original task: ${originalPrompt}
+
+Previous attempt:
+${lastResponse}
+
+Critic feedback:
+${criticFeedback}
+
+Produce an IMPROVED response addressing all issues raised. Do not repeat the same mistakes.`;
+  }
+}