genoma-evolution 1.0.0

package/run.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+set -e
+
+cd /Users/leandrothomas/Desktop/Projects/genoma
+
+# Install deps once (silent)
+echo "Installing dependencies..."
+python3 -m pip install fastapi uvicorn pydantic python-dotenv --break-system-packages -q 2>/dev/null || true
+pnpm install --ignore-scripts -q 2>/dev/null || true
+
+echo "Starting backend on :8000..."
+python3 -m uvicorn backend.main:app --reload --port 8000 &
+BACKEND_PID=$!
+
+echo "Starting MCP server (stdio)..."
+python3 -m backend.mcp_server &
+MCP_PID=$!
+
+echo "Starting frontend on :3000..."
+sleep 2
+
+# Kill backend + MCP if script exits
+trap "kill $BACKEND_PID $MCP_PID 2>/dev/null || true" EXIT
+
+# Run frontend (foreground — Ctrl+C kills both)
+pnpm dev

package/scripts/postinstall.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+const ROOT_DIR = path.resolve(__dirname, '..');
+const REQUIREMENTS_FILE = path.join(ROOT_DIR, 'backend', 'requirements.txt');
+
+function getPythonVersion() {
+  try {
+    const output = execSync('python3 --version', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+    const match = output.match(/Python (\d+)\.(\d+)/);
+    if (!match) return null;
+    return { major: parseInt(match[1], 10), minor: parseInt(match[2], 10) };
+  } catch {
+    return null;
+  }
+}
+
+function main() {
+  const version = getPythonVersion();
+
+  if (!version) {
+    console.warn('Warning: Python not found, skipping backend deps');
+    return;
+  }
+
+  if (version.major < 3 || (version.major === 3 && version.minor < 10)) {
+    console.warn(
+      `Warning: Python 3.10+ required (found ${version.major}.${version.minor}), skipping backend deps`
+    );
+    return;
+  }
+
+  console.log('Installing Python dependencies...');
+
+  try {
+    execSync(`pip install -r "${REQUIREMENTS_FILE}"`, {
+      cwd: ROOT_DIR,
+      stdio: 'inherit',
+    });
+    console.log('Python dependencies installed');
+  } catch (err) {
+    console.warn(`Warning: Failed to install Python dependencies — ${err.message}`);
+  }
+}
+
+main();

package/skills-lock.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "skills": {
+    "frontend-design": {
+      "source": "anthropics/skills",
+      "sourceType": "github",
+      "computedHash": "063a0e6448123cd359ad0044cc46b0e490cc7964d45ef4bb9fd842bd2ffbca67"
+    }
+  }
+}

package/specs/event-schema.md

@@ -0,0 +1,223 @@
+# Canonical Run Event Schema v0.1
+
+## Purpose
+
+Define a vendor-neutral event format for agent execution telemetry. Any agent (Hermes, Claude Code, Codex, OpenCode) can emit runs in this schema. The schema is the single source of truth for cross-agent comparison, evaluation, and regression detection.
+
+---
+
+## Design Principles
+
+1. **Agent-agnostic:** No special cases for any single agent. Required fields are minimal; optional fields capture agent-specific context.
+2. **Append-only:** New fields may be added to optional sections. Removing or renaming required fields is breaking.
+3. **Graceful degradation:** Missing optional fields never break ingestion. Unknown fields go into `context{}` dict.
+4. **Deterministic evaluation:** The same run, evaluated twice, always produces identical scores.
+5. **Cross-comparable:** Two runs from different agents can be compared on: outcome, token usage, tool calls, errors, improvement delta.
+
+---
+
+## Root Object: `CanonicalRun`
+
+### Required Fields
+
+These fields MUST be present and non-null for a valid run event. Collectors must fail fast if unable to provide them.
+
+| Field | Type | Example | Notes |
+|-------|------|---------|-------|
+| `run_id` | string (UUID) | `"a1b2c3d4-e5f6-..."` | Unique run identifier. Collectors assign via trace_id or session_id. |
+| `agent_name` | string | `"hermes"`, `"claude-code"`, `"codex"`, `"opencode"` | Which agent ran this. |
+| `collector` | string | `"hermes-trace-ingestor"`, `"claude-code-session-collector"` | Which collector produced this event. Enables audit trail. |
+| `started_at` | ISO 8601 string | `"2026-05-19T14:32:00Z"` | When the run began. |
+| `task_name` | string | `"Implement user authentication"` | What the agent was asked to do. Max 500 chars; first sentence only. |
+| `task_name` | string | (max 500 chars) | Task description (first sentence). |
+| `outcome` | enum string | `"success"`, `"failure"`, `"partial"`, `"unknown"` | Did the agent succeed? `success`: no errors, completed. `failure`: critical error. `partial`: partial success with non-critical errors. `unknown`: insufficient info. |
+
+### Optional Fields
+
+These fields MAY be absent or null. Collectors should populate them when available. Evaluators must handle missing values gracefully.
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `agent_version` | string | null | Agent version at run time. E.g., `"2.1.143"`. |
+| `provider` | string | null | AI provider: `"anthropic"`, `"openai"`, `"hermes"`, `"ollama"`, etc. |
+| `model` | string | null | Model ID. E.g., `"claude-opus-4-7"`, `"gpt-4-turbo"`. |
+| `repo` | string | null | Source code repo (git remote URL or local path). Used for run grouping. |
+| `session_id` | string | null | Unique session UUID from the agent. Links multiple runs to one session. |
+| `ended_at` | ISO 8601 string | null | When the run completed. If null, use current time. |
+| `tool_calls` | array of objects | `[]` | All tool invocations in sequence. See schema below. |
+| `files_touched` | array of objects | `[]` | All files read/written/deleted. See schema below. |
+| `artifacts` | array of objects | `[]` | Output artifacts (code, docs, reports). See schema below. |
+| `errors` | array of objects | `[]` | Exceptions and error signatures. See schema below. |
+| `metrics` | object | null | Aggregated execution metrics. See schema below. |
+| `eval_scores` | array of objects | `[]` | Scores from Phase 5 evaluation. Written post-run. See schema below. |
+| `improvement_candidates` | array of objects | `[]` | Proposed improvements (Phase 8+). |
+| `context` | object | `{}` | Catch-all for agent-specific or collector-specific fields. Never fails ingestion. |
+| `resolution` | string | null | How the run was resolved (if outcome == `"failure"`). Diagnostic text. |
+| `collector_version` | string | `"0.1.0"` | Version of the collector that produced this event. For forward compatibility. |
+
+---
+
+## Nested Object Schemas
+
+### `ToolCallRecord` (items in `tool_calls[]`)
+
+```json
+{
+  "id": "tool-call-uuid",
+  "name": "Read",
+  "input_summary": "Read /path/to/file.ts",
+  "duration_ms": 245,
+  "result_summary": "Returned 1240 chars",
+  "error": null
+}
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | string | Unique ID for this tool call. E.g., UUID or sequential counter. |
+| `name` | string | Tool name. E.g., `"Read"`, `"Bash"`, `"Edit"`, `"Write"`, `"Grep"`, `"Agent"`. |
+| `input_summary` | string | First 200 chars of input. Omit secrets. |
+| `duration_ms` | integer | Execution time in milliseconds. Omit if not available. |
+| `result_summary` | string | First 200 chars of result/output. |
+| `error` | string or null | Error message if tool failed. Otherwise null. |
+
+### `FileTouchRecord` (items in `files_touched[]`)
+
+```json
+{
+  "path": "src/components/Button.tsx",
+  "action": "write",
+  "size_bytes": 2048
+}
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `path` | string | File path. May be relative or absolute. |
+| `action` | string | One of: `"read"`, `"write"`, `"delete"`. |
+| `size_bytes` | integer or null | Final file size. Omit for deletes. |
+
+### `RunMetrics` (the `metrics` field)
+
+```json
+{
+  "input_tokens": 4200,
+  "output_tokens": 1850,
+  "cache_tokens": 512,
+  "latency_ms": 8500,
+  "cost_usd": 0.082,
+  "tool_call_count": 12
+}
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `input_tokens` | integer or null | Tokens sent to model. |
+| `output_tokens` | integer or null | Tokens generated by model. |
+| `cache_tokens` | integer or null | Cached input tokens (prompt caching). |
+| `latency_ms` | integer or null | Total run duration in ms. |
+| `cost_usd` | float or null | Estimated cost in USD. |
+| `tool_call_count` | integer | Total tool calls made. Defaults to 0. |
+
+### `ErrorRecord` (items in `errors[]`)
+
+```json
+{
+  "signature": "TypeError: Cannot read property 'foo' of undefined",
+  "message": "TypeError: Cannot read property 'foo' of undefined at line 42",
+  "stack_excerpt": "at Object.<anonymous> (file.js:42:10)",
+  "count": 3
+}
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `signature` | string | Error class + first line. Used for deduplication. E.g., `"TypeError: Cannot read property..."`. |
+| `message` | string | Full error message. |
+| `stack_excerpt` | string | First few stack frames (first 300 chars). |
+| `count` | integer | How many times this error occurred. Default 1. |
+
+### `EvalScore` (items in `eval_scores[]`)
+
+Written by Phase 5 evaluation engine. Not set by collectors.
+
+```json
+{
+  "scorer": "outcome_scorer",
+  "score": 1.0,
+  "passed": true,
+  "details": {
+    "outcome": "success",
+    "reason": "Run completed without errors"
+  }
+}
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `scorer` | string | Name of the scorer that produced this. E.g., `"outcome_scorer"`, `"token_cost_scorer"`. |
+| `score` | float | Score in range [0.0, 1.0]. |
+| `passed` | boolean | Did this scorer report success? |
+| `details` | object | Scorer-specific metadata. Free-form. |
+
+### `Artifact` (items in `artifacts[]`)
+
+```json
+{
+  "path": "output/evolved_skill.md",
+  "type": "markdown",
+  "size_bytes": 4096
+}
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `path` | string | Path to artifact. |
+| `type` | string | MIME-like type. E.g., `"markdown"`, `"json"`, `"python"`, `"typescript"`. |
+| `size_bytes` | integer | Size in bytes. |
+
+---
+
+## Backward Compatibility
+
+### Mapping from `TraceRecord` (Hermes legacy)
+
+The existing `TraceRecord` dataclass in `backend/promethean/models.py` maps to `CanonicalRun` as follows:
+
+| TraceRecord | CanonicalRun | Mapping rule |
+|-------------|--------------|--------------|
+| `trace_id` | `run_id` | Direct copy. |
+| `agent` | `agent_name` | Direct copy. |
+| `agent_version` | `agent_version` | Direct copy. |
+| `timestamp` | `started_at` | Direct copy (ISO 8601). |
+| — | `ended_at` | Set to `started_at` if missing. |
+| `task` | `task_name` | Direct copy. |
+| `outcome` | `outcome` | Direct copy (`"success"`, `"failure"`, `"partial"`). |
+| `error_signature` | `errors[0].signature` | Wrap in array. If empty, set `errors = []`. |
+| `context` | `context` | Direct copy (dict). |
+| `resolution` | `resolution` | Direct copy. |
+| — | `collector` | Set to `"hermes-trace-ingestor"` (constant). |
+| — | `provider` | Set to `"hermes"` (constant). |
+
+All other `CanonicalRun` fields default to null/empty if not present in `TraceRecord`.
+
+### Unknown Fields
+
+If a collector encounters a field not in this schema:
+- If it's non-sensitive: include it in `context{}`
+- If it's sensitive (API key, secret): omit it
+- Never reject the run due to unknown fields
+
+---
+
+## Version History
+
+### v0.1 (current)
+- Initial schema
+- Maps `TraceRecord` to `CanonicalRun`
+- Defines required fields: `run_id`, `agent_name`, `collector`, `started_at`, `task_name`, `outcome`
+- Defines optional fields for tools, files, metrics, errors, and scores
+
+### Future versions
+- v0.2: Add `parent_run_id` for nested agent calls
+- v0.3: Add `reproducibility_hash` for deterministic replay

package/specs/examples/run.jsonl

@@ -0,0 +1,3 @@
+{"run_id": "hermes-trace-001", "agent_name": "hermes", "collector": "hermes-trace-ingestor", "collector_version": "0.1.0", "started_at": "2026-05-19T14:32:00Z", "ended_at": "2026-05-19T14:35:42Z", "task_name": "Implement user authentication middleware", "outcome": "success", "agent_version": "2.1.143", "provider": "hermes", "model": null, "repo": "https://github.com/org/genoma.git", "session_id": null, "tool_calls": [{"id": "call-001", "name": "Read", "input_summary": "Read backend/main.py", "duration_ms": 145, "result_summary": "Returned 3240 chars", "error": null}, {"id": "call-002", "name": "Edit", "input_summary": "Add JWT middleware to FastAPI", "duration_ms": 320, "result_summary": "Edited 5 lines", "error": null}, {"id": "call-003", "name": "Bash", "input_summary": "pytest tests/test_auth.py", "duration_ms": 2100, "result_summary": "All 8 tests passed", "error": null}], "files_touched": [{"path": "backend/main.py", "action": "write", "size_bytes": 3240}, {"path": "backend/auth_middleware.py", "action": "write", "size_bytes": 1847}, {"path": "tests/test_auth.py", "action": "read", "size_bytes": 2156}], "artifacts": [{"path": "backend/auth_middleware.py", "type": "python", "size_bytes": 1847}], "errors": [], "metrics": {"input_tokens": 4200, "output_tokens": 1850, "cache_tokens": 512, "latency_ms": 8500, "cost_usd": 0.082, "tool_call_count": 3}, "eval_scores": [], "improvement_candidates": [], "context": {"skill_name": "auth-middleware", "commands": ["read backend/main.py", "edit backend/main.py", "bash pytest"], "files_touched": ["backend/main.py", "backend/auth_middleware.py", "tests/test_auth.py"]}, "resolution": null}
+{"run_id": "cc-session-e8f7a9d3", "agent_name": "claude-code", "collector": "claude-code-session-collector", "collector_version": "0.1.0", "started_at": "2026-05-19T11:22:00Z", "ended_at": "2026-05-19T11:28:15Z", "task_name": "Add dark mode toggle to React dashboard", "outcome": "success", "agent_version": "2.0.5", "provider": "anthropic", "model": "claude-opus-4-7", "repo": "main", "session_id": "e8f7a9d3-2bc1-4f8e-9a2b-5c7e9f1d3a4b", "tool_calls": [{"id": "tool-read-1", "name": "Read", "input_summary": "Read src/components/Sidebar.tsx", "duration_ms": 234, "result_summary": "Returned 1240 chars", "error": null}, {"id": "tool-edit-1", "name": "Edit", "input_summary": "Add theme state to Sidebar", "duration_ms": 412, "result_summary": "Edited 8 lines", "error": null}, {"id": "tool-write-1", "name": "Write", "input_summary": "Create src/hooks/useTheme.ts", "duration_ms": 178, "result_summary": "Created new file 745 bytes", "error": null}], "files_touched": [{"path": "src/components/Sidebar.tsx", "action": "write", "size_bytes": 1512}, {"path": "src/hooks/useTheme.ts", "action": "write", "size_bytes": 745}, {"path": "src/lib/theme.ts", "action": "write", "size_bytes": 892}], "artifacts": [{"path": "src/hooks/useTheme.ts", "type": "typescript", "size_bytes": 745}, {"path": "src/lib/theme.ts", "type": "typescript", "size_bytes": 892}], "errors": [], "metrics": {"input_tokens": 3450, "output_tokens": 1220, "cache_tokens": 340, "latency_ms": 5820, "cost_usd": 0.067, "tool_call_count": 3}, "eval_scores": [], "improvement_candidates": [], "context": {"cwd": "/Users/leandrothomas/Desktop/Projects/genoma", "gitBranch": "feature/dark-mode", "version": "2.0.5", "usage": {"input_tokens": 3450, "output_tokens": 1220, "cache_read_input_tokens": 340}}, "resolution": null}
+{"run_id": "unknown-run-abc123", "agent_name": "unknown-agent", "collector": "generic-json-ingestor", "started_at": "2026-05-19T10:00:00Z", "task_name": "Fix database query", "outcome": "partial"}

package/src/app/api/[...path]/route.ts

@@ -0,0 +1,55 @@
+import { NextRequest, NextResponse } from "next/server";
+
+const HERMES_SERVER = "http://127.0.0.1:8000";
+
+/**
+ * Catch-all proxy for Hermes web server endpoints.
+ *
+ * Routes with specific files at src/app/api/* take precedence.
+ * This handler catches everything else (e.g., /api/skills, /api/status, etc.)
+ * and proxies requests to the Hermes FastAPI backend (:9119).
+ */
+async function handler(request: NextRequest): Promise<NextResponse> {
+  const { pathname, search } = new URL(request.url);
+  const targetUrl = `${HERMES_SERVER}${pathname}${search}`;
+
+  try {
+    const headers = new Headers(request.headers);
+    // Remove host header (Next.js sets it to localhost:3000)
+    headers.delete("host");
+
+    // Forward the session token if present
+    const token = request.headers.get("x-hermes-session-token");
+    if (!token) {
+      // Try to extract from referer or cookie (browser will have set it)
+      headers.set("x-hermes-session-token", "");
+    }
+
+    const proxyResponse = await fetch(targetUrl, {
+      method: request.method,
+      headers,
+      body: request.method !== "GET" && request.method !== "HEAD"
+        ? await request.text().catch(() => null)
+        : undefined,
+    });
+
+    const contentType = proxyResponse.headers.get("content-type") || "";
+    const body = contentType.includes("application/json")
+      ? await proxyResponse.json()
+      : await proxyResponse.text();
+
+    return NextResponse.json(body, {
+      status: proxyResponse.status,
+      headers: {
+        "content-type": contentType || "application/json",
+      },
+    });
+  } catch (err) {
+    return NextResponse.json(
+      { detail: `Backend unreachable: ${err instanceof Error ? err.message : "unknown"}` },
+      { status: 503 },
+    );
+  }
+}
+
+export { handler as GET, handler as POST, handler as PUT, handler as DELETE, handler as PATCH };

package/src/app/api/auth/token/route.ts

@@ -0,0 +1,22 @@
+import { NextResponse } from "next/server";
+
+const HERMES_SERVER = "http://127.0.0.1:8000";
+
+/**
+ * Proxy the Hermes session token from the web server's HTML.
+ * The browser calls this to avoid CORS issues when fetching the token directly.
+ */
+export async function GET() {
+  try {
+    const html = await fetch(`${HERMES_SERVER}/`, {
+      signal: AbortSignal.timeout(5_000),
+    }).then((r) => r.text());
+
+    const match = html.match(/__HERMES_SESSION_TOKEN__\s*=\s*"([^"]+)"/);
+    const token = match?.[1] ?? null;
+
+    return NextResponse.json({ token });
+  } catch {
+    return NextResponse.json({ token: null }, { status: 503 });
+  }
+}