@minasoft/mina-ai-router 0.1.0

package/dist/packages/mcp/src/provider.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMinaMcpProvider = createMinaMcpProvider;
+const tools = [
+    {
+        name: "list_agents",
+        description: "List registered Mina helper agents.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "register_agent",
+        description: "Register or update an agent in Mina AI Router. Use this from a visible project Codex session to connect itself to the router.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                name: { type: "string" },
+                agentType: { type: "string" },
+                transport: { type: "string" },
+                sessionId: { type: "string" },
+                projectRoot: { type: "string" },
+                tmuxTarget: { type: "string" },
+                startupCommand: { type: "string" },
+                capabilitySummary: { type: "string" },
+                capabilitySources: { type: "string" },
+            },
+            required: ["id", "agentType", "transport", "sessionId", "projectRoot"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "call_agent",
+        description: "Send a task to a registered helper agent and wait for a marker-wrapped response.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                target: { type: "string" },
+                task: { type: "string" },
+                timeoutMs: { type: "number" },
+            },
+            required: ["target", "task"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "get_request_status",
+        description: "Return status for a Mina AI Router request.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                requestId: { type: "string" },
+            },
+            required: ["requestId"],
+            additionalProperties: false,
+        },
+    },
+];
+function createMinaMcpProvider(context) {
+    return {
+        serverInfo: {
+            name: "mina-ai-router",
+            version: "0.1.0",
+        },
+        tools: {
+            async list() {
+                return { items: tools };
+            },
+            async call({ name, arguments: args }) {
+                return callTool(context, name, args ?? {});
+            },
+        },
+    };
+}
+async function callTool(context, name, args) {
+    switch (name) {
+        case "list_agents": {
+            const agents = await context.router.listAgentStatuses();
+            return jsonToolResult({ agents });
+        }
+        case "register_agent": {
+            try {
+                const agent = agentFromArgs(args);
+                context.registry.register(agent);
+                context.save();
+                const agents = await context.router.listAgentStatuses();
+                return jsonToolResult({
+                    agent,
+                    agents,
+                });
+            }
+            catch (error) {
+                return {
+                    kind: "invalid_params",
+                    message: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }
+        case "call_agent": {
+            const target = typeof args.target === "string" ? args.target : "";
+            const task = typeof args.task === "string" ? args.task : "";
+            const timeoutMs = typeof args.timeoutMs === "number" ? args.timeoutMs : undefined;
+            if (!target || !task) {
+                return { kind: "invalid_params", message: "call_agent requires string target and task." };
+            }
+            try {
+                const response = await context.router.callAgent({ target, task, timeoutMs });
+                return jsonToolResult(response);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    kind: "tool_error",
+                    content: [{ type: "text", text: message }],
+                    structuredContent: { error: message },
+                };
+            }
+            finally {
+                context.save();
+            }
+        }
+        case "get_request_status": {
+            const requestId = typeof args.requestId === "string" ? args.requestId : "";
+            if (!requestId) {
+                return { kind: "invalid_params", message: "get_request_status requires string requestId." };
+            }
+            try {
+                const found = context.router.getRequest(requestId);
+                return jsonToolResult({
+                    requestId: found.id,
+                    status: found.status,
+                    error: found.error,
+                });
+            }
+            catch {
+                return { kind: "not_found", message: `Request "${requestId}" was not found.` };
+            }
+        }
+        default:
+            return { kind: "not_found", message: `Unknown tool "${name}".` };
+    }
+}
+function agentFromArgs(args) {
+    const id = requiredString(args.id, "id");
+    return {
+        id,
+        name: stringValue(args.name) ?? id,
+        agentType: requiredString(args.agentType, "agentType"),
+        transport: requiredString(args.transport, "transport"),
+        sessionId: requiredString(args.sessionId, "sessionId"),
+        projectRoot: requiredString(args.projectRoot, "projectRoot"),
+        tmuxTarget: stringValue(args.tmuxTarget),
+        startupCommand: stringValue(args.startupCommand),
+        capabilitySummary: stringValue(args.capabilitySummary),
+        capabilitySources: stringValue(args.capabilitySources),
+    };
+}
+function requiredString(value, field) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`register_agent requires string ${field}.`);
+    }
+    return value.trim();
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function jsonToolResult(value) {
+    const text = JSON.stringify(value, null, 2);
+    return {
+        kind: "success",
+        content: [{ type: "text", text }],
+        structuredContent: value,
+    };
+}

package/dist/packages/transports/src/headless/headless-transport.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeadlessTransport = void 0;
+class HeadlessTransport {
+    constructor() {
+        this.buffers = new Map();
+    }
+    async send(agent, input) {
+        this.buffers.set(agent.id, input);
+    }
+    async capture(agent) {
+        return this.buffers.get(agent.id) ?? "";
+    }
+    async waitForResponse(agent, requestId) {
+        const prompt = this.buffers.get(agent.id) ?? "";
+        const answer = [
+            `Headless response from ${agent.id}.`,
+            "",
+            "This transport is for local testing only.",
+            "It proves the router envelope, request lifecycle, and response parser without a live CLI session.",
+            "",
+            `Received ${prompt.length} prompt characters for request ${requestId}.`,
+        ].join("\n");
+        return [
+            `<<<MINA_AGENT_RESPONSE_START ${requestId}>>>`,
+            answer,
+            `<<<MINA_AGENT_RESPONSE_END ${requestId}>>>`,
+        ].join("\n");
+    }
+}
+exports.HeadlessTransport = HeadlessTransport;

package/dist/packages/transports/src/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./headless/headless-transport"), exports);
+__exportStar(require("./tmux/tmux-client"), exports);
+__exportStar(require("./tmux/tmux-transport"), exports);
+__exportStar(require("./transport-registry"), exports);
+__exportStar(require("./zmux/zmux-client"), exports);
+__exportStar(require("./zmux/zmux-transport"), exports);

package/dist/packages/transports/src/tmux/tmux-client.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TmuxClient = void 0;
+const node_child_process_1 = require("node:child_process");
+class TmuxClient {
+    constructor(options = {}) {
+        this.binary = options.binary ?? process.env.MINA_TMUX_BIN ?? "tmux";
+        this.captureLines = options.captureLines ?? 2000;
+        this.submitDelayMs = options.submitDelayMs ?? Number(process.env.MINA_TMUX_SUBMIT_DELAY_MS ?? "350");
+        this.submitKey = options.submitKey ?? process.env.MINA_TMUX_SUBMIT_KEY ?? "C-m";
+        this.inputChunkSize = options.inputChunkSize ?? Number(process.env.MINA_TMUX_INPUT_CHUNK_SIZE ?? "800");
+        this.clearInputKeys = options.clearInputKeys ?? splitKeys(process.env.MINA_TMUX_CLEAR_INPUT_KEYS ?? "C-u");
+        this.chunkDelayMs = options.chunkDelayMs ?? Number(process.env.MINA_TMUX_CHUNK_DELAY_MS ?? "50");
+        this.maxSubmitDelayMs = options.maxSubmitDelayMs ?? Number(process.env.MINA_TMUX_MAX_SUBMIT_DELAY_MS ?? "5000");
+    }
+    isAvailable() {
+        try {
+            this.run(["-V"]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    hasSession(sessionId) {
+        try {
+            this.run(["has-session", "-t", sessionId]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    killSession(sessionId) {
+        if (!this.hasSession(sessionId)) {
+            return;
+        }
+        this.run(["kill-session", "-t", sessionId]);
+    }
+    ensureSession(agent) {
+        if (this.hasSession(agent.sessionId)) {
+            return;
+        }
+        const args = ["new-session", "-d", "-s", agent.sessionId, "-x", "200", "-y", "60", "-c", agent.projectRoot];
+        if (agent.startupCommand) {
+            args.push(agent.startupCommand);
+        }
+        this.run(args);
+    }
+    sendText(target, text) {
+        this.run(["load-buffer", "-"], text);
+        this.run(["paste-buffer", "-t", target, "-d"]);
+        this.sleep(this.submitDelayMs);
+        this.run(["send-keys", "-t", target, this.submitKey]);
+    }
+    sendEnter(target) {
+        this.run(["send-keys", "-t", target, this.submitKey]);
+    }
+    sendCodexText(target, text) {
+        const prompt = asSingleLinePrompt(text);
+        for (const key of this.clearInputKeys) {
+            this.run(["send-keys", "-t", target, key]);
+            this.sleep(this.submitDelayMs);
+        }
+        this.sleep(this.submitDelayMs);
+        for (const chunk of chunks(prompt, this.inputChunkSize)) {
+            this.run(["send-keys", "-t", target, "-l", chunk]);
+            this.sleep(this.chunkDelayMs);
+        }
+        this.sleep(submitDelayFor(prompt, this.submitDelayMs, this.maxSubmitDelayMs));
+        this.run(["send-keys", "-t", target, this.submitKey]);
+    }
+    capture(target) {
+        return this.run(["capture-pane", "-t", target, "-p", "-J", "-S", `-${this.captureLines}`]);
+    }
+    attachCommand(agent) {
+        return `${this.binary} attach -t ${agent.sessionId}`;
+    }
+    run(args, input) {
+        try {
+            return (0, node_child_process_1.execFileSync)(this.binary, args, {
+                encoding: "utf8",
+                input,
+                stdio: input === undefined ? ["ignore", "pipe", "pipe"] : ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error(`tmux ${args.join(" ")} failed: ${detail}`);
+        }
+    }
+    sleep(milliseconds) {
+        if (!Number.isFinite(milliseconds) || milliseconds <= 0) {
+            return;
+        }
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+    }
+}
+exports.TmuxClient = TmuxClient;
+function asSingleLinePrompt(text) {
+    return text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .join(" | ");
+}
+function chunks(text, chunkSize) {
+    const size = Number.isFinite(chunkSize) && chunkSize > 0 ? Math.floor(chunkSize) : 800;
+    const result = [];
+    for (let index = 0; index < text.length; index += size) {
+        result.push(text.slice(index, index + size));
+    }
+    return result;
+}
+function splitKeys(value) {
+    return value
+        .split(",")
+        .map((key) => key.trim())
+        .filter(Boolean);
+}
+function submitDelayFor(text, minimumDelayMs, maximumDelayMs) {
+    const minimum = Number.isFinite(minimumDelayMs) && minimumDelayMs > 0 ? minimumDelayMs : 350;
+    const maximum = Number.isFinite(maximumDelayMs) && maximumDelayMs > 0 ? maximumDelayMs : 5000;
+    const proportional = 1000 + text.length * 3;
+    return Math.min(Math.max(minimum, proportional), maximum);
+}

package/dist/packages/transports/src/tmux/tmux-transport.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TmuxTransport = void 0;
+const src_1 = require("../../../core/src");
+const tmux_client_1 = require("./tmux-client");
+const pollIntervalMs = 500;
+class TmuxTransport {
+    constructor(client = new tmux_client_1.TmuxClient()) {
+        this.client = client;
+    }
+    async send(agent, input) {
+        this.client.ensureSession(agent);
+        if (agent.agentType === "codex") {
+            this.client.sendCodexText(targetFor(agent), input);
+            return;
+        }
+        this.client.sendText(targetFor(agent), input);
+    }
+    async capture(agent) {
+        this.client.ensureSession(agent);
+        return this.client.capture(targetFor(agent));
+    }
+    async waitForResponse(agent, requestId, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        let lastOutput = "";
+        while (Date.now() < deadline) {
+            lastOutput = await this.capture(agent);
+            try {
+                (0, src_1.parseMarkedResponse)(lastOutput, requestId);
+                return lastOutput;
+            }
+            catch {
+                await sleep(pollIntervalMs);
+            }
+        }
+        throw new Error(`Timed out waiting for response markers for ${requestId}. Last capture:\n${lastOutput}`);
+    }
+    async status(agent) {
+        if (!this.client.isAvailable()) {
+            return { status: "missing", detail: "tmux binary is not available" };
+        }
+        if (!this.client.hasSession(agent.sessionId)) {
+            return { status: "missing", detail: `tmux session "${agent.sessionId}" does not exist` };
+        }
+        return { status: "available", detail: this.client.attachCommand(agent) };
+    }
+}
+exports.TmuxTransport = TmuxTransport;
+function targetFor(agent) {
+    return agent.tmuxTarget ?? agent.sessionId;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/packages/transports/src/transport-registry.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultTransportRegistry = void 0;
+class DefaultTransportRegistry {
+    constructor() {
+        this.transports = new Map();
+    }
+    register(type, transport) {
+        this.transports.set(type, transport);
+        return this;
+    }
+    get(type) {
+        const transport = this.transports.get(type);
+        if (!transport) {
+            throw new Error(`Transport "${type}" is not configured.`);
+        }
+        return transport;
+    }
+}
+exports.DefaultTransportRegistry = DefaultTransportRegistry;

package/dist/packages/transports/src/zmux/zmux-client.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZmuxJsonRpcClient = void 0;
+class ZmuxJsonRpcClient {
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async sendPrompt(sessionId, prompt) {
+        void sessionId;
+        void prompt;
+        throw new Error(`Zmux JSON-RPC client is not wired yet${this.options.endpoint ? ` for ${this.options.endpoint}` : ""}.`);
+    }
+    async capture(sessionId) {
+        void sessionId;
+        throw new Error(`Zmux JSON-RPC client is not wired yet${this.options.endpoint ? ` for ${this.options.endpoint}` : ""}.`);
+    }
+}
+exports.ZmuxJsonRpcClient = ZmuxJsonRpcClient;

package/dist/packages/transports/src/zmux/zmux-transport.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZmuxTransport = void 0;
+const src_1 = require("../../../core/src");
+const zmux_client_1 = require("./zmux-client");
+const pollIntervalMs = 500;
+class ZmuxTransport {
+    constructor(client = new zmux_client_1.ZmuxJsonRpcClient()) {
+        this.client = client;
+    }
+    async send(agent, input) {
+        await this.client.sendPrompt(agent.sessionId, input);
+    }
+    async capture(agent) {
+        return this.client.capture(agent.sessionId);
+    }
+    async waitForResponse(agent, requestId, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        let lastOutput = "";
+        while (Date.now() < deadline) {
+            lastOutput = await this.capture(agent);
+            try {
+                (0, src_1.parseMarkedResponse)(lastOutput, requestId);
+                return lastOutput;
+            }
+            catch {
+                await sleep(pollIntervalMs);
+            }
+        }
+        throw new Error(`Timed out waiting for response markers for ${requestId}. Last capture:\n${lastOutput}`);
+    }
+}
+exports.ZmuxTransport = ZmuxTransport;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/docs/DEVELOPER-START-GUIDE.md

@@ -0,0 +1,111 @@
+# Developer Start Guide
+
+This guide is for developing Mina AI Router.
+
+## 1. Install Dependencies
+
+```sh
+cd mina-ai-router
+npm install
+```
+
+## 2. Build
+
+```sh
+npm run build
+```
+
+## 3. Register the Local CLI
+
+Use `npm link` so your shell can run `mair` directly.
+
+```sh
+npm link
+mair version
+```
+
+This links the package bin entries:
+
+- `mair`
+- `mair-mcp`
+- `mair-http`
+
+## 4. Run the Server During Development
+
+Preferred:
+
+```sh
+mair server start --port 3333
+mair server status
+```
+
+Direct Node fallback:
+
+```sh
+node dist/apps/cli/src/index.js server start --port 3333
+```
+
+Open:
+
+```text
+http://127.0.0.1:3333/
+```
+
+## 5. Run Verification
+
+```sh
+npm run verify
+```
+
+This runs:
+
+- TypeScript build
+- core tests
+- HTTP UI smoke test
+- CLI control smoke test
+- tmux smoke test
+- MCP smoke test
+- multi-agent smoke test
+
+## 6. Useful Development Commands
+
+```sh
+npm run build
+npm run smoke:http
+npm run smoke:mcp
+npm run smoke:tmux
+mair health
+mair verify
+```
+
+## 7. Local State
+
+By default, MAIR stores local state in:
+
+```text
+data/router-state.json
+```
+
+Override it with:
+
+```sh
+export MINA_ROUTER_STATE=/path/to/router-state.json
+```
+
+## 8. Important Paths
+
+- CLI: `apps/cli/src/index.ts`
+- HTTP UI/server: `apps/http-server/src/index.ts`
+- Browser UI HTML: `apps/http-server/src/ui.html`
+- MCP provider: `packages/mcp/src/provider.ts`
+- tmux transport: `packages/transports/src/tmux`
+- agent registration skill: `skills/mina-ai-router-agent/SKILL.md`
+
+## 9. Before Committing
+
+Run:
+
+```sh
+npm run verify
+git status --short
+```

package/docs/GETTING-STARTED.md

@@ -0,0 +1,32 @@
+# Getting Started
+
+Choose the guide that matches what you are trying to do.
+
+## For Users
+
+Start here if you want to run Mina AI Router, create agents, open their terminals in the browser, and make agents talk to each other.
+
+[User Start Guide](./USER-START-GUIDE.md)
+
+## For Developers
+
+Start here if you want to build, test, modify, or package this repository.
+
+[Developer Start Guide](./DEVELOPER-START-GUIDE.md)
+
+## Required Setup Guides
+
+Use these once per machine or per AI CLI profile:
+
+- [MCP Client Setup](./MCP-CLIENT-SETUP.md): connect Codex or Claude to the local MAIR MCP server.
+- [Skill Install Guide](./SKILL-INSTALL-GUIDE.md): install the MAIR registration skill for Codex or Claude.
+
+## Recommended First Path
+
+1. Install the local `mair` command.
+2. Start the MAIR server.
+3. Connect your AI CLI to MAIR MCP.
+4. Install the MAIR agent registration skill.
+5. Create an agent from the Web UI or with `mair codex` / `mair claude`.
+
+The user guide walks through that path with screenshots.