@minasoft/mina-ai-router 0.1.0

package/dist/apps/mcp-server/src/index.js

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const node_fs_1 = require("node:fs");
+const src_1 = require("../../../packages/core/src");
+const src_2 = require("../../../packages/transports/src");
+const importEsm = new Function("specifier", "return import(specifier)");
+const runtimeModuleUrl = (0, node_url_1.pathToFileURL)((0, node_path_1.join)(__dirname, "../../../../node_modules/@minasoft/mcp-runtime/dist/index.js")).href;
+const statePath = process.env.MINA_ROUTER_STATE ?? (0, node_path_1.join)(process.cwd(), "data", "router-state.json");
+const logPath = process.env.MINA_MCP_LOG;
+const context = createContext();
+let inputBuffer = Buffer.alloc(0);
+let runtimePromise;
+let providerPromise;
+process.stdin.on("data", (chunk) => {
+    debugLog(`stdin data bytes=${chunk.length}`);
+    debugLog(`stdin raw=${JSON.stringify(chunk.toString("utf8"))}`);
+    inputBuffer = Buffer.concat([inputBuffer, chunk]);
+    readFrames().catch((error) => {
+        debugLog(`readFrames error=${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+        sendFallbackError(undefined, error instanceof Error ? error.message : String(error));
+    });
+});
+debugLog(`startup cwd=${process.cwd()} statePath=${statePath} runtime=${runtimeModuleUrl}`);
+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 baseContext = {
+        fileState,
+        registry,
+        requestStore,
+        save: () => fileState.save({
+            agents: registry.list(),
+            requests: requestStore.list(),
+        }),
+    };
+    const router = new src_1.AgentRouter({
+        registry,
+        requestStore,
+        transports,
+        onStateChanged: baseContext.save,
+    });
+    return {
+        ...baseContext,
+        transports,
+        router,
+    };
+}
+async function readFrames() {
+    while (true) {
+        const headerEnd = inputBuffer.indexOf("\r\n\r\n");
+        if (headerEnd === -1) {
+            return;
+        }
+        const header = inputBuffer.slice(0, headerEnd).toString("utf8");
+        const lengthMatch = /Content-Length:\s*(\d+)/i.exec(header);
+        if (!lengthMatch) {
+            throw new Error("Missing Content-Length header.");
+        }
+        const contentLength = Number(lengthMatch[1]);
+        const frameStart = headerEnd + 4;
+        const frameEnd = frameStart + contentLength;
+        if (inputBuffer.length < frameEnd) {
+            return;
+        }
+        const body = inputBuffer.slice(frameStart, frameEnd).toString("utf8");
+        inputBuffer = inputBuffer.slice(frameEnd);
+        debugLog(`frame body=${body}`);
+        await handleMessage(JSON.parse(body));
+    }
+}
+async function handleMessage(message) {
+    const runtime = await loadRuntime();
+    const provider = await createProvider();
+    debugLog(`handle method=${message.method} id=${String(message.id ?? "")}`);
+    const result = await runtime.handleMcpJsonRpcMessage(message, provider, {
+        context: { requestId: String(message.id ?? "") },
+    });
+    debugLog(`result kind=${result.kind}`);
+    sendRuntimeResult(result);
+}
+async function loadRuntime() {
+    runtimePromise ?? (runtimePromise = importEsm(runtimeModuleUrl));
+    return runtimePromise;
+}
+async function createProvider() {
+    if (providerPromise) {
+        return providerPromise;
+    }
+    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,
+            },
+        },
+    ];
+    providerPromise = Promise.resolve({
+        serverInfo: {
+            name: "mina-ai-router",
+            version: "0.1.0",
+        },
+        tools: {
+            async list() {
+                return { items: tools };
+            },
+            async call({ name, arguments: args }) {
+                return callTool(name, args ?? {});
+            },
+        },
+    });
+    return providerPromise;
+}
+async function callTool(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,
+    };
+}
+function sendRuntimeResult(result) {
+    if (result.kind === "accepted") {
+        debugLog("send accepted/no-response");
+        return;
+    }
+    if (result.kind === "raw") {
+        debugLog(`send raw bytes=${Buffer.byteLength(result.body)}`);
+        process.stdout.write(`Content-Length: ${Buffer.byteLength(result.body)}\r\n\r\n`);
+        process.stdout.write(result.body);
+        return;
+    }
+    const body = JSON.stringify(result.body);
+    debugLog(`send json body=${body}`);
+    process.stdout.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n`);
+    process.stdout.write(body);
+}
+function sendFallbackError(id, message) {
+    if (id === undefined) {
+        return;
+    }
+    const body = JSON.stringify({
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32603, message },
+    });
+    process.stdout.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n`);
+    process.stdout.write(body);
+}
+function debugLog(message) {
+    if (!logPath) {
+        return;
+    }
+    try {
+        (0, node_fs_1.appendFileSync)(logPath, `${new Date().toISOString()} ${message}\n`);
+    }
+    catch {
+        // Never break MCP startup because logging failed.
+    }
+}

package/dist/packages/core/src/file-state.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileState = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const emptyState = {
+    agents: [],
+    requests: [],
+};
+class FileState {
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    load() {
+        if (!(0, node_fs_1.existsSync)(this.filePath)) {
+            return { ...emptyState };
+        }
+        const raw = (0, node_fs_1.readFileSync)(this.filePath, "utf8").trim();
+        if (!raw) {
+            return { ...emptyState };
+        }
+        const parsed = JSON.parse(raw);
+        return {
+            agents: parsed.agents ?? [],
+            requests: parsed.requests ?? [],
+        };
+    }
+    save(state) {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(this.filePath), { recursive: true });
+        const tempPath = `${this.filePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+        (0, node_fs_1.writeFileSync)(tempPath, `${JSON.stringify(state, null, 2)}\n`);
+        (0, node_fs_1.renameSync)(tempPath, this.filePath);
+    }
+}
+exports.FileState = FileState;

package/dist/packages/core/src/ids.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRequestId = createRequestId;
+let sequence = 0;
+function createRequestId() {
+    sequence += 1;
+    return `mar-${Date.now().toString(36)}-${sequence.toString(36)}`;
+}

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

@@ -0,0 +1,24 @@
+"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("./ids"), exports);
+__exportStar(require("./file-state"), exports);
+__exportStar(require("./prompt-envelope"), exports);
+__exportStar(require("./registry"), exports);
+__exportStar(require("./request-store"), exports);
+__exportStar(require("./response-parser"), exports);
+__exportStar(require("./router"), exports);
+__exportStar(require("./types"), exports);

package/dist/packages/core/src/prompt-envelope.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPromptEnvelope = buildPromptEnvelope;
+function buildPromptEnvelope(request, target) {
+    return [
+        "[Mina AI Router Request]",
+        `Request ID: ${request.id}`,
+        `From: ${request.sourceAgent}`,
+        `To: ${target.id} / ${target.agentType}`,
+        "",
+        "The source agent is asking you to answer the following request:",
+        `"${request.task}"`,
+        "",
+        "Please answer based on your current project context.",
+        "Include:",
+        "- relevant project flow",
+        "- API/status constraints",
+        "- UI or integration states the source project should support",
+        "- recommended behavior",
+        "- risks or assumptions",
+        "",
+        "Wrap your final answer with:",
+        `<<<MINA_AGENT_RESPONSE_START ${request.id}>>>`,
+        "[your answer]",
+        `<<<MINA_AGENT_RESPONSE_END ${request.id}>>>`,
+    ].join("\n");
+}

package/dist/packages/core/src/registry.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRegistry = void 0;
+class AgentRegistry {
+    constructor(agents = []) {
+        this.agents = new Map();
+        for (const agent of agents) {
+            this.register(agent);
+        }
+    }
+    register(agent) {
+        this.agents.set(agent.id, agent);
+        return agent;
+    }
+    list() {
+        return Array.from(this.agents.values()).sort((a, b) => a.id.localeCompare(b.id));
+    }
+    get(id) {
+        return this.agents.get(id);
+    }
+    unregister(id) {
+        const agent = this.require(id);
+        this.agents.delete(id);
+        return agent;
+    }
+    require(id) {
+        const agent = this.get(id);
+        if (!agent) {
+            throw new Error(`Agent "${id}" is not registered.`);
+        }
+        return agent;
+    }
+}
+exports.AgentRegistry = AgentRegistry;

package/dist/packages/core/src/request-store.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestStore = void 0;
+class RequestStore {
+    constructor(requests = []) {
+        this.requests = new Map();
+        for (const request of requests) {
+            this.requests.set(request.id, request);
+        }
+    }
+    create(request) {
+        this.requests.set(request.id, request);
+        return request;
+    }
+    list() {
+        return Array.from(this.requests.values()).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    get(id) {
+        return this.requests.get(id);
+    }
+    require(id) {
+        const request = this.get(id);
+        if (!request) {
+            throw new Error(`Request "${id}" was not found.`);
+        }
+        return request;
+    }
+    updateStatus(id, status, patch = {}) {
+        const current = this.require(id);
+        const updated = {
+            ...current,
+            ...patch,
+            status,
+            updatedAt: new Date().toISOString(),
+        };
+        this.requests.set(id, updated);
+        return updated;
+    }
+    patch(id, patch) {
+        const current = this.require(id);
+        const updated = {
+            ...current,
+            ...patch,
+            updatedAt: new Date().toISOString(),
+        };
+        this.requests.set(id, updated);
+        return updated;
+    }
+}
+exports.RequestStore = RequestStore;

package/dist/packages/core/src/response-parser.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResponseMarkerNotFoundError = void 0;
+exports.parseMarkedResponse = parseMarkedResponse;
+class ResponseMarkerNotFoundError extends Error {
+    constructor(requestId) {
+        super(`Response markers were not found for request ${requestId}.`);
+        this.name = "ResponseMarkerNotFoundError";
+    }
+}
+exports.ResponseMarkerNotFoundError = ResponseMarkerNotFoundError;
+function parseMarkedResponse(output, requestId) {
+    const startMarker = `<<<MINA_AGENT_RESPONSE_START ${requestId}>>>`;
+    const endMarker = `<<<MINA_AGENT_RESPONSE_END ${requestId}>>>`;
+    let end = output.lastIndexOf(endMarker);
+    while (end !== -1) {
+        const start = output.lastIndexOf(startMarker, end);
+        if (start === -1) {
+            throw new ResponseMarkerNotFoundError(requestId);
+        }
+        const contentStart = start + startMarker.length;
+        const answer = output.slice(contentStart, end).trim();
+        if (!isPlaceholderAnswer(answer)) {
+            return answer;
+        }
+        end = output.lastIndexOf(endMarker, start - 1);
+    }
+    throw new ResponseMarkerNotFoundError(requestId);
+}
+function isPlaceholderAnswer(answer) {
+    const normalized = answer.replace(/[|\s]/g, "");
+    return normalized === "..." || normalized === "[youranswer]";
+}

package/dist/packages/core/src/router.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRouter = void 0;
+const ids_1 = require("./ids");
+const prompt_envelope_1 = require("./prompt-envelope");
+const response_parser_1 = require("./response-parser");
+class AgentRouter {
+    constructor(options) {
+        this.busyAgents = new Set();
+        this.registry = options.registry;
+        this.requestStore = options.requestStore;
+        this.transports = options.transports;
+        this.defaultSourceAgent = options.defaultSourceAgent ?? "main";
+        this.defaultTimeoutMs = options.defaultTimeoutMs ?? 300000;
+        this.onStateChanged = options.onStateChanged;
+    }
+    listAgents() {
+        return this.registry.list();
+    }
+    listRequests() {
+        return this.requestStore.list();
+    }
+    async listAgentStatuses() {
+        const requests = this.requestStore.list();
+        return Promise.all(this.registry.list().map(async (agent) => {
+            const agentRequests = requests.filter((request) => request.targetAgent === agent.id);
+            const lastRequest = agentRequests[agentRequests.length - 1];
+            const transport = this.transports.get(agent.transport);
+            const status = transport.status
+                ? await transport.status(agent)
+                : { status: "unknown" };
+            return {
+                id: agent.id,
+                name: agent.name,
+                agentType: agent.agentType,
+                transport: agent.transport,
+                sessionId: agent.sessionId,
+                projectRoot: agent.projectRoot,
+                capabilitySummary: agent.capabilitySummary,
+                capabilitySources: agent.capabilitySources,
+                status: this.busyAgents.has(agent.id) ? "busy" : status.status,
+                detail: status.detail,
+                lastRequestStatus: lastRequest?.status,
+            };
+        }));
+    }
+    getRequest(requestId) {
+        return this.requestStore.require(requestId);
+    }
+    async callAgent(input) {
+        const target = this.registry.require(input.target);
+        if (this.busyAgents.has(target.id)) {
+            throw new Error(`Agent "${target.id}" is busy with another request.`);
+        }
+        this.busyAgents.add(target.id);
+        const now = new Date().toISOString();
+        const request = this.requestStore.create({
+            id: (0, ids_1.createRequestId)(),
+            sourceAgent: input.sourceAgent ?? this.defaultSourceAgent,
+            targetAgent: target.id,
+            task: input.task,
+            status: "created",
+            createdAt: now,
+            updatedAt: now,
+        });
+        this.persistState();
+        const transport = this.transports.get(target.transport);
+        const prompt = (0, prompt_envelope_1.buildPromptEnvelope)(request, target);
+        try {
+            await transport.send(target, prompt, request.id);
+            this.requestStore.updateStatus(request.id, "sent");
+            this.persistState();
+            this.requestStore.updateStatus(request.id, "waiting");
+            this.persistState();
+            const output = await transport.waitForResponse(target, request.id, input.timeoutMs ?? this.defaultTimeoutMs);
+            const answer = (0, response_parser_1.parseMarkedResponse)(output, request.id);
+            this.requestStore.updateStatus(request.id, "answered", { answer });
+            this.persistState();
+            return {
+                requestId: request.id,
+                target: target.id,
+                answer,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const status = /time(?:d)?\s*out|timeout/i.test(message) ? "timeout" : "failed";
+            this.requestStore.updateStatus(request.id, status, { error: message });
+            this.persistState();
+            throw error;
+        }
+        finally {
+            this.busyAgents.delete(target.id);
+        }
+    }
+    persistState() {
+        this.onStateChanged?.();
+    }
+}
+exports.AgentRouter = AgentRouter;

package/dist/packages/core/src/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });