@sns-myagent/cli 0.2.0 → 0.3.0

package/src/agents/config.ts

@@ -0,0 +1,367 @@
+/**
+ * agents.yaml config system — SNS-MyAgent Phase 5.2
+ *
+ * Parses custom agent roles from ~/.sns-myagent/agents.yaml (user-level)
+ * or ./.sns-myagent/agents.yaml (project-level).
+ *
+ * Falls back to bundled Pi agents when no custom config exists.
+ * Hot-reloads on file change via fs.watch.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { EventEmitter } from "node:events";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface AgentRoleConfig {
+  /** Model to use (e.g. "claude-sonnet", "gpt-4o", "perplexity") */
+  model: string;
+  /** Provider (e.g. "anthropic", "openai", "custom") */
+  provider?: string;
+  /** Tools this agent can use */
+  tools?: string[];
+  /** Custom system prompt override */
+  system_prompt?: string;
+  /** Thinking level: low | medium | high | max */
+  thinking_level?: string;
+  /** Max tokens for output */
+  max_tokens?: number;
+  /** Temperature override */
+  temperature?: number;
+}
+
+export interface EnsembleConfig {
+  /** Strategy: consensus | critic | best_of_n */
+  strategy: "consensus" | "critic" | "best_of_n";
+  /** For consensus/best_of_n: list of agent roles to spawn */
+  agents?: string[];
+  /** For critic: generator agent */
+  generator?: string;
+  /** For critic: critic agent */
+  critic?: string;
+  /** Max iteration rounds (critic strategy) */
+  max_rounds?: number;
+  /** Consensus threshold 0-1 (consensus strategy) */
+  threshold?: number;
+  /** Number of candidates (best_of_n strategy) */
+  n?: number;
+}
+
+export interface AgentsConfig {
+  /** Named agent roles */
+  agents: Record<string, AgentRoleConfig>;
+  /** Named ensemble strategies */
+  ensembles?: Record<string, EnsembleConfig>;
+  /** Default agent for unspecified tasks */
+  default_agent?: string;
+  /** Global concurrency limit */
+  max_concurrency?: number;
+  /** Global timeout per task (ms) */
+  task_timeout_ms?: number;
+  /** Retry attempts on failure */
+  retry_attempts?: number;
+}
+
+// ─── Config Paths ────────────────────────────────────────────────────────────
+
+const USER_CONFIG_DIR = path.join(os.homedir(), ".sns-myagent");
+const USER_CONFIG_PATH = path.join(USER_CONFIG_DIR, "agents.yaml");
+const PROJECT_CONFIG_FILENAME = ".sns-myagent/agents.yaml";
+
+function findProjectConfig(): string | null {
+  let dir = process.cwd();
+  const root = path.parse(dir).root;
+  while (dir !== root) {
+    const candidate = path.join(dir, PROJECT_CONFIG_FILENAME);
+    if (fs.existsSync(candidate)) return candidate;
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+// ─── YAML Parser (lightweight, no deps) ─────────────────────────────────────
+
+/**
+ * Minimal YAML parser for agents.yaml structure.
+ * Handles: top-level keys, nested objects, arrays, strings, numbers, booleans.
+ * NOT a full YAML parser — sufficient for our flat config schema.
+ */
+function parseYamlSimple(text: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const lines = text.split("\n");
+  let currentKey = "";
+  let currentSubObj: Record<string, unknown> | null = null;
+  let currentArray: string[] | null = null;
+  let inMultiline = false;
+  let multilineKey = "";
+  let multilineIndent = 0;
+  let multilineLines: string[] = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, "");
+    // Skip empty lines and comments
+    if (/^\s*$/.test(line) || /^\s*#/.test(line)) continue;
+
+    const indent = line.search(/\S/);
+    const trimmed = line.trim();
+
+    // Handle multiline strings (|)
+    if (inMultiline) {
+      if (indent > multilineIndent) {
+        multilineLines.push(line.slice(multilineIndent + 2));
+        continue;
+      } else {
+        // End multiline
+        if (currentSubObj) {
+          currentSubObj[multilineKey] = multilineLines.join("\n");
+        } else {
+          result[multilineKey] = multilineLines.join("\n");
+        }
+        inMultiline = false;
+        multilineLines = [];
+      }
+    }
+
+    // Top-level key
+    if (indent === 0 && trimmed.includes(":")) {
+      const colonIdx = trimmed.indexOf(":");
+      currentKey = trimmed.slice(0, colonIdx).trim();
+      const rest = trimmed.slice(colonIdx + 1).trim();
+      if (rest === "|" || rest === ">") {
+        inMultiline = true;
+        multilineKey = currentKey;
+        multilineIndent = 0;
+        multilineLines = [];
+      } else if (rest === "" || rest === "{}") {
+        result[currentKey] = {};
+      } else {
+        result[currentKey] = parseValue(rest);
+      }
+      currentSubObj = null;
+      currentArray = null;
+      continue;
+    }
+
+    // Nested key (indent > 0)
+    if (indent > 0 && trimmed.includes(":") && !trimmed.startsWith("-")) {
+      const colonIdx = trimmed.indexOf(":");
+      const subKey = trimmed.slice(0, colonIdx).trim();
+      const rest = trimmed.slice(colonIdx + 1).trim();
+
+      // Ensure parent exists as object
+      if (!result[currentKey] || typeof result[currentKey] !== "object") {
+        result[currentKey] = {};
+      }
+      const parent = result[currentKey] as Record<string, unknown>;
+
+      if (rest === "|" || rest === ">") {
+        inMultiline = true;
+        multilineKey = subKey;
+        multilineIndent = indent;
+        multilineLines = [];
+      } else if (rest === "") {
+        // Could be a sub-sub-object; create placeholder
+        if (!parent[subKey]) parent[subKey] = {};
+      } else {
+        parent[subKey] = parseValue(rest);
+      }
+      currentSubObj = parent;
+      currentArray = null;
+      continue;
+    }
+
+    // Array item
+    if (trimmed.startsWith("- ")) {
+      const value = trimmed.slice(2).trim();
+      if (!result[currentKey]) {
+        result[currentKey] = [];
+      }
+      const arr = result[currentKey] as string[];
+      arr.push(parseValue(value) as string);
+      currentArray = arr;
+      continue;
+    }
+
+    // Sub-level array item (indented)
+    if (indent > 0 && trimmed.startsWith("- ")) {
+      const value = trimmed.slice(2).trim();
+      if (currentSubObj) {
+        // Find the last key in currentSubObj that's an array
+        const keys = Object.keys(currentSubObj);
+        const lastKey = keys[keys.length - 1];
+        if (lastKey && Array.isArray(currentSubObj[lastKey])) {
+          (currentSubObj[lastKey] as string[]).push(parseValue(value) as string);
+        }
+      }
+      continue;
+    }
+  }
+
+  // Close any open multiline
+  if (inMultiline && multilineLines.length > 0) {
+    if (currentSubObj) {
+      currentSubObj[multilineKey] = multilineLines.join("\n");
+    } else {
+      result[multilineKey] = multilineLines.join("\n");
+    }
+  }
+
+  return result;
+}
+
+function parseValue(raw: string): unknown {
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (raw === "null" || raw === "~") return null;
+  if (/^\d+$/.test(raw)) return Number.parseInt(raw, 10);
+  if (/^\d+\.\d+$/.test(raw)) return Number.parseFloat(raw);
+  // Strip quotes
+  if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+    return raw.slice(1, -1);
+  }
+  return raw;
+}
+
+// ─── Config Loader ──────────────────────────────────────────────────────────
+
+const DEFAULT_CONFIG: AgentsConfig = {
+  agents: {},
+  ensembles: {},
+  default_agent: "task",
+  max_concurrency: 4,
+  task_timeout_ms: 120_000,
+  retry_attempts: 3,
+};
+
+function parseConfig(raw: Record<string, unknown>): AgentsConfig {
+  const config: AgentsConfig = { ...DEFAULT_CONFIG };
+
+  if (raw.agents && typeof raw.agents === "object") {
+    config.agents = raw.agents as Record<string, AgentRoleConfig>;
+  }
+  if (raw.ensembles && typeof raw.ensembles === "object") {
+    config.ensembles = raw.ensembles as Record<string, EnsembleConfig>;
+  }
+  if (typeof raw.default_agent === "string") {
+    config.default_agent = raw.default_agent;
+  }
+  if (typeof raw.max_concurrency === "number") {
+    config.max_concurrency = raw.max_concurrency;
+  }
+  if (typeof raw.task_timeout_ms === "number") {
+    config.task_timeout_ms = raw.task_timeout_ms;
+  }
+  if (typeof raw.retry_attempts === "number") {
+    config.retry_attempts = raw.retry_attempts;
+  }
+
+  return config;
+}
+
+// ─── Singleton + Hot Reload ─────────────────────────────────────────────────
+
+class AgentsConfigManager extends EventEmitter {
+  #config: AgentsConfig = DEFAULT_CONFIG;
+  #watcher: fs.FSWatcher | null = null;
+  #configPath: string | null = null;
+
+  get config(): AgentsConfig {
+    return this.#config;
+  }
+
+  get configPath(): string | null {
+    return this.#configPath;
+  }
+
+  /**
+   * Load config from project-level, then user-level, then defaults.
+   * Project overrides user which overrides defaults.
+   */
+  load(): AgentsConfig {
+    const projectPath = findProjectConfig();
+    const userPath = fs.existsSync(USER_CONFIG_PATH) ? USER_CONFIG_PATH : null;
+    const loadPath = projectPath ?? userPath;
+
+    if (!loadPath) {
+      this.#config = DEFAULT_CONFIG;
+      this.#configPath = null;
+      return this.#config;
+    }
+
+    try {
+      const text = fs.readFileSync(loadPath, "utf-8");
+      const raw = parseYamlSimple(text);
+      this.#config = parseConfig(raw);
+      this.#configPath = loadPath;
+    } catch {
+      this.#config = DEFAULT_CONFIG;
+      this.#configPath = null;
+    }
+
+    return this.#config;
+  }
+
+  /**
+   * Start watching the config file for changes.
+   * Emits 'reload' event when config changes.
+   */
+  watch(): void {
+    if (this.#watcher) return;
+    if (!this.#configPath) return;
+
+    this.#watcher = fs.watch(this.#configPath, { persistent: false }, () => {
+      this.load();
+      this.emit("reload", this.#config);
+    });
+  }
+
+  stopWatching(): void {
+    if (this.#watcher) {
+      this.#watcher.close();
+      this.#watcher = null;
+    }
+  }
+
+  /**
+   * Resolve a role to its config. Falls back to default_agent.
+   */
+  resolveRole(roleName: string): AgentRoleConfig | null {
+    return this.#config.agents[roleName] ?? null;
+  }
+
+  /**
+   * Get ensemble config by name.
+   */
+  getEnsemble(name: string): EnsembleConfig | null {
+    return this.#config.ensembles?.[name] ?? null;
+  }
+
+  /**
+   * List all configured agent role names.
+   */
+  listRoles(): string[] {
+    return Object.keys(this.#config.agents);
+  }
+
+  /**
+   * List all configured ensemble names.
+   */
+  listEnsembles(): string[] {
+    return Object.keys(this.#config.ensembles ?? {});
+  }
+}
+
+// Singleton
+let _instance: AgentsConfigManager | null = null;
+
+export function getAgentsConfig(): AgentsConfigManager {
+  if (!_instance) {
+    _instance = new AgentsConfigManager();
+    _instance.load();
+  }
+  return _instance;
+}
+
+export { AgentsConfigManager, DEFAULT_CONFIG, parseYamlSimple };

package/src/agents/ensemble.ts

@@ -0,0 +1,224 @@
+/**
+ * Ensemble Orchestrator — SNS-MyAgent Phase 5.3e
+ *
+ * Main entry point for multi-agent ensemble execution.
+ * Loads agents.yaml config, resolves strategy, executes with resilience.
+ */
+
+import { getAgentsConfig } from "./config.js";
+import * as resilience from "./resilience.js";
+import type { AgentRoleConfig } from "./config.js";
+import type { AgentResponse, EnsembleResult, EnsembleStrategy } from "./strategies/types.js";
+import { ConsensusStrategy } from "./strategies/consensus.js";
+import { CriticStrategy } from "./strategies/critic.js";
+import { BestOfNStrategy } from "./strategies/best-of-n.js";
+
+export interface EnsembleOptions {
+  /** Ensemble name from agents.yaml, or strategy name inline */
+  ensemble?: string;
+  /** Inline strategy override: "consensus" | "critic" | "best_of_n" */
+  strategy?: "consensus" | "critic" | "best_of_n";
+  /** Agent roles to use (overrides ensemble config) */
+  agents?: string[];
+  /** Strategy-specific options */
+  strategyOptions?: Record<string, unknown>;
+  /** Override max concurrency */
+  maxConcurrency?: number;
+  /** Override task timeout (ms) */
+  taskTimeoutMs?: number;
+  /** Enable resilience (retry/timeout/circuit-breaker) */
+  resilient?: boolean;
+}
+
+export interface EnsembleExecutionResult extends EnsembleResult {
+  configUsed: {
+    ensemble?: string;
+    strategy: string;
+    agents: string[];
+  };
+  costBreakdown: Array<{ role: string; model: string; inputTokens: number; outputTokens: number; costUsd?: number }>;
+}
+
+/**
+ * Execute an ensemble task.
+ *
+ * @param prompt - User prompt/task description
+ * @param executeAgent - Function to spawn an agent and get response
+ * @param options - Ensemble configuration
+ * @returns Ensemble result with cost breakdown
+ */
+export async function executeEnsemble(
+  prompt: string,
+  executeAgent: (role: string, prompt: string) => Promise<AgentResponse>,
+  options: EnsembleOptions = {},
+): Promise<EnsembleExecutionResult> {
+  const config = getAgentsConfig().config;
+
+  // Resolve ensemble/strategy/agents
+  const { strategyName, agentRoles, strategyOpts } = resolveEnsembleConfig(config, options);
+
+  // Get strategy instance
+  const strategy = createStrategy(strategyName, strategyOpts);
+
+  // Execute with resilience if enabled
+  const executeWithResilience = options.resilient !== false
+    ? createResilientExecutor(config, options)
+    : executeAgent;
+
+  const result = await strategy.execute(prompt, agentRoles, executeWithResilience);
+
+  // Build cost breakdown
+  const costBreakdown = buildCostBreakdown(result, agentRoles, config);
+
+  return {
+    ...result,
+    configUsed: {
+      ensemble: options.ensemble,
+      strategy: strategyName,
+      agents: agentRoles,
+    },
+    costBreakdown,
+  };
+}
+
+function resolveEnsembleConfig(
+  config: ReturnType<typeof getAgentsConfig>["config"],
+  options: EnsembleOptions,
+): { strategyName: string; agentRoles: string[]; strategyOpts: Record<string, unknown> } {
+  // 1. Explicit ensemble name from agents.yaml
+  if (options.ensemble) {
+    const ensemble = config.ensembles?.[options.ensemble];
+    if (!ensemble) throw new Error(`Ensemble "${options.ensemble}" not found in agents.yaml`);
+    return {
+      strategyName: ensemble.strategy,
+      agentRoles: options.agents ?? ensemble.agents ?? [],
+      strategyOpts: { ...ensemble, ...options.strategyOptions },
+    };
+  }
+
+  // 2. Inline strategy
+  if (options.strategy) {
+    return {
+      strategyName: options.strategy,
+      agentRoles: options.agents ?? (config.default_agent ? [config.default_agent] : []),
+      strategyOpts: options.strategyOptions ?? {},
+    };
+  }
+
+  // 3. Default: single agent (no ensemble)
+  const defaultAgent = config.default_agent ?? "task";
+  return {
+    strategyName: "single",
+    agentRoles: options.agents ?? [defaultAgent],
+    strategyOpts: {},
+  };
+}
+
+function createStrategy(name: string, options: Record<string, unknown>): EnsembleStrategy {
+  switch (name) {
+    case "consensus":
+      return new ConsensusStrategy(options);
+    case "critic":
+      return new CriticStrategy(options);
+    case "best_of_n":
+      return new BestOfNStrategy(options);
+    case "single":
+      // Single agent fallback
+      return {
+        name: "single",
+        async execute(prompt, agents, executeAgent) {
+          const response = await executeAgent(agents[0], prompt);
+          return {
+            final: response.content,
+            responses: [response],
+            strategy: "single",
+            rounds: 1,
+            totalTimeMs: response.timeMs,
+            totalTokens: response.tokens ?? { input: 0, output: 0 },
+            winner: agents[0],
+          };
+        },
+      };
+    default:
+      throw new Error(`Unknown ensemble strategy: ${name}`);
+  }
+}
+
+function createResilientExecutor(
+  config: ReturnType<typeof getAgentsConfig>["config"],
+  options: EnsembleOptions,
+) {
+  return async (role: string, prompt: string): Promise<AgentResponse> => {
+    const agentConfig = config.agents[role];
+    const modelKey = agentConfig?.model ?? "default";
+
+    const breaker = resilience.getCircuitBreaker(modelKey);
+
+    return resilience.withRetry(
+      async () => {
+        return resilience.withTimeout(
+          async () => {
+            // This will be replaced by actual agent execution via the wrapper
+            throw new Error("executeAgent must be provided by caller");
+          },
+          options.taskTimeoutMs ?? config.task_timeout_ms ?? 120_000,
+          `ensemble:${role}`,
+        );
+      },
+      {
+        maxAttempts: config.retry_attempts ?? 3,
+        baseDelayMs: 1000,
+      },
+    );
+  };
+}
+
+function buildCostBreakdown(
+  result: EnsembleResult,
+  agentRoles: string[],
+  config: ReturnType<typeof getAgentsConfig>["config"],
+): EnsembleExecutionResult["costBreakdown"] {
+  const breakdown: EnsembleExecutionResult["costBreakdown"] = [];
+
+  for (const response of result.responses) {
+    const role = response.role;
+    const agentConfig = config.agents[role] as AgentRoleConfig | undefined;
+
+    breakdown.push({
+      role,
+      model: agentConfig?.model ?? "unknown",
+      inputTokens: response.tokens?.input ?? 0,
+      outputTokens: response.tokens?.output ?? 0,
+      // costUsd: calculateCost(agentConfig?.model, response.tokens), // TODO: add pricing
+    });
+  }
+
+  return breakdown;
+}
+
+/**
+ * Execute a simple single-agent task with resilience.
+ * Convenience wrapper for non-ensemble usage.
+ */
+export async function executeAgentTask(
+  role: string,
+  prompt: string,
+  executeAgent: (role: string, prompt: string) => Promise<AgentResponse>,
+  options: { timeoutMs?: number; retries?: number } = {},
+): Promise<AgentResponse> {
+  const config = getAgentsConfig().config;
+  const timeoutMs = options.timeoutMs ?? config.task_timeout_ms ?? 120_000;
+  const retries = options.retries ?? config.retry_attempts ?? 3;
+
+  return resilience.withRetry(
+    async () => resilience.withTimeout(
+      () => executeAgent(role, prompt),
+      timeoutMs,
+      `agent:${role}`,
+    ),
+    { maxAttempts: retries },
+  );
+}
+
+export { getAgentsConfig } from "./config.js";
+export { ConsensusStrategy, CriticStrategy, BestOfNStrategy } from "./strategies/index.js";