@minasoft/mina-ai-router 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# Mina AI Router
+
+Mina AI Router is a local control plane for visible CLI AI agents.
+
+It lets a developer run project-scoped Codex or Claude sessions in `tmux`, register them as agents, inspect their capabilities, and route questions between agents through a local MCP server.
+
+## What It Does
+
+- Runs a local HTTP UI and MCP endpoint.
+- Shows live agents in a router-centered flow diagram.
+- Starts Codex or Claude agents in `tmux` from a project directory.
+- Includes a repo-local agent registration skill for self-registration.
+- Captures and controls each agent terminal from the browser.
+- Stores agent metadata, capability notices, and routed request history locally.
+- Lets one registered agent ask another registered agent for project-specific context.
+
+## Install the `mair` Command
+
+```sh
+npm install -g @minasoft/mina-ai-router
+mair version
+```
+
+Then start the local router:
+
+```sh
+mair server start --port 3333
+```
+
+Open:
+
+```text
+http://127.0.0.1:3333/
+```
+
+## Documentation
+
+- [Getting Started](./docs/GETTING-STARTED.md): choose the right start guide.
+- [User Start Guide](./docs/USER-START-GUIDE.md): UI-first usage with screenshots.
+- [Developer Start Guide](./docs/DEVELOPER-START-GUIDE.md): build, test, and development workflow.
+- [MCP Client Setup](./docs/MCP-CLIENT-SETUP.md): Codex and Claude MCP registration.
+- [Skill Install Guide](./docs/SKILL-INSTALL-GUIDE.md): Codex and Claude skill installation.
+- [HTTP UI and MCP Server](./docs/HTTP-UI-MCP.md): server, MCP, and command reference.
+- [Agent Registration Skill](./skills/mina-ai-router-agent/SKILL.md): instructions used by Codex or Claude to register the current visible CLI session.
+- [Troubleshooting](./docs/TROUBLESHOOTING.md): common routing and tmux issues.
+
+## Verification
+
+```sh
+npm run verify
+```
+
+This runs core tests plus HTTP, CLI control, tmux, MCP, and multi-agent smoke tests.

package/dist/apps/cli/src/index.js

@@ -0,0 +1,574 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
+const src_1 = require("../../../packages/core/src");
+const src_2 = require("../../../packages/transports/src");
+const statePath = process.env.MINA_ROUTER_STATE ?? (0, node_path_1.join)(process.cwd(), "data", "router-state.json");
+const version = "0.1.0";
+const serverPidPath = process.env.MINA_SERVER_PID ?? (0, node_path_1.join)(process.cwd(), "data", "mair-server.json");
+async function main(argv) {
+    const command = argv[2];
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        printHelp();
+        return;
+    }
+    const context = createContext();
+    switch (command) {
+        case "version":
+        case "--version":
+        case "-v":
+            printJson({ name: "@minasoft/mina-ai-router", version });
+            break;
+        case "health":
+            await showHealth(context);
+            break;
+        case "verify":
+            runVerify();
+            break;
+        case "server":
+            handleServerCommand(argv.slice(3));
+            break;
+        case "codex":
+            startVisibleAgent("codex", "codex --no-alt-screen", argv.slice(3), context);
+            break;
+        case "claude":
+            startVisibleAgent("claude", "claude", argv.slice(3), context);
+            break;
+        case "register":
+            registerAgent(argv.slice(3), context);
+            break;
+        case "agents":
+            await listAgents(context);
+            break;
+        case "agent":
+            await showAgent(argv.slice(3), context);
+            break;
+        case "attach":
+            showAttach(argv.slice(3), context);
+            break;
+        case "setup-codex-pair":
+            setupCodexPair(argv.slice(3), context);
+            break;
+        case "serve":
+            serveHttp(argv.slice(3));
+            break;
+        case "ask":
+            await askAgent(argv.slice(3), context);
+            break;
+        case "requests":
+            listRequests(argv.slice(3), context);
+            break;
+        case "request":
+            showRequest(argv.slice(3), context);
+            break;
+        default:
+            throw new Error(`Unknown command "${command}". Run "mair help".`);
+    }
+}
+function handleServerCommand(args) {
+    const action = args[0] ?? "status";
+    const flags = parseFlags(args.slice(1));
+    switch (action) {
+        case "start":
+            startServer(flags);
+            break;
+        case "stop":
+            stopServer();
+            break;
+        case "status":
+            printJson(serverStatus());
+            break;
+        default:
+            throw new Error("Usage: mair server <start|stop|status> [--port 3333] [--host 127.0.0.1]");
+    }
+}
+function startServer(flags) {
+    const current = serverStatus();
+    if (current.running) {
+        printJson(current);
+        return;
+    }
+    const port = flags.port ?? process.env.MINA_HTTP_PORT ?? "3333";
+    const host = flags.host ?? process.env.MINA_HTTP_HOST ?? "127.0.0.1";
+    const serverPath = (0, node_path_1.join)(__dirname, "../../http-server/src/index.js");
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(serverPidPath), { recursive: true });
+    const logPath = flags.log ?? (0, node_path_1.join)((0, node_path_1.dirname)(serverPidPath), "mair-server.log");
+    const child = (0, node_child_process_1.spawn)(process.execPath, [serverPath], {
+        detached: true,
+        stdio: "ignore",
+        env: {
+            ...process.env,
+            PORT: port,
+            HOST: host,
+            MINA_ROUTER_STATE: process.env.MINA_ROUTER_STATE ?? statePath,
+        },
+    });
+    child.unref();
+    const pid = child.pid;
+    if (!pid) {
+        throw new Error("Failed to start Mina HTTP server.");
+    }
+    sleep(500);
+    (0, node_fs_1.writeFileSync)(serverPidPath, `${JSON.stringify({
+        pid,
+        port,
+        host,
+        statePath: process.env.MINA_ROUTER_STATE ?? statePath,
+        logPath,
+        uiUrl: `http://${host}:${port}/`,
+        mcpUrl: `http://${host}:${port}/mcp`,
+        startedAt: new Date().toISOString(),
+    }, null, 2)}\n`);
+    printJson(serverStatus());
+}
+function stopServer() {
+    const status = serverStatus();
+    if (!status.pid) {
+        printJson({ ok: true, running: false, message: "No Mina server pid file found." });
+        return;
+    }
+    if (status.running) {
+        process.kill(status.pid, "SIGTERM");
+    }
+    try {
+        (0, node_fs_1.unlinkSync)(serverPidPath);
+    }
+    catch {
+        // pid file may already be gone
+    }
+    printJson({ ok: true, running: false, stoppedPid: status.pid });
+}
+function serverStatus() {
+    if (!(0, node_fs_1.existsSync)(serverPidPath)) {
+        return {
+            running: false,
+            pidPath: serverPidPath,
+        };
+    }
+    const saved = JSON.parse((0, node_fs_1.readFileSync)(serverPidPath, "utf8"));
+    const running = saved.pid ? isProcessRunning(saved.pid) : false;
+    return {
+        ...saved,
+        running,
+        pidPath: serverPidPath,
+    };
+}
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function startVisibleAgent(agentType, defaultCommand, args, context) {
+    assertCommandAvailable("tmux");
+    const flags = parseFlags(args);
+    const root = flags.root ?? process.cwd();
+    const projectName = flags.name ?? (0, node_path_1.basename)(root);
+    const id = flags.id ?? sanitizeName(projectName);
+    const sessionId = flags.session ?? `${agentType}-${sanitizeName(projectName)}`;
+    const startupCommand = flags.command ?? defaultCommand;
+    assertCommandAvailable(startupCommand.split(/\s+/)[0]);
+    const shouldAttach = flags.attach !== "false" && flags["no-attach"] !== "true";
+    const shouldPromptRegister = flags.register !== "false" && flags["no-register"] !== "true";
+    const registerDelayMs = flags["register-delay-ms"] ? Number(flags["register-delay-ms"]) : 4000;
+    const agent = {
+        id,
+        name: id,
+        agentType,
+        transport: "tmux",
+        sessionId,
+        projectRoot: root,
+        startupCommand,
+    };
+    const tmux = new src_2.TmuxClient();
+    const existed = tmux.hasSession(sessionId);
+    tmux.ensureSession(agent);
+    if (shouldPromptRegister && !context.registry.get(id)) {
+        sleep(registerDelayMs);
+        const prompt = buildSelfRegistrationPrompt(agent);
+        if (agentType === "codex") {
+            tmux.sendCodexText(sessionId, prompt);
+        }
+        else {
+            tmux.sendText(sessionId, prompt);
+        }
+    }
+    const summary = {
+        agent,
+        existed,
+        attach: `tmux attach -t ${sessionId}`,
+        registration: shouldPromptRegister && !context.registry.get(id)
+            ? "registration prompt sent to agent"
+            : "registration prompt skipped",
+    };
+    if (!shouldAttach) {
+        printJson(summary);
+        return;
+    }
+    console.log(JSON.stringify(summary, null, 2));
+    (0, node_child_process_1.execFileSync)("tmux", ["attach", "-t", sessionId], {
+        stdio: "inherit",
+    });
+}
+function buildSelfRegistrationPrompt(agent) {
+    return [
+        "Use Mina AI Router MCP register_agent to register this visible CLI session.",
+        "Collect any missing context yourself when possible, but use these values as authoritative:",
+        `- id: ${agent.id}`,
+        `- name: ${agent.name}`,
+        `- agentType: ${agent.agentType}`,
+        `- transport: ${agent.transport}`,
+        `- sessionId: ${agent.sessionId}`,
+        `- projectRoot: ${agent.projectRoot}`,
+        `- startupCommand: ${agent.startupCommand ?? ""}`,
+        "",
+        "Before registering, create a concise capability notice for this session:",
+        "- Prefer capability docs in this order when present: CLAUDE.md/claude.md, AGENTS.md/agents.md, agent.md, README.md.",
+        "- If those files are missing, inspect package metadata and the project file tree to infer what this project/agent can help with.",
+        "- Set register_agent capabilitySummary to 2-5 short bullets or one short paragraph under 800 characters.",
+        "- Set register_agent capabilitySources to a comma-separated list of the files or project signals you used.",
+        "After registering, call list_agents and confirm this agent is available.",
+    ].join("\n");
+}
+async function showHealth(context) {
+    const agents = await context.router.listAgentStatuses();
+    const requests = context.router.listRequests();
+    const openRequests = requests.filter((request) => ["created", "sent", "waiting"].includes(request.status));
+    printJson({
+        ok: agents.every((agent) => agent.status !== "missing"),
+        version,
+        statePath,
+        tmuxAvailable: new src_2.TmuxClient().isAvailable(),
+        agents: {
+            total: agents.length,
+            available: agents.filter((agent) => agent.status === "available").length,
+            busy: agents.filter((agent) => agent.status === "busy").length,
+            missing: agents.filter((agent) => agent.status === "missing").length,
+            unknown: agents.filter((agent) => agent.status === "unknown").length,
+        },
+        requests: {
+            total: requests.length,
+            open: openRequests.length,
+            answered: requests.filter((request) => request.status === "answered").length,
+            failed: requests.filter((request) => ["failed", "timeout"].includes(request.status)).length,
+            archived: requests.filter((request) => request.status === "archived").length,
+        },
+        mcp: {
+            httpUrl: `http://${process.env.MINA_HTTP_HOST ?? "127.0.0.1"}:${process.env.MINA_HTTP_PORT ?? "3333"}/mcp`,
+        },
+    });
+}
+function runVerify() {
+    (0, node_child_process_1.execFileSync)("npm", ["run", "verify"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    printJson({ ok: true, command: "npm run verify" });
+}
+function serveHttp(args) {
+    const flags = parseFlags(args);
+    const port = flags.port ?? process.env.MINA_HTTP_PORT ?? "3333";
+    const serverPath = (0, node_path_1.join)(__dirname, "../../http-server/src/index.js");
+    const child = (0, node_child_process_1.spawn)(process.execPath, [serverPath], {
+        stdio: "inherit",
+        env: {
+            ...process.env,
+            PORT: port,
+            MINA_ROUTER_STATE: process.env.MINA_ROUTER_STATE ?? statePath,
+        },
+    });
+    child.on("exit", (code) => {
+        process.exitCode = code ?? 0;
+    });
+}
+function setupCodexPair(args, context) {
+    const options = parseFlags(args);
+    const mainRoot = options["main-root"] ?? "/Users/stevenna/WebstormProjects/minasoftai";
+    const helperRoot = options["helper-root"] ?? "/Users/stevenna/PycharmProjects/mina-ralph-loop-bootstrap-nextjs";
+    const helperId = options["helper-id"] ?? "ralph";
+    const sessionId = options.session ?? "mina-ralph-codex";
+    const mcpName = options["mcp-name"] ?? "mina-ai-router";
+    const codexCommand = options["codex-command"] ?? "codex --no-alt-screen";
+    assertCommandAvailable("codex");
+    assertCommandAvailable("tmux");
+    const agent = {
+        id: helperId,
+        name: helperId,
+        agentType: "codex",
+        transport: "tmux",
+        sessionId,
+        projectRoot: helperRoot,
+        startupCommand: codexCommand,
+    };
+    const tmux = new src_2.TmuxClient();
+    tmux.ensureSession(agent);
+    context.registry.register(agent);
+    context.save();
+    const mcpServerPath = (0, node_path_1.join)(process.cwd(), "dist", "apps", "mcp-server", "src", "index.js");
+    const mcpAddCommand = [
+        "codex",
+        "mcp",
+        "add",
+        mcpName,
+        "--env",
+        `MINA_ROUTER_STATE=${statePath}`,
+        "--",
+        "node",
+        mcpServerPath,
+    ];
+    printJson({
+        ok: true,
+        statePath,
+        helper: {
+            id: helperId,
+            root: helperRoot,
+            session: sessionId,
+            attach: `tmux attach -t ${sessionId}`,
+        },
+        main: {
+            root: mainRoot,
+            startCodex: `cd ${shellQuote(mainRoot)} && codex --no-alt-screen`,
+        },
+        mcp: {
+            addCommand: mcpAddCommand.map(shellQuote).join(" "),
+            listCommand: "codex mcp list",
+            removeCommand: `codex mcp remove ${shellQuote(mcpName)}`,
+        },
+        nextSteps: [
+            "Run npm run build before installing the MCP command if you changed source files.",
+            "Run the mcp.addCommand once so Codex CLI can see Mina AI Router.",
+            "Attach to the helper session and make sure helper Codex is ready.",
+            "Start Codex in the main.root project.",
+            `Ask main Codex to call Mina AI Router target '${helperId}' for questions about the helper project.`,
+        ],
+    });
+}
+function createContext() {
+    const fileState = new src_1.FileState(statePath);
+    const state = fileState.load();
+    const registry = new src_1.AgentRegistry(state.agents);
+    const requestStore = new src_1.RequestStore(state.requests);
+    const transports = new src_2.DefaultTransportRegistry()
+        .register("mock", new src_2.HeadlessTransport())
+        .register("headless", new src_2.HeadlessTransport())
+        .register("tmux", new src_2.TmuxTransport())
+        .register("zmux", new src_2.ZmuxTransport());
+    const context = {
+        fileState,
+        registry,
+        requestStore,
+        save: () => fileState.save({
+            agents: registry.list(),
+            requests: requestStore.list(),
+        }),
+    };
+    const router = new src_1.AgentRouter({
+        registry,
+        requestStore,
+        transports,
+        onStateChanged: context.save,
+    });
+    return {
+        ...context,
+        transports,
+        router,
+    };
+}
+function registerAgent(args, context) {
+    const id = args[0];
+    if (!id) {
+        throw new Error("Usage: mair register <id> --agent <type> --transport <transport> --session <session> --root <path>");
+    }
+    const options = parseFlags(args.slice(1));
+    const agent = {
+        id,
+        name: options.name ?? id,
+        agentType: options.agent ?? "unknown",
+        transport: (options.transport ?? "headless"),
+        sessionId: options.session ?? id,
+        projectRoot: options.root ?? process.cwd(),
+        tmuxTarget: options.target,
+        startupCommand: options.command,
+        capabilitySummary: options.summary ?? options["capability-summary"],
+        capabilitySources: options.sources ?? options["capability-sources"],
+    };
+    context.registry.register(agent);
+    context.save();
+    printJson({ agent });
+}
+async function listAgents(context) {
+    const agents = await context.router.listAgentStatuses();
+    printJson({
+        agents,
+    });
+}
+async function showAgent(args, context) {
+    const id = args[0];
+    if (!id) {
+        throw new Error("Usage: mair agent <id>");
+    }
+    const agent = context.registry.require(id);
+    const statuses = await context.router.listAgentStatuses();
+    printJson({
+        agent,
+        status: statuses.find((candidate) => candidate.id === id),
+        attach: agent.transport === "tmux" ? `tmux attach -t ${agent.sessionId}` : undefined,
+    });
+}
+function showAttach(args, context) {
+    const id = args[0];
+    if (!id) {
+        throw new Error("Usage: mair attach <id>");
+    }
+    const agent = context.registry.require(id);
+    if (agent.transport !== "tmux") {
+        throw new Error(`Agent "${id}" uses transport "${agent.transport}", not tmux.`);
+    }
+    printJson({
+        agent: agent.id,
+        command: `tmux attach -t ${agent.sessionId}`,
+    });
+}
+async function askAgent(args, context) {
+    const target = args[0];
+    const task = args.slice(1).join(" ").trim();
+    if (!target || !task) {
+        throw new Error('Usage: mair ask <target> "question" [--timeout-ms 300000]');
+    }
+    const flags = parseFlags(args);
+    try {
+        const response = await context.router.callAgent({
+            target,
+            task: taskFromArgs(args.slice(1)),
+            timeoutMs: flags["timeout-ms"] ? Number(flags["timeout-ms"]) : undefined,
+        });
+        printJson(response);
+    }
+    finally {
+        context.save();
+    }
+}
+function listRequests(args, context) {
+    const flags = parseFlags(args);
+    const target = flags.target;
+    const requests = target
+        ? context.router.listRequests().filter((request) => request.targetAgent === target)
+        : context.router.listRequests();
+    printJson({ requests });
+}
+function showRequest(args, context) {
+    const requestId = args[0];
+    if (!requestId) {
+        throw new Error("Usage: mair request <request-id>");
+    }
+    printJson(context.router.getRequest(requestId));
+}
+function parseFlags(args) {
+    const flags = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (!token?.startsWith("--")) {
+            continue;
+        }
+        const key = token.slice(2);
+        const value = args[index + 1];
+        if (!value || value.startsWith("--")) {
+            flags[key] = "true";
+            continue;
+        }
+        flags[key] = value;
+        index += 1;
+    }
+    return flags;
+}
+function assertCommandAvailable(command) {
+    try {
+        (0, node_child_process_1.execFileSync)("which", [command], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch {
+        throw new Error(`Required command "${command}" is not available on PATH.`);
+    }
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_/:=.,@+-]+$/.test(value)) {
+        return value;
+    }
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function sanitizeName(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "agent";
+}
+function sleep(milliseconds) {
+    if (!Number.isFinite(milliseconds) || milliseconds <= 0) {
+        return;
+    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+function taskFromArgs(args) {
+    const taskTokens = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token === "--timeout-ms") {
+            index += 1;
+            continue;
+        }
+        taskTokens.push(token);
+    }
+    return taskTokens.join(" ").trim();
+}
+function printHelp() {
+    console.log(`Mina AI Router
+
+Commands:
+  mair version
+  mair health
+  mair verify
+  mair server start [--port 3333] [--host 127.0.0.1]
+  mair server stop
+  mair server status
+  mair codex [--id <id>] [--session <tmux-session>] [--root <path>] [--no-attach] [--no-register]
+  mair claude [--id <id>] [--session <tmux-session>] [--root <path>] [--no-attach] [--no-register]
+  mair register <id> --agent <type> --transport <headless|mock|tmux|zmux> --session <session> --root <path>
+  mair agents
+  mair agent <id>
+  mair attach <id>
+  mair setup-codex-pair [--main-root <path>] [--helper-root <path>] [--helper-id <id>] [--session <tmux-session>]
+  mair serve [--port 3333]
+  mair ask <target> "question"
+  mair requests [--target <id>]
+  mair request <request-id>
+
+Example:
+  mair register payment --agent gemini --transport headless --session payment --root ./payment
+  mair register payment --agent gemini --transport tmux --session payment --root ~/work/payment
+  mair setup-codex-pair
+  mair serve
+  mair server start --port 3333
+  mair codex
+  mair claude
+  mair ask payment "현재 payment flow를 요약해줘."
+
+State:
+  Set MINA_ROUTER_STATE=/path/to/router-state.json to share state between CLI and MCP.
+`);
+}
+function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+main(process.argv).catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});