@tritard/waterbrother 0.16.40 → 0.16.42

package/README.md

@@ -266,6 +266,7 @@ Shared project foundation is now live:
 - inspect it with `waterbrother room status`
 - control conversation vs execution with `waterbrother room mode chat|plan|execute`
 - manage collaborators with `waterbrother room members`, `waterbrother room invites`, `waterbrother room invite`, `waterbrother room invite accept`, and `waterbrother room remove`
+- inspect recent collaboration activity with `waterbrother room events`
 - manage the shared backlog with `waterbrother room tasks`, `waterbrother room task add`, and `waterbrother room task move`
 - assign, claim, and discuss shared work with `waterbrother room task assign`, `waterbrother room task claim`, `waterbrother room task comment`, and `waterbrother room task history`
 - choose a shared execution preset with `waterbrother room runtime <profile>`
@@ -296,6 +297,7 @@ Current Telegram behavior:
 - paired Telegram users drive the same live session and permissions as the terminal operator when the TUI bridge is attached
 - Telegram now supports remote workspace control with `/cwd`, `/use <path>`, `/desktop`, and `/new-project <name>`
 - shared projects now support `/room`, `/members`, `/invites`, `/tasks`, `/mode`, `/claim`, `/release`, `/invite`, `/accept-invite`, `/approve-invite`, `/reject-invite`, `/remove-member`, `/room-runtime`, and `/task ...` from Telegram
+- Telegram now supports `/whoami` for Telegram-id and shared-room membership visibility, plus `/events` for recent shared-room activity
 - `/room` now includes pending invite count plus task ownership summaries
 - local `/status` now includes `sharedRoom` with pending invites, task ownership summary, and recent shared-room event activity
 - the TUI now prints a small Roundtable event feed when new shared-room activity lands
@@ -304,6 +306,10 @@ Current Telegram behavior:
 - room administration is owner-only, and only owners/editors can hold the operator lock
 - `/room` status now shows the active executor surface plus provider/model/runtime identity
 - repo-first concept resolution now covers Waterbrother itself, Roundtable, Telegram, shared rooms, the gateway, runtime profiles, approvals, and sessions
+- collaboration how-to questions now answer from local state too, including:
+  - how to invite a partner
+  - how to share the current project
+  - how to make a new project
 - in Telegram groups, Waterbrother only responds when directly targeted: slash commands, `@botname` mentions, or replies to a bot message
 - in Telegram groups, directly targeted messages are now classified as chat, planning, or execution; explicit execution should use `/run <prompt>`
 - in Telegram group `chat` or `plan` flows, targeted Waterbrother/project questions are now answered directly from local repo state instead of returning only a generic planner hint

package/package.json

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

package/src/cli.js

@@ -81,6 +81,7 @@ import {
   formatSharedProjectStatus,
   getSharedTaskHistory,
   getSharedProjectPaths,
+  listSharedEvents,
   listSharedInvites,
   listSharedMembers,
   listSharedTasks,
@@ -178,6 +179,7 @@ const INTERACTIVE_COMMANDS = [
   { name: "/share-project", description: "Enable shared-project mode in the current cwd" },
   { name: "/unshare-project", description: "Disable shared-project mode in the current cwd" },
   { name: "/room", description: "Show shared room status for the current project" },
+  { name: "/room events", description: "Show recent Roundtable room events" },
   { name: "/room members", description: "List shared-project members" },
   { name: "/room invites", description: "List pending shared-project invites" },
   { name: "/room add <id> [owner|editor|observer]", description: "Add or update a shared-project member" },
@@ -4047,6 +4049,22 @@ async function runRoomCommand(positional, { cwd = process.cwd(), asJson = false,
     return;
   }
 
+  if (sub === "events") {
+    const events = await listSharedEvents(cwd, 12);
+    if (asJson) {
+      printData({ ok: true, events }, true);
+      return;
+    }
+    if (!events.length) {
+      console.log("No recent shared-room events");
+      return;
+    }
+    for (const event of events) {
+      console.log(`${event.createdAt}\t${event.type}\t${event.actorName || event.actorId || "-"}\t${event.text}`);
+    }
+    return;
+  }
+
   if (sub === "tasks") {
     const tasks = await listSharedTasks(cwd);
     if (asJson) {
@@ -4296,7 +4314,7 @@ async function runRoomCommand(positional, { cwd = process.cwd(), asJson = false,
     return;
   }
 
-  throw new Error("Usage: waterbrother room status|members|invites|add <member-id> [owner|editor|observer] [display name]|invite <member-id> [owner|editor|observer] [display name]|invite approve <invite-id>|invite accept <invite-id>|invite reject <invite-id>|remove <member-id>|tasks|task add <text>|task assign <id> <member-id>|task claim <id>|task move <id> <open|active|blocked|done>|task comment <id> <text>|task history <id>|runtime [<name>|clear]|mode <chat|plan|execute>|claim|release");
+  throw new Error("Usage: waterbrother room status|events|members|invites|add <member-id> [owner|editor|observer] [display name]|invite <member-id> [owner|editor|observer] [display name]|invite approve <invite-id>|invite accept <invite-id>|invite reject <invite-id>|remove <member-id>|tasks|task add <text>|task assign <id> <member-id>|task claim <id>|task move <id> <open|active|blocked|done>|task comment <id> <text>|task history <id>|runtime [<name>|clear]|mode <chat|plan|execute>|claim|release");
 }
 
 async function runMcpCommand(positional, runtime, { cwd, asJson = false } = {}) {
@@ -8241,6 +8259,15 @@ Be concrete about surfaces — name actual pages/flows. Choose the best stack fo
       continue;
     }
 
+    if (line === "/room events") {
+      try {
+        await runRoomCommand(["room", "events"], { cwd: context.cwd, asJson: false, runtime: context.runtime, currentSession, agent, context });
+      } catch (error) {
+        console.log(`room events failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
     if (line === "/room tasks") {
       try {
         await runRoomCommand(["room", "tasks"], { cwd: context.cwd, asJson: false, runtime: context.runtime, currentSession, agent, context });

package/src/gateway.js

@@ -8,7 +8,7 @@ import { createSession, listSessions, loadSession, saveSession } from "./session
 import { DEFAULT_PENDING_PAIRING_TTL_MINUTES, loadGatewayBridge, loadGatewayState, prunePendingPairings, saveGatewayBridge, saveGatewayState } from "./gateway-state.js";
 import { getGatewayStatus, getChannelSpec } from "./channels.js";
 import { canonicalizeLoosePath } from "./path-utils.js";
-import { acceptSharedInvite, addSharedTask, approveSharedInvite, assignSharedTask, claimSharedOperator, claimSharedTask, commentSharedTask, createSharedInvite, getSharedTaskHistory, listSharedInvites, listSharedTasks, loadSharedProject, moveSharedTask, rejectSharedInvite, releaseSharedOperator, setSharedRoom, setSharedRoomMode, setSharedRuntimeProfile, removeSharedMember } from "./shared-project.js";
+import { acceptSharedInvite, addSharedTask, approveSharedInvite, assignSharedTask, claimSharedOperator, claimSharedTask, commentSharedTask, createSharedInvite, getSharedTaskHistory, listSharedEvents, listSharedInvites, listSharedTasks, loadSharedProject, moveSharedTask, rejectSharedInvite, releaseSharedOperator, setSharedRoom, setSharedRoomMode, setSharedRuntimeProfile, removeSharedMember } from "./shared-project.js";
 import { buildSelfAwarenessManifest, formatAboutWaterbrother, formatSelfState, resolveLocalConceptQuestion } from "./self-awareness.js";
 
 const execFileAsync = promisify(execFile);
@@ -27,9 +27,11 @@ const TELEGRAM_COMMANDS = [
   { command: "state", description: "Show current Waterbrother self-awareness state" },
   { command: "run", description: "Execute an explicit remote prompt" },
   { command: "status", description: "Show the linked remote session" },
+  { command: "whoami", description: "Show your Telegram identity and room membership" },
   { command: "cwd", description: "Show the current remote working directory" },
   { command: "runtime", description: "Show active runtime status" },
   { command: "room", description: "Show shared room status" },
+  { command: "events", description: "Show recent shared room events" },
   { command: "members", description: "List shared room members" },
   { command: "invites", description: "List pending shared room invites" },
   { command: "tasks", description: "List shared Roundtable tasks" },
@@ -204,12 +206,14 @@ function buildRemoteHelp() {
     "<code>/state</code> show current Waterbrother self-awareness state",
     "<code>/run &lt;prompt&gt;</code> execute an explicit remote request",
     "<code>/status</code> show the current linked remote session",
+    "<code>/whoami</code> show your Telegram identity and room membership",
     "<code>/cwd</code> show the current remote working directory",
     "<code>/use &lt;path&gt;</code> switch the linked session to another directory",
     "<code>/desktop</code> switch the linked session to <code>~/Desktop</code>",
     "<code>/new-project &lt;name&gt;</code> create a folder on Desktop and switch into it",
     "<code>/runtime</code> show active provider/model/runtime state",
     "<code>/room</code> show shared project room status",
+    "<code>/events</code> show recent shared room events",
     "<code>/members</code> list shared project members",
     "<code>/tasks</code> list shared project tasks",
     "<code>/task add &lt;text&gt;</code> add a shared Roundtable task",
@@ -388,6 +392,51 @@ function formatTelegramInvitesMarkup(invites = []) {
   ].join("\n");
 }
 
+function formatTelegramEventsMarkup(events = []) {
+  if (!events.length) {
+    return "<b>Recent room events</b>\n• none";
+  }
+  return [
+    "<b>Recent room events</b>",
+    ...events.map((event) => {
+      const actor = String(event.actorName || event.actorId || "").trim();
+      const when = String(event.createdAt || "").trim();
+      return `• ${actor ? `${escapeTelegramHtml(actor)} — ` : ""}${escapeTelegramHtml(event.text || "")}${when ? `\n  <code>${escapeTelegramHtml(when)}</code>` : ""}`;
+    })
+  ].join("\n");
+}
+
+function formatTelegramWhoamiMarkup({ message, member = null, invites = [], sharedEnabled = false }) {
+  const from = message?.from || {};
+  const userId = String(from.id || "").trim();
+  const username = String(from.username || "").trim();
+  const displayName = [from.first_name, from.last_name].filter(Boolean).join(" ").trim() || username || userId;
+  const pending = invites.filter((invite) => String(invite.memberId || "").trim() === userId);
+  const lines = [
+    "<b>Telegram identity</b>",
+    `name: <code>${escapeTelegramHtml(displayName)}</code>`,
+    `user id: <code>${escapeTelegramHtml(userId)}</code>`,
+    `username: <code>${escapeTelegramHtml(username || "none")}</code>`
+  ];
+  if (!sharedEnabled) {
+    lines.push("shared room: <code>off</code>");
+    lines.push("This project is not shared yet. Start with <code>waterbrother project share</code>.");
+    return lines.join("\n");
+  }
+  lines.push(`shared member: <code>${member ? "yes" : "no"}</code>`);
+  if (member) {
+    lines.push(`role: <code>${escapeTelegramHtml(member.role || "editor")}</code>`);
+  }
+  if (pending.length) {
+    lines.push("<b>Pending invites you can accept</b>");
+    lines.push(...pending.map((invite) => `• <code>${escapeTelegramHtml(invite.id)}</code> <i>(${escapeTelegramHtml(invite.role || "editor")})</i>`));
+    lines.push("Use <code>/accept-invite &lt;invite-id&gt;</code> to join the shared room.");
+  } else if (!member) {
+    lines.push("No pending Waterbrother room invite for this Telegram user id.");
+  }
+  return lines.join("\n");
+}
+
 function formatTelegramTasksMarkup(tasks = []) {
   if (!tasks.length) {
     return "<b>Shared tasks</b>\n• none";
@@ -1152,6 +1201,20 @@ class TelegramGateway {
       return;
     }
 
+    if (text === "/whoami") {
+      const { project } = await this.bindSharedRoomForMessage(message, sessionId);
+      const invites = project?.enabled ? await listSharedInvites(sessionCwd).catch(() => []) : [];
+      const member = Array.isArray(project?.members)
+        ? project.members.find((entry) => String(entry?.id || "").trim() === userId) || null
+        : null;
+      await this.sendMessage(
+        message.chat.id,
+        formatTelegramWhoamiMarkup({ message, member, invites, sharedEnabled: project?.enabled === true }),
+        message.message_id
+      );
+      return;
+    }
+
     if (text === "/status") {
       await this.sendMessage(
         message.chat.id,
@@ -1195,6 +1258,21 @@ class TelegramGateway {
       return;
     }
 
+    if (text === "/events") {
+      const { session, project } = await this.bindSharedRoomForMessage(message, sessionId);
+      if (!project?.enabled) {
+        await this.sendMessage(message.chat.id, "This project is not shared.", message.message_id);
+        return;
+      }
+      try {
+        const events = await listSharedEvents(session.cwd || this.cwd, 12);
+        await this.sendMessage(message.chat.id, formatTelegramEventsMarkup(events), message.message_id);
+      } catch (error) {
+        await this.sendMessage(message.chat.id, escapeTelegramHtml(error instanceof Error ? error.message : String(error)), message.message_id);
+      }
+      return;
+    }
+
     if (text === "/tasks") {
       const { session, project } = await this.bindSharedRoomForMessage(message, sessionId);
       if (!project?.enabled) {

package/src/self-awareness.js

@@ -258,6 +258,9 @@ export function resolveLocalConceptQuestion(text = "", manifest = {}) {
   const mentionsRoundtable = /\bround[\s-]?table\b/.test(lower);
   const asksWhatIs = /^(what('| i)?s|what is|tell me about|explain)\b/.test(lower) || /\bwhat is\b/.test(lower);
   const asksHowToUseRoundtable = mentionsRoundtable && /\b(how do i|how to|add to|join|use|set up|enable|create)\b/.test(lower);
+  const asksHowToInvitePartner = /\b(invite|add)\b/.test(lower) && /\b(partner|teammate|teammates|teammember|collaborator|member)\b/.test(lower);
+  const asksHowToShareProject = /\b(how do i|how to|share)\b/.test(lower) && /\b(this project|project)\b/.test(lower);
+  const asksHowToMakeProject = /\b(how do i|how to|make|create|start)\b/.test(lower) && /\b(new project|project)\b/.test(lower);
   const sourcesFor = (...keys) => keys.map((key) => manifest.sourceHints?.[key]).filter(Boolean);
   const withSources = (lines, sources = []) => [
     ...lines,
@@ -280,6 +283,35 @@ export function resolveLocalConceptQuestion(text = "", manifest = {}) {
     ], sources);
   }
 
+  if (asksHowToInvitePartner) {
+    const sources = sourcesFor("roundtableDocs", "telegramDocs", "sharedState");
+    return withSources([
+      "To collaborate with a Telegram partner, there are two separate steps.",
+      "First, add the human to the Telegram group/chat itself using normal Telegram controls.",
+      "Second, add them to the Waterbrother shared room with `waterbrother room invite <member-id> [owner|editor|observer]` or `/invite <user-id> [owner|editor|observer]`.",
+      "Then the invited person accepts with `waterbrother room invite accept <invite-id>` or `/accept-invite <invite-id>`.",
+      "If this repo is not shared yet, start with `waterbrother project share`."
+    ], sources);
+  }
+
+  if (asksHowToShareProject) {
+    const sources = sourcesFor("roundtableDocs", "sharedState");
+    return withSources([
+      "To share the current project, run `waterbrother project share` in the repo.",
+      "In an interactive terminal, Waterbrother will guide room mode, room runtime profile, and the first invite.",
+      "After that, use `waterbrother room status`, `waterbrother room invite <member-id> [owner|editor|observer]`, and `waterbrother room mode <chat|plan|execute>` to manage collaboration."
+    ], sources);
+  }
+
+  if (asksHowToMakeProject) {
+    const sources = sourcesFor("roundtableDocs", "telegramDocs", "readme");
+    return withSources([
+      "To make a new project from the TUI, use `/new-project <name>`.",
+      "That creates a folder on `~/Desktop/<name>`, switches the live session into it, and now asks whether the new project should be shared.",
+      "From Telegram, use `/new-project <name>` to create the folder and switch the linked session there. Then use `waterbrother project share` or the TUI sharing prompt if you want collaboration enabled."
+    ], sources);
+  }
+
   if ((/\bshared project\b/.test(lower) || /\bshared room\b/.test(lower) || /\broom mode\b/.test(lower)) && asksWhatIs) {
     const sources = sourcesFor("sharedState", "roundtableDocs", "roundtable");
     return withSources([

package/src/shared-project.js

@@ -456,6 +456,17 @@ export async function listSharedInvites(cwd) {
   return project.pendingInvites || [];
 }
 
+export async function listSharedEvents(cwd, limit = 12) {
+  const project = await loadSharedProject(cwd);
+  requireSharedProject(project);
+  const max = Number.isFinite(Number(limit)) && Number(limit) > 0 ? Math.max(1, Math.floor(Number(limit))) : 12;
+  return Array.isArray(project.recentEvents)
+    ? [...project.recentEvents]
+        .sort((a, b) => String(b.createdAt || "").localeCompare(String(a.createdAt || "")))
+        .slice(0, max)
+    : [];
+}
+
 export async function upsertSharedMember(cwd, member = {}, options = {}) {
   const existing = await loadSharedProject(cwd);
   requireOwner(existing, options.actorId);