darwin-agents 0.4.9 → 0.5.0-alpha.2

package/dist/core/agent.js

@@ -0,0 +1,172 @@
+/**
+ * Darwin — Agent Definition & Config
+ *
+ * Factory functions for creating validated agent definitions
+ * and merging config with sensible defaults.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+// ─── Defaults ────────────────────────────────────────
+const DEFAULT_MAX_TURNS = 10;
+const DEFAULT_MODEL = 'claude-sonnet-4-20250514';
+const AGENT_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+ * Auto-detect the best available provider.
+ * Priority: ANTHROPIC_API_KEY > OPENAI_API_KEY > claude-cli
+ */
+function detectDefaultProvider() {
+    if (process.env.ANTHROPIC_API_KEY)
+        return 'anthropic-api';
+    if (process.env.OPENAI_API_KEY)
+        return 'openai';
+    return 'claude-cli';
+}
+const DEFAULT_CONFIG = {
+    provider: detectDefaultProvider(),
+    memory: 'sqlite',
+    evolution: {
+        enabled: false,
+        minRuns: 5,
+        safetyGate: true,
+    },
+    dataDir: undefined,
+};
+// ─── Validation Helpers ──────────────────────────────
+function validateAgentName(name) {
+    if (!name || name.length === 0) {
+        throw new Error('Agent name is required');
+    }
+    if (!AGENT_NAME_PATTERN.test(name)) {
+        throw new Error(`Agent name "${name}" is invalid. Must be lowercase, start with a letter, ` +
+            `and contain only letters, digits, and hyphens.`);
+    }
+    if (name.length > 64) {
+        throw new Error(`Agent name "${name}" exceeds 64 character limit`);
+    }
+}
+function validateSystemPrompt(prompt, agentName) {
+    if (!prompt || prompt.trim().length === 0) {
+        throw new Error(`Agent "${agentName}" requires a non-empty systemPrompt`);
+    }
+}
+function validateSystemAgent(def) {
+    if (def.type === 'system' && typeof def.handler !== 'function') {
+        throw new Error(`System agent "${def.name}" requires a handler function`);
+    }
+    if (def.type !== 'system' && def.handler) {
+        throw new Error(`Agent "${def.name}" has a handler but type is "${def.type ?? 'llm'}". ` +
+            `Set type: 'system' to use a handler.`);
+    }
+}
+// ─── Public API ──────────────────────────────────────
+/**
+ * Define and validate an agent definition.
+ * Returns the definition with defaults applied for optional fields.
+ *
+ * @example
+ * ```ts
+ * const researcher = defineAgent({
+ *   name: 'researcher',
+ *   role: 'Deep Research Agent',
+ *   description: 'Researches topics with web sources',
+ *   systemPrompt: 'You are a research agent...',
+ *   mcp: ['tavily', 'memory'],
+ *   tools: ['Read', 'Glob', 'Grep'],
+ * });
+ * ```
+ */
+export function defineAgent(def) {
+    // Validate required fields
+    validateAgentName(def.name);
+    validateSystemPrompt(def.systemPrompt, def.name);
+    validateSystemAgent(def);
+    if (!def.role || def.role.trim().length === 0) {
+        throw new Error(`Agent "${def.name}" requires a non-empty role`);
+    }
+    if (!def.description || def.description.trim().length === 0) {
+        throw new Error(`Agent "${def.name}" requires a non-empty description`);
+    }
+    // Return with defaults applied
+    return {
+        ...def,
+        type: def.type ?? 'llm',
+        maxTurns: def.maxTurns ?? DEFAULT_MAX_TURNS,
+        model: def.model ?? DEFAULT_MODEL,
+        mcp: def.mcp ?? [],
+        tools: def.tools ?? [],
+    };
+}
+/**
+ * Define a Darwin configuration by merging partial overrides with defaults.
+ *
+ * @example
+ * ```ts
+ * const config = defineConfig({
+ *   memory: 'postgres',
+ *   postgresUrl: 'postgresql://...',
+ *   evolution: { enabled: true },
+ * });
+ * ```
+ */
+export function defineConfig(config) {
+    return {
+        ...DEFAULT_CONFIG,
+        ...config,
+        // Deep-merge evolution settings so partial overrides don't wipe defaults
+        evolution: {
+            enabled: config.evolution?.enabled ?? DEFAULT_CONFIG.evolution?.enabled ?? false,
+            minRuns: config.evolution?.minRuns ?? DEFAULT_CONFIG.evolution?.minRuns,
+            safetyGate: config.evolution?.safetyGate ?? DEFAULT_CONFIG.evolution?.safetyGate,
+        },
+    };
+}
+/**
+ * Load config from darwin.config.ts in the current working directory.
+ * Falls back to defaults if no config file is found.
+ *
+ * Also checks for DARWIN_POSTGRES_URL env var and auto-sets
+ * memory: 'postgres' + postgresUrl when present.
+ */
+export async function loadConfig() {
+    let config = { ...DEFAULT_CONFIG };
+    // Try loading darwin.config.ts from cwd
+    const configPath = join(process.cwd(), 'darwin.config.ts');
+    if (existsSync(configPath)) {
+        try {
+            const configUrl = pathToFileURL(configPath).href;
+            const imported = await import(configUrl);
+            if (imported.default) {
+                config = defineConfig(imported.default);
+            }
+        }
+        catch {
+            // Config file exists but failed to load — use defaults
+            console.warn(`[darwin] Warning: Failed to load ${configPath}, using defaults`);
+        }
+    }
+    // Auto-detect postgres from env var
+    const postgresUrl = process.env['DARWIN_POSTGRES_URL'];
+    if (postgresUrl) {
+        config.memory = 'postgres';
+        config.postgresUrl = postgresUrl;
+    }
+    return config;
+}
+/**
+ * Synchronous config loader — returns defaults only.
+ * Used by callers that cannot await (kept for backward compatibility).
+ *
+ * @deprecated Use loadConfig() (async) instead.
+ */
+export function loadConfigSync() {
+    const config = { ...DEFAULT_CONFIG };
+    // Auto-detect postgres from env var
+    const postgresUrl = process.env['DARWIN_POSTGRES_URL'];
+    if (postgresUrl) {
+        config.memory = 'postgres';
+        config.postgresUrl = postgresUrl;
+    }
+    return config;
+}
+//# sourceMappingURL=agent.js.map

package/dist/core/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"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"}

package/dist/core/runner.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Darwin — Agent Runner
+ *
+ * Executes agents via pluggable LLM providers.
+ * Supports: Claude CLI (with MCP), Anthropic API, OpenAI, Ollama.
+ *
+ * The runner handles metrics, experiment records, and reports.
+ * The provider handles the actual LLM call.
+ */
+import type { AgentDefinition, DarwinConfig, RunResult } from '../types.js';
+import type { LLMProvider } from '../providers/types.js';
+/** Options for a single agent run */
+export interface RunOptions {
+    /** Override the agent's model for this run */
+    model?: string;
+    /** Override max turns for this run */
+    maxTurns?: number;
+    /** Task category for experiment tracking */
+    taskType?: string;
+    /** Darwin config (for MCP servers, data dir, etc.) */
+    config?: DarwinConfig;
+    /** Prompt version identifier for experiment tracking */
+    promptVersion?: string;
+    /** Working directory for the Claude CLI process */
+    cwd?: string;
+    /** Timeout in milliseconds (default: 600_000 = 10 minutes) */
+    timeout?: number;
+    /** Run in autonomous mode with bypassed permissions */
+    autonomous?: boolean;
+    /** Explicit LLM provider (overrides config.provider) */
+    provider?: LLMProvider;
+}
+/** Override the per-process run cap (0 = disabled). Primarily for tests. */
+export declare function setMaxRunsPerProcess(n: number): void;
+/** Override the wall-clock cap in ms (0 = disabled). Primarily for tests. */
+export declare function setMaxRunWallMs(ms: number): void;
+/** Reset the process run counter + wall-clock start. Primarily for tests. */
+export declare function resetRunCounters(): void;
+/** Error thrown when a process-lifetime budget cap is exceeded. */
+export declare class DarwinBudgetError extends Error {
+    readonly budget: 'runs' | 'wall';
+    constructor(message: string, budget: 'runs' | 'wall');
+}
+/**
+ * Run an agent using the configured LLM provider.
+ *
+ * For Claude CLI: spawns a child process with MCP support.
+ * For API providers: makes a direct HTTP call (10-100x faster).
+ *
+ * @example
+ * ```ts
+ * // Default: uses Claude CLI
+ * const result = await runAgent(writer, 'Write a landing page', {
+ *   taskType: 'market',
+ *   config: darwinConfig,
+ * });
+ *
+ * // Explicit provider: Anthropic API (faster, no MCP)
+ * import { createProvider } from '../providers/index.js';
+ * const result = await runAgent(critic, 'Evaluate this output', {
+ *   provider: createProvider({ type: 'anthropic-api' }),
+ * });
+ * ```
+ */
+export declare function runAgent(agent: AgentDefinition, task: string, opts?: RunOptions): Promise<RunResult>;
+/**
+ * Error thrown when an LLM provider fails.
+ * Preserves the exit code (CLI) and any partial output for debugging.
+ */
+export declare class RunnerError extends Error {
+    readonly exitCode: number | null;
+    readonly partialOutput: string;
+    constructor(message: string, exitCode: number | null, partialOutput: string);
+}
+//# sourceMappingURL=runner.d.ts.map

package/dist/core/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/core/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EAGZ,SAAS,EACV,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAMzD,qCAAqC;AACrC,MAAM,WAAW,UAAU;IACzB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAgCD,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAEpD;AACD,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAEhD;AACD,6EAA6E;AAC7E,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC;AAED,mEAAmE;AACnE,qBAAa,iBAAkB,SAAQ,KAAK;aACG,MAAM,EAAE,MAAM,GAAG,MAAM;gBAAxD,OAAO,EAAE,MAAM,EAAkB,MAAM,EAAE,MAAM,GAAG,MAAM;CAIrE;AA8JD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,SAAS,CAAC,CAwEpB;AAID;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAGlB,QAAQ,EAAE,MAAM,GAAG,IAAI;aACvB,aAAa,EAAE,MAAM;gBAFrC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,aAAa,EAAE,MAAM;CAKxC"}

package/dist/core/runner.js

@@ -0,0 +1,255 @@
+/**
+ * Darwin — Agent Runner
+ *
+ * Executes agents via pluggable LLM providers.
+ * Supports: Claude CLI (with MCP), Anthropic API, OpenAI, Ollama.
+ *
+ * The runner handles metrics, experiment records, and reports.
+ * The provider handles the actual LLM call.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { ClaudeCliProvider } from '../providers/claude-cli.js';
+import { createProvider } from '../providers/index.js';
+// ─── Constants ───────────────────────────────────────
+const DEFAULT_TIMEOUT = 600_000; // 10 minutes
+const DEFAULT_MODEL = 'claude-sonnet-4-20250514';
+const DEFAULT_MAX_TURNS = 10;
+const DEFAULT_DATA_DIR = '.darwin';
+const DEFAULT_TASK_TYPE = 'general';
+// ─── Process-lifetime budget caps ────────────────────
+//
+// Self-evolving agent loops (A/B tests, multi-model critics, convergence
+// bugs) can fan out into hundreds of provider calls if nothing stops them,
+// and each call hits the billed API. These caps short-circuit the runner
+// before the next LLM call so a runaway loop tops out at a known ceiling.
+// Both are opt-out (`0` = disabled), overridable via env or the explicit
+// setters below. Original feature landed in 29c4367; Round-4 added the
+// DarwinBudgetError class + test helpers so regressions can be asserted.
+const DEFAULT_MAX_RUNS_PER_PROCESS = 100;
+const DEFAULT_MAX_RUN_WALL_MS = 60 * 60 * 1000; // 1 h
+let maxRunsPerProcess = Number(process.env.DARWIN_MAX_RUNS_PER_PROCESS ?? DEFAULT_MAX_RUNS_PER_PROCESS);
+let maxRunWallMs = Number(process.env.DARWIN_MAX_RUN_WALL_MS ?? DEFAULT_MAX_RUN_WALL_MS);
+let runsThisProcess = 0;
+let processStartMs = Date.now();
+/** Override the per-process run cap (0 = disabled). Primarily for tests. */
+export function setMaxRunsPerProcess(n) {
+    maxRunsPerProcess = n;
+}
+/** Override the wall-clock cap in ms (0 = disabled). Primarily for tests. */
+export function setMaxRunWallMs(ms) {
+    maxRunWallMs = ms;
+}
+/** Reset the process run counter + wall-clock start. Primarily for tests. */
+export function resetRunCounters() {
+    runsThisProcess = 0;
+    processStartMs = Date.now();
+}
+/** Error thrown when a process-lifetime budget cap is exceeded. */
+export class DarwinBudgetError extends Error {
+    budget;
+    constructor(message, budget) {
+        super(message);
+        this.budget = budget;
+        this.name = 'DarwinBudgetError';
+    }
+}
+function enforceBudget() {
+    if (maxRunsPerProcess > 0 && runsThisProcess >= maxRunsPerProcess) {
+        throw new DarwinBudgetError(`Darwin run cap reached: ${String(runsThisProcess)}/${String(maxRunsPerProcess)} runs in this process. ` +
+            `Set DARWIN_MAX_RUNS_PER_PROCESS=0 to disable or raise the limit.`, 'runs');
+    }
+    const elapsed = Date.now() - processStartMs;
+    if (maxRunWallMs > 0 && elapsed >= maxRunWallMs) {
+        throw new DarwinBudgetError(`Darwin wall-clock cap reached: ${String(Math.round(elapsed / 1000))}s / ${String(Math.round(maxRunWallMs / 1000))}s. ` +
+            `Restart the process, or set DARWIN_MAX_RUN_WALL_MS=0 to disable.`, 'wall');
+    }
+}
+// Matches common URL patterns for source counting
+const URL_PATTERN = /https?:\/\/[^\s)>\]"'`]+/g;
+// ─── Metrics Parser ──────────────────────────────────
+/**
+ * Parse basic metrics from agent output.
+ * - sourceCount: number of unique URLs found in output
+ * - outputLength: character count of the output
+ */
+function parseMetrics(output, durationMs) {
+    const urls = output.match(URL_PATTERN);
+    const uniqueUrls = urls ? new Set(urls) : new Set();
+    return {
+        qualityScore: null, // Set later by evaluator
+        sourceCount: uniqueUrls.size,
+        outputLength: output.length,
+        errorCount: 0,
+        durationMs,
+    };
+}
+// ─── Experiment Factory ──────────────────────────────
+function generateExperimentId(agentName) {
+    const date = new Date().toISOString().slice(0, 10);
+    const random = Math.random().toString(36).slice(2, 10);
+    return `exp-${agentName}-${date}-${random}`;
+}
+function createExperiment(agent, task, output, startedAt, completedAt, success, metrics, opts) {
+    return {
+        id: generateExperimentId(agent.name),
+        agentName: agent.name,
+        promptVersion: opts.promptVersion ?? 'v1',
+        task,
+        taskType: opts.taskType ?? DEFAULT_TASK_TYPE,
+        startedAt,
+        completedAt,
+        success,
+        metrics,
+        output,
+    };
+}
+// ─── Report Writer ───────────────────────────────────
+function saveReport(experiment, dataDir) {
+    const reportsDir = resolve(join(dataDir, 'reports'));
+    mkdirSync(reportsDir, { recursive: true });
+    const filename = `${experiment.id}.md`;
+    const filepath = join(reportsDir, filename);
+    const durationSec = (experiment.metrics.durationMs / 1000).toFixed(1);
+    const report = `# ${experiment.id}
+
+## Meta
+- **Agent:** ${experiment.agentName}
+- **Task Type:** ${experiment.taskType}
+- **Prompt Version:** ${experiment.promptVersion}
+- **Started:** ${experiment.startedAt}
+- **Completed:** ${experiment.completedAt}
+- **Duration:** ${durationSec}s
+- **Success:** ${experiment.success ? 'Yes' : 'No'}
+
+## Metrics
+| Metric | Value |
+|--------|-------|
+| Quality Score | ${experiment.metrics.qualityScore ?? 'pending'} |
+| Source Count | ${experiment.metrics.sourceCount} |
+| Output Length | ${experiment.metrics.outputLength} chars |
+| Error Count | ${experiment.metrics.errorCount} |
+| Duration | ${durationSec}s |
+
+## Task
+${experiment.task}
+
+## Output
+${experiment.output ?? 'No output captured'}
+`;
+    writeFileSync(filepath, report, 'utf-8');
+    return filepath;
+}
+// ─── Provider Resolution ─────────────────────────────
+/**
+ * Resolve which LLM provider to use for a given agent and options.
+ *
+ * Priority: opts.provider > config.provider > 'claude-cli' (default)
+ *
+ * Auto-fallback: If agent uses MCP tools and provider doesn't support MCP,
+ * automatically falls back to Claude CLI with a warning.
+ */
+function resolveProvider(agent, opts) {
+    // Explicit provider passed in options
+    if (opts.provider) {
+        return opts.provider;
+    }
+    // Determine provider type from config
+    const providerType = opts.config?.provider ?? 'claude-cli';
+    const provider = createProvider({ type: providerType });
+    // Auto-fallback: if agent needs MCP but provider doesn't support it
+    const needsMcp = agent.mcp && agent.mcp.length > 0;
+    if (needsMcp && !provider.supportsMcp) {
+        console.warn(`⚠ Agent "${agent.name}" uses MCP tools but provider "${provider.name}" doesn't support MCP. Falling back to claude-cli.`);
+        return createProvider({ type: 'claude-cli' });
+    }
+    return provider;
+}
+// ─── Runner ──────────────────────────────────────────
+/**
+ * Run an agent using the configured LLM provider.
+ *
+ * For Claude CLI: spawns a child process with MCP support.
+ * For API providers: makes a direct HTTP call (10-100x faster).
+ *
+ * @example
+ * ```ts
+ * // Default: uses Claude CLI
+ * const result = await runAgent(writer, 'Write a landing page', {
+ *   taskType: 'market',
+ *   config: darwinConfig,
+ * });
+ *
+ * // Explicit provider: Anthropic API (faster, no MCP)
+ * import { createProvider } from '../providers/index.js';
+ * const result = await runAgent(critic, 'Evaluate this output', {
+ *   provider: createProvider({ type: 'anthropic-api' }),
+ * });
+ * ```
+ */
+export async function runAgent(agent, task, opts = {}) {
+    // System agents don't use LLM providers
+    if (agent.type === 'system') {
+        throw new Error(`Agent "${agent.name}" is a system agent. ` +
+            `System agents must be run through their handler, not the CLI runner.`);
+    }
+    // Hard-stop before paying for the next provider call if the process has
+    // blown through its budget (run count or wall-clock).
+    enforceBudget();
+    const startedAt = new Date().toISOString();
+    const dataDir = opts.config?.dataDir ?? DEFAULT_DATA_DIR;
+    const model = opts.model ?? agent.model ?? DEFAULT_MODEL;
+    const timeout = opts.timeout ?? DEFAULT_TIMEOUT;
+    runsThisProcess += 1;
+    // Resolve provider
+    const provider = resolveProvider(agent, opts);
+    // Configure Claude CLI-specific options
+    if (provider instanceof ClaudeCliProvider) {
+        provider.setRunOptions({
+            agent,
+            darwinConfig: opts.config,
+            maxTurns: opts.maxTurns ?? agent.maxTurns ?? DEFAULT_MAX_TURNS,
+            cwd: opts.cwd,
+            autonomous: opts.autonomous,
+        });
+    }
+    // Execute via provider
+    const result = await provider.run({
+        model,
+        systemPrompt: agent.systemPrompt,
+        userMessage: task,
+        timeout,
+    });
+    const output = result.output;
+    const completedAt = new Date().toISOString();
+    // Parse metrics from output
+    const metrics = parseMetrics(output, result.durationMs);
+    // Detect truncated runs (max turns reached = not a real success)
+    const isMaxTurns = output.startsWith('Error: Reached max turns');
+    const success = !isMaxTurns && output.length > 50;
+    // Create experiment record
+    const experiment = createExperiment(agent, task, output, startedAt, completedAt, success, metrics, opts);
+    // Save report to disk
+    const reportPath = saveReport(experiment, dataDir);
+    return {
+        experiment,
+        output,
+        reportPath,
+    };
+}
+// ─── Error Type ──────────────────────────────────────
+/**
+ * Error thrown when an LLM provider fails.
+ * Preserves the exit code (CLI) and any partial output for debugging.
+ */
+export class RunnerError extends Error {
+    exitCode;
+    partialOutput;
+    constructor(message, exitCode, partialOutput) {
+        super(message);
+        this.exitCode = exitCode;
+        this.partialOutput = partialOutput;
+        this.name = 'RunnerError';
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/core/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/core/runner.ts"],"names":[],"mappings":"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"}

package/dist/evolution/loop.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Darwin — Evolution Loop
+ *
+ * The core evolution cycle. Called after every agent run, it:
+ *   1. Records the experiment
+ *   2. Checks for failure rollback
+ *   3. Manages A/B tests between prompt versions
+ *   4. Triggers prompt optimization when enough data exists
+ *
+ * This is the brain of Darwin's self-evolution.
+ */
+import type { AgentDefinition, DarwinExperiment, DarwinPattern, MemoryProvider } from '../types.js';
+import type { ExperimentTracker } from './tracker.js';
+import type { PromptOptimizer } from './optimizer.js';
+import type { SafetyGate } from './safety.js';
+import type { PatternDetector } from './patterns.js';
+import type { NotificationConfig } from './notifications.js';
+export interface EvolutionResult {
+    patternsFound: DarwinPattern[];
+    promptEvolved: boolean;
+    abTestStarted: boolean;
+    abTestCompleted: boolean;
+    rolledBack: boolean;
+    newVersion?: string;
+    message: string;
+}
+interface DarwinLoopDeps {
+    memory: MemoryProvider;
+    tracker: ExperimentTracker;
+    optimizer: PromptOptimizer;
+    safety: SafetyGate;
+    patterns: PatternDetector;
+    /** Agent definition — used to pass tool context to optimizer */
+    agent?: AgentDefinition;
+    /** Notification config (Telegram alerts) — auto-loaded from env if not set */
+    notifications?: NotificationConfig;
+}
+export declare class DarwinLoop {
+    private memory;
+    private tracker;
+    private optimizer;
+    private safety;
+    private patterns;
+    private agent?;
+    private notifications;
+    constructor(deps: DarwinLoopDeps);
+    /**
+     * Called AFTER every agent run. Drives the evolution cycle.
+     *
+     * Flow:
+     *   0. Detect incomplete runs (skip them)
+     *   1. Record experiment
+     *   2. Rollback check (consecutive failures)
+     *   3. A/B test management (if active)
+     *   4. Validate data quality before evolving
+     *   5. Evolution trigger (if enough data and no active test)
+     */
+    afterRun(experiment: DarwinExperiment): Promise<EvolutionResult>;
+    private handleABTest;
+    /**
+     * Roll back to the last known good prompt version.
+     * Returns true if a rollback was performed.
+     */
+    private rollback;
+    /**
+     * Activate a specific prompt version and deactivate all others.
+     */
+    private activateVersion;
+    /**
+     * Extract recent critic feedback reports from experiments.
+     *
+     * Returns up to `limit` feedback report texts from the most recent experiments
+     * that have critic feedback. Experiments are already ordered by started_at DESC
+     * from loadExperiments(), so we just filter for ones with feedback.
+     */
+    private getRecentFeedback;
+    /**
+     * Increment version string: "v1" -> "v2", "v12" -> "v13".
+     */
+    private nextVersion;
+    /**
+     * Check if a run is incomplete (agent ran out of turns or produced no real output).
+     * Incomplete runs are NOT recorded as experiments to avoid poisoning the data.
+     *
+     * Checks output length regardless of success flag — a 300-char "successful" run
+     * is still garbage data that shouldn't influence evolution.
+     */
+    private isIncompleteRun;
+    /**
+     * Validate that experiment data is clean enough for evolution.
+     * Prevents garbage-in-garbage-out (e.g., broken search backend producing 0 sources).
+     */
+    private validateDataQuality;
+    /**
+     * Build a human-readable change reason from detected patterns.
+     */
+    private buildChangeReason;
+}
+export {};
+//# sourceMappingURL=loop.d.ts.map

package/dist/evolution/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/evolution/loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAEV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EAEf,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAoB,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAK7D,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,aAAa,EAAE,CAAC;IAC/B,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,UAAU,cAAc;IACtB,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,eAAe,CAAC;IAC1B,gEAAgE;IAChE,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAYD,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,KAAK,CAAC,CAAkB;IAChC,OAAO,CAAC,aAAa,CAAqB;gBAE9B,IAAI,EAAE,cAAc;IAUhC;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;YA4NxD,YAAY;IAiG1B;;;OAGG;YACW,QAAQ;IA8BtB;;OAEG;YACW,eAAe;IAe7B;;;;;;OAMG;YACW,iBAAiB;IAe/B;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAKvB;;;OAGG;YACW,mBAAmB;IAiDjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAsB1B"}