magi-ai 0.1.0

package/README.md

@@ -0,0 +1,377 @@
+# MAGI System
+
+> English | **[日本語](./README.ja.md)**
+
+[![CI](https://github.com/ryu-tada/MAGI-system/actions/workflows/ci.yml/badge.svg)](https://github.com/ryu-tada/MAGI-system/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-v24+-green.svg)](https://nodejs.org/)
+[![Tests](https://img.shields.io/badge/tests-2135_passing-brightgreen.svg)](./test/)
+[![Soul Systems](https://img.shields.io/badge/soul_systems-20-blueviolet.svg)](#soul-system--20-subsystems-that-give-magi-a-soul)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+
+**When one AI isn't enough** — Three AI models debate, cross-examine, and vote. Catch what a single model misses.
+
+> *Unofficial fan project inspired by Neon Genesis Evangelion. Not affiliated with Khara, Inc.*
+
+<p align="center">
+  <img src="docs/demo.gif" alt="MAGI System Demo — Evangelion TUI deliberation" width="700">
+</p>
+
+## Try It in 60 Seconds
+
+No API keys needed. Watch a pre-recorded 3-body deliberation with the Evangelion TUI:
+
+```bash
+npx magi-ai demo
+```
+
+Ready to deliberate for real? See [Quick Start](#quick-start).
+
+---
+
+## Why Multi-AI Consensus?
+
+Every AI model has blind spots. Claude is thorough but verbose. GPT is practical but sometimes overconfident. Gemini is cautious but can be vague. **Using any single model means inheriting its biases undetected.**
+
+MAGI forces disagreement to surface. When three models independently analyze the same code and two flag a security issue that the third missed, you know the issue is real. When all three agree, you can act with higher confidence than any single review provides.
+
+| Single-model review | MAGI 3-body review |
+|---------------------|--------------------|
+| One perspective, one bias | Three perspectives, biases cancel out |
+| "Looks good to me" | 2/3 APPROVE, 1 REJECT (dissent recorded) |
+| You trust the model | The models verify each other |
+| Silent failures | Cross-examination catches oversights |
+
+---
+
+## What is MAGI?
+
+In *Neon Genesis Evangelion*, the MAGI supercomputer consists of three systems, each imprinted with a different aspect of Dr. Naoko Akagi's personality, making decisions through collective deliberation.
+
+This project recreates that architecture: three AI models from different providers analyze the same problem from distinct perspectives. Cross-validation between models eliminates provider-specific biases, achieving judgment quality that no single model can reach alone.
+
+| MAGI Unit | CLI Tool | Persona | Focus |
+|-----------|----------|---------|-------|
+| **MELCHIOR-1** | Claude Code (Anthropic) | Scientist | Logic, consistency, structured reasoning |
+| **BALTHASAR-2** | Codex CLI (OpenAI) | Engineer | Practicality, code quality |
+| **CASPER-3** | Gemini CLI (Google) | Auditor | Safety, risk, holistic perspective |
+
+> **N-body support**: Defaults to 3 units, but supports 2-7 arbitrary AI units for deliberation.
+
+---
+
+## How It Works
+
+```
+Phase 1: INITIAL OPINION (parallel)
+  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
+  │  MELCHIOR   │  │  BALTHASAR  │  │   CASPER    │
+  │  (Claude)   │  │  (Codex)    │  │  (Gemini)   │
+  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘
+         └────── Promise.allSettled() ─────┘
+                          │
+              Early exit if unanimous
+                          │
+Phase 2: CROSS-EXAMINATION (parallel)
+  Each unit critiques the other two — may change position
+                          │
+Phase 3: FINAL VOTE (parallel)
+  Final vote informed by full deliberation history → Consensus Engine decides
+                          │
+                  ┌───────▼───────┐
+                  │ MAGI DECISION │
+                  └───────────────┘
+```
+
+| Decision | Condition | Outcome |
+|----------|-----------|---------|
+| **Unanimous** | 3/3 agree | Immediate adoption |
+| **Majority** | 2/3 agree | Adopted (dissent recorded) |
+| **Deadlock** | All disagree | Tiebreak / Human-in-the-loop |
+| **No quorum** | 2+ ABSTAIN | Unable to decide |
+
+---
+
+## Use Cases
+
+| Scenario | Command | What MAGI adds |
+|----------|---------|----------------|
+| PR code review | `magi review src/auth.ts` | 3 models catch different bug classes |
+| Architecture decision | `magi decide "PostgreSQL vs MongoDB?"` | Structured pros/cons from 3 perspectives |
+| Security audit | `magi deliberate "Audit this endpoint"` | Cross-validation reduces false negatives |
+| Technical debt assessment | `/ops prophecy src/legacy/` | Random forest prediction from git history |
+| CI/CD gate | `magi review --output json` | Machine-readable consensus for merge gates |
+| Team tie-breaking | `magi decide "Monorepo migration?"` | Objective multi-perspective arbitration |
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- **Node.js v24+** (v20+ minimum)
+- The following 3 AI CLIs installed and authenticated:
+
+<details>
+<summary><strong>Claude Code</strong> — MELCHIOR (Anthropic)</summary>
+
+```bash
+# Install (either one)
+curl -fsSL https://claude.ai/install.sh | bash   # Recommended
+npm install -g @anthropic-ai/claude-code           # Via Node.js
+
+# Auth — browser authentication opens on first launch
+claude
+```
+
+Requires a paid plan (Pro / Max / Teams / Enterprise). → [Official docs](https://docs.anthropic.com/en/docs/claude-code)
+
+</details>
+
+<details>
+<summary><strong>Codex CLI</strong> — BALTHASAR (OpenAI)</summary>
+
+```bash
+# Install
+npm install -g @openai/codex
+
+# Auth — setup wizard starts on first launch
+codex
+```
+
+Requires a ChatGPT subscription (Plus / Pro / Team / Enterprise). → [Official repo](https://github.com/openai/codex)
+
+</details>
+
+<details>
+<summary><strong>Gemini CLI</strong> — CASPER (Google)</summary>
+
+```bash
+# Install
+npm install -g @google/gemini-cli
+
+# Auth — select "Sign in with Google" on first launch
+gemini
+```
+
+Free with a Google account (60 req/min, 1,000 req/day). → [Official repo](https://github.com/google-gemini/gemini-cli)
+
+</details>
+
+### Install
+
+```bash
+npm install -g magi-ai
+```
+
+### Verify
+
+```bash
+magi doctor
+```
+
+```
+  ✓ MELCHIOR: 2.x.x (Claude Code)
+  ✓ BALTHASAR: codex-cli 0.x.x
+  ✓ CASPER: 0.x.x
+```
+
+### Start
+
+```bash
+magi
+```
+
+---
+
+## Usage
+
+On launch, a NERV boot sequence plays and the interactive REPL starts. Type a question in natural language and a 3-body deliberation begins, with the full-screen TUI showing the process in real time.
+
+```
+  ╔════════════════════════════════════════════╗
+  ║          M A G I  S Y S T E M              ║
+  ║          REPL INTERFACE READY              ║
+  ╚════════════════════════════════════════════╝
+  Type a question to deliberate. /help for commands.
+
+MAGI[01|NORM|3/3|CTX:0]> Should we mass-adopt this new ORM?
+  [Full-screen TUI → NERV boot → 3-body deliberation → result]
+
+  ╔═══════════════════════════════════════════════╗
+  ║  MAGI DECISION: MAJORITY_APPROVE   CONF 82%   ║
+  ╠═══════════════════════════════════════════════╣
+  ║  MELCHIOR   ✓ APPROVE  ████████░░  84%        ║
+  ║  BALTHASAR  ✓ APPROVE  ██████████  95%        ║
+  ║  CASPER     ✗ REJECT   ██████░░░░  67%        ║
+  ╚═══════════════════════════════════════════════╝
+
+MAGI[02|NORM|3/3|CTX:1]> Can you elaborate on the risks?
+  [Re-deliberation with previous context auto-injected]
+```
+
+Type any question to start deliberation. Slash commands provide specialized operations:
+
+| Command | Action |
+|---------|--------|
+| `/review <file>` | Code review deliberation (Tab completion) |
+| `/decide <question>` | Architecture decision |
+| `/berserk <prompt>` | BERSERK mode (5 strategies x N units deathmatch) |
+| `/status` | System dashboard |
+| `/export [file]` | Export deliberation results |
+| `/ops watch start` | Start Angel detection daemon |
+| `/diag evolve` | S² Engine self-evolution |
+| `/admin self-destruct <reason>` | Self-destruct sequence (unanimous required) |
+| `/help` | Full command list |
+
+**Context persistence:** The last 5 deliberation summaries are retained and automatically injected into follow-up questions. Project context (git status, package.json, related files) is also auto-collected.
+
+### MCP Server (Claude Code Integration)
+
+An `.mcp.json` is included at the repo root. Restart Claude Code and the 4 tools (`magi_deliberate`, `magi_review`, `magi_decide`, `magi_doctor`) become available automatically. Verify with MCP Inspector: `npx @modelcontextprotocol/inspector magi-mcp`
+
+### Programmatic API
+
+```typescript
+import { Magi } from 'magi-ai';
+
+const magi = new Magi();
+const result = await magi.deliberate({
+  type: 'code-review',
+  title: 'Review auth middleware',
+  artifacts: [{ type: 'file', path: 'src/auth.ts', content: '...', language: 'typescript' }],
+});
+
+console.log(result.consensus.decision); // => 'MAJORITY_APPROVE'
+```
+
+> Non-interactive commands (`magi deliberate`, `magi review`, `magi decide`) are also available for CI/scripts. See `magi --help`.
+
+---
+
+## Features
+
+### Evangelion TUI
+
+An Evangelion-themed full-screen interface launches by default. From the NERV boot sequence to the inverted-Y 3-panel vote visualization, it faithfully recreates the feel of the original. Zero additional dependencies (raw ANSI + chalk).
+
+- NERV boot sequence (~1.5s)
+- Inverted-Y panels — BALTHASAR (top center), CASPER (bottom left), MELCHIOR (bottom right)
+- Breathing animation — panel borders pulse on a sin() curve while thinking
+- Cascading vote reveal + decision stamps
+- BERSERK flash — red flash on berserk warning
+- Detail overlay — press `1`/`2`/`3` to view per-unit reasoning
+
+### Soul System — 20 Subsystems That Give MAGI a Soul
+
+20 subsystems that map Evangelion lore into technically meaningful features:
+
+- **Memory & Personality (EngRam)** — TF-IDF similarity search, 3-layer memory, 12-dim drift detection
+- **Sync Rate** — Beta-distribution Bayesian estimation for task-fitness tracking
+- **A.T. Field** — Quantitative groupthink bias detection and neutralization
+- **BERSERK Mode** — 5 strategies x N units in parallel, fitness-based selection deathmatch
+- **Instrumentality** — MoA weighted reasoning fusion for deadlock resolution
+- **LCL** — Phase-based information density control + 4-type hallucination detection/purification
+- **Angel Detection** — Git-diff-based 6-type code threat pattern detection
+- **Dead Sea Scrolls** — Random forest (50 trees) technical debt prediction
+- **Type-666 Firewall** — 4-layer defense-in-depth firewall
+- **Self-Destruct Sequence** — BFT f=0 unanimous irreversible operation ritual
+- **S² Engine** — Self-diagnosis, improvement proposals, meta-deliberation self-evolution
+- **SEELE Council** — PBFT+Raft distributed consensus protocol
+- **Neon Genesis** — Fisher-Yates memory survival full reset
+
+### Security
+
+9-layer security hardening: Zod schema input validation → prompt injection prevention (9 patterns) → stdin delivery + dangerous flag detection → process sandbox (ENV/CMD allowlist) → SafeOpinionSchema output validation → SHA-256 hash-chain audit log → semaphore + timeouts → replay prevention nonce → random-salt encryption
+
+### Auto-Context Collection
+
+Automatically collects and injects project context (git status, package.json, directory tree) and related files (imports, test files) during deliberation. Opt out with `--no-auto-context`. Sensitive files (.env, .key, credentials, etc.) are excluded automatically.
+
+---
+
+## Architecture
+
+```
+MAGI-system/
+├── bin/                   # CLI entry points (magi, magi-mcp, magi-benchmark)
+├── src/
+│   ├── index.ts           # Public API (Magi class)
+│   ├── types/             # TypeScript types & Zod schemas
+│   ├── adapters/          # CLI wrappers (claude, codex, gemini)
+│   ├── engine/            # Core deliberation (kernel, consensus, middleware)
+│   │   ├── kernel/        #   Deliberation loop, phase runner, unit executor
+│   │   └── middleware/    #   Koa-style chain (cache, firewall)
+│   ├── parsers/           # Opinion extraction (JSON extractor, Zod schema, unstructured)
+│   ├── pipelines/         # Task-specific flows (code-review, architecture, bug-analysis)
+│   ├── tui/               # Evangelion full-screen TUI (raw ANSI, double-buffered)
+│   ├── repl/              # Interactive REPL (19 slash commands, state machine)
+│   ├── mcp/               # MCP server (4 tools, stdio transport)
+│   ├── context/           # Auto-context collection (git, imports, tests)
+│   ├── cache/             # SHA-256 keyed result cache with TTL
+│   ├── metrics/           # Token usage tracking
+│   ├── audit/             # SHA-256 hash chain audit logging
+│   └── utils/             # Shared utilities (process sandbox, file validation)
+├── test/                  # 2135 tests (vitest)
+│   ├── e2e/               #   E2E with real CLIs (MAGI_E2E=1 gated)
+│   ├── integration/       #   Orchestrator + TUI integration
+│   └── unit/              #   Per-module unit tests
+└── docs/                  # User-facing documentation
+```
+
+---
+
+## Development
+
+To develop from source:
+
+```bash
+git clone https://github.com/ryu-tada/MAGI-system.git
+cd MAGI-system
+npm install
+npm test              # 2135 tests
+npm run typecheck     # Type check
+npm run build         # Build
+```
+
+---
+
+## Documentation
+
+- [Practical Examples](docs/EXAMPLES.md) — 8 scenarios with commands and expected output
+- [Tuning Guide](docs/TUNING_GUIDE.md) — Configuration reference and optimization strategies
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — Common issues and solutions
+- [Benchmark Results](docs/BENCHMARK_RESULTS.md) — Scoring framework validation (run with real CLIs for production data)
+- [Contributing](CONTRIBUTING.md) — Development setup, adding adapters/pipelines
+- [Changelog](CHANGELOG.md) — Release history
+
+---
+
+## Tech Stack
+
+- **Language**: TypeScript (ESM)
+- **Runtime**: Node.js v24+ (v20+ minimum)
+- **Dependencies**: commander, chalk, zod, @modelcontextprotocol/sdk
+- **Test**: Vitest (2135 tests)
+- **Dev**: tsx
+
+---
+
+## Credits & Legal
+
+> "The MAGI's answer is — unanimous."
+> — Ritsuko Akagi, *Neon Genesis Evangelion*
+
+MAGI System is inspired by the MAGI supercomputer system from *Neon Genesis Evangelion*, created by Hideaki Anno and produced by Gainax / Khara, Inc.
+
+### Disclaimer
+
+This is an **unofficial, non-commercial, fan-made** open-source project. It is not affiliated with, endorsed by, or connected to Khara, Inc. or any official Evangelion production.
+
+*Neon Genesis Evangelion* and related names are copyrighted works of Khara, Inc. All rights reserved by their respective owners.
+
+---
+
+## License
+
+MIT — See [LICENSE](./LICENSE) for details.

package/dist/bin/magi-benchmark.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * MAGI Benchmark CLI
+ *
+ * Runs golden-task benchmarks comparing single-Claude vs MAGI 3-body deliberation.
+ *
+ * Usage:
+ *   npx tsx bin/magi-benchmark.ts                    # Full benchmark
+ *   npx tsx bin/magi-benchmark.ts --dry-run           # MockAdapter dry-run
+ *   npx tsx bin/magi-benchmark.ts --single-only       # Single Claude only
+ *   npx tsx bin/magi-benchmark.ts --magi-only         # MAGI 3-body only
+ *   npx tsx bin/magi-benchmark.ts --category security  # Category filter
+ */
+export {};

package/dist/bin/magi-benchmark.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * MAGI Benchmark CLI
+ *
+ * Runs golden-task benchmarks comparing single-Claude vs MAGI 3-body deliberation.
+ *
+ * Usage:
+ *   npx tsx bin/magi-benchmark.ts                    # Full benchmark
+ *   npx tsx bin/magi-benchmark.ts --dry-run           # MockAdapter dry-run
+ *   npx tsx bin/magi-benchmark.ts --single-only       # Single Claude only
+ *   npx tsx bin/magi-benchmark.ts --magi-only         # MAGI 3-body only
+ *   npx tsx bin/magi-benchmark.ts --category security  # Category filter
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { BenchmarkRunner } from '../src/benchmark/runner.js';
+import { GOLDEN_TASKS } from '../src/benchmark/golden-tasks.js';
+const program = new Command();
+program
+    .name('magi-benchmark')
+    .description('Run MAGI quality benchmarks against golden tasks')
+    .option('--dry-run', 'Use MockAdapters for scoring logic validation')
+    .option('--single-only', 'Run single-Claude benchmark only')
+    .option('--magi-only', 'Run MAGI 3-body benchmark only')
+    .option('--category <name>', 'Filter by category (code-review|architecture|bug-analysis|security)')
+    .option('--output-dir <path>', 'Output directory for result JSON files')
+    .action(async (opts) => {
+    const categories = new Set(GOLDEN_TASKS.map(t => t.category));
+    if (opts.category && !categories.has(opts.category)) {
+        console.error(chalk.red(`Unknown category: ${opts.category}`));
+        console.error(`Available: ${[...categories].join(', ')}`);
+        process.exit(1);
+    }
+    const runner = new BenchmarkRunner({
+        dryRun: opts.dryRun,
+        singleOnly: opts.singleOnly,
+        magiOnly: opts.magiOnly,
+        category: opts.category,
+        outputDir: opts.outputDir,
+    });
+    const taskCount = opts.category
+        ? GOLDEN_TASKS.filter(t => t.category === opts.category).length
+        : GOLDEN_TASKS.length;
+    console.log(chalk.cyan('━'.repeat(60)));
+    console.log(chalk.cyan.bold('  MAGI Benchmark'));
+    console.log(chalk.cyan('━'.repeat(60)));
+    console.log(`  Tasks: ${taskCount}`);
+    console.log(`  Mode:  ${opts.dryRun ? 'dry-run (MockAdapter)' : 'real CLI'}`);
+    if (opts.singleOnly)
+        console.log('  Scope: single-Claude only');
+    if (opts.magiOnly)
+        console.log('  Scope: MAGI 3-body only');
+    if (opts.category)
+        console.log(`  Filter: ${opts.category}`);
+    console.log(chalk.cyan('━'.repeat(60)));
+    console.log();
+    try {
+        const { single, magi } = await runner.runAll();
+        if (single) {
+            console.log(chalk.yellow('── Single Claude ──'));
+            console.log(`  Weighted Score:     ${pct(single.aggregate.weightedScore)}`);
+            console.log(`  Vote Accuracy:      ${pct(single.aggregate.voteAccuracy)}`);
+            console.log(`  Detection Coverage: ${pct(single.aggregate.detectionCoverage)}`);
+            console.log(`  Avg Duration:       ${Math.round(single.aggregate.avgDurationMs)}ms`);
+            console.log();
+        }
+        if (magi) {
+            console.log(chalk.green('── MAGI 3-Body ──'));
+            console.log(`  Weighted Score:     ${pct(magi.aggregate.weightedScore)}`);
+            console.log(`  Vote Accuracy:      ${pct(magi.aggregate.voteAccuracy)}`);
+            console.log(`  Detection Coverage: ${pct(magi.aggregate.detectionCoverage)}`);
+            console.log(`  Avg Duration:       ${Math.round(magi.aggregate.avgDurationMs)}ms`);
+            console.log();
+        }
+        if (single && magi) {
+            const delta = magi.aggregate.weightedScore - single.aggregate.weightedScore;
+            const sign = delta >= 0 ? '+' : '';
+            const color = delta >= 0 ? chalk.green : chalk.red;
+            console.log(color(`  Delta (MAGI - Single): ${sign}${(delta * 100).toFixed(1)}pp`));
+            console.log();
+        }
+        console.log(chalk.gray('Report saved to docs/BENCHMARK_RESULTS.md'));
+        console.log(chalk.gray('Result JSON saved to test/benchmark/results/'));
+    }
+    catch (err) {
+        console.error(chalk.red('Benchmark failed:'), err);
+        process.exit(1);
+    }
+});
+program.parse();
+function pct(value) {
+    return `${(value * 100).toFixed(1)}%`;
+}

package/dist/bin/magi-mcp.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * MAGI MCP Server — stdio transport entry point
+ *
+ * Prevents stdout pollution from libraries (ora, chalk, etc.)
+ * so only MCP JSON-RPC frames appear on stdout.
+ */
+export {};

package/dist/bin/magi-mcp.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * MAGI MCP Server — stdio transport entry point
+ *
+ * Prevents stdout pollution from libraries (ora, chalk, etc.)
+ * so only MCP JSON-RPC frames appear on stdout.
+ */
+// Layer 1: Redirect console.log/info to stderr before any imports
+console.log = (...args) => console.error(...args);
+console.info = (...args) => console.error(...args);
+// Layer 2: Environment variables to suppress color/spinner output
+process.env['NO_COLOR'] = '1';
+process.env['FORCE_COLOR'] = '0';
+process.env['CI'] = '1';
+// Layer 3: Safety flag for future use
+process.env['MAGI_MCP_MODE'] = '1';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMagiMcpServer } from '../src/mcp/server.js';
+async function main() {
+    const server = createMagiMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('[magi-mcp] Server started on stdio');
+}
+main().catch((error) => {
+    console.error('[magi-mcp] Fatal error:', error);
+    process.exit(1);
+});

package/dist/bin/magi.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};