@minasoft/mina-ai-router 0.1.4 → 0.2.0

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

@@ -1,13 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMinaMcpProvider = createMinaMcpProvider;
+const src_1 = require("../../core/src");
 const tools = [
     {
         name: "list_agents",
         description: "List registered Mina helper agents.",
         inputSchema: {
             type: "object",
-            properties: {},
+            properties: {
+                callerAgentId: { type: "string" },
+                sourceAgent: { type: "string" },
+                callerSessionFingerprint: { type: "string" },
+            },
             additionalProperties: false,
         },
     },
@@ -22,11 +27,15 @@ const tools = [
                 agentType: { type: "string" },
                 transport: { type: "string" },
                 sessionId: { type: "string" },
+                sessionFingerprint: { type: "string" },
                 projectRoot: { type: "string" },
                 tmuxTarget: { type: "string" },
                 startupCommand: { type: "string" },
                 capabilitySummary: { type: "string" },
                 capabilitySources: { type: "string" },
+                capabilitySource: { type: "string" },
+                capabilityUpdatedAt: { type: "string" },
+                lastCapabilityRefreshAt: { type: "string" },
             },
             required: ["id", "agentType", "transport", "sessionId", "projectRoot"],
             additionalProperties: false,
@@ -40,6 +49,10 @@ const tools = [
             properties: {
                 target: { type: "string" },
                 task: { type: "string" },
+                sourceAgent: { type: "string" },
+                callerAgentId: { type: "string" },
+                callerSessionFingerprint: { type: "string" },
+                allowSelfCall: { type: "boolean" },
                 timeoutMs: { type: "number" },
             },
             required: ["target", "task"],
@@ -63,7 +76,7 @@ function createMinaMcpProvider(context) {
     return {
         serverInfo: {
             name: "mina-ai-router",
-            version: "0.1.0",
+            version: (0, src_1.packageVersion)(),
         },
         tools: {
             async list() {
@@ -78,17 +91,29 @@ function createMinaMcpProvider(context) {
 async function callTool(context, name, args) {
     switch (name) {
         case "list_agents": {
-            const agents = await context.router.listAgentStatuses();
+            const caller = resolveCallerAgent(context.registry, args);
+            const agents = await context.router.listAgentStatuses({ callerAgentId: caller?.id });
             return jsonToolResult({ agents });
         }
         case "register_agent": {
             try {
                 const agent = agentFromArgs(args);
-                context.registry.register(agent);
+                const now = new Date().toISOString();
+                const registered = context.registry.register({
+                    ...agent,
+                    bootstrapStatus: "ready",
+                    registrationSource: "mcp",
+                    registrationStatus: "confirmed",
+                    lastRegistrationAttemptAt: now,
+                    confirmedByAgentAt: now,
+                    sessionFingerprint: agent.sessionFingerprint ?? agent.sessionId,
+                }, {
+                    capabilitySource: agent.capabilitySummary || agent.capabilitySources ? "generated" : undefined,
+                });
                 context.save();
                 const agents = await context.router.listAgentStatuses();
                 return jsonToolResult({
-                    agent,
+                    agent: registered,
                     agents,
                 });
             }
@@ -103,11 +128,19 @@ async function callTool(context, name, args) {
             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;
+            const caller = resolveCallerAgent(context.registry, args);
+            const allowSelfCall = args.allowSelfCall === true;
             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 });
+                const response = await context.router.callAgent({
+                    sourceAgent: caller?.id,
+                    target,
+                    task,
+                    timeoutMs,
+                    allowSelfCall,
+                });
                 return jsonToolResult(response);
             }
             catch (error) {
@@ -133,6 +166,9 @@ async function callTool(context, name, args) {
                     requestId: found.id,
                     status: found.status,
                     error: found.error,
+                    diagnosticStatus: found.diagnosticStatus,
+                    parserDiagnostics: found.parserDiagnostics,
+                    rawEvidence: found.rawEvidence,
                 });
             }
             catch {
@@ -143,6 +179,14 @@ async function callTool(context, name, args) {
             return { kind: "not_found", message: `Unknown tool "${name}".` };
     }
 }
+function resolveCallerAgent(registry, args) {
+    const callerAgentId = stringValue(args.callerAgentId) ?? stringValue(args.sourceAgent);
+    if (callerAgentId) {
+        return registry.get(callerAgentId);
+    }
+    const fingerprint = stringValue(args.callerSessionFingerprint);
+    return fingerprint ? registry.findBySessionFingerprint(fingerprint) : undefined;
+}
 function agentFromArgs(args) {
     const id = requiredString(args.id, "id");
     return {
@@ -151,11 +195,15 @@ function agentFromArgs(args) {
         agentType: requiredString(args.agentType, "agentType"),
         transport: requiredString(args.transport, "transport"),
         sessionId: requiredString(args.sessionId, "sessionId"),
+        sessionFingerprint: stringValue(args.sessionFingerprint) ?? stringValue(args.sessionId),
         projectRoot: requiredString(args.projectRoot, "projectRoot"),
         tmuxTarget: stringValue(args.tmuxTarget),
         startupCommand: stringValue(args.startupCommand),
         capabilitySummary: stringValue(args.capabilitySummary),
         capabilitySources: stringValue(args.capabilitySources),
+        capabilitySource: capabilitySourceValue(args.capabilitySource),
+        capabilityUpdatedAt: stringValue(args.capabilityUpdatedAt),
+        lastCapabilityRefreshAt: stringValue(args.lastCapabilityRefreshAt),
     };
 }
 function requiredString(value, field) {
@@ -167,6 +215,9 @@ function requiredString(value, field) {
 function stringValue(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
+function capabilitySourceValue(value) {
+    return value === "manual" || value === "generated" ? value : undefined;
+}
 function jsonToolResult(value) {
     const text = JSON.stringify(value, null, 2);
     return {

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

@@ -13,14 +13,19 @@ class HeadlessTransport {
     }
     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");
+        const answer = prompt.includes("capabilitySummary") && prompt.includes("capabilitySources")
+            ? JSON.stringify({
+                capabilitySummary: `Headless capability refresh for ${agent.id}.`,
+                capabilitySources: "headless transport prompt",
+            })
+            : [
+                `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,

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

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TmuxClient = void 0;
+exports.detectAgentPermissionPrompt = detectAgentPermissionPrompt;
+exports.detectAgentBootstrapPrompt = detectAgentBootstrapPrompt;
 const node_child_process_1 = require("node:child_process");
 class TmuxClient {
     constructor(options = {}) {
@@ -56,6 +58,9 @@ class TmuxClient {
     sendEnter(target) {
         this.run(["send-keys", "-t", target, this.submitKey]);
     }
+    sendInterrupt(target) {
+        this.run(["send-keys", "-t", target, "C-c"]);
+    }
     sendCodexText(target, text) {
         const prompt = asSingleLinePrompt(text);
         for (const key of this.clearInputKeys) {
@@ -97,6 +102,335 @@ class TmuxClient {
     }
 }
 exports.TmuxClient = TmuxClient;
+function detectAgentPermissionPrompt(agent, capture) {
+    const prompt = detectAgentBootstrapPrompt(agent, capture);
+    return prompt?.kind === "client-update"
+        ? undefined
+        : prompt;
+}
+function detectAgentBootstrapPrompt(agent, capture) {
+    const promptWindow = recentPromptWindow(capture);
+    const latestSegment = latestInteractiveSegment(promptWindow);
+    const normalized = latestSegment.replace(/\s+/g, " ").trim();
+    if (!normalized) {
+        return undefined;
+    }
+    if (agent.agentType === "codex" && hasActiveCodexUpdatePrompt(latestSegment)) {
+        return {
+            client: "codex",
+            kind: "client-update",
+            message: "Codex is waiting at an update prompt before Mina can continue registration.",
+            action: `Attach with "tmux attach -t ${agent.sessionId}" and choose a safe update option, or use Mina's Skip Codex Update action when available.`,
+            evidence: promptEvidence(latestSegment, [codexUpdateBannerPattern, ...codexUpdateChoicePatterns]),
+        };
+    }
+    if (agent.agentType === "codex" && hasCodexMcpRegistrationApproval(normalized, agent)) {
+        return {
+            client: "codex",
+            kind: "codex-mcp-registration-approval",
+            message: "Codex is waiting for approval of a Mina MCP registration or verification call.",
+            action: `Review the Mina MCP call, then approve option 1 in Mina or attach with "tmux attach -t ${agent.sessionId}".`,
+            evidence: promptEvidence(latestSegment, codexMcpApprovalPatterns),
+        };
+    }
+    if (agent.agentType === "codex" && hasCodexTrustPrompt(normalized)) {
+        return {
+            client: "codex",
+            kind: "directory-trust",
+            message: "Codex is waiting for directory trust approval before it can work in this project.",
+            action: `Review the project directory, then attach with "tmux attach -t ${agent.sessionId}" or press Send Enter in Mina to approve the prompt.`,
+            evidence: promptEvidence(promptWindow, codexTrustPatterns),
+        };
+    }
+    if (agent.agentType === "claude" && hasClaudeMcpRegistrationApproval(normalized, agent)) {
+        return {
+            client: "claude",
+            kind: "mcp-registration-approval",
+            message: "Claude is waiting for approval of a scoped Mina MCP call.",
+            action: `Review the Mina MCP call, then approve option 1 in Mina or attach with "tmux attach -t ${agent.sessionId}".`,
+            evidence: promptEvidence(latestSegment, claudeMcpApprovalPatterns),
+        };
+    }
+    if (agent.agentType === "claude" && hasClaudeFolderTrustPrompt(normalized, agent.projectRoot)) {
+        return {
+            client: "claude",
+            kind: "claude-folder-trust",
+            message: "Claude is waiting for trust approval of this project folder.",
+            action: `Review the folder path, then approve option 1 in Mina or attach with "tmux attach -t ${agent.sessionId}".`,
+            evidence: promptEvidence(latestSegment, claudeFolderTrustPatterns),
+        };
+    }
+    if (agent.agentType === "claude" && hasClaudeScopedRegistrationApproval(normalized, agent.projectRoot)) {
+        return {
+            client: "claude",
+            kind: "scoped-command-approval",
+            message: "Claude is waiting for approval of a Mina registration command scoped to this project.",
+            action: `Review the scoped command, then approve it in Mina or attach with "tmux attach -t ${agent.sessionId}".`,
+            evidence: promptEvidence(promptWindow, claudeScopedRegistrationApprovalPatterns),
+        };
+    }
+    if (agent.agentType === "claude" && hasClaudePermissionPrompt(normalized)) {
+        return {
+            client: "claude",
+            kind: "permission-approval",
+            message: "Claude is waiting for a permission or trust approval before it can work in this project.",
+            action: `Review the project directory, then attach with "tmux attach -t ${agent.sessionId}" and approve the Claude prompt.`,
+            evidence: promptEvidence(promptWindow, claudePermissionPatterns),
+        };
+    }
+    return undefined;
+}
+function hasCodexTrustPrompt(value) {
+    return codexTrustPatterns.some((pattern) => pattern.test(value));
+}
+function hasActiveCodexUpdatePrompt(value) {
+    const lines = promptLines(value);
+    const latestNormalPromptIndex = lastIndexWhere(lines, (line) => codexNormalPromptPattern.test(line));
+    const latestUpdateChoiceIndex = lastIndexWhere(lines, (line) => codexUpdateChoiceLinePatterns.some((pattern) => pattern.test(line)));
+    if (latestNormalPromptIndex > latestUpdateChoiceIndex) {
+        return false;
+    }
+    return codexUpdateBannerPattern.test(value)
+        && codexUpdateChoicePatterns.every((pattern) => pattern.test(value));
+}
+function hasClaudePermissionPrompt(value) {
+    return hasClaudeInteractiveApprovalUi(value)
+        && claudePermissionPatterns.some((pattern) => pattern.test(value));
+}
+function hasClaudeScopedRegistrationApproval(value, projectRoot) {
+    if (!projectRoot || !claudeScopedRegistrationApprovalPatterns.some((pattern) => pattern.test(value))) {
+        return false;
+    }
+    const tmuxContextProbe = /tmux\s+display-message\s+-p/i.test(value)
+        && /\bpwd\b/i.test(value);
+    if (tmuxContextProbe) {
+        return true;
+    }
+    const safetyValue = value.replace(safeDevNullRedirectionPattern, "");
+    if (unsafeShellCommandPatterns.some((pattern) => pattern.test(safetyValue))) {
+        return false;
+    }
+    const projectScopedRead = includesProjectRoot(value, projectRoot)
+        && claudeReadOnlyRegistrationCommandPatterns.some((pattern) => pattern.test(value));
+    const cwdScopedRead = !absolutePathPattern.test(value)
+        && claudeReadOnlyRegistrationCommandPatterns.some((pattern) => pattern.test(value));
+    return projectScopedRead || cwdScopedRead;
+}
+function hasCodexMcpRegistrationApproval(value, agent) {
+    if (!codexMcpApprovalPatterns.every((pattern) => pattern.test(value))) {
+        return false;
+    }
+    return hasCodexRegisterAgentApproval(value, agent)
+        || hasCodexListAgentsApproval(value, agent);
+}
+function hasClaudeMcpRegistrationApproval(value, agent) {
+    if (!claudeMcpApprovalPatterns.every((pattern) => pattern.test(value))) {
+        return false;
+    }
+    return hasClaudeRegisterAgentApproval(value, agent)
+        || hasClaudeListAgentsApproval(value, agent)
+        || hasClaudeCallAgentApproval(value, agent);
+}
+function hasCodexRegisterAgentApproval(value, agent) {
+    return /mina-ai-router\.register_agent/i.test(value)
+        && /run tool ["“]register_agent["”]\?/i.test(value)
+        && value.includes(agent.id)
+        && value.includes(agent.sessionId)
+        && includesProjectRoot(value, agent.projectRoot);
+}
+function hasCodexListAgentsApproval(value, agent) {
+    return /mina-ai-router\.list_agents/i.test(value)
+        && /run tool ["“]list_agents["”]\?/i.test(value)
+        && value.includes(agent.id)
+        && value.includes(agent.sessionFingerprint ?? agent.sessionId);
+}
+function hasClaudeRegisterAgentApproval(value, agent) {
+    return /mina-ai-router\s+-\s+register_agent/i.test(value)
+        && value.includes(agent.id)
+        && value.includes(agent.sessionId)
+        && includesProjectRoot(value, agent.projectRoot);
+}
+function hasClaudeListAgentsApproval(value, agent) {
+    return /mina-ai-router\s+-\s+list_agents/i.test(value)
+        && (includesProjectRoot(value, agent.projectRoot)
+            || value.includes(agent.id)
+            || value.includes(agent.sessionFingerprint ?? agent.sessionId));
+}
+function hasClaudeCallAgentApproval(value, agent) {
+    return /mina-ai-router\s+-\s+call_agent/i.test(value)
+        && (includesProjectRoot(value, agent.projectRoot)
+            || value.includes(agent.id)
+            || value.includes(agent.sessionFingerprint ?? agent.sessionId));
+}
+function hasClaudeFolderTrustPrompt(value, projectRoot) {
+    return claudeFolderTrustPatterns.every((pattern) => pattern.test(value))
+        && includesProjectRoot(value, projectRoot);
+}
+const codexUpdateBannerPattern = /update available!\s+\S+\s*->\s*\S+/i;
+const codexUpdateChoicePatterns = [
+    /(?:^|\s)1[.)]?\s*update now/i,
+    /(?:^|\s)2[.)]?\s*skip(?:\s|$)/i,
+];
+const codexUpdateChoiceLinePatterns = [
+    /^[›>\s]*1[.)]?\s*update now/i,
+    /^[›>\s]*2[.)]?\s*skip(?:\s|$)/i,
+    /^[›>\s]*3[.)]?\s*skip until next version/i,
+];
+const codexNormalPromptPattern = /^›\s+(?!1[.)]?\s*update now|2[.)]?\s*skip(?:\s|$)|3[.)]?\s*skip until next version).+/i;
+const codexTrustPatterns = [
+    /do you trust the contents of this directory\?/i,
+    /yes,\s*continue/i,
+    /codex.+(?:trust|permission|approval)/i,
+];
+const claudePermissionPatterns = [
+    /claude.+(?:permission|approval|trust)/i,
+    /(?:allow|approve).+claude/i,
+    /do you trust.+(?:folder|directory|workspace|project)/i,
+    /do you want to proceed\?/i,
+    /permission.+(?:press enter|continue|approve|allow)/i,
+];
+const claudeFolderTrustPatterns = [
+    /accessing workspace:/i,
+    /yes,\s*i trust this folder/i,
+    /enter to confirm/i,
+];
+const claudeMcpApprovalPatterns = [
+    /mina-ai-router\s+-\s+(?:register_agent|list_agents|call_agent)/i,
+    /do you want to proceed\?/i,
+    /1\.\s*yes/i,
+    /\(mcp\)/i,
+];
+const codexMcpApprovalPatterns = [
+    /mina-ai-router\.(?:register_agent|list_agents)/i,
+    /allow the mina-ai-router mcp server to run tool ["“](?:register_agent|list_agents)["”]\?/i,
+    /1[.)]\s*allow/i,
+    /enter to submit/i,
+];
+const claudeScopedRegistrationApprovalPatterns = [
+    /bash command/i,
+    /(?:manual approval required|compound command contains cd|contains simple_expansion|this command requires approval|uses shell operators that require approval)/i,
+];
+const claudeReadOnlyRegistrationCommandPatterns = [
+    /mina-ai-router-agent/i,
+    /mina ai router/i,
+    /register_agent/i,
+    /list_agents/i,
+    /\bls\s+-la\b/i,
+    /\bpwd\b/i,
+    /tmux\s+display-message\s+-p/i,
+    /\b(?:cat|head|find|rg)\b/i,
+];
+const unsafeShellCommandPatterns = [
+    /\brm\s+-/i,
+    /\bsudo\b/i,
+    /\bchmod\b/i,
+    /\bchown\b/i,
+    /\b(?:cp|mv|touch|mkdir|rmdir)\b/i,
+    /\bcurl\b/i,
+    /\bwget\b/i,
+    /\bnpm\s+(?:install|i)\b/i,
+    /\bpnpm\s+(?:install|add)\b/i,
+    /\byarn\s+add\b/i,
+    /(?:^|\s)\.\.(?:\/|\s|$)/i,
+    />\s*(?:\/|~|\.)/i,
+];
+const safeDevNullRedirectionPattern = /\b[12]?>\s*\/dev\/null\b/g;
+const absolutePathPattern = /(?:^|[\s"'])(?:\/|~\/)/;
+function hasClaudeInteractiveApprovalUi(value) {
+    return /do you want to proceed\?/i.test(value) && /(?:❯\s*)?1\.\s*(?:yes|allow)/i.test(value)
+        || /enter to confirm/i.test(value)
+        || /press enter to continue/i.test(value)
+        || /yes,\s*i trust this folder/i.test(value);
+}
+function recentPromptWindow(capture) {
+    return capture
+        .split(/\r?\n/)
+        .slice(-80)
+        .join("\n");
+}
+function latestInteractiveSegment(capture) {
+    const lines = capture.split(/\r?\n/);
+    const trimmed = lines.map((line) => line.trim());
+    const latestCompletionIndex = lastIndexWhere(trimmed, (line) => /^(ready|trusted-|approved-|codex prompt ready|selected:)/i.test(line));
+    const latestPromptishIndex = lastIndexWhere(trimmed, (line) => /^›\s+/.test(line)
+        || /do you want to proceed\?/i.test(line)
+        || /quick safety check:/i.test(line)
+        || /bash command/i.test(line)
+        || /update available!/i.test(line)
+        || /do you trust the contents of this directory\?/i.test(line));
+    if (latestCompletionIndex > latestPromptishIndex) {
+        return lines.slice(latestCompletionIndex).join("\n");
+    }
+    const latestNormalPromptIndex = lastIndexWhere(trimmed, (line) => codexNormalPromptPattern.test(line));
+    const latestUpdateChoiceIndex = lastIndexWhere(trimmed, (line) => codexUpdateChoiceLinePatterns.some((pattern) => pattern.test(line)));
+    const latestUpdateBannerIndex = lastIndexWhere(trimmed, (line) => codexUpdateBannerPattern.test(line));
+    const latestCodexMcpToolIndex = lastIndexWhere(trimmed, (line) => /mina-ai-router\.(?:register_agent|list_agents)/i.test(line));
+    if (latestCodexMcpToolIndex >= 0) {
+        const callingIndex = lastIndexWhere(trimmed.slice(0, latestCodexMcpToolIndex + 1), (line) => /calling/i.test(line));
+        return lines.slice(Math.max(0, callingIndex >= 0 ? callingIndex : latestCodexMcpToolIndex)).join("\n");
+    }
+    if (latestNormalPromptIndex > latestUpdateChoiceIndex && latestNormalPromptIndex > latestUpdateBannerIndex) {
+        return lines.slice(latestNormalPromptIndex).join("\n");
+    }
+    const latestMcpToolIndex = lastIndexWhere(trimmed, (line) => /mina-ai-router\s+-\s+(?:register_agent|list_agents|call_agent)/i.test(line));
+    if (latestMcpToolIndex >= 0) {
+        const toolUseIndex = lastIndexWhere(trimmed.slice(0, latestMcpToolIndex + 1), (line) => /tool use/i.test(line));
+        return lines.slice(Math.max(0, toolUseIndex >= 0 ? toolUseIndex : latestMcpToolIndex)).join("\n");
+    }
+    const latestWorkspaceIndex = lastIndexWhere(trimmed, (line) => /accessing workspace:/i.test(line));
+    if (latestWorkspaceIndex >= 0) {
+        return lines.slice(latestWorkspaceIndex).join("\n");
+    }
+    const latestBashIndex = lastIndexWhere(trimmed, (line) => /bash command/i.test(line));
+    if (latestBashIndex >= 0) {
+        return lines.slice(latestBashIndex).join("\n");
+    }
+    if (latestUpdateBannerIndex >= 0) {
+        return lines.slice(latestUpdateBannerIndex).join("\n");
+    }
+    return capture;
+}
+function promptLines(value) {
+    return value
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+function lastIndexWhere(values, predicate) {
+    for (let index = values.length - 1; index >= 0; index -= 1) {
+        if (predicate(values[index])) {
+            return index;
+        }
+    }
+    return -1;
+}
+function includesProjectRoot(value, projectRoot) {
+    return projectRootAliases(projectRoot).some((alias) => value.includes(alias));
+}
+function projectRootAliases(projectRoot) {
+    const aliases = new Set([projectRoot]);
+    if (projectRoot.startsWith("/tmp/")) {
+        aliases.add(`/private${projectRoot}`);
+    }
+    if (projectRoot.startsWith("/var/")) {
+        aliases.add(`/private${projectRoot}`);
+    }
+    if (projectRoot.startsWith("/private/tmp/")) {
+        aliases.add(projectRoot.replace(/^\/private/, ""));
+    }
+    if (projectRoot.startsWith("/private/var/")) {
+        aliases.add(projectRoot.replace(/^\/private/, ""));
+    }
+    return [...aliases].filter(Boolean);
+}
+function promptEvidence(capture, patterns) {
+    const lines = capture
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const matched = lines.find((line) => patterns.some((pattern) => pattern.test(line)));
+    return (matched ?? lines.slice(-1)[0] ?? "").slice(0, 240);
+}
 function asSingleLinePrompt(text) {
     return text
         .split(/\r?\n/)

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

@@ -42,6 +42,16 @@ class TmuxTransport {
         if (!this.client.hasSession(agent.sessionId)) {
             return { status: "missing", detail: `tmux session "${agent.sessionId}" does not exist` };
         }
+        const capture = this.client.capture(targetFor(agent));
+        const bootstrapPrompt = (0, tmux_client_1.detectAgentBootstrapPrompt)(agent, capture);
+        if (bootstrapPrompt) {
+            return {
+                status: "needs-attention",
+                detail: `${bootstrapPrompt.message} ${bootstrapPrompt.action}`,
+                bootstrapStatus: bootstrapPrompt.kind === "client-update" ? "client-update-required" : "permission-required",
+                permissionPrompt: bootstrapPrompt,
+            };
+        }
         return { status: "available", detail: this.client.attachCommand(agent) };
     }
 }

package/docs/DEVELOPER-START-GUIDE.md

@@ -75,9 +75,15 @@ npm run smoke:http
 npm run smoke:mcp
 npm run smoke:tmux
 mair health
+npm run verify
 mair verify
 ```
 
+`npm run verify` is the checkout test suite. A linked checkout may also make
+`mair verify` run that same suite from the Mina package root. In an installed
+package, `mair verify` is the CLI self-check and must not run the current
+directory's npm scripts.
+
 ## 7. Local State
 
 By default, MAIR stores local state in:
@@ -96,7 +102,9 @@ export MINA_ROUTER_STATE=/path/to/router-state.json
 
 - CLI: `apps/cli/src/index.ts`
 - HTTP UI/server: `apps/http-server/src/index.ts`
-- Browser UI HTML: `apps/http-server/src/ui.html`
+- React browser UI: `apps/http-server/ui/src`
+- Vite UI entry: `apps/http-server/ui/index.html`
+- Built UI assets served from: `dist/apps/http-server/src/public`
 - MCP provider: `packages/mcp/src/provider.ts`
 - tmux transport: `packages/transports/src/tmux`
 - agent registration skill: `skills/mina-ai-router-agent/SKILL.md`

package/docs/GETTING-STARTED.md

@@ -1,5 +1,9 @@
 # Getting Started
 
+Mina AI Router lets multiple local Codex and Claude CLI agents collaborate through one local MCP router and browser console.
+
+![Mina AI Router overview](./assets/mina-ai-router-overview.svg)
+
 Choose the guide that matches what you are trying to do.
 
 ## For Users
@@ -14,9 +18,9 @@ Start here if you want to build, test, modify, or package this repository.
 
 [Developer Start Guide](./DEVELOPER-START-GUIDE.md)
 
-## Required Setup Guides
+## Setup Reference Guides
 
-Use these once per machine or per AI CLI profile:
+Use these when you need manual repair details or custom client profiles:
 
 - [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.
@@ -25,8 +29,9 @@ Use these once per machine or per AI CLI profile:
 
 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`.
+3. Run `mair setup codex --project /path/to/project` and `mair doctor --client codex --project /path/to/project` if you use Codex, or the matching `claude` commands if you use Claude.
+4. Use `mair doctor --client all --project /path/to/project` only when both clients are installed and configured.
+5. Create two or more agents from the Web UI or with `mair codex` / `mair claude`.
+6. Ask one registered agent to use Mina AI Router to call another agent.
 
 The user guide walks through that path with screenshots.