@tritard/waterbrother 0.16.69 → 0.16.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tritard/waterbrother",
-  "version": "0.16.69",
+  "version": "0.16.71",
   "description": "Waterbrother: bring-your-own-model coding CLI with local tools, sessions, operator modes, and approval controls",
   "type": "module",
   "bin": {

package/src/gateway.js

@@ -272,6 +272,68 @@ function buildRemoteHelp() {
   ].join("\n");
 }
 
+function buildTelegramDmOnboardingMarkup({ cwd = "", project = null, peer = null } = {}) {
+  const activeProject = project?.projectName || (cwd ? path.basename(cwd) : "");
+  return [
+    "<b>Waterbrother on Telegram</b>",
+    "You can talk to me here much like the TUI. Ask questions, make changes, refine work, or share a project into a room.",
+    activeProject ? `current project: <code>${escapeTelegramHtml(activeProject)}</code>` : "",
+    cwd ? `cwd: <code>${escapeTelegramHtml(cwd)}</code>` : "",
+    peer?.sessionId ? `linked session: <code>${escapeTelegramHtml(peer.sessionId)}</code>` : "",
+    "",
+    "<b>Good first moves</b>",
+    "• ask <code>what project are you in?</code>",
+    "• say <code>make a test page in this project</code>",
+    "• say <code>share this project in my Telegram room</code>",
+    "",
+    "<b>Need the full command list?</b>",
+    "Use <code>/help</code>."
+  ].filter(Boolean).join("\n");
+}
+
+function buildTelegramRoomOnboardingMarkup({ project = null, actorName = "", executor = {} } = {}) {
+  const participants = listProjectParticipants(project);
+  const agents = listProjectAgents(project);
+  return [
+    "<b>Roundtable room</b>",
+    actorName ? `${escapeTelegramHtml(actorName)} is talking to Waterbrother in the shared room for <code>${escapeTelegramHtml(project?.projectName || "this project")}</code>.` : "",
+    `room mode: <code>${escapeTelegramHtml(project?.roomMode || "chat")}</code>`,
+    `participants: <code>${escapeTelegramHtml(String(participants.length || (project?.members || []).length || 0))}</code>`,
+    `agents: <code>${escapeTelegramHtml(String(agents.length || 0))}</code>`,
+    executor?.provider && executor?.model ? `active runtime: <code>${escapeTelegramHtml(`${executor.provider}/${executor.model}`)}</code>` : "",
+    "",
+    "<b>What you can do here</b>",
+    "• ask <code>what project is this chat bound to?</code>",
+    "• ask <code>who is in the room?</code>",
+    "• say <code>add Austin as editor</code>",
+    "• in execute mode, address Waterbrother directly to build or change code",
+    "",
+    "Use <code>/help</code> for the full command list."
+  ].filter(Boolean).join("\n");
+}
+
+function buildTelegramRoomGuidanceMarkup({ project = null, member = null, executor = {} } = {}) {
+  const role = String(member?.role || "observer").trim() || "observer";
+  const roleGuidance = role === "owner"
+    ? "As owner, you can add people, change room mode, assign terminal roles, and run work."
+    : role === "editor"
+      ? "As editor, you can collaborate on tasks, discuss plans, and execute work when the room is in execute mode and you hold the floor."
+      : "As observer, you can ask questions, discuss plans, and review work here.";
+  return [
+    "<b>What you can do here</b>",
+    `project: <code>${escapeTelegramHtml(project?.projectName || "unknown")}</code>`,
+    `your role: <code>${escapeTelegramHtml(role)}</code>`,
+    `room mode: <code>${escapeTelegramHtml(project?.roomMode || "chat")}</code>`,
+    executor?.provider && executor?.model ? `active runtime: <code>${escapeTelegramHtml(`${executor.provider}/${executor.model}`)}</code>` : "",
+    roleGuidance,
+    "Try asking:",
+    "• <code>what project is this chat bound to?</code>",
+    "• <code>who is in the room?</code>",
+    "• <code>who are the bots?</code>",
+    role === "owner" ? "• <code>add Austin as editor</code>" : "• <code>what mode are we in?</code>"
+  ].filter(Boolean).join("\n");
+}
+
 function formatGatewaySessionStatus({ sessionId, userId, username, cwd, runtimeProfile, provider, model }) {
   const bits = [
     "<b>Telegram remote session</b>",
@@ -501,6 +563,34 @@ function parseTelegramAgentIntent(text = "") {
   const lowered = value.toLowerCase();
   if (!value) return null;
   if (/^(how|what|why|when|where|who)\b/.test(lowered)) return null;
+  const reviewPatterns = [
+    /^(?:have|ask|use)\s+(.+?)['’]s\s+(?:bot|terminal)\s+(?:to\s+)?review(?:\s+this)?\s*$/i,
+    /^(?:have|ask|use)\s+(.+?)\s+(?:bot|terminal)\s+(?:to\s+)?review(?:\s+this)?\s*$/i
+  ];
+  for (const pattern of reviewPatterns) {
+    const match = value.match(pattern);
+    if (!match) continue;
+    const target = String(match[1] || "").trim();
+    if (target) {
+      return { action: "agent-review", target, role: "reviewer" };
+    }
+  }
+
+  const executePatterns = [
+    /^(?:have|ask|use)\s+(.+?)['’]s\s+(?:bot|terminal)\s+(?:to\s+)?(?:take execution|execute|handle execution|take this)\s*$/i,
+    /^(?:have|ask|use)\s+(.+?)\s+(?:bot|terminal)\s+(?:to\s+)?(?:take execution|execute|handle execution|take this)\s*$/i,
+    /^(.+?)['’]s\s+(?:bot|terminal)\s+should\s+(?:take execution|execute|handle execution)\s*$/i,
+    /^(.+?)\s+(?:bot|terminal)\s+should\s+(?:take execution|execute|handle execution)\s*$/i
+  ];
+  for (const pattern of executePatterns) {
+    const match = value.match(pattern);
+    if (!match) continue;
+    const target = String(match[1] || "").trim();
+    if (target) {
+      return { action: "agent-execute", target, role: "executor" };
+    }
+  }
+
   const roleMatch = lowered.match(/\b(executor|reviewer|standby)\b/);
   const role = roleMatch?.[1] || "";
   if (!role) return null;
@@ -540,6 +630,9 @@ function parseTelegramStateIntent(text = "") {
   if (/\bwho can act\b/.test(lower) || /\bwho is the active operator\b/.test(lower) || /\bwho has the floor\b/.test(lower) || /\bwho claimed\b/.test(lower)) {
     return { action: "active-operator" };
   }
+  if (/\bwhat can i do here\b/.test(lower) || /\bhow do i use this room\b/.test(lower) || /\bhow do i use this chat\b/.test(lower) || /\bwhat do i do here\b/.test(lower)) {
+    return { action: "room-guidance" };
+  }
   if (/\bwho are the bots\b/.test(lower) || /\bwho are the agents\b/.test(lower) || /\bwhat bots are here\b/.test(lower) || /\bwhat agents are here\b/.test(lower)) {
     return { action: "agent-list" };
   }
@@ -1555,16 +1648,28 @@ class TelegramGateway {
       actorId,
       actorName: actor.displayName || actorId
     });
+    const runtimeLabel = targetAgent.provider && targetAgent.model ? `${targetAgent.provider}/${targetAgent.model}` : "unknown";
+    const actionTitle = intent.action === "agent-review"
+      ? "Roundtable reviewer assigned"
+      : intent.action === "agent-execute"
+        ? "Roundtable executor assigned"
+        : "Roundtable terminal updated";
+    const note = intent.action === "agent-review"
+      ? "This sets the room reviewer role. It does not automatically run a review pass yet."
+      : intent.action === "agent-execute"
+        ? "This sets the room executor role. Claim/mode rules still control actual execution."
+        : "";
     return {
       kind: "agent",
       project: nextProject,
       markup: [
-        "<b>Roundtable terminal updated</b>",
+        `<b>${escapeTelegramHtml(actionTitle)}</b>`,
         `owner: <code>${escapeTelegramHtml(targetAgent.ownerName || targetAgent.ownerId || targetAgent.label || targetAgent.id || "-")}</code>`,
         `terminal: <code>${escapeTelegramHtml(targetAgent.label || targetAgent.id || "-")}</code>`,
         `role: <code>${escapeTelegramHtml(intent.role)}</code>`,
-        `runtime: <code>${escapeTelegramHtml(targetAgent.provider && targetAgent.model ? `${targetAgent.provider}/${targetAgent.model}` : "unknown")}</code>`,
-        `project: <code>${escapeTelegramHtml(nextProject.projectName || path.basename(session.cwd || this.cwd))}</code>`
+        `runtime: <code>${escapeTelegramHtml(runtimeLabel)}</code>`,
+        `project: <code>${escapeTelegramHtml(nextProject.projectName || path.basename(session.cwd || this.cwd))}</code>`,
+        note
       ].join("\n")
     };
   }
@@ -1611,6 +1716,24 @@ class TelegramGateway {
         : "<b>Active operator</b>\nnone";
     }
 
+    if (intent.action === "room-guidance") {
+      if (!project?.enabled) {
+        return [
+          "<b>What you can do here</b>",
+          "This chat is not bound to a shared project yet.",
+          "Try:",
+          "• <code>share this project in this chat</code>",
+          "• <code>what project are you in?</code>",
+          "• <code>/help</code> for the full command list"
+        ].join("\n");
+      }
+      const actorId = String(message?.from?.id || "").trim();
+      const member = Array.isArray(project?.members)
+        ? project.members.find((entry) => String(entry?.id || "").trim() === actorId) || null
+        : null;
+      return buildTelegramRoomGuidanceMarkup({ project, member, executor });
+    }
+
     if (intent.action === "agent-list") {
       if (!project?.enabled) {
         return "This project is not shared.";
@@ -2279,11 +2402,45 @@ class TelegramGateway {
     this.clearContinuation(message);
     const userId = String(message.from.id);
 
-    if (text === "/help" || text === "/start") {
+    if (text === "/help") {
       await this.sendMessage(message.chat.id, buildRemoteHelp(), message.message_id);
       return;
     }
 
+    if (text === "/start") {
+      if (this.isGroupChat(message)) {
+        const sessionId = await this.ensurePeerSession(message);
+        const { project } = await this.bindSharedRoomForMessage(message, sessionId);
+        const host = await this.getLiveBridgeHost();
+        await this.sendMarkup(
+          message.chat.id,
+          buildTelegramRoomOnboardingMarkup({
+            project,
+            actorName: this.describeTelegramUser(message?.from || {}).displayName,
+            executor: {
+              provider: host?.provider || this.runtime.provider,
+              model: host?.model || this.runtime.model
+            }
+          }),
+          message.message_id
+        );
+      } else {
+        const peer = this.getPeerState(String(message?.from?.id || "").trim());
+        const session = peer?.sessionId ? await loadSession(peer.sessionId).catch(() => null) : null;
+        const project = session?.cwd ? await loadSharedProject(session.cwd).catch(() => null) : null;
+        await this.sendMarkup(
+          message.chat.id,
+          buildTelegramDmOnboardingMarkup({
+            cwd: session?.cwd || this.cwd,
+            project,
+            peer
+          }),
+          message.message_id
+        );
+      }
+      return;
+    }
+
     if (text === "/new") {
       const sessionId = await this.startFreshSession(message);
       await this.sendMessage(message.chat.id, `Started new remote session: <code>${escapeTelegramHtml(sessionId)}</code>`, message.message_id);