@tritard/waterbrother 0.16.24 → 0.16.26

package/README.md

@@ -265,6 +265,7 @@ Shared project foundation is now live:
 - enable it with `waterbrother project share`
 - 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 add`, and `waterbrother room remove`
 - claim or release the shared operator lock with `waterbrother room claim` and `waterbrother room release`
 - shared project metadata lives in `.waterbrother/shared.json`
 - human collaboration notes live in `ROUNDTABLE.md`
@@ -277,8 +278,9 @@ Current Telegram behavior:
 - pending pairings are explicit and expire automatically after 12 hours unless approved
 - 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`, `/mode`, `/claim`, and `/release` from Telegram with a single active-operator lock
+- shared projects now support `/room`, `/members`, `/mode`, `/claim`, `/release`, `/invite`, and `/remove-member` from Telegram
 - shared Telegram execution only runs when the shared room is in `execute` mode
+- room administration is owner-only, and only owners/editors can hold the operator lock
 - in Telegram groups, Waterbrother only responds when directly targeted: slash commands, `@botname` mentions, or replies to a bot message
 - pairing is now explicit: first DM creates a pending request, then approve locally with `waterbrother gateway pair telegram <user-id>`
 

package/package.json

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

package/src/cli.js

@@ -63,9 +63,12 @@ import {
   enableSharedProject,
   formatSharedProjectStatus,
   getSharedProjectPaths,
+  listSharedMembers,
   loadSharedProject,
   releaseSharedOperator,
-  setSharedRoomMode
+  removeSharedMember,
+  setSharedRoomMode,
+  upsertSharedMember
 } from "./shared-project.js";
 
 const execFileAsync = promisify(execFile);
@@ -148,6 +151,9 @@ 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 members", description: "List shared-project members" },
+  { name: "/room add <id> [owner|editor|observer]", description: "Add or update a shared-project member" },
+  { name: "/room remove <id>", description: "Remove a shared-project member" },
   { name: "/room mode <chat|plan|execute>", description: "Set collaboration mode for the shared room" },
   { name: "/room claim", description: "Claim operator control for the shared room" },
   { name: "/room release", description: "Release operator control for the shared room" },
@@ -272,6 +278,9 @@ Usage:
   waterbrother project share
   waterbrother project unshare
   waterbrother room status
+  waterbrother room members
+  waterbrother room add <member-id> [owner|editor|observer]
+  waterbrother room remove <member-id>
   waterbrother room mode <chat|plan|execute>
   waterbrother room claim
   waterbrother room release
@@ -3758,6 +3767,7 @@ async function runProjectCommand(positional, { cwd = process.cwd(), asJson = fal
 
 async function runRoomCommand(positional, { cwd = process.cwd(), asJson = false } = {}) {
   const sub = String(positional[1] || "status").trim().toLowerCase();
+  const operator = getLocalOperatorIdentity();
   if (sub === "status") {
     const project = await loadSharedProject(cwd);
     if (asJson) {
@@ -3768,8 +3778,57 @@ async function runRoomCommand(positional, { cwd = process.cwd(), asJson = false
     return;
   }
 
+  if (sub === "members") {
+    const members = await listSharedMembers(cwd);
+    if (asJson) {
+      printData({ ok: true, members }, true);
+      return;
+    }
+    if (!members.length) {
+      console.log("No shared-project members");
+      return;
+    }
+    for (const member of members) {
+      console.log(`${member.id}\t${member.role}\t${member.name || ""}`);
+    }
+    return;
+  }
+
+  if (sub === "add") {
+    const memberId = String(positional[2] || "").trim();
+    const role = String(positional[3] || "editor").trim().toLowerCase();
+    const name = String(positional.slice(4).join(" ") || memberId).trim();
+    if (!memberId) {
+      throw new Error("Usage: waterbrother room add <member-id> [owner|editor|observer] [display name]");
+    }
+    const project = await upsertSharedMember(
+      cwd,
+      { id: memberId, role, name, paired: true },
+      { actorId: operator.id }
+    );
+    if (asJson) {
+      printData({ ok: true, action: "add", memberId, role, project }, true);
+      return;
+    }
+    console.log(`Shared-project member ${memberId} set to ${role}`);
+    return;
+  }
+
+  if (sub === "remove") {
+    const memberId = String(positional[2] || "").trim();
+    if (!memberId) {
+      throw new Error("Usage: waterbrother room remove <member-id>");
+    }
+    const project = await removeSharedMember(cwd, memberId, { actorId: operator.id });
+    if (asJson) {
+      printData({ ok: true, action: "remove", memberId, project }, true);
+      return;
+    }
+    console.log(`Shared-project member ${memberId} removed`);
+    return;
+  }
+
   if (sub === "claim") {
-    const operator = getLocalOperatorIdentity();
     const project = await claimSharedOperator(cwd, operator);
     if (asJson) {
       printData({ ok: true, action: "claim", project }, true);
@@ -3780,8 +3839,7 @@ async function runRoomCommand(positional, { cwd = process.cwd(), asJson = false
   }
 
   if (sub === "release") {
-    const operator = getLocalOperatorIdentity();
-    const project = await releaseSharedOperator(cwd, operator.id);
+    const project = await releaseSharedOperator(cwd, operator.id, { actorId: operator.id });
     if (asJson) {
       printData({ ok: true, action: "release", project }, true);
       return;
@@ -3801,7 +3859,7 @@ async function runRoomCommand(positional, { cwd = process.cwd(), asJson = false
       console.log(project?.roomMode || "shared project: off");
       return;
     }
-    const project = await setSharedRoomMode(cwd, nextMode);
+    const project = await setSharedRoomMode(cwd, nextMode, { actorId: operator.id });
     if (asJson) {
       printData({ ok: true, action: "mode", roomMode: project.roomMode, project }, true);
       return;
@@ -3810,7 +3868,7 @@ async function runRoomCommand(positional, { cwd = process.cwd(), asJson = false
     return;
   }
 
-  throw new Error("Usage: waterbrother room status|mode <chat|plan|execute>|claim|release");
+  throw new Error("Usage: waterbrother room status|members|add <member-id> [owner|editor|observer] [display name]|remove <member-id>|mode <chat|plan|execute>|claim|release");
 }
 
 async function runMcpCommand(positional, runtime, { cwd, asJson = false } = {}) {
@@ -7638,6 +7696,52 @@ Be concrete about surfaces — name actual pages/flows. Choose the best stack fo
       continue;
     }
 
+    if (line === "/room members") {
+      try {
+        await runRoomCommand(["room", "members"], { cwd: context.cwd, asJson: false });
+      } catch (error) {
+        console.log(`room members failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
+    if (line.startsWith("/room add ")) {
+      const raw = line.replace("/room add", "").trim();
+      if (!raw) {
+        console.log("Usage: /room add <member-id> [owner|editor|observer] [display name]");
+        continue;
+      }
+      const parts = raw.split(/\s+/).filter(Boolean);
+      const memberId = parts.shift() || "";
+      let role = "editor";
+      if (parts.length && ["owner", "editor", "observer"].includes(String(parts[0] || "").toLowerCase())) {
+        role = String(parts.shift() || "editor").toLowerCase();
+      }
+      const displayName = parts.join(" ").trim();
+      try {
+        const positional = ["room", "add", memberId, role];
+        if (displayName) positional.push(...displayName.split(" "));
+        await runRoomCommand(positional, { cwd: context.cwd, asJson: false });
+      } catch (error) {
+        console.log(`room add failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
+    if (line.startsWith("/room remove ")) {
+      const memberId = line.replace("/room remove", "").trim();
+      if (!memberId) {
+        console.log("Usage: /room remove <member-id>");
+        continue;
+      }
+      try {
+        await runRoomCommand(["room", "remove", memberId], { cwd: context.cwd, asJson: false });
+      } catch (error) {
+        console.log(`room remove failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
     if (line.startsWith("/room mode ")) {
       const nextMode = line.replace("/room mode", "").trim().toLowerCase();
       if (!nextMode) {

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 { claimSharedOperator, loadSharedProject, releaseSharedOperator, setSharedRoom, setSharedRoomMode } from "./shared-project.js";
+import { claimSharedOperator, getSharedMember, loadSharedProject, releaseSharedOperator, setSharedRoom, setSharedRoomMode, upsertSharedMember, removeSharedMember } from "./shared-project.js";
 
 const execFileAsync = promisify(execFile);
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -26,6 +26,7 @@ const TELEGRAM_COMMANDS = [
   { command: "cwd", description: "Show the current remote working directory" },
   { command: "runtime", description: "Show active runtime status" },
   { command: "room", description: "Show shared room status" },
+  { command: "members", description: "List shared room members" },
   { command: "mode", description: "Show or set shared room mode" },
   { command: "claim", description: "Claim operator control for a shared project" },
   { command: "release", description: "Release operator control for a shared project" },
@@ -199,6 +200,9 @@ function buildRemoteHelp() {
     "<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>/members</code> list shared project members",
+    "<code>/invite &lt;user-id&gt; [owner|editor|observer]</code> add or update a shared project member",
+    "<code>/remove-member &lt;user-id&gt;</code> remove a shared project member",
     "<code>/mode</code> or <code>/mode &lt;chat|plan|execute&gt;</code> inspect or change shared room mode",
     "<code>/claim</code> claim operator control for a shared project",
     "<code>/release</code> release operator control for a shared project",
@@ -292,6 +296,30 @@ function formatTelegramRoomMarkup(project) {
   ].join("\n");
 }
 
+function formatTelegramMembersMarkup(project) {
+  if (!project?.enabled) {
+    return "This project is not shared.";
+  }
+  const members = Array.isArray(project.members) ? project.members : [];
+  if (!members.length) {
+    return "<b>Shared members</b>\n• none";
+  }
+  return [
+    "<b>Shared members</b>",
+    ...members.map((member) => `• ${escapeTelegramHtml(member.name || member.id)} <i>(${escapeTelegramHtml(member.role || "editor")})</i> <code>${escapeTelegramHtml(member.id || "")}</code>`)
+  ].join("\n");
+}
+
+function parseInviteCommand(text) {
+  const parts = String(text || "").trim().split(/\s+/).filter(Boolean);
+  const userId = String(parts[1] || "").trim();
+  let role = "editor";
+  if (parts[2] && ["owner", "editor", "observer"].includes(String(parts[2]).toLowerCase())) {
+    role = String(parts[2]).toLowerCase();
+  }
+  return { userId, role };
+}
+
 function extractRetryDelayMs(error, attempt) {
   const retryAfter = Number(error?.retryAfterSeconds);
   if (Number.isFinite(retryAfter) && retryAfter > 0) {
@@ -916,6 +944,12 @@ class TelegramGateway {
       return;
     }
 
+    if (text === "/members") {
+      const { project } = await this.bindSharedRoomForMessage(message, sessionId);
+      await this.sendMessage(message.chat.id, formatTelegramMembersMarkup(project), message.message_id);
+      return;
+    }
+
     if (text === "/mode") {
       const { project } = await this.bindSharedRoomForMessage(message, sessionId);
       await this.sendMessage(
@@ -936,7 +970,7 @@ class TelegramGateway {
         return;
       }
       try {
-        const next = await setSharedRoomMode(session.cwd || this.cwd, requestedMode);
+        const next = await setSharedRoomMode(session.cwd || this.cwd, requestedMode, { actorId: userId });
         await this.sendMessage(message.chat.id, `Shared room mode set to <code>${escapeTelegramHtml(next.roomMode)}</code>`, message.message_id);
       } catch (error) {
         await this.sendMessage(message.chat.id, escapeTelegramHtml(error instanceof Error ? error.message : String(error)), message.message_id);
@@ -969,7 +1003,7 @@ class TelegramGateway {
         return;
       }
       try {
-        const released = await releaseSharedOperator(session.cwd || this.cwd, userId);
+        const released = await releaseSharedOperator(session.cwd || this.cwd, userId, { actorId: userId });
         await this.sendMessage(message.chat.id, released.activeOperator?.id ? formatTelegramRoomMarkup(released) : "Shared room released.", message.message_id);
       } catch (error) {
         await this.sendMessage(message.chat.id, escapeTelegramHtml(error instanceof Error ? error.message : String(error)), message.message_id);
@@ -977,6 +1011,59 @@ class TelegramGateway {
       return;
     }
 
+    if (text.startsWith("/invite ")) {
+      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;
+      }
+      const { userId: nextUserId, role } = parseInviteCommand(text);
+      if (!nextUserId) {
+        await this.sendMessage(message.chat.id, "Usage: /invite <user-id> [owner|editor|observer]", message.message_id);
+        return;
+      }
+      try {
+        const next = await upsertSharedMember(
+          session.cwd || this.cwd,
+          { id: nextUserId, role, name: nextUserId, paired: true },
+          { actorId: userId }
+        );
+        const member = getSharedMember(next, nextUserId);
+        await this.sendMessage(
+          message.chat.id,
+          `Shared member set: <code>${escapeTelegramHtml(member?.id || nextUserId)}</code> <i>(${escapeTelegramHtml(member?.role || role)})</i>`,
+          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.startsWith("/remove-member ")) {
+      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;
+      }
+      const nextUserId = text.replace("/remove-member", "").trim();
+      if (!nextUserId) {
+        await this.sendMessage(message.chat.id, "Usage: /remove-member <user-id>", message.message_id);
+        return;
+      }
+      try {
+        await removeSharedMember(session.cwd || this.cwd, nextUserId, { actorId: userId });
+        await this.sendMessage(
+          message.chat.id,
+          `Removed shared member <code>${escapeTelegramHtml(nextUserId)}</code>`,
+          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 === "/runtime") {
       const status = await this.runRuntimeStatus();
       await this.sendMessage(message.chat.id, formatRuntimeStatus(status), message.message_id);

package/src/shared-project.js

@@ -15,6 +15,14 @@ function normalizeMember(member = {}) {
   };
 }
 
+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 normalizeSharedProject(project = {}, cwd = process.cwd()) {
   const members = Array.isArray(project.members) ? project.members.map(normalizeMember).filter((item) => item.id) : [];
   const activeOperator = project.activeOperator && typeof project.activeOperator === "object"
@@ -200,9 +208,9 @@ export async function setSharedRoom(cwd, room = {}) {
   return next;
 }
 
-export async function setSharedRoomMode(cwd, roomMode = "chat") {
+export async function setSharedRoomMode(cwd, roomMode = "chat", options = {}) {
   const existing = await loadSharedProject(cwd);
-  if (!existing?.enabled) throw new Error("Project is not shared.");
+  requireOwner(existing, options.actorId);
   const normalized = String(roomMode || "").trim().toLowerCase();
   if (!["chat", "plan", "execute"].includes(normalized)) {
     throw new Error("Invalid room mode. Expected one of chat, plan, execute.");
@@ -215,15 +223,95 @@ export async function setSharedRoomMode(cwd, roomMode = "chat") {
   return next;
 }
 
+export function getSharedMember(project, memberId = "") {
+  const normalizedId = String(memberId || "").trim();
+  if (!normalizedId || !project?.members?.length) return null;
+  return project.members.find((member) => String(member?.id || "").trim() === normalizedId) || null;
+}
+
+export function memberHasAtLeastRole(project, memberId = "", role = "editor") {
+  const member = getSharedMember(project, memberId);
+  return memberRoleWeight(member?.role) >= memberRoleWeight(role);
+}
+
+function requireSharedProject(project) {
+  if (!project?.enabled) {
+    throw new Error("Project is not shared.");
+  }
+}
+
+function requireOwner(project, actorId = "") {
+  requireSharedProject(project);
+  if (!memberHasAtLeastRole(project, actorId, "owner")) {
+    throw new Error("Only a shared-project owner can do that.");
+  }
+}
+
+export async function listSharedMembers(cwd) {
+  const project = await loadSharedProject(cwd);
+  requireSharedProject(project);
+  return project.members || [];
+}
+
+export async function upsertSharedMember(cwd, member = {}, options = {}) {
+  const existing = await loadSharedProject(cwd);
+  requireOwner(existing, options.actorId);
+  const nextMember = normalizeMember(member);
+  if (!nextMember.id) throw new Error("member id is required");
+  const members = Array.isArray(existing.members) ? [...existing.members] : [];
+  const index = members.findIndex((item) => item.id === nextMember.id);
+  if (index >= 0) {
+    members[index] = { ...members[index], ...nextMember };
+  } else {
+    members.push(nextMember);
+  }
+  const next = await saveSharedProject(cwd, {
+    ...existing,
+    members
+  });
+  await appendRoundtableEvent(
+    cwd,
+    `- ${new Date().toISOString()}: member ${nextMember.name || nextMember.id} set to role ${nextMember.role}`
+  );
+  return next;
+}
+
+export async function removeSharedMember(cwd, memberId = "", options = {}) {
+  const existing = await loadSharedProject(cwd);
+  requireOwner(existing, options.actorId);
+  const normalizedId = String(memberId || "").trim();
+  if (!normalizedId) throw new Error("member id is required");
+  const current = getSharedMember(existing, normalizedId);
+  if (!current) throw new Error(`No shared-project member found for ${normalizedId}`);
+  const owners = (existing.members || []).filter((member) => member.role === "owner");
+  if (current.role === "owner" && owners.length <= 1) {
+    throw new Error("Cannot remove the last owner from a shared project.");
+  }
+  const next = await saveSharedProject(cwd, {
+    ...existing,
+    members: (existing.members || []).filter((member) => member.id !== normalizedId),
+    activeOperator: existing.activeOperator?.id === normalizedId ? null : existing.activeOperator
+  });
+  await appendRoundtableEvent(
+    cwd,
+    `- ${new Date().toISOString()}: member removed ${current.name || current.id}`
+  );
+  return next;
+}
+
 export async function claimSharedOperator(cwd, operator = {}) {
   const existing = await loadSharedProject(cwd);
-  if (!existing?.enabled) throw new Error("Project is not shared.");
+  requireSharedProject(existing);
   const nextOperator = {
     id: String(operator.id || "").trim(),
     name: String(operator.name || "").trim(),
     claimedAt: new Date().toISOString()
   };
   if (!nextOperator.id) throw new Error("operator id is required");
+  const existingMember = getSharedMember(existing, nextOperator.id);
+  if (existingMember && !memberHasAtLeastRole(existing, nextOperator.id, "editor")) {
+    throw new Error("Observers cannot claim operator control.");
+  }
   if (existing.activeOperator?.id && existing.activeOperator.id !== nextOperator.id) {
     throw new Error(`Room is currently claimed by ${existing.activeOperator.name || existing.activeOperator.id}`);
   }
@@ -240,11 +328,17 @@ export async function claimSharedOperator(cwd, operator = {}) {
   return next;
 }
 
-export async function releaseSharedOperator(cwd, operatorId = "") {
+export async function releaseSharedOperator(cwd, operatorId = "", options = {}) {
   const existing = await loadSharedProject(cwd);
-  if (!existing?.enabled) throw new Error("Project is not shared.");
+  requireSharedProject(existing);
   const normalizedId = String(operatorId || "").trim();
-  if (existing.activeOperator?.id && normalizedId && existing.activeOperator.id !== normalizedId) {
+  const actorId = String(options.actorId || "").trim();
+  if (
+    existing.activeOperator?.id &&
+    normalizedId &&
+    existing.activeOperator.id !== normalizedId &&
+    !memberHasAtLeastRole(existing, actorId, "owner")
+  ) {
     throw new Error(`Room is currently claimed by ${existing.activeOperator.name || existing.activeOperator.id}`);
   }
   const next = await saveSharedProject(cwd, {