@minasoft/mina-ai-router 0.1.0

package/docs/HTTP-UI-MCP.md

@@ -0,0 +1,142 @@
+# HTTP UI and MCP Server
+
+Mina AI Router now runs as a local HTTP server.
+
+It serves both:
+
+- management UI: `http://127.0.0.1:3333/`
+- streamable HTTP MCP endpoint: `http://127.0.0.1:3333/mcp`
+
+## MCP Tools
+
+The HTTP MCP endpoint exposes:
+
+- `list_agents`
+- `register_agent`
+- `call_agent`
+- `get_request_status`
+
+## Start
+
+```sh
+cd mina-ai-router
+npm run build
+node dist/apps/cli/src/index.js server start --port 3333
+node dist/apps/cli/src/index.js server status
+```
+
+Or, after `npm link`:
+
+```sh
+mair server start --port 3333
+mair server status
+```
+
+Stop:
+
+```sh
+mair server stop
+```
+
+## Connect Codex CLI
+
+```sh
+codex mcp remove mina-ai-router
+codex mcp add mina-ai-router --url http://127.0.0.1:3333/mcp
+codex mcp get mina-ai-router
+```
+
+Expected transport:
+
+```text
+transport: streamable_http
+url: http://127.0.0.1:3333/mcp
+```
+
+## Use the UI
+
+Open:
+
+```text
+http://127.0.0.1:3333/
+```
+
+The page shows:
+
+- a router-centered agent flow diagram
+- registered agents as clickable nodes around the router
+- each agent's short capability notice on the node
+- agent status, project root, capability details, and tmux metadata in a modal
+- per-agent request history in a modal opened from the agent context menu
+- agent controls in the context menu: details, history, ask, attach commands, copy attach command, restart session, delete agent
+- right-click flow background menu for creating a tmux-backed Codex or Claude agent from a project directory
+- a `Connect Agent` guide instead of manual UI registration
+- hidden `Developer Tools` for diagnostics such as the two-Codex demo and stale request cleanup
+
+## Health
+
+The server exposes a local health endpoint:
+
+```text
+http://127.0.0.1:3333/api/health
+```
+
+The CLI exposes the same operator view:
+
+```sh
+mair health
+mair version
+mair verify
+```
+
+## Visible Agent Commands
+
+Start a visible Codex agent in the current directory:
+
+```sh
+mair codex
+```
+
+This derives the agent id and tmux session from the current directory. For example, from `/Users/stevenna/WebstormProjects/minasoftai`, it uses:
+
+- agent id: `minasoftai`
+- tmux session: `codex-minasoftai`
+- project root: current directory
+
+The started agent also receives a self-registration prompt. During registration it should inspect `CLAUDE.md`, `claude.md`, `AGENTS.md`, `agents.md`, `agent.md`, `README.md`, or project metadata and send `capabilitySummary` and `capabilitySources` to MCP `register_agent`.
+
+Start a visible Claude agent:
+
+```sh
+mair claude
+```
+
+Override values when needed:
+
+```sh
+mair codex --id ralph --session mina-ralph-codex --root /Users/stevenna/PycharmProjects/mina-ralph-loop-bootstrap-nextjs
+```
+
+## Verify
+
+```sh
+npm run smoke:http
+```
+
+## Current Test Flow
+
+1. Start HTTP server with `mair server start --port 3333`.
+2. Open the UI.
+3. Click `Connect Agent` for the registration command guide.
+4. Start an agent from its project directory with `mair codex` or `mair claude`.
+5. Confirm the agent appears in the flow diagram.
+6. Click the agent node and use the context menu to inspect details, view history, or delete it.
+
+Alternative UI-created agent flow:
+
+1. Right-click the `Live Agent Flow` background.
+2. Choose `Create tmux Agent`.
+3. Select `codex` or `claude`.
+4. Enter the target project directory or use `Browse Directory` to select it.
+5. Create the agent.
+6. Use the agent context menu `Attach Commands` when direct terminal control is needed.

package/docs/MCP-CLIENT-SETUP.md

@@ -0,0 +1,71 @@
+# MCP Client Setup
+
+Mina AI Router exposes a local HTTP MCP endpoint:
+
+```text
+http://127.0.0.1:3333/mcp
+```
+
+Start the router first:
+
+```sh
+mair server start --port 3333
+```
+
+## Codex
+
+Register the MAIR MCP server with Codex:
+
+```sh
+codex mcp remove mina-ai-router
+codex mcp add mina-ai-router --url http://127.0.0.1:3333/mcp
+codex mcp get mina-ai-router
+```
+
+Expected result:
+
+```text
+transport: streamable_http
+url: http://127.0.0.1:3333/mcp
+```
+
+Then start Codex inside a project with MAIR:
+
+```sh
+cd /path/to/project
+mair codex
+```
+
+## Claude
+
+Register the MAIR MCP server with Claude Code:
+
+```sh
+claude mcp remove mina-ai-router
+claude mcp add --transport http mina-ai-router http://127.0.0.1:3333/mcp
+claude mcp get mina-ai-router
+```
+
+Then start Claude inside a project with MAIR:
+
+```sh
+cd /path/to/project
+mair claude
+```
+
+## Verify From the AI CLI
+
+In Codex or Claude, ask:
+
+```text
+Use Mina AI Router MCP list_agents and summarize the registered agents.
+```
+
+If the MCP setup is working, the agent should call `list_agents`.
+
+## Available MCP Tools
+
+- `list_agents`: list known agents and their statuses
+- `register_agent`: register or update the current visible agent
+- `call_agent`: send a task to another registered agent
+- `get_request_status`: check a routed request

package/docs/SKILL-INSTALL-GUIDE.md

@@ -0,0 +1,96 @@
+# Skill Install Guide
+
+Mina AI Router includes a local skill:
+
+```text
+skills/mina-ai-router-agent/SKILL.md
+```
+
+The skill lets Codex or Claude register the current visible tmux-backed CLI session with MAIR without requiring the user to write a full registration payload.
+
+## Codex
+
+Install the skill into your Codex skills directory:
+
+```sh
+mkdir -p ~/.codex/skills
+ln -sfn "$(npm root -g)/@minasoft/mina-ai-router/skills/mina-ai-router-agent" \
+  ~/.codex/skills/mina-ai-router-agent
+```
+
+Restart Codex or open a new Codex session.
+
+Use it from a MAIR-started session:
+
+```sh
+cd /path/to/project
+mair codex
+```
+
+Then tell Codex:
+
+```text
+Register this CLI session with Mina AI Router.
+```
+
+Expected behavior:
+
+1. Codex reads the skill.
+2. Codex infers `pwd`, tmux session id, agent id, and agent type.
+3. Codex reads project docs or metadata for capabilities.
+4. Codex calls MCP `register_agent`.
+5. Codex calls MCP `list_agents` and confirms registration.
+
+## Claude
+
+Claude Code project skills live under `.claude/skills/*/SKILL.md`.
+
+For a single project, copy or link the MAIR skill into that project:
+
+```sh
+cd /path/to/project
+mkdir -p .claude/skills
+ln -sfn "$(npm root -g)/@minasoft/mina-ai-router/skills/mina-ai-router-agent" \
+  .claude/skills/mina-ai-router-agent
+```
+
+Restart Claude or open a new Claude session.
+
+Use it from a MAIR-started session:
+
+```sh
+cd /path/to/project
+mair claude
+```
+
+Then tell Claude:
+
+```text
+Register this CLI session with Mina AI Router.
+```
+
+Expected behavior:
+
+1. Claude invokes the `mina-ai-router-agent` skill.
+2. Claude infers `pwd`, tmux session id, agent id, and agent type.
+3. Claude reads project docs or metadata for capabilities.
+4. Claude calls MCP `register_agent`.
+5. Claude calls MCP `list_agents` and confirms registration.
+
+## Web UI Created Agents
+
+If you create an agent from the Web UI, installing the skill is still useful but not mandatory for the first node to appear.
+
+The Web UI already creates an initial registration so the agent is visible immediately. The skill improves that registration by letting the agent inspect its own project and update `capabilitySummary` and `capabilitySources`.
+
+## Verify
+
+Open the MAIR UI:
+
+```text
+http://127.0.0.1:3333/
+```
+
+Click the agent node and choose `Status & Details`.
+
+The capability summary should describe the target project, and the capability sources should mention files such as `CLAUDE.md`, `AGENTS.md`, `README.md`, or package metadata.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,75 @@
+# Troubleshooting
+
+## `tmux binary is not available`
+
+Install tmux or set `MINA_TMUX_BIN` to the tmux binary path.
+
+```sh
+command -v tmux
+export MINA_TMUX_BIN=/opt/homebrew/bin/tmux
+```
+
+## MCP and CLI See Different Agents
+
+They are probably using different state files.
+
+Set the same `MINA_ROUTER_STATE` for both processes:
+
+```sh
+export MINA_ROUTER_STATE=/absolute/path/to/router-state.json
+```
+
+## `call_agent` Times Out
+
+Common causes:
+
+- the helper agent is not running inside the tmux session
+- the helper agent did not follow the response marker instruction
+- the tmux session target is wrong
+- the response markers wrapped across terminal lines in an unusual way
+
+Useful checks:
+
+```sh
+tmux ls
+tmux capture-pane -t payment -p -J -S -200
+mair request <request-id>
+mair attach payment
+```
+
+## Answer Is `...` or `[your answer]`
+
+This should be rejected by the parser. If it appears again, the parser is likely reading the prompt example instead of the helper answer.
+
+Run:
+
+```sh
+npm test
+npm run smoke:tmux
+```
+
+## Wrong Agent Receives the Prompt
+
+Check the registered session ids:
+
+```sh
+mair agents
+mair agent payment
+mair agent delivery
+```
+
+If needed, register with an explicit tmux pane target:
+
+```sh
+mair register payment --agent gemini --transport tmux --session payment --target payment:0.0 --root ~/work/payment
+```
+
+## Reset Local State
+
+Runtime JSON state is ignored by git.
+
+```sh
+rm data/router-state.json
+```
+
+Use this carefully; it deletes local registrations and request history.

package/docs/USER-START-GUIDE.md

@@ -0,0 +1,187 @@
+# User Start Guide
+
+This guide is for someone who wants to use Mina AI Router, not develop it.
+
+## What You Will Set Up
+
+You will:
+
+1. Install the `mair` command.
+2. Start the local router and Web UI.
+3. Connect Codex or Claude to the local MCP server.
+4. Install the agent registration skill.
+5. Create visible tmux-backed agents.
+6. Inspect and control agents from the browser.
+
+## 1. Install the `mair` Command
+
+Install the published package:
+
+```sh
+npm install -g @minasoft/mina-ai-router
+```
+
+Verify:
+
+```sh
+mair version
+```
+
+Expected output:
+
+```json
+{
+  "name": "@minasoft/mina-ai-router",
+  "version": "0.1.0"
+}
+```
+
+## 2. Start the Router
+
+```sh
+mair server start --port 3333
+mair server status
+```
+
+Open:
+
+```text
+http://127.0.0.1:3333/
+```
+
+The center node is the local MCP router. The surrounding nodes are registered agents.
+
+![Live agent flow](./assets/mair-live-flow.jpg)
+
+## 3. Connect Your AI CLI to MCP
+
+Pick the guide for the CLI you use:
+
+- Codex: [Codex MCP Setup](./MCP-CLIENT-SETUP.md#codex)
+- Claude: [Claude MCP Setup](./MCP-CLIENT-SETUP.md#claude)
+
+This gives the AI CLI access to these MAIR MCP tools:
+
+- `list_agents`
+- `register_agent`
+- `call_agent`
+- `get_request_status`
+
+## 4. Install the Registration Skill
+
+Pick the guide for the CLI you use:
+
+- Codex: [Codex Skill Install](./SKILL-INSTALL-GUIDE.md#codex)
+- Claude: [Claude Skill Install](./SKILL-INSTALL-GUIDE.md#claude)
+
+The skill lets the agent register itself without asking you to type a long JSON payload.
+
+It automatically infers:
+
+- project root
+- tmux session id
+- agent id
+- agent type
+- capability summary
+- capability sources
+
+## 5. Create an Agent From the Web UI
+
+This is the easiest path for most users.
+
+1. Right-click the empty area in `Live Agent Flow`.
+2. Click `Create tmux Agent`.
+3. Choose `codex` or `claude`.
+4. Select a project directory.
+5. Click `Create Agent`.
+
+Mina creates or reuses a tmux session and registers the agent in the router.
+
+If Codex or Claude needs trust approval, the Web UI shows the terminal so you can respond.
+
+## 6. Alternative: Create an Agent From a Terminal
+
+From the project you want to expose as an agent:
+
+```sh
+cd /path/to/project
+mair codex
+```
+
+For Claude:
+
+```sh
+cd /path/to/project
+mair claude
+```
+
+Mina derives the agent id and tmux session name from the current directory.
+
+## 7. Self-Register With the Skill
+
+If the agent did not fully self-register, open the agent terminal and send:
+
+```text
+Register this CLI session with Mina AI Router.
+```
+
+If you created the agent from the Web UI, this step is still useful but not always required:
+
+- the Web UI creates an initial registration immediately
+- the skill can update that registration with a better project-aware capability summary
+
+## 8. Inspect or Edit Capabilities
+
+Click an agent node and choose `Status & Details`.
+
+You can view and edit:
+
+- capability summary
+- capability sources
+- project root
+- tmux session
+- attach commands
+
+![Agent details and capabilities](./assets/mair-agent-details.jpg)
+
+## 9. Open the Agent Terminal
+
+Click an agent node and choose `Open Terminal`.
+
+The browser shows the current tmux screen. Type into the input field and press `Enter`, or click `Send`.
+
+Use this when:
+
+- the agent is waiting for trust approval
+- the agent is stuck at a prompt
+- you want to see what the CLI is doing
+- you need to manually type into the session
+
+![Terminal preview](./assets/mair-terminal-preview.jpg)
+
+## 10. Ask One Agent to Use Another
+
+In a registered Codex or Claude session, ask it to use Mina AI Router.
+
+Example:
+
+```text
+Use Mina AI Router to ask api_server:
+Which REST API should aiagent call first for user lookup?
+Summarize method, endpoint, parameters, and source files.
+```
+
+Expected flow:
+
+1. The source agent calls `list_agents`.
+2. It chooses the target agent.
+3. It calls `call_agent`.
+4. MAIR sends the task into the target tmux session.
+5. The target agent answers with Mina response markers.
+6. MAIR returns the parsed answer to the source agent.
+
+## 11. Stop the Router
+
+```sh
+mair server stop
+```

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@minasoft/mina-ai-router",
+  "version": "0.1.0",
+  "description": "Local MCP router and Web UI for visible tmux-backed AI agents.",
+  "main": "dist/apps/cli/src/index.js",
+  "bin": {
+    "mair": "dist/apps/cli/src/index.js",
+    "mair-mcp": "dist/apps/mcp-server/src/index.js",
+    "mair-http": "dist/apps/http-server/src/index.js"
+  },
+  "files": [
+    "dist",
+    "docs/assets",
+    "docs/GETTING-STARTED.md",
+    "docs/USER-START-GUIDE.md",
+    "docs/DEVELOPER-START-GUIDE.md",
+    "docs/MCP-CLIENT-SETUP.md",
+    "docs/SKILL-INSTALL-GUIDE.md",
+    "docs/HTTP-UI-MCP.md",
+    "docs/TROUBLESHOOTING.md",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node scripts/core-tests.js",
+    "mair": "node dist/apps/cli/src/index.js",
+    "mcp": "node dist/apps/mcp-server/src/index.js",
+    "http": "node dist/apps/http-server/src/index.js",
+    "smoke": "npm run build && node dist/apps/cli/src/index.js register payment --agent gemini --transport headless --session payment --root ./payment && node dist/apps/cli/src/index.js ask payment \"현재 payment flow를 요약해줘.\"",
+    "smoke:http": "npm run build && node scripts/smoke-http.js",
+    "smoke:cli-controls": "npm run build && node scripts/smoke-cli-controls.js",
+    "smoke:tmux": "npm run build && node scripts/smoke-tmux.js",
+    "smoke:mcp": "npm run build && node scripts/smoke-mcp.js",
+    "smoke:multi": "npm run build && node scripts/smoke-multi-agent.js",
+    "verify": "npm run test && npm run smoke:http && npm run smoke:cli-controls && npm run smoke:tmux && npm run smoke:mcp && npm run smoke:multi"
+  },
+  "dependencies": {
+    "@minasoft/mcp-runtime": "^0.1.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/mina-ai-router-agent/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: mina-ai-router-agent
+description: Register the current visible Codex or Claude CLI session with Mina AI Router through MCP. Use when the user says to connect, register, join, attach, or make the current CLI agent available in Mina/MAIR, especially from inside a tmux-backed project session.
+---
+
+# Mina AI Router Agent
+
+## Purpose
+
+Register the current visible CLI agent session with Mina AI Router using the MCP tool `register_agent`.
+
+Use this skill when the user asks for a short instruction such as:
+
+- "register this session with Mina"
+- "connect this agent to MAIR"
+- "join the router"
+- "make this Codex/Claude visible in Mina"
+
+## Workflow
+
+1. Collect local context with shell commands when available:
+
+```sh
+pwd
+tmux display-message -p '#S' 2>/dev/null || true
+tmux display-message -p '#{pane_id}' 2>/dev/null || true
+```
+
+2. Infer fields:
+
+- `projectRoot`: output of `pwd`
+- `sessionId`: tmux session name from `tmux display-message -p '#S'`
+- `id`: project directory basename, lowercased and normalized to letters, digits, `_`, and `-`
+- `name`: same as `id` unless the user gave a name
+- `agentType`: `codex` when running in Codex; `claude` when running in Claude
+- `transport`: `tmux`
+- `startupCommand`: `codex --no-alt-screen` for Codex, `claude` for Claude
+
+3. Build a capability notice for this session.
+
+Prefer these project files when present:
+
+- `CLAUDE.md` or `claude.md`
+- `AGENTS.md` or `agents.md`
+- `agent.md`
+- `README.md`
+
+If none of those files exist, inspect project metadata and structure, such as `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, source directories, and test directories.
+
+Set:
+
+- `capabilitySummary`: 2-5 short bullets or one short paragraph under 800 characters that explains what this agent can help with.
+- `capabilitySources`: comma-separated file paths or project signals used for the summary.
+
+4. Call Mina MCP `register_agent` with the inferred values and capability notice.
+
+5. Call Mina MCP `list_agents` and confirm the registered agent is present with its capability notice.
+
+## Rules
+
+- Do not ask the user to manually provide the full registration payload unless inference fails.
+- If not running inside tmux, explain that Mina visible-session routing expects a tmux session and ask the user to start through `mair codex` or `mair claude`.
+- If `register_agent` is not available, ask the user to update Mina AI Router or restart the MCP server.
+- Keep the user-facing response short: say the agent id, session id, project root, capability source, and registration status.

package/skills/mina-ai-router-agent/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Mina AI Router Agent"
+  short_description: "Register the current visible CLI agent with Mina AI Router."
+  default_prompt: "Register this CLI session with Mina AI Router."