@dolusoft/claude-collab 1.9.2 → 1.9.3

package/dist/mcp-main.js

@@ -314,6 +314,10 @@ var P2PNode = class {
   sentQuestions = /* @__PURE__ */ new Map();
   questionToSender = /* @__PURE__ */ new Map();
   pendingHandlers = /* @__PURE__ */ new Set();
+  // Push-based answer resolution: questionId → resolve callback
+  answerWaiters = /* @__PURE__ */ new Map();
+  // Answers queued for offline peers: peerName → AnswerMsg (delivered on reconnect)
+  pendingOutboundAnswers = /* @__PURE__ */ new Map();
   broadcaster = null;
   stopPeerWatcher = null;
   boundPort = 0;
@@ -357,9 +361,27 @@ var P2PNode = class {
     await ackPromise;
     return questionId;
   }
+  waitForAnswer(questionId, timeoutMs) {
+    const cached = this.receivedAnswers.get(questionId);
+    if (cached) {
+      return Promise.resolve(this.formatAnswer(questionId, cached));
+    }
+    return new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        this.answerWaiters.delete(questionId);
+        resolve(null);
+      }, timeoutMs);
+      this.answerWaiters.set(questionId, (result) => {
+        clearTimeout(timeout);
+        resolve(result);
+      });
+    });
+  }
   async checkAnswer(questionId) {
     const cached = this.receivedAnswers.get(questionId);
-    if (!cached) return null;
+    return cached ? this.formatAnswer(questionId, cached) : null;
+  }
+  formatAnswer(questionId, cached) {
     return {
       questionId,
       from: { displayName: `${cached.fromName} Claude`, teamName: cached.fromName },
@@ -376,16 +398,20 @@ var P2PNode = class {
     question.answerFormat = format;
     const senderName = this.questionToSender.get(questionId);
     if (senderName) {
+      const answerMsg = {
+        type: "ANSWER",
+        from: this.myName,
+        questionId,
+        content,
+        format,
+        answeredAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
       const ws = this.peerConnections.get(senderName);
       if (ws && ws.readyState === WebSocket.OPEN) {
-        this.sendToWs(ws, {
-          type: "ANSWER",
-          from: this.myName,
-          questionId,
-          content,
-          format,
-          answeredAt: (/* @__PURE__ */ new Date()).toISOString()
-        });
+        this.sendToWs(ws, answerMsg);
+      } else {
+        this.pendingOutboundAnswers.set(senderName, answerMsg);
+        console.error(`[p2p] "${senderName}" is offline, answer queued for delivery on reconnect`);
       }
     }
     injectionQueue.notifyReplied();
@@ -561,6 +587,7 @@ var P2PNode = class {
         this.connectingPeers.delete(msg.name);
         this.sendToWs(ws, { type: "HELLO_ACK", name: this.myName });
         console.error(`[p2p] peer joined (inbound): ${msg.name}`);
+        this.deliverPendingAnswer(msg.name, ws);
         break;
       }
       case "HELLO_ACK": {
@@ -572,6 +599,7 @@ var P2PNode = class {
         this.wsToName.set(ws, msg.name);
         this.connectingPeers.delete(msg.name);
         console.error(`[p2p] connected to peer: ${msg.name}`);
+        this.deliverPendingAnswer(msg.name, ws);
         break;
       }
       case "ASK":
@@ -579,12 +607,18 @@ var P2PNode = class {
         break;
       case "ANSWER":
         if (!this.receivedAnswers.has(msg.questionId)) {
-          this.receivedAnswers.set(msg.questionId, {
+          const record = {
             content: msg.content,
             format: msg.format,
             answeredAt: msg.answeredAt,
             fromName: msg.from
-          });
+          };
+          this.receivedAnswers.set(msg.questionId, record);
+          const waiter = this.answerWaiters.get(msg.questionId);
+          if (waiter) {
+            this.answerWaiters.delete(msg.questionId);
+            waiter(this.formatAnswer(msg.questionId, record));
+          }
         }
         break;
     }
@@ -610,6 +644,14 @@ var P2PNode = class {
       ageMs: 0
     });
   }
+  deliverPendingAnswer(peerName, ws) {
+    const pending = this.pendingOutboundAnswers.get(peerName);
+    if (pending) {
+      this.pendingOutboundAnswers.delete(peerName);
+      this.sendToWs(ws, pending);
+      console.error(`[p2p] delivered queued answer to "${peerName}" after reconnect`);
+    }
+  }
   sendToWs(ws, msg) {
     if (ws.readyState === WebSocket.OPEN) {
       ws.send(serialize(msg));
@@ -632,110 +674,144 @@ var P2PNode = class {
     });
   }
 };
+var ASK_DESCRIPTION = `Send a question to another Claude instance on the LAN and wait for their answer.
+
+WHEN TO USE:
+- You need input, a decision, or work output from a specific peer Claude
+- You want to delegate a subtask to another Claude and use their result
+- You need to coordinate or synchronize work across multiple Claudes
+
+WORKFLOW:
+1. Call peers() first to confirm the target is online and get their exact name
+2. Call ask(peer, question) \u2014 this blocks until they reply (up to 5 minutes)
+3. Use their answer directly in your ongoing task
+
+WRITING GOOD QUESTIONS:
+- Include all context the other Claude needs \u2014 they cannot see your conversation
+- Be specific about what format or level of detail you expect in the answer
+- If you need code, specify language and constraints
+- One focused question per call works better than multiple combined
+
+DO NOT use this tool if:
+- The peer is not listed in peers() \u2014 the call will fail immediately
+- You just want to share information without needing a response (there is no broadcast tool yet)`;
 var askSchema = {
-  peer: z.string().describe('Name of the peer to ask (e.g., "alice", "backend")'),
-  question: z.string().describe("The question to ask (supports markdown)")
+  peer: z.string().describe("Exact name of the peer to ask. Use peers() first to see who is online and get the correct name."),
+  question: z.string().describe(
+    "Your question in markdown. Include all necessary context \u2014 the other Claude cannot see your conversation history. Be specific about what kind of answer you need."
+  )
 };
 function registerAskTool(server, client) {
-  server.tool("ask", askSchema, async (args) => {
+  server.tool("ask", ASK_DESCRIPTION, askSchema, async (args) => {
     const targetPeer = args.peer;
     const question = args.question;
     try {
       if (!client.currentTeamId) {
         return {
-          content: [
-            {
-              type: "text",
-              text: "Node is not ready yet. Wait a moment and try again."
-            }
-          ],
+          content: [{
+            type: "text",
+            text: "P2P node is not ready yet. Wait a moment and try again."
+          }],
           isError: true
         };
       }
       const questionId = await client.ask(targetPeer, question, "markdown");
-      const POLL_INTERVAL_MS = 5e3;
-      const MAX_WAIT_MS = 5 * 60 * 1e3;
-      const deadline = Date.now() + MAX_WAIT_MS;
-      while (Date.now() < deadline) {
-        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
-        const answer = await client.checkAnswer(questionId);
-        if (answer !== null) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `**${answer.from.displayName} (${answer.from.teamName}) cevaplad\u0131:**
+      const answer = await client.waitForAnswer(questionId, 5 * 60 * 1e3);
+      if (answer !== null) {
+        return {
+          content: [{
+            type: "text",
+            text: `**${answer.from.displayName} answered:**
 
 ${answer.content}`
-              }
-            ]
-          };
-        }
+          }]
+        };
       }
       return {
-        content: [
-          {
-            type: "text",
-            text: `Soru g\xF6nderildi ancak 5 dakika i\xE7inde cevap gelmedi.
-Question ID: \`${questionId}\`
-
-Manuel kontrol i\xE7in "check_answer" tool'unu kullanabilirsin.`
-          }
-        ]
+        content: [{
+          type: "text",
+          text: [
+            `Question sent to "${targetPeer}" but no answer arrived within 5 minutes.`,
+            `Question ID: \`${questionId}\``,
+            ``,
+            `The peer may be busy or offline. You can:`,
+            `- Call peers() to check if they are still connected`,
+            `- Continue with your task and follow up later`
+          ].join("\n")
+        }]
       };
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      const isPeerOffline = errorMessage.includes("not connected");
       return {
-        content: [
-          {
-            type: "text",
-            text: `Failed to send question: ${errorMessage}`
-          }
-        ],
+        content: [{
+          type: "text",
+          text: isPeerOffline ? `Peer "${targetPeer}" is not connected. Call peers() to see who is currently online.` : `Failed to send question: ${errorMessage}`
+        }],
         isError: true
       };
     }
   });
 }
+var REPLY_DESCRIPTION = `Send your answer back to a Claude instance that asked you a question.
+
+WHEN TO USE:
+- A question has been injected into your terminal by another Claude (you will see it appear automatically)
+- You have finished thinking through the answer and are ready to respond
+
+WORKFLOW:
+1. Read the injected question carefully \u2014 it includes a questionId at the top
+2. Think through a complete answer
+3. Call reply(questionId, answer) \u2014 your answer is sent directly back to the asking Claude
+4. The asking Claude's ask() call unblocks and they receive your answer immediately
+
+WRITING GOOD ANSWERS:
+- Be thorough \u2014 the asking Claude will use your answer directly in their task
+- Use markdown for code blocks, lists, and structure
+- Include any caveats, assumptions, or follow-up suggestions that would help them
+- If you cannot answer fully, say so clearly and explain why
+
+IMPORTANT:
+- Each question can only be replied to once
+- The questionId is a UUID shown in the injected question prompt \u2014 copy it exactly`;
 var replySchema = {
-  questionId: z.string().describe("The ID of the question to reply to (from inbox)"),
-  answer: z.string().describe("Your answer to the question (supports markdown)")
+  questionId: z.string().describe(
+    "The UUID of the question to reply to. Shown at the top of the injected question prompt in your terminal."
+  ),
+  answer: z.string().describe(
+    "Your complete answer in markdown. Be thorough \u2014 the asking Claude is waiting and will use your response directly in their work."
+  )
 };
 function registerReplyTool(server, client) {
-  server.tool("reply", replySchema, async (args) => {
+  server.tool("reply", REPLY_DESCRIPTION, replySchema, async (args) => {
     const questionId = args.questionId;
     const answer = args.answer;
     try {
       if (!client.currentTeamId) {
         return {
-          content: [
-            {
-              type: "text",
-              text: 'You must join a team first. Use the "join" tool to join a team.'
-            }
-          ],
+          content: [{
+            type: "text",
+            text: "P2P node is not ready yet. Wait a moment and try again."
+          }],
           isError: true
         };
       }
       await client.reply(questionId, answer, "markdown");
       injectionQueue.notifyReplied();
       return {
-        content: [
-          {
-            type: "text",
-            text: `Reply sent successfully to question \`${questionId}\`.`
-          }
-        ]
+        content: [{
+          type: "text",
+          text: `Answer sent. The peer's ask() call has been unblocked and they received your response.`
+        }]
       };
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      const isNotFound = errorMessage.includes("not found");
       return {
-        content: [
-          {
-            type: "text",
-            text: `Failed to send reply: ${errorMessage}`
-          }
-        ],
+        content: [{
+          type: "text",
+          text: isNotFound ? `Question \`${questionId}\` not found. Check that you copied the questionId exactly from the injected prompt.` : `Failed to send reply: ${errorMessage}`
+        }],
         isError: true
       };
     }
@@ -743,8 +819,24 @@ function registerReplyTool(server, client) {
 }
 
 // src/presentation/mcp/tools/peers.tool.ts
+var PEERS_DESCRIPTION = `Show your identity on the P2P network and list all currently connected peers.
+
+WHEN TO USE:
+- Before calling ask() \u2014 to confirm the target peer is online and get their exact name
+- After startup \u2014 to verify you joined the network successfully
+- When a peer seems unreachable \u2014 to check if they are still connected
+
+WHAT IT SHOWS:
+- Your own name and the port you are listening on
+- All peers who have established a direct connection to you
+
+IF NO PEERS ARE LISTED:
+- Peers discover each other automatically via LAN broadcast every 3 seconds
+- If a peer just started, wait a few seconds and call peers() again
+- Call firewall_open() so peers on other machines can connect inbound to you
+- If still no peers, verify all machines are on the same LAN/subnet`;
 function registerPeersTool(server, client) {
-  server.tool("peers", {}, async () => {
+  server.tool("peers", PEERS_DESCRIPTION, {}, async () => {
     const info = client.getInfo();
     const myName = info.teamName ?? "(starting...)";
     const myPort = info.port ?? "?";
@@ -753,7 +845,10 @@ function registerPeersTool(server, client) {
       return {
         content: [{
           type: "text",
-          text: `P2P server is not running yet. Port ${myPort} may be in use. Check the MCP logs for details.`
+          text: [
+            `P2P server is not running yet (port ${myPort} may be in use).`,
+            `Check the MCP process logs for the error details.`
+          ].join("\n")
         }],
         isError: true
       };
@@ -762,8 +857,13 @@ function registerPeersTool(server, client) {
       return {
         content: [{
           type: "text",
-          text: `You are "${myName}" (listening on port ${myPort}). No peers connected yet.
-Use firewall_open to allow inbound connections, or wait for peers to connect to you.`
+          text: [
+            `You are "${myName}" (listening on port ${myPort}).`,
+            `No peers connected yet.`,
+            ``,
+            `Peers auto-discover via LAN broadcast \u2014 wait a few seconds if they just started.`,
+            `Call firewall_open() if peers on other machines cannot reach you.`
+          ].join("\n")
         }]
       };
     }
@@ -779,14 +879,27 @@ ${list}`
 }
 
 // src/presentation/mcp/tools/history.tool.ts
+var HISTORY_DESCRIPTION = `Show all questions and answers exchanged this session \u2014 both sent and received.
+
+WHEN TO USE:
+- To review what was already discussed before asking a follow-up question
+- To check if a previously sent question has been answered yet
+- To find a questionId you need to reference
+- To catch up on received questions you may have missed
+
+OUTPUT FORMAT:
+- \u2192 peer: question you sent, with their answer below
+- \u2190 peer: question they sent you, with your reply below
+- (no answer yet) means the question is still waiting for a response`;
 function registerHistoryTool(server, client) {
-  server.tool("history", {}, async () => {
+  server.tool("history", HISTORY_DESCRIPTION, {}, async () => {
     const entries = client.getHistory();
     if (entries.length === 0) {
       return {
-        content: [{ type: "text", text: "No questions yet this session." }]
+        content: [{ type: "text", text: "No questions exchanged yet this session." }]
       };
     }
+    const unanswered = entries.filter((e) => !e.answer);
     const lines = entries.map((e) => {
       const time = new Date(e.askedAt).toLocaleTimeString();
       if (e.direction === "sent") {
@@ -794,13 +907,16 @@ function registerHistoryTool(server, client) {
         return `[${time}] \u2192 ${e.peer}: ${e.question}
 ${answerLine}`;
       } else {
-        const answerLine = e.answer ? `  \u21B3 you: ${e.answer}` : `  \u21B3 (not replied yet)`;
+        const answerLine = e.answer ? `  \u21B3 you: ${e.answer}` : `  \u21B3 (not replied yet \u2014 use reply() if you haven't answered)`;
         return `[${time}] \u2190 ${e.peer}: ${e.question}
 ${answerLine}`;
       }
     });
+    const summary = unanswered.length > 0 ? `
+
+\u26A0 ${unanswered.length} question(s) still waiting for a response.` : "";
     return {
-      content: [{ type: "text", text: lines.join("\n\n") }]
+      content: [{ type: "text", text: lines.join("\n\n") + summary }]
     };
   });
 }
@@ -861,72 +977,123 @@ async function removeFirewallRule(port) {
 }
 
 // src/presentation/mcp/tools/firewall-open.tool.ts
+var FIREWALL_OPEN_DESCRIPTION = `Open a Windows Firewall inbound rule so peers on the LAN can connect directly to you.
+
+WHEN YOU NEED THIS:
+- Other peers cannot see you in their peers() list even though you are on the same LAN
+- You just started and want to make sure all peers can reach you
+- A peer explicitly says they cannot connect to you
+
+WHEN YOU DO NOT NEED THIS:
+- You can already see peers in peers() \u2014 the connection is working
+- You are connecting outbound to others (outbound connections do not require firewall rules)
+
+WHAT HAPPENS:
+- On most systems: the rule is applied immediately (terminal is already elevated)
+- On standard Windows: a UAC popup appears \u2014 the user must click Yes
+- On VMs or headless setups: applied directly if running as Administrator
+
+The rule is named "claude-collab-{port}" and allows inbound TCP on your current listen port.
+Call firewall_close() when you are done to clean up the rule.`;
 function registerFirewallOpenTool(server, client) {
   server.tool(
     "firewall_open",
-    "Open a Windows Firewall inbound rule for your P2P listen port. A UAC popup will appear \u2014 accept it to allow peers to connect to you directly.",
+    FIREWALL_OPEN_DESCRIPTION,
     {
-      port: z.number().min(1024).max(65535).optional().describe("Port to open (defaults to your current listen port)")
+      port: z.number().min(1024).max(65535).optional().describe(
+        "Port to open. Defaults to your current listen port \u2014 omit this unless you have a specific reason to override."
+      )
     },
     async ({ port }) => {
       const targetPort = port ?? client.getInfo().port;
       if (!targetPort) {
         return {
-          content: [{ type: "text", text: "Could not determine port. Pass port explicitly." }],
+          content: [{ type: "text", text: "P2P node is not running yet \u2014 port unknown. Try again in a moment." }],
           isError: true
         };
       }
       try {
         const { method } = await addFirewallRule(targetPort);
-        const how = method === "direct" ? "applied directly (process already elevated)" : "applied via UAC elevation popup";
+        const how = method === "direct" ? "applied directly (already elevated)" : "applied via UAC popup";
         return {
           content: [{
             type: "text",
             text: [
-              `Firewall rule opened for port ${targetPort} (rule name: claude-collab-${targetPort}).`,
-              `Method: ${how}.`,
-              `Peers on the LAN can now connect to you directly.`
+              `Firewall rule opened for port ${targetPort} (claude-collab-${targetPort}). ${how}.`,
+              `Peers on the LAN can now connect to you inbound.`,
+              `Call firewall_close() when you are done with this session.`
             ].join("\n")
           }]
         };
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         return {
-          content: [{ type: "text", text: `Failed to open firewall: ${msg}` }],
+          content: [{
+            type: "text",
+            text: [
+              `Failed to open firewall: ${msg}`,
+              ``,
+              `Try running your terminal as Administrator and call firewall_open() again.`
+            ].join("\n")
+          }],
           isError: true
         };
       }
     }
   );
 }
+var FIREWALL_CLOSE_DESCRIPTION = `Remove the Windows Firewall inbound rule that was opened by firewall_open().
+
+WHEN TO USE:
+- At the end of a collaboration session to clean up
+- When you no longer want to accept inbound peer connections
+- As general hygiene \u2014 open firewall rules should not be left indefinitely
+
+WHAT HAPPENS:
+- The inbound TCP rule "claude-collab-{port}" is deleted from Windows Firewall
+- Existing active connections are not dropped \u2014 only new inbound connections are blocked
+- On standard Windows: a UAC popup appears \u2014 the user must click Yes
+- On VMs or admin terminals: applied directly without a popup
+
+NOTE: Because ports are random each session, each startup creates a new rule name.
+Old rules from previous sessions can be removed by passing the port explicitly.`;
 function registerFirewallCloseTool(server, client) {
   server.tool(
     "firewall_close",
-    "Remove the Windows Firewall inbound rule for your P2P listen port. A UAC popup will appear \u2014 accept it to close the rule.",
+    FIREWALL_CLOSE_DESCRIPTION,
     {
-      port: z.number().min(1024).max(65535).optional().describe("Port to close (defaults to your current listen port)")
+      port: z.number().min(1024).max(65535).optional().describe(
+        "Port whose rule to remove. Defaults to your current listen port. Pass a specific port to clean up a rule from a previous session."
+      )
     },
     async ({ port }) => {
       const targetPort = port ?? client.getInfo().port;
       if (!targetPort) {
         return {
-          content: [{ type: "text", text: "Could not determine port. Pass port explicitly." }],
+          content: [{ type: "text", text: "P2P node is not running yet \u2014 port unknown. Try again in a moment." }],
           isError: true
         };
       }
       try {
         const { method } = await removeFirewallRule(targetPort);
-        const how = method === "direct" ? "applied directly (process already elevated)" : "applied via UAC elevation popup";
+        const how = method === "direct" ? "applied directly (already elevated)" : "applied via UAC popup";
         return {
           content: [{
             type: "text",
-            text: `Firewall rule removed for port ${targetPort} (rule name: claude-collab-${targetPort}). Method: ${how}.`
+            text: `Firewall rule removed for port ${targetPort} (claude-collab-${targetPort}). ${how}.`
           }]
         };
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         return {
-          content: [{ type: "text", text: `Failed to close firewall: ${msg}` }],
+          content: [{
+            type: "text",
+            text: [
+              `Failed to remove firewall rule: ${msg}`,
+              ``,
+              `The rule may not exist (if firewall_open was never called this session), or try running as Administrator.`
+            ].join("\n")
+          }],
           isError: true
         };
       }