@minasoft/mina-ai-router 0.2.0 → 0.2.1

package/README.md

@@ -46,6 +46,8 @@ While this server is running, it owns the live router state for that state file.
 
 `mair server start` reports success only after the local Mina health endpoint is ready. If startup fails because the port is occupied, or a stale pid file points at a non-Mina process, Mina reports an actionable diagnostic instead of a healthy-looking server.
 
+By default, Mina stores local runtime files under `~/.mair`, so `mair server status`, `mair health`, and agent commands point at the same local server no matter which project directory you run them from. Set `MINA_RUNTIME_DIR`, `MINA_ROUTER_STATE`, or `MINA_SERVER_PID` only when you intentionally want an isolated test or custom runtime.
+
 ## Connect Codex or Claude
 
 Run setup from the project you want an agent to work in. It discovers the matching running router URL, configures MCP, installs the registration skill, and verifies the client profile.

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

@@ -6,9 +6,9 @@ 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 statePath = process.env.MINA_ROUTER_STATE ?? (0, src_1.defaultRouterStatePath)();
 const version = (0, src_1.packageVersion)();
-const serverPidPath = process.env.MINA_SERVER_PID ?? (0, node_path_1.join)(process.cwd(), "data", "mair-server.json");
+const serverPidPath = process.env.MINA_SERVER_PID ?? (0, src_1.defaultServerPidPath)();
 const agentStaleAfterMs = Number(process.env.MINA_AGENT_STALE_AFTER_MS ?? 15 * 60 * 1000);
 async function main(argv) {
     const command = argv[2];
@@ -1673,7 +1673,8 @@ Example:
   mair ask payment "현재 payment flow를 요약해줘."
 
 State:
-  Set MINA_ROUTER_STATE=/path/to/router-state.json to share state between CLI and MCP.
+  By default, Mina uses ~/.mair for router state, pid, and logs across directories.
+  Set MINA_RUNTIME_DIR, MINA_ROUTER_STATE, or MINA_SERVER_PID only for an isolated runtime.
 `);
 }
 function printCommandHelp(command) {

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

@@ -13,7 +13,7 @@ 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 port = Number(process.env.PORT ?? process.env.MINA_HTTP_PORT ?? 3333);
 const host = process.env.HOST ?? process.env.MINA_HTTP_HOST ?? "127.0.0.1";
-const statePath = process.env.MINA_ROUTER_STATE ?? (0, node_path_1.join)(process.cwd(), "data", "router-state.json");
+const statePath = process.env.MINA_ROUTER_STATE ?? (0, src_1.defaultRouterStatePath)();
 const agentStaleAfterMs = Number(process.env.MINA_AGENT_STALE_AFTER_MS ?? 15 * 60 * 1000);
 const context = createContext();
 let mcpHandlerPromise;

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

@@ -1,14 +1,13 @@
 #!/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)(require.resolve("@minasoft/mcp-runtime")).href;
-const statePath = process.env.MINA_ROUTER_STATE ?? (0, node_path_1.join)(process.cwd(), "data", "router-state.json");
+const statePath = process.env.MINA_ROUTER_STATE ?? (0, src_1.defaultRouterStatePath)();
 const logPath = process.env.MINA_MCP_LOG;
 const context = createContext();
 let inputBuffer = Buffer.alloc(0);

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

@@ -23,5 +23,6 @@ __exportStar(require("./registry"), exports);
 __exportStar(require("./request-store"), exports);
 __exportStar(require("./response-parser"), exports);
 __exportStar(require("./router"), exports);
+__exportStar(require("./runtime-paths"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./version"), exports);

package/dist/packages/core/src/runtime-paths.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultRuntimeDir = defaultRuntimeDir;
+exports.defaultRouterStatePath = defaultRouterStatePath;
+exports.defaultServerPidPath = defaultServerPidPath;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+function defaultRuntimeDir() {
+    return process.env.MINA_RUNTIME_DIR ?? (0, node_path_1.join)((0, node_os_1.homedir)(), ".mair");
+}
+function defaultRouterStatePath() {
+    return (0, node_path_1.join)(defaultRuntimeDir(), "router-state.json");
+}
+function defaultServerPidPath() {
+    return (0, node_path_1.join)(defaultRuntimeDir(), "mair-server.json");
+}

package/docs/TROUBLESHOOTING.md

@@ -11,7 +11,9 @@ export MINA_TMUX_BIN=/opt/homebrew/bin/tmux
 
 ## MCP and CLI See Different Agents
 
-They are probably using different state files.
+By default, Mina uses `~/.mair/router-state.json` and `~/.mair/mair-server.json` so commands run from different directories share one local server.
+
+If MCP and CLI still see different agents, they are probably using explicit custom state files.
 
 Set the same `MINA_ROUTER_STATE` for both processes:
 
@@ -39,7 +41,7 @@ Useful checks:
 ```sh
 mair server status
 lsof -nP -iTCP:3333 -sTCP:LISTEN
-cat data/mair-server.log
+cat ~/.mair/mair-server.log
 ```
 
 Stop the process that owns the port, or start Mina on another port:
@@ -56,7 +58,7 @@ Safe recovery:
 
 ```sh
 mair server status
-rm data/mair-server.json
+rm ~/.mair/mair-server.json
 mair server start --port 3333
 ```
 
@@ -116,7 +118,7 @@ mair register payment --agent gemini --transport tmux --session payment --target
 Runtime JSON state is ignored by git.
 
 ```sh
-rm data/router-state.json
+rm ~/.mair/router-state.json
 ```
 
 Use this carefully; it deletes local registrations and request history.

package/docs/USER-START-GUIDE.md

@@ -82,6 +82,8 @@ The center node is the local MCP router. The surrounding nodes are visible Codex
 
 While the router server is running, it owns the live state for that `MINA_ROUTER_STATE` file. Normal CLI reads and writes talk to the matching server when possible, so `mair health`, `mair agents`, `mair agent <id>`, the Web UI, and MCP calls stay aligned during active routes.
 
+By default, those runtime files live in `~/.mair`. You can run `mair server status` from your home directory or any project directory and it will check the same local server. Use `MINA_RUNTIME_DIR`, `MINA_ROUTER_STATE`, or `MINA_SERVER_PID` only when you intentionally want an isolated test/runtime.
+
 ## 3. Connect Your AI CLI to MCP
 
 Run setup from the project directory you want the agent to work in:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minasoft/mina-ai-router",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Local MCP router and Web UI for visible tmux-backed AI agents.",
   "homepage": "https://github.com/stevennana/mina-ai-router#readme",
   "repository": {