darwin-agents 0.4.5 → 0.4.7

package/dist/examples/closed-loop-feedback.js.map

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

package/dist/examples/custom-agent.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Example: Defining a Custom Darwin Agent
+ *
+ * This shows how to create a fully configured agent with evolution,
+ * custom metric weights, and MCP tool access.
+ *
+ * Run: npx tsx examples/custom-agent.ts
+ */
+export {};
+//# sourceMappingURL=custom-agent.d.ts.map

package/dist/examples/custom-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-agent.d.ts","sourceRoot":"","sources":["../../examples/custom-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/examples/custom-agent.js

@@ -0,0 +1,98 @@
+/**
+ * Example: Defining a Custom Darwin Agent
+ *
+ * This shows how to create a fully configured agent with evolution,
+ * custom metric weights, and MCP tool access.
+ *
+ * Run: npx tsx examples/custom-agent.ts
+ */
+import { defineAgent, runAgent } from '../src/index.js';
+// ─── Step 1: Define the agent ─────────────────────────
+//
+// Every agent needs: name, role, description, systemPrompt.
+// The systemPrompt is what Darwin evolves over time.
+const codeReviewer = defineAgent({
+    name: 'code-reviewer',
+    role: 'Code Review Assistant',
+    description: 'Reviews code for bugs, performance issues, and style. Evolves to catch more issues over time.',
+    // This prompt is the starting point. After enough runs,
+    // Darwin will analyze patterns in the critic's feedback
+    // and generate an improved variant automatically.
+    systemPrompt: `You are a senior code reviewer.
+
+REVIEW CHECKLIST:
+- Security: injection, auth, secrets in code
+- Performance: N+1 queries, unnecessary allocations, missing indexes
+- Correctness: edge cases, null handling, off-by-one errors
+- Style: naming, function length, dead code
+
+RULES:
+- Be specific. "Line 42: missing null check on user.email" not "handle nulls better"
+- Severity levels: CRITICAL / WARNING / SUGGESTION
+- If the code is clean, say so. Don't invent problems.
+- Max 10 findings per review, prioritized by severity
+
+OUTPUT FORMAT:
+## Summary
+One-sentence verdict.
+
+## Findings
+1. [SEVERITY] File:Line — Description
+   Fix: concrete suggestion
+
+## Verdict
+APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION`,
+    // ─── Step 2: Configure evolution ──────────────────────
+    //
+    // enabled: true  — Darwin will optimize this agent's prompt
+    // evaluator: 'critic' — the built-in critic agent scores each run
+    // minRuns: 5 — wait for 5 runs before attempting optimization
+    evolution: {
+        enabled: true,
+        evaluator: 'critic',
+        minRuns: 5,
+        // ─── Step 3: Set metric weights ──────────────────────
+        //
+        // These control what Darwin optimizes FOR. Weights must sum to ~1.0.
+        //
+        // For a code reviewer:
+        // - quality matters most (did it find real issues?)
+        // - success is critical (don't crash mid-review)
+        // - sources/length matter less than for a researcher
+        metrics: {
+            quality: 0.50, // Critic's quality score (most important)
+            sourceCount: 0.00, // Not relevant for code review
+            outputLength: 0.10, // Structured output should be consistent
+            duration: 0.10, // Fast reviews preferred
+            success: 0.30, // Must complete reliably
+        },
+    },
+    // Optional: MCP servers and built-in tools this agent can use
+    mcp: [], // No MCP servers needed
+    tools: ['Read', 'Glob', 'Grep'], // Filesystem access for reading code
+    maxTurns: 12, // Enough turns for a thorough review
+});
+// ─── Step 4: Run the agent ──────────────────────────────
+async function main() {
+    console.log(`Running ${codeReviewer.name}...`);
+    const result = await runAgent(codeReviewer, 'Review this TypeScript function for issues:\n\n' +
+        'function getUser(id: string) {\n' +
+        '  const user = db.query(`SELECT * FROM users WHERE id = ${id}`);\n' +
+        '  return user[0].name.toUpperCase();\n' +
+        '}', {
+        taskType: 'code-review', // Categorize for per-type analytics
+    });
+    console.log(`\nCompleted in ${result.experiment.metrics.durationMs}ms`);
+    console.log(`Output length: ${result.experiment.metrics.outputLength} chars`);
+    if (result.reportPath) {
+        console.log(`Report saved: ${result.reportPath}`);
+    }
+    // The evolution cycle:
+    // 1. This run's output gets evaluated by the critic agent
+    // 2. After 5+ runs, Darwin detects patterns (e.g., "misses SQL injection")
+    // 3. A new prompt variant is generated and A/B tested
+    // 4. If the new variant scores >5% better, it becomes the default
+    // 5. If it regresses >20%, Darwin rolls back automatically (safety gate)
+}
+main().catch(console.error);
+//# sourceMappingURL=custom-agent.js.map

package/dist/examples/custom-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-agent.js","sourceRoot":"","sources":["../../examples/custom-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAGxD,yDAAyD;AACzD,EAAE;AACF,4DAA4D;AAC5D,qDAAqD;AAErD,MAAM,YAAY,GAAoB,WAAW,CAAC;IAChD,IAAI,EAAE,eAAe;IACrB,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EAAE,+FAA+F;IAE5G,wDAAwD;IACxD,wDAAwD;IACxD,kDAAkD;IAClD,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;;6CAuB6B;IAE3C,yDAAyD;IACzD,EAAE;IACF,4DAA4D;IAC5D,kEAAkE;IAClE,8DAA8D;IAC9D,SAAS,EAAE;QACT,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,QAAQ;QACnB,OAAO,EAAE,CAAC;QAEV,wDAAwD;QACxD,EAAE;QACF,qEAAqE;QACrE,EAAE;QACF,uBAAuB;QACvB,oDAAoD;QACpD,iDAAiD;QACjD,qDAAqD;QACrD,OAAO,EAAE;YACP,OAAO,EAAE,IAAI,EAAO,0CAA0C;YAC9D,WAAW,EAAE,IAAI,EAAG,+BAA+B;YACnD,YAAY,EAAE,IAAI,EAAE,yCAAyC;YAC7D,QAAQ,EAAE,IAAI,EAAM,yBAAyB;YAC7C,OAAO,EAAE,IAAI,EAAO,yBAAyB;SAC9C;KACF;IAED,8DAA8D;IAC9D,GAAG,EAAE,EAAE,EAA+B,wBAAwB;IAC9D,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAM,qCAAqC;IAC1E,QAAQ,EAAE,EAAE,EAA0B,qCAAqC;CAC5E,CAAC,CAAC;AAEH,2DAA2D;AAE3D,KAAK,UAAU,IAAI;IACjB,OAAO,CAAC,GAAG,CAAC,WAAW,YAAY,CAAC,IAAI,KAAK,CAAC,CAAC;IAE/C,MAAM,MAAM,GAAc,MAAM,QAAQ,CACtC,YAAY,EACZ,iDAAiD;QACjD,kCAAkC;QAClC,oEAAoE;QACpE,wCAAwC;QACxC,GAAG,EACH;QACE,QAAQ,EAAE,aAAa,EAAG,oCAAoC;KAC/D,CACF,CAAC;IAEF,OAAO,CAAC,GAAG,CAAC,kBAAkB,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC;IACxE,OAAO,CAAC,GAAG,CAAC,kBAAkB,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,YAAY,QAAQ,CAAC,CAAC;IAC9E,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,iBAAiB,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,uBAAuB;IACvB,0DAA0D;IAC1D,2EAA2E;IAC3E,sDAAsD;IACtD,kEAAkE;IAClE,yEAAyE;AAC3E,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC"}

package/dist/examples/mcp-memory-bridge.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Example: Generic MCP-Memory Bridge (Darwin → any MCP-compliant memory server)
+ *
+ * Wraps the `FeedbackStore` interface from closed-loop-feedback.ts with a
+ * thin JSON-RPC 2.0 client for MCP. Works with any MCP server that exposes
+ * a write tool (e.g. `memory_learn`) and a read tool (e.g. `memory_search`).
+ *
+ * Default wiring targets `@studiomeyer/local-memory-mcp` (zero-config, lives
+ * in a single SQLite file under the OS data dir, no cloud, no API keys).
+ * Drop in Mem0 / Zep / Letta / Cognee / your own self-hosted MCP server by
+ * overriding `writeTool` / `readTool` and providing schema mappers.
+ *
+ * Why raw JSON-RPC and not @modelcontextprotocol/sdk?
+ *  - Darwin keeps a "zero hard deps" policy (peerDependencies only).
+ *  - MCP wire protocol is three messages: initialize, tools/list, tools/call.
+ *  - Keeps the bridge testable without a mock SDK.
+ *
+ * Why a single bridge instead of per-provider clients?
+ *  - The wire is the same. Only tool names and arg/result shapes vary.
+ *  - One reconnect / lifecycle path, one place to harden timeouts.
+ *
+ * Run demo (requires `@studiomeyer/local-memory-mcp` installed):
+ *   npm install -g @studiomeyer/local-memory-mcp
+ *   npx tsx examples/mcp-memory-bridge.ts
+ */
+import type { FeedbackRecord, FeedbackStore } from './closed-loop-feedback.js';
+/** A lesson retrieved from the memory store — what gets injected into the next prompt. */
+export interface Lesson {
+    /** Free-form text the agent should consider next run. */
+    content: string;
+    /** Tags surfaced by the store (may be empty). */
+    tags: string[];
+    /** Optional ranking score (semantics depend on the backing store). */
+    score?: number;
+}
+/** Options bag for `fetchRelevant()`. Object-shaped for future-compat. */
+export interface FetchRelevantOptions {
+    query: string;
+    /** Max number of lessons. Default: 5. */
+    limit?: number;
+    /** Optional tag filter — passed through to the read tool if it honours it. */
+    tags?: string[];
+}
+/** Darwin-side store contract extended with retrieval + lifecycle. */
+export interface RetrievableFeedbackStore extends FeedbackStore {
+    /**
+     * Retrieve lessons relevant to a query.
+     * Backward-compatible: accepts either a plain string (legacy) or an
+     * options object. The bag form is preferred for v0.4.7+.
+     */
+    fetchRelevant(queryOrOpts: string | FetchRelevantOptions, limit?: number): Promise<Lesson[]>;
+    close(): Promise<void>;
+}
+/** Transport-agnostic configuration. */
+export interface McpMemoryConfig {
+    transport: 'stdio' | 'http';
+    /**
+     * - stdio: [command, ...args] for `spawn`. Example: ['npx', '-y', '@studiomeyer/local-memory-mcp'].
+     * - http: full URL of the MCP endpoint. Example: 'https://memory.example.com/mcp'.
+     */
+    endpoint: string | string[];
+    /** Optional Authorization header value for http transport (e.g. 'Bearer …'). */
+    authHeader?: string;
+    /** Name of the tool that writes a memory. Default: 'memory_learn'. */
+    writeTool?: string;
+    /** Name of the tool that searches memories. Default: 'memory_search'. */
+    readTool?: string;
+    /** Translate a FeedbackRecord to the writeTool's input arguments. */
+    mapWriteArgs?: (rec: FeedbackRecord) => Record<string, unknown>;
+    /** Translate a raw tools/call result into Lesson[]. */
+    mapReadResult?: (toolResult: unknown) => Lesson[];
+    /** Per-RPC timeout in ms (default: 10_000). */
+    requestTimeoutMs?: number;
+    /** Number of automatic respawn attempts after a stdio EPIPE/exit (default: 1). */
+    maxRespawn?: number;
+    /**
+     * HTTP retry policy. Number of retries for 5xx + transient network errors
+     * (ECONNRESET / ETIMEDOUT / abort). Default: 2. Exponential backoff
+     * starting at 250 ms.
+     */
+    httpMaxRetries?: number;
+    /** Protocol version handed to the server during initialize. Default: '2025-11-25'. */
+    protocolVersion?: string;
+    /** Logger for diagnostics. Defaults to console.warn on errors only. */
+    logger?: {
+        warn: (msg: string) => void;
+        debug?: (msg: string) => void;
+    };
+}
+/** Default mapping for `memory_learn` shape (local-memory-mcp, mcp-nex). */
+export declare function defaultMapWriteArgs(rec: FeedbackRecord): Record<string, unknown>;
+/**
+ * Default mapping for `memory_search` shape.
+ * Accepts both the raw MCP CallToolResult shape `{content:[{text:JSON}]}`
+ * and a pre-parsed object — that keeps the parser tolerant when a custom
+ * server returns structured content directly.
+ */
+export declare function defaultMapReadResult(raw: unknown): Lesson[];
+/**
+ * Generic MCP-Memory bridge.
+ *
+ * Lifecycle:
+ *   const m = openLocalMemory();         // or openRemoteMemory(...)
+ *   await m.save({...});                  // FeedbackStore.save
+ *   const lessons = await m.fetchRelevant({ query: 'topic', limit: 5 });
+ *   await m.close();
+ *
+ * Errors in save/fetch are swallowed at the FeedbackStore level (the
+ * closed-loop callsite logs them) — the bridge surfaces them as thrown
+ * Errors so the caller decides whether to fail-loud or fail-quiet.
+ */
+export declare class McpMemoryBridge implements RetrievableFeedbackStore {
+    private readonly config;
+    private child;
+    private nextId;
+    private pending;
+    private stdoutBuffer;
+    private respawnCount;
+    private initialized;
+    private initInFlight;
+    private closed;
+    constructor(config: McpMemoryConfig);
+    save(record: FeedbackRecord): Promise<void>;
+    fetchRelevant(queryOrOpts: string | FetchRelevantOptions, legacyLimit?: number): Promise<Lesson[]>;
+    close(): Promise<void>;
+    private ensureReady;
+    private initialize;
+    private spawnStdio;
+    private onChildExit;
+    private onStdoutData;
+    private handleIncomingLine;
+    private sendStdio;
+    /**
+     * Send one JSON-RPC request and await the matching response.
+     * Used for both initialize and tools/call.
+     * F1: no inline respawn — ensureReady/initialize is the only path that
+     * spawns. This avoids the double-spawn race where rpc() and ensureReady()
+     * both spawn children competing for `this.child`.
+     */
+    private rpc;
+    private rpcStdio;
+    /**
+     * HTTP transport with bounded retries on 5xx + transient network errors.
+     * Per-attempt timeout via AbortController. Honors `httpMaxRetries`.
+     */
+    private rpcHttp;
+    private callTool;
+}
+/**
+ * Parse an HTTP body that may be either plain JSON or Server-Sent Events.
+ * F2: SSE framing is `data: …\n\n` per event with possible multi-line data
+ * payloads. We take the last well-formed event so a streamed in-progress
+ * frame doesn't override the final result.
+ */
+export declare function parseHttpRpcBody(text: string): {
+    result?: unknown;
+    error?: unknown;
+    id?: unknown;
+    jsonrpc?: unknown;
+};
+/**
+ * Default zero-config wiring: spawn `@studiomeyer/local-memory-mcp` via npx.
+ *
+ * Requires the package to be reachable (either installed globally or via
+ * `npx -y @studiomeyer/local-memory-mcp` which fetches on first run).
+ */
+export declare function localMemory(overrides?: Partial<McpMemoryConfig>): McpMemoryBridge;
+/**
+ * Connect to a remote MCP server over HTTP.
+ *
+ * Example: connect to your hosted memory.studiomeyer.io endpoint
+ *   remoteMemory('https://memory.studiomeyer.io/mcp', { authHeader: `Bearer ${KEY}` })
+ *
+ * Example: Mem0 with tool-name + arg aliasing
+ *   remoteMemory('https://api.mem0.ai/mcp', {
+ *     authHeader: `Bearer ${process.env.MEM0_KEY}`,
+ *     writeTool: 'mem0_add',
+ *     readTool: 'mem0_search',
+ *     mapWriteArgs: (rec) => ({ content: rec.content, metadata: { tags: rec.tags } }),
+ *   })
+ */
+export declare function remoteMemory(url: string, overrides?: Partial<McpMemoryConfig>): McpMemoryBridge;
+//# sourceMappingURL=mcp-memory-bridge.d.ts.map

package/dist/examples/mcp-memory-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-memory-bridge.d.ts","sourceRoot":"","sources":["../../examples/mcp-memory-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAI/E,0FAA0F;AAC1F,MAAM,WAAW,MAAM;IACrB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,sEAAsE;AACtE,MAAM,WAAW,wBAAyB,SAAQ,aAAa;IAC7D;;;;OAIG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChE,uDAAuD;IACvD,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,OAAO,KAAK,MAAM,EAAE,CAAC;IAClD,+CAA+C;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CACzE;AAWD,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAShF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,EAAE,CAmC3D;AA6BD;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,YAAW,wBAAwB;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGrB;IACF,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,eAAe;IAqB7B,IAAI,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3C,aAAa,CACjB,WAAW,EAAE,MAAM,GAAG,oBAAoB,EAC1C,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,EAAE,CAAC;IAYd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAqBd,WAAW;YAuBX,UAAU;IAwBxB,OAAO,CAAC,UAAU;IA8BlB,OAAO,CAAC,WAAW;IAoBnB,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,kBAAkB;IAwB1B,OAAO,CAAC,SAAS;IAWjB;;;;;;OAMG;YACW,GAAG;IAOjB,OAAO,CAAC,QAAQ;IAkBhB;;;OAGG;YACW,OAAO;YA8EP,QAAQ;CAIvB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,EAAE,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAmBrH;AAaD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,SAAS,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,eAAe,CAMrF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,eAAe,CAMnG"}