@tritard/waterbrother 0.16.68 → 0.16.70

package/package.json

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

package/src/gateway.js

@@ -9,7 +9,7 @@ import { DEFAULT_PENDING_PAIRING_TTL_MINUTES, loadGatewayBridge, loadGatewayStat
 import { getGatewayStatus, getChannelSpec } from "./channels.js";
 import { getConfigPath, loadConfigLayers, saveConfig } from "./config.js";
 import { canonicalizeLoosePath } from "./path-utils.js";
-import { acceptSharedInvite, addSharedTask, approveSharedInvite, assignSharedTask, claimSharedOperator, claimSharedTask, commentSharedTask, createSharedInvite, enableSharedProject, getSharedTaskHistory, listSharedEvents, listSharedInvites, listSharedTasks, loadSharedProject, moveSharedTask, rejectSharedInvite, releaseSharedOperator, setSharedRoom, setSharedRoomMode, setSharedRuntimeProfile, removeSharedMember, upsertSharedMember } from "./shared-project.js";
+import { acceptSharedInvite, addSharedTask, approveSharedInvite, assignSharedTask, claimSharedOperator, claimSharedTask, commentSharedTask, createSharedInvite, enableSharedProject, getSharedTaskHistory, listSharedEvents, listSharedInvites, listSharedTasks, loadSharedProject, moveSharedTask, rejectSharedInvite, releaseSharedOperator, setSharedRoom, setSharedRoomMode, setSharedRuntimeProfile, removeSharedMember, upsertSharedAgent, upsertSharedMember } from "./shared-project.js";
 import { buildSelfAwarenessManifest, formatAboutWaterbrother, formatSelfState, resolveLocalConceptQuestion } from "./self-awareness.js";
 
 const execFileAsync = promisify(execFile);
@@ -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>",
@@ -340,6 +402,23 @@ function chooseExecutorAgent(project, fallbackExecutor = {}) {
   return null;
 }
 
+function memberRoleWeight(role = "") {
+  const normalized = String(role || "").trim().toLowerCase();
+  if (normalized === "owner") return 3;
+  if (normalized === "editor") return 2;
+  if (normalized === "observer") return 1;
+  return 0;
+}
+
+function memberHasAtLeastRole(project, memberId = "", role = "editor") {
+  const normalizedId = String(memberId || "").trim();
+  if (!normalizedId) return false;
+  const member = Array.isArray(project?.members)
+    ? project.members.find((entry) => String(entry?.id || "").trim() === normalizedId) || null
+    : null;
+  return memberRoleWeight(member?.role) >= memberRoleWeight(role);
+}
+
 function formatAgentLabel(agent = {}) {
   const label = String(agent?.label || agent?.name || "").trim();
   const role = String(agent?.role || "").trim();
@@ -479,6 +558,33 @@ function parseTelegramPairingIntent(text = "") {
   return null;
 }
 
+function parseTelegramAgentIntent(text = "") {
+  const value = normalizeTelegramProjectIntentText(text);
+  const lowered = value.toLowerCase();
+  if (!value) return null;
+  if (/^(how|what|why|when|where|who)\b/.test(lowered)) return null;
+  const roleMatch = lowered.match(/\b(executor|reviewer|standby)\b/);
+  const role = roleMatch?.[1] || "";
+  if (!role) return null;
+
+  const patterns = [
+    /^(?:have|make|set)\s+(.+?)['’]s\s+(?:bot|terminal)\s+(?:be|as|to)?\s*(?:the\s+)?(executor|reviewer|standby)\s*$/i,
+    /^(?:have|make|set)\s+(.+?)\s+(?:bot|terminal)\s+(?:be|as|to)?\s*(?:the\s+)?(executor|reviewer|standby)\s*$/i,
+    /^(.+?)['’]s\s+(?:bot|terminal)\s+should\s+(?:be\s+)?(?:the\s+)?(executor|reviewer|standby)\s*$/i,
+    /^(.+?)\s+(?:bot|terminal)\s+should\s+(?:be\s+)?(?:the\s+)?(executor|reviewer|standby)\s*$/i
+  ];
+  for (const pattern of patterns) {
+    const match = value.match(pattern);
+    if (!match) continue;
+    const target = String(match[1] || "").trim();
+    const nextRole = String(match[2] || role).trim().toLowerCase();
+    if (target && nextRole) {
+      return { action: "agent-role", target, role: nextRole };
+    }
+  }
+  return null;
+}
+
 function parseTelegramStateIntent(text = "") {
   const value = normalizeTelegramProjectIntentText(text);
   const lower = value.toLowerCase();
@@ -496,6 +602,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" };
   }
@@ -1490,6 +1599,41 @@ class TelegramGateway {
     };
   }
 
+  async handleConversationalAgentIntent(message, sessionId, intent) {
+    const { session, project } = await this.bindSharedRoomForMessage(message, sessionId);
+    if (!project?.enabled) {
+      throw new Error("This project is not shared yet. Use /project share first.");
+    }
+    const actorId = String(message?.from?.id || "").trim();
+    if (!memberHasAtLeastRole(project, actorId, "owner")) {
+      throw new Error("Only a shared-project owner can change terminal roles.");
+    }
+    const actor = this.describeTelegramUser(message?.from || {});
+    const targetAgent = resolveProjectAgent(project, intent.target);
+    if (!targetAgent) {
+      throw new Error(`No terminal found for ${intent.target}. Ask them to connect their Waterbrother bot/terminal first.`);
+    }
+    const nextProject = await upsertSharedAgent(session.cwd || this.cwd, {
+      ...targetAgent,
+      role: intent.role
+    }, {
+      actorId,
+      actorName: actor.displayName || actorId
+    });
+    return {
+      kind: "agent",
+      project: nextProject,
+      markup: [
+        "<b>Roundtable terminal updated</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>`
+      ].join("\n")
+    };
+  }
+
   async handleStateIntent(message, sessionId, intent) {
     const { session, project } = await this.bindSharedRoomForMessage(message, sessionId);
     const cwd = session.cwd || this.cwd;
@@ -1532,6 +1676,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.";
@@ -2200,11 +2362,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);
@@ -2962,6 +3158,16 @@ Ask them to run <code>/whoami</code> and then <code>/accept-invite ${escapeTeleg
       }
       return;
     }
+    const agentIntent = parseTelegramAgentIntent(promptText);
+    if (agentIntent) {
+      try {
+        const result = await this.handleConversationalAgentIntent(message, sessionId, agentIntent);
+        await this.sendMarkup(message.chat.id, result.markup, message.message_id);
+      } catch (error) {
+        await this.sendMessage(message.chat.id, escapeTelegramHtml(error instanceof Error ? error.message : String(error)), message.message_id);
+      }
+      return;
+    }
     const memberIntent = parseTelegramMemberIntent(promptText);
     if (memberIntent) {
       try {