dual-brain 0.1.0

package/mcp-server/README.md

@@ -0,0 +1,81 @@
+# dual-brain MCP Server
+
+Exposes dual-brain's routing engine as MCP tools so any MCP-compatible client (VS Code, Cursor, Windsurf, etc.) can use smart provider/model routing.
+
+## Usage
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "dual-brain": {
+      "command": "node",
+      "args": ["node_modules/dual-brain/mcp-server/index.mjs"]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "dual-brain": {
+      "command": "node",
+      "args": ["/path/to/dual-brain/mcp-server/index.mjs"]
+    }
+  }
+}
+```
+
+## Tools
+
+### `dual_brain_detect`
+Classify a task into intent, risk, complexity, and tier.
+
+```json
+{ "prompt": "refactor the auth module", "files": ["src/auth.mjs"] }
+```
+
+Returns: `{ intent, risk, complexity, effort, tier, requiresWrite, explanation }`
+
+### `dual_brain_decide`
+Full routing decision — detect + route to provider and model.
+
+```json
+{ "prompt": "fix the login bug", "files": ["src/auth.mjs"], "profile": "quality-first" }
+```
+
+Returns: `{ provider, model, effort, tier, dualBrain, explanation, detection }`
+
+### `dual_brain_status`
+Provider health, routing scores, and session stats.
+
+```json
+{}
+```
+
+Returns: `{ providers: { claude: {...}, openai: {...} }, session, profile }`
+
+### `dual_brain_remember`
+Save a routing preference that persists across sessions.
+
+```json
+{ "preference": "prefer claude for architecture tasks" }
+```
+
+Returns: `{ saved: true, preference, preferences: string[] }`
+
+## Standalone test
+
+```bash
+node mcp-server/index.mjs
+```
+
+Then send JSON-RPC over stdin:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node mcp-server/index.mjs
+```

package/mcp-server/index.mjs

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+/**
+ * mcp-server/index.mjs — MCP server for dual-brain routing engine.
+ *
+ * Exposes dual-brain capabilities as MCP tools via JSON-RPC 2.0 over stdin/stdout.
+ * No external dependencies — uses only Node.js built-ins and the src/ modules.
+ *
+ * Tools:
+ *   dual_brain_detect   — Classify a task (intent, risk, complexity, tier)
+ *   dual_brain_decide   — Route a task (provider, model, tier, reason)
+ *   dual_brain_status   — Provider health and budget overview
+ *   dual_brain_remember — Save a routing preference
+ *
+ * Usage (standalone):
+ *   node mcp-server/index.mjs
+ *
+ * MCP client config:
+ *   {
+ *     "mcpServers": {
+ *       "dual-brain": {
+ *         "command": "node",
+ *         "args": ["node_modules/dual-brain/mcp-server/index.mjs"]
+ *       }
+ *     }
+ *   }
+ */
+
+import { createInterface } from 'readline';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SRC = join(__dirname, '..', 'src');
+
+// ─── Tool definitions (JSON Schema) ──────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'dual_brain_detect',
+    description: 'Classify a task prompt into intent, risk, complexity, and routing tier. Returns classification data used by the dual-brain routing engine.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: {
+          type: 'string',
+          description: 'The task description or prompt to classify.',
+        },
+        files: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Optional list of file paths involved in the task. Used for risk classification.',
+        },
+      },
+      required: ['prompt'],
+    },
+  },
+  {
+    name: 'dual_brain_decide',
+    description: 'Detect a task and route it to the best provider and model. Returns provider, model, tier, explanation, and whether dual-brain review is recommended.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: {
+          type: 'string',
+          description: 'The task description or prompt.',
+        },
+        files: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Optional list of file paths involved in the task.',
+        },
+        profile: {
+          type: 'string',
+          description: 'Optional profile mode override: "auto", "balanced", "cost-saver", or "quality-first".',
+        },
+      },
+      required: ['prompt'],
+    },
+  },
+  {
+    name: 'dual_brain_status',
+    description: 'Get current provider health, routing scores, and session statistics. Shows which providers are healthy, degraded, or rate-limited.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'dual_brain_remember',
+    description: 'Save a routing preference that persists across sessions. Examples: "prefer claude for architecture", "use cost-saver mode", "never dual-brain".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        preference: {
+          type: 'string',
+          description: 'The routing preference to remember in plain English.',
+        },
+      },
+      required: ['preference'],
+    },
+  },
+  {
+    name: 'dual_brain_search',
+    description: 'Search across all previous sessions for context. Use this when the user references past work ("we did this before", "yesterday we worked on", "remember when we", "didn\'t we already"). Returns matching sessions with prompts, topics, and files.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Search keywords to find in previous sessions. Can be topic, file name, or description of past work.',
+        },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'dual_brain_session_context',
+    description: 'Get detailed context from a specific previous session. Use after dual_brain_search to retrieve details about what happened in a found session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: {
+          type: 'string',
+          description: 'The session UUID to get context for (from search results).',
+        },
+      },
+      required: ['sessionId'],
+    },
+  },
+];
+
+// ─── Tool handlers ────────────────────────────────────────────────────────────
+
+async function handleDetect({ prompt, files = [] }) {
+  const { detectTask } = await import(`${SRC}/detect.mjs`);
+  const result = detectTask({ prompt, files });
+  return {
+    intent: result.intent,
+    risk: result.risk,
+    complexity: result.complexity,
+    effort: result.effort,
+    tier: result.tier,
+    fileCount: result.fileCount,
+    requiresWrite: result.requiresWrite,
+    riskyFiles: result.riskyFiles,
+    explanation: result.explanation,
+  };
+}
+
+async function handleDecide({ prompt, files = [], profile: profileOverride }) {
+  const { detectTask } = await import(`${SRC}/detect.mjs`);
+  const { decideRoute } = await import(`${SRC}/decide.mjs`);
+  const { loadProfile } = await import(`${SRC}/profile.mjs`);
+
+  const cwd = process.cwd();
+  let profile = loadProfile(cwd);
+
+  // Apply profile override if requested
+  if (profileOverride) {
+    profile = { ...profile, mode: profileOverride, profile: profileOverride };
+  }
+
+  const detection = detectTask({ prompt, files });
+  const decision = decideRoute({ profile, detection, cwd });
+
+  return {
+    provider: decision.provider,
+    model: decision.model,
+    effort: decision.effort,
+    tier: decision.tier,
+    dualBrain: decision.dualBrain,
+    modes: decision.modes,
+    sandbox: decision.sandbox,
+    explanation: decision.explanation,
+    detection: {
+      intent: detection.intent,
+      risk: detection.risk,
+      complexity: detection.complexity,
+    },
+  };
+}
+
+async function handleStatus() {
+  const { loadProfile, getAvailableProviders } = await import(`${SRC}/profile.mjs`);
+  const { getHealth, getProviderScore, getSessionStats } = await import(`${SRC}/health.mjs`);
+
+  const cwd = process.cwd();
+  const profile = loadProfile(cwd);
+  const health = getHealth(cwd);
+
+  const providers = {};
+
+  for (const prov of ['claude', 'openai']) {
+    const cfg = profile?.providers?.[prov];
+    if (!cfg) {
+      providers[prov] = { enabled: false };
+      continue;
+    }
+
+    // Get scores for each tier model
+    const models = {
+      search: prov === 'claude' ? 'haiku' : 'gpt-4.1-mini',
+      execute: prov === 'claude' ? 'sonnet' : 'gpt-5.4',
+      think: prov === 'claude' ? 'opus' : 'gpt-5.5',
+    };
+
+    const scores = {};
+    const states = {};
+    for (const [tier, modelClass] of Object.entries(models)) {
+      scores[tier] = getProviderScore(prov, modelClass, cwd);
+      const key = `${prov}:${modelClass}`;
+      states[modelClass] = health.states[key] ?? { status: 'healthy' };
+    }
+
+    providers[prov] = {
+      enabled: cfg.enabled ?? false,
+      plan: cfg.plan ?? null,
+      scores,
+      states,
+    };
+  }
+
+  const session = getSessionStats ? getSessionStats(cwd) : (health.session ?? null);
+
+  return {
+    providers,
+    session,
+    profile: {
+      mode: profile?.mode || profile?.profile || 'auto',
+      dualBrainEnabled: profile?.dual_brain_enabled !== false,
+      preferences: (profile?.preferences || []).filter(p => p.enabled).map(p => p.text),
+    },
+  };
+}
+
+async function handleRemember({ preference }) {
+  const { rememberPreference, getActivePreferences } = await import(`${SRC}/profile.mjs`);
+  const cwd = process.cwd();
+  rememberPreference(preference, { cwd });
+  const all = getActivePreferences(cwd);
+  return {
+    saved: true,
+    preference,
+    preferences: all.map(p => p.text),
+  };
+}
+
+async function handleSearch({ query }) {
+  const { searchSessions, buildSessionIndex } = await import(`${SRC}/session.mjs`);
+  const cwd = process.cwd();
+  try { buildSessionIndex(cwd); } catch {}
+  const results = searchSessions(query, cwd);
+  return {
+    count: results.length,
+    sessions: results.slice(0, 5).map(s => ({
+      id: s.id,
+      tool: s.tool,
+      date: s.date,
+      firstPrompt: s.prompts.first,
+      lastPrompt: s.prompts.last,
+      topics: s.topics.slice(0, 5),
+      files: s.files.slice(0, 10),
+      messageCount: s.messageCount,
+    })),
+  };
+}
+
+async function handleSessionContext({ sessionId }) {
+  const { getSessionContext } = await import(`${SRC}/session.mjs`);
+  const cwd = process.cwd();
+  const ctx = getSessionContext(sessionId, cwd);
+  if (!ctx) return { error: 'Session not found' };
+  return ctx;
+}
+
+// ─── JSON-RPC dispatcher ──────────────────────────────────────────────────────
+
+async function dispatchTool(name, args) {
+  switch (name) {
+    case 'dual_brain_detect':  return handleDetect(args);
+    case 'dual_brain_decide':  return handleDecide(args);
+    case 'dual_brain_status':  return handleStatus();
+    case 'dual_brain_remember': return handleRemember(args);
+    case 'dual_brain_search':   return handleSearch(args);
+    case 'dual_brain_session_context': return handleSessionContext(args);
+    default:
+      throw Object.assign(new Error(`Unknown tool: ${name}`), { code: -32601 });
+  }
+}
+
+// ─── JSON-RPC helpers ─────────────────────────────────────────────────────────
+
+function respond(id, result) {
+  return JSON.stringify({ jsonrpc: '2.0', id, result });
+}
+
+function errorResponse(id, code, message, data) {
+  const err = { code, message };
+  if (data !== undefined) err.data = data;
+  return JSON.stringify({ jsonrpc: '2.0', id, error: err });
+}
+
+// ─── Request handlers ─────────────────────────────────────────────────────────
+
+async function handleRequest(msg) {
+  const { id, method, params } = msg;
+
+  try {
+    switch (method) {
+      case 'initialize':
+        return respond(id, {
+          protocolVersion: '2024-11-05',
+          capabilities: { tools: {} },
+          serverInfo: { name: 'dual-brain', version: '7.1.4' },
+        });
+
+      case 'initialized':
+        // Notification (no id), no response needed
+        return null;
+
+      case 'tools/list':
+        return respond(id, { tools: TOOLS });
+
+      case 'tools/call': {
+        const { name, arguments: args = {} } = params || {};
+        if (!name) {
+          return errorResponse(id, -32602, 'Missing tool name');
+        }
+        const result = await dispatchTool(name, args);
+        return respond(id, {
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        });
+      }
+
+      case 'ping':
+        return respond(id, {});
+
+      default:
+        return errorResponse(id, -32601, `Method not found: ${method}`);
+    }
+  } catch (err) {
+    const code = err.code ?? -32000;
+    const message = err.message ?? 'Internal error';
+    return errorResponse(id, code, message);
+  }
+}
+
+// ─── Main loop ────────────────────────────────────────────────────────────────
+
+const rl = createInterface({ input: process.stdin, terminal: false });
+
+// Track in-flight requests so we don't exit while work is pending
+let pending = 0;
+let stdinClosed = false;
+
+function maybeExit() {
+  if (stdinClosed && pending === 0) process.exit(0);
+}
+
+rl.on('line', (line) => {
+  const raw = line.trim();
+  if (!raw) return;
+
+  let msg;
+  try {
+    msg = JSON.parse(raw);
+  } catch {
+    process.stdout.write(errorResponse(null, -32700, 'Parse error') + '\n');
+    return;
+  }
+
+  pending++;
+  handleRequest(msg).then((response) => {
+    if (response !== null) {
+      process.stdout.write(response + '\n');
+    }
+  }).catch((err) => {
+    process.stdout.write(errorResponse(msg?.id ?? null, -32000, err?.message ?? 'Internal error') + '\n');
+  }).finally(() => {
+    pending--;
+    maybeExit();
+  });
+});
+
+rl.on('close', () => {
+  stdinClosed = true;
+  maybeExit();
+});

package/orchestrator.json

@@ -0,0 +1,215 @@
+{
+  "subscriptions": {
+    "claude": {
+      "plan": "$100",
+      "models": {
+        "opus":   { "tier": "think",   "input_per_mtok": 5.0,   "output_per_mtok": 25.0,  "context_window": 1000000, "max_output": 128000 },
+        "sonnet": { "tier": "execute", "input_per_mtok": 3.0,   "output_per_mtok": 15.0,  "context_window": 1000000, "max_output": 64000 },
+        "haiku":  { "tier": "search",  "input_per_mtok": 1.0,   "output_per_mtok": 5.0,   "context_window": 200000,  "max_output": 64000 }
+      }
+    },
+    "openai": {
+      "plan": "$100",
+      "models": {
+        "gpt-5.5":      { "tier": "think",   "input_per_mtok": 5.0,   "output_per_mtok": 30.0,  "context_window": 1000000, "max_output": 128000 },
+        "gpt-5.4":      { "tier": "execute", "input_per_mtok": 2.5,   "output_per_mtok": 15.0,  "context_window": 1000000, "max_output": 128000 },
+        "gpt-4.1-mini": { "tier": "search",  "input_per_mtok": 0.40,  "output_per_mtok": 1.60,  "context_window": 1047576, "max_output": 32768 }
+      }
+    }
+  },
+
+  "model_intelligence": {
+    "opus": {
+      "model_id": "claude-opus-4-6",
+      "strengths": ["agentic coding", "complex reasoning", "tool use", "error recovery", "architecture decisions"],
+      "weaknesses": ["higher latency", "tokenizer tax on 4.7 (12-35% more tokens)"],
+      "best_for": "architecture, security review, complex debugging, multi-step planning",
+      "avoid_for": "simple file reads, grep, formatting — wasteful at this tier"
+    },
+    "sonnet": {
+      "model_id": "claude-sonnet-4-6",
+      "strengths": ["best speed/intelligence ratio", "precise minimal diffs", "1M context", "extended thinking"],
+      "weaknesses": ["less reliable on complex multi-step reasoning than Opus"],
+      "best_for": "implementation, refactoring, test writing, code edits, git operations",
+      "avoid_for": "architecture decisions, security audits — upgrade to think tier"
+    },
+    "haiku": {
+      "model_id": "claude-haiku-4-5-20251001",
+      "strengths": ["fastest latency", "cheapest", "good enough for read-only tasks"],
+      "weaknesses": ["200k context (vs 1M for others)", "weaker reasoning", "older knowledge cutoff"],
+      "best_for": "file lookups, grep, explore, read-only research, listing files",
+      "avoid_for": "any task requiring edits, reasoning, or judgment"
+    },
+    "gpt-5.5": {
+      "model_id": "gpt-5.5",
+      "strengths": ["complex reasoning", "fast interactive responses", "strong code review", "independent perspective from Claude"],
+      "weaknesses": ["different failure modes than Claude — feature not bug for dual-brain"],
+      "best_for": "independent code review (dual-brain), second opinions on architecture",
+      "codex_compatible": true
+    },
+    "gpt-5.4": {
+      "model_id": "gpt-5.4",
+      "strengths": ["good speed/cost ratio", "1M context", "strong instruction following"],
+      "weaknesses": ["less capable reasoning than gpt-5.5"],
+      "best_for": "implementation and execution tasks via Codex",
+      "codex_compatible": true
+    },
+    "gpt-4.1-mini": {
+      "model_id": "gpt-4.1-mini",
+      "strengths": ["extremely cheap", "good instruction following", "1M context"],
+      "weaknesses": ["32k max output", "no reasoning chain"],
+      "best_for": "cheap search/lookup tasks via Codex",
+      "codex_compatible": true
+    }
+  },
+
+  "tiers": {
+    "search": {
+      "description": "Read-only lookups, exploration, grep, find, file reads",
+      "prefer": "cheapest available model",
+      "tasks": ["explore", "grep", "find", "ls", "read_file", "git_log", "git_status"]
+    },
+    "execute": {
+      "description": "Implementation, edits, test runs, git operations, linting",
+      "prefer": "mid-tier model",
+      "tasks": ["edit", "write", "test_run", "lint", "format", "simple_fix", "refactor_small"]
+    },
+    "think": {
+      "description": "Architecture, review, planning, security, complex debugging",
+      "prefer": "most capable model",
+      "tasks": ["architecture", "review", "planning", "security", "complex_debug", "design"]
+    }
+  },
+
+  "quality_gate": {
+    "enabled": true,
+    "trigger_extensions": [".ts", ".tsx", ".js", ".jsx", ".py", ".rs", ".go", ".java", ".rb", ".swift", ".kt"],
+    "skip_patterns": ["test", "__tests__", "spec", ".md", ".json", ".yaml", ".toml", ".txt"]
+  },
+
+  "routing_rules": {
+    "subagent_defaults": {
+      "Explore": "search",
+      "general-purpose": "execute",
+      "Plan": "think",
+      "code-reviewer": "think"
+    },
+    "max_concurrent_think": 1,
+    "max_concurrent_execute": 3,
+    "max_concurrent_search": 4,
+    "model_routing_note": "Claude Code model: param may be silently ignored (issue #43869). Set CLAUDE_CODE_SUBAGENT_MODEL env var as fallback if subagents all run on parent model."
+  },
+
+  "codex_skills": {
+    "review": {
+      "description": "Independent GPT code review via ChatGPT subscription",
+      "command": "node .claude/hooks/dual-brain-review.mjs",
+      "requires": "codex_auth"
+    },
+    "quality_gate": {
+      "description": "Config-driven quality gate with review artifacts",
+      "command": "node .claude/hooks/quality-gate.mjs"
+    },
+    "cost_report": {
+      "description": "Session activity and cost estimate by model tier",
+      "command": "node .claude/hooks/cost-report.mjs"
+    },
+    "test": {
+      "description": "Self-test harness for all orchestrator hooks",
+      "command": "node .claude/hooks/test-orchestrator.mjs"
+    },
+    "health_check": {
+      "description": "Verify all hooks are wired and system is healthy",
+      "command": "node .claude/hooks/health-check.mjs"
+    },
+    "session_report": {
+      "description": "Comprehensive session-end summary: activity by tier, routing compliance, quality gate status, data quality, drift warnings",
+      "command": "node .claude/hooks/session-report.mjs"
+    },
+    "setup_wizard": {
+      "description": "Interactive setup wizard — configures Claude Code hooks, dual-provider routing (Claude + OpenAI/Codex), subscription tiers, and cost-tracking settings",
+      "command": "node .claude/hooks/setup-wizard.mjs"
+    },
+    "gpt_dispatch": {
+      "description": "Dispatch execution tasks to GPT via Codex CLI",
+      "command": "node .claude/hooks/gpt-work-dispatcher.mjs"
+    },
+    "budget_balance": {
+      "description": "Show provider balance status and routing recommendations",
+      "command": "node .claude/hooks/budget-balancer.mjs"
+    }
+  },
+
+  "pricing_verified": "2026-05-13",
+
+  "budgets": {
+    "session_warn_usd": 5.00,
+    "session_limit_usd": 10.00,
+    "daily_warn_usd": 20.00,
+    "daily_limit_usd": 50.00,
+    "alert_cooldown_minutes": 15
+  },
+
+  "routing": {
+    "strategy": "hybrid-specialized-balanced",
+    "codex_startup_penalty_ms": 20000,
+    "min_codex_task_ms": 180000,
+    "dual_thinking_permission_threshold": {
+      "estimated_tokens": 50000,
+      "agent_count": 2
+    }
+  },
+
+  "providers": {
+    "claude": {
+      "enabled": true,
+      "subscription": "max-5x",
+      "models": {
+        "think": "opus",
+        "execute": "sonnet",
+        "search": "haiku"
+      },
+      "rolling_window_hours": 5,
+      "pressure_thresholds": {
+        "warm": 0.65,
+        "hot": 0.82,
+        "throttled": 0.95
+      }
+    },
+    "openai": {
+      "enabled": true,
+      "subscription": "pro",
+      "codex_command": "codex",
+      "models": {
+        "think": "gpt-5.5",
+        "execute": "gpt-5.4",
+        "search": "gpt-4.1-mini"
+      },
+      "rolling_window_hours": 5,
+      "pressure_thresholds": {
+        "warm": 0.65,
+        "hot": 0.82,
+        "throttled": 0.95
+      }
+    }
+  },
+
+  "dual_thinking": {
+    "enabled": true,
+    "auto_triggers": [
+      "architecture",
+      "security",
+      "database-migration",
+      "public-api",
+      "large-refactor",
+      "dependency-upgrade",
+      "production-incident"
+    ],
+    "sensitive_paths": [
+      "auth", "security", "middleware/auth", "payment", "billing",
+      "migration", "schema", "permissions", "secrets", "crypto",
+      "api/public", ".env"
+    ],
+    "conflict_resolver": "least-pressured-think-model"
+  }
+}