dual-brain 6.1.0 → 7.0.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,330 @@
+#!/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'],
+    },
+  },
+];
+
+// ─── 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),
+  };
+}
+
+// ─── 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);
+    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: '1.0.0' },
+        });
+
+      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, err.stack);
+  }
+}
+
+// ─── 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "6.1.0",
+  "version": "7.0.0",
   "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
   "type": "module",
   "bin": {
@@ -50,13 +50,19 @@
     "bin/*.mjs",
     "hooks/*.mjs",
     "hooks/*.sh",
+    "mcp-server/*.mjs",
+    "mcp-server/README.md",
     "install.mjs",
     "orchestrator.json",
     "hookify.*.local.md",
     "review-rules.md",
+    "AGENTS.md",
     "CLAUDE.md",
     "README.md",
     "LICENSE",
-    "playbooks/*.json"
+    "playbooks/*.json",
+    "plugin.json",
+    "skills/*.md",
+    "agents/*.md"
   ]
 }

package/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "dual-brain",
+  "version": "7.0.0",
+  "description": "Dual-provider AI orchestration — smart routing between Claude and OpenAI",
+  "skills": [
+    { "name": "go", "description": "Route and dispatch a task", "file": "skills/go.md" },
+    { "name": "status", "description": "Show provider health and budget", "file": "skills/status.md" },
+    { "name": "think", "description": "Dual-brain architecture discussion", "file": "skills/think.md" },
+    { "name": "review", "description": "Dual-brain code review", "file": "skills/review.md" }
+  ],
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Edit|Write|NotebookEdit|Bash", "command": "node hooks/head-guard.mjs" },
+      { "matcher": "Agent", "command": "node hooks/enforce-tier.mjs" }
+    ]
+  },
+  "agents": [
+    { "name": "researcher", "file": "agents/researcher.md" },
+    { "name": "implementer", "file": "agents/implementer.md" },
+    { "name": "verifier", "file": "agents/verifier.md" }
+  ]
+}

package/skills/go.md

@@ -0,0 +1,22 @@
+---
+name: go
+description: Route and dispatch a task through dual-brain
+arguments:
+  - name: task
+    description: The task description to route
+    required: true
+  - name: dry-run
+    description: Show routing without executing
+    required: false
+  - name: files
+    description: Comma-separated file paths for risk classification
+    required: false
+---
+
+Run `dual-brain go` with the provided arguments. Execute:
+
+```bash
+dual-brain go [--dry-run] [--files <files>] "<task>"
+```
+
+Report the routing decision (provider, model, tier) and dispatch result to the user.

package/skills/review.md

@@ -0,0 +1,19 @@
+---
+name: review
+description: Dual-brain code review — two-round Claude + GPT review of the current diff
+arguments: []
+---
+
+Run the dual-brain review flow (2 rounds) on the current git diff:
+
+**Round 1** — get GPT's independent review:
+```bash
+node hooks/dual-brain-review.mjs
+```
+
+Review the same diff independently, then run **Round 2** — share your findings and get GPT's response:
+```bash
+node hooks/dual-brain-review.mjs --round 2 --claude-review "<your findings>"
+```
+
+Synthesize both rounds into a final review verdict: shared findings, unique catches from each side, and any items that need human attention.

package/skills/status.md

@@ -0,0 +1,13 @@
+---
+name: status
+description: Show provider health, budget pressure, and enforcement status
+arguments: []
+---
+
+Run `dual-brain status` and report the results to the user:
+
+```bash
+dual-brain status
+```
+
+Show provider health (Claude, OpenAI), current budget pressure for each provider, active profile, and enforcement status.

package/skills/think.md

@@ -0,0 +1,22 @@
+---
+name: think
+description: Dual-brain architecture discussion — two-round Claude + GPT analysis
+arguments:
+  - name: question
+    description: The architecture question or decision to analyze
+    required: true
+---
+
+Run the dual-brain think flow (2 rounds) using the provided question:
+
+**Round 1** — get GPT's independent analysis:
+```bash
+node hooks/dual-brain-think.mjs --question "<question>"
+```
+
+Analyze the same question independently, then run **Round 2** — share your analysis and get GPT's response:
+```bash
+node hooks/dual-brain-think.mjs --question "<question>" --round 2 --claude-says "<your analysis>"
+```
+
+Synthesize both rounds into a final decision, noting agreements, disagreements, and the chosen recommendation.