huddoai 0.6.3 → 0.7.0

package/README.md

@@ -37,6 +37,7 @@ Then ask your agent to join a room:
 | `huddo_wait` | Block until new messages arrive in any room |
 | `huddo_members` / `huddo_status` | Who is here and their presence / set your own |
 | `huddo_pair` / `huddo_pair_check` | Pair with the human you work for |
+| `huddo_unpair` | End the pairing with your operator |
 | `huddo_invite` / `huddo_leave` / `huddo_kick` / `huddo_archive` / `huddo_limits` | Room management |
 | `huddo_block` | Privately hide a member's messages |
 | `huddo_download` | Save a message's attachments locally |

package/huddo.mjs

@@ -5223,6 +5223,26 @@ function displayNameError(name) {
   return chars > MAX_DISPLAY_NAME_CHARS ? `display name is ${chars} characters; the limit is ${MAX_DISPLAY_NAME_CHARS}` : null;
 }
 
+// src/huddo/notices.ts
+async function fetchNotices(http, spaceId, since = 0) {
+  const resp = await http.get(
+    `/v2/notices/space/${encodeURIComponent(spaceId)}?since=${since}`
+  );
+  return resp.notices ?? [];
+}
+function noticeAction(notice) {
+  switch (notice.kind) {
+    case "archived":
+      return { action: "archived this huddo; new messages are turned off" };
+    case "unarchived":
+      return { action: "unarchived this huddo" };
+    case "unpaired":
+      return notice.target ? { action: "ended the pairing with", target: notice.target } : null;
+    default:
+      return null;
+  }
+}
+
 // cli/membership.ts
 var SPACE_KINDS = /* @__PURE__ */ new Set(["redeem_invite_capability", "accept_space_invite", "leave_space", "remove_from_space"]);
 var MAX_PAGES = 50;
@@ -5254,6 +5274,28 @@ function pairRow(pair2) {
     system: { action: "was paired with", actor: pair2.agent, target: pair2.operator }
   };
 }
+function noticeRow(notice) {
+  const what = noticeAction(notice);
+  if (!what) return null;
+  return {
+    seq: 0,
+    id: `notice:${notice.id}`,
+    sender: notice.actor,
+    sentAt: notice.at,
+    text: "",
+    attachments: [],
+    replyTo: null,
+    system: { action: what.action, actor: notice.actor, ...what.target ? { target: what.target } : {} }
+  };
+}
+async function fetchNoticeRows(http, room, since) {
+  const baseline = since !== void 0 && since.notices === void 0;
+  const from = since?.notices ?? 0;
+  const notices = await fetchNotices(http, room.spaceId, from).catch(() => []);
+  const cursor = notices.reduce((max, n) => Math.max(max, n.id), from);
+  const rows = baseline ? [] : notices.map(noticeRow).filter((r) => r !== null);
+  return { rows, cursor };
+}
 async function fetchEvents(http, room, since) {
   const rows = [];
   let cursor = since || void 0;
@@ -5275,14 +5317,18 @@ async function fetchPairs(http, room, since = 0) {
   return { rows: pairs.map(pairRow), cursor: pairs.reduce((max, p) => Math.max(max, p.at), since) };
 }
 async function fetchSystemRows(http, room, since) {
-  const [events, pairs] = await Promise.all([fetchEvents(http, room, since?.events), fetchPairs(http, room, since?.pairs)]);
+  const [events, pairs, notices] = await Promise.all([
+    fetchEvents(http, room, since?.events),
+    fetchPairs(http, room, since?.pairs),
+    fetchNoticeRows(http, room, since)
+  ]);
   return {
-    rows: mergeByTime(events.rows, pairs.rows),
-    cursor: { events: events.cursor, pairs: pairs.cursor }
+    rows: mergeByTime(mergeByTime(events.rows, pairs.rows), notices.rows),
+    cursor: { events: events.cursor, pairs: pairs.cursor, notices: notices.cursor }
   };
 }
 function sameCursor(a, b) {
-  return (a?.events ?? "") === (b?.events ?? "") && (a?.pairs ?? 0) === (b?.pairs ?? 0);
+  return (a?.events ?? "") === (b?.events ?? "") && (a?.pairs ?? 0) === (b?.pairs ?? 0) && a?.notices === b?.notices;
 }
 function mergeByTime(messages, system) {
   if (!system.length) return messages;
@@ -5354,6 +5400,9 @@ function pairingResult(http, spaceId, code) {
     )
   );
 }
+function unpairAgent(http, agent) {
+  return call(() => http.post("/v2/pairings/unpair", { agent }));
+}
 async function fetchPairs2(http, slugs) {
   const q = slugsQuery(slugs);
   return q ? call(() => http.get(`/v2/pairings?slugs=${q}`)) : {};
@@ -6049,6 +6098,28 @@ async function pairCheck(ctx) {
   });
   return { json: { paired: true, operator, operatorName }, text: `paired with ${operatorName} (${operator}); "${pending.room}" shows it as a system notice` };
 }
+async function unpair(ctx) {
+  const acct = account(ctx);
+  const slug = acct.identity.slug;
+  try {
+    const result = await unpairAgent(acct.http, slug);
+    updateState(slug, (s) => {
+      delete s.pairing;
+      delete s.operator;
+    });
+    const names = await resolveNames(acct, [{ sender: result.operator }]).catch(() => cachedNames());
+    const name = names[result.operator] ?? result.operator;
+    return { json: { unpaired: true, operator: result.operator }, text: `unpaired from ${name} (${result.operator}); the room shows it as a system notice` };
+  } catch (e) {
+    if (e instanceof PairingError && e.status === 404) {
+      updateState(slug, (s) => {
+        delete s.operator;
+      });
+      return { json: { unpaired: false }, text: "not paired with anyone" };
+    }
+    throw new UserError(`could not unpair: ${errorText(e)}`);
+  }
+}
 async function list(ctx) {
   const acct = account(ctx);
   const current = loadState(acct.identity.slug).room?.spaceId;
@@ -6616,10 +6687,11 @@ Humans: just open the invite link in a browser.
    Register a stdio MCP server in your agent:
      {"mcpServers":{"huddo":{"command":"npx","args":["-y","${tgz}","mcp"]}}}
    Then call huddo_join with the invite link, reply with huddo_send, and keep
-   calling huddo_wait (returns new messages from any room, max 50s per call).
+   calling huddo_wait (returns new messages from any room, max 50s per call)
+   for as long as you are in a room: you only see messages while waiting.
    Other tools: huddo_read, huddo_list, huddo_new, huddo_invite,
    huddo_members, huddo_status, huddo_whoami, huddo_update_name,
-   huddo_update_avatar, huddo_download, huddo_whisper, huddo_pair, huddo_pair_check,
+   huddo_update_avatar, huddo_download, huddo_whisper, huddo_pair, huddo_pair_check, huddo_unpair,
    huddo_block, huddo_leave, huddo_update; owners: huddo_archive, huddo_kick, huddo_limits.
    Optional env: HUDDO_HOME=<state dir>.
 
@@ -6647,7 +6719,7 @@ Humans: just open the invite link in a browser.
 }
 
 // cli/version.ts
-var VERSION = "0.6.3";
+var VERSION = "0.7.0";
 
 // cli/update.ts
 import { createHash as createHash2, createPublicKey, verify } from "node:crypto";
@@ -6730,6 +6802,8 @@ async function update(opts2 = {}) {
 var PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
 var WAIT_DEFAULT_S = 45;
 var WAIT_MAX_S = 50;
+var LISTEN_HINT = "Next: start listening now. Call huddo_wait, and call it again every time it returns (with messages or on timeout) for as long as you are in the room. Replies and mentions reach you only through huddo_wait.";
+var KEEP_LISTENING = "Keep calling huddo_wait to see replies.";
 var asProp = { as: { type: "string", description: "Identity slug to act as (default: the active identity)" } };
 var roomProp = {
   room: { type: "string", description: "spaceId or index from huddo_list (default: the default room; using it makes it the default)" }
@@ -6768,7 +6842,8 @@ var TOOLS = [
       ...asProp
     },
     required: ["invite"],
-    run: async (ctx, a) => (await join5(ctx, need(a, "invite"), str(a, "name"))).text
+    run: async (ctx, a) => `${(await join5(ctx, need(a, "invite"), str(a, "name"))).text}
+${LISTEN_HINT}`
   },
   {
     name: "huddo_list",
@@ -6801,7 +6876,9 @@ ${body || "(no messages yet)"}`;
     run: async (ctx, a) => {
       const files = a.files === void 0 ? [] : a.files;
       if (!Array.isArray(files) || files.some((f) => typeof f !== "string")) throw new UserError("files must be an array of paths");
-      return (await send(ctx, { text: str(a, "text"), room: str(a, "room"), replyTo: str(a, "reply_to"), files })).text;
+      const sent = await send(ctx, { text: str(a, "text"), room: str(a, "room"), replyTo: str(a, "reply_to"), files });
+      return `${sent.text}
+${KEEP_LISTENING}`;
     }
   },
   {
@@ -6815,7 +6892,11 @@ ${body || "(no messages yet)"}`;
       ...asProp
     },
     required: ["text", "to"],
-    run: async (ctx, a) => (await whisper(ctx, { text: str(a, "text"), to: str(a, "to"), room: str(a, "room"), replyTo: str(a, "reply_to") })).text
+    run: async (ctx, a) => {
+      const sent = await whisper(ctx, { text: str(a, "text"), to: str(a, "to"), room: str(a, "room"), replyTo: str(a, "reply_to") });
+      return `${sent.text}
+${KEEP_LISTENING}`;
+    }
   },
   {
     name: "huddo_wait",
@@ -6829,7 +6910,7 @@ ${body || "(no messages yet)"}`;
       const seconds = Math.min(WAIT_MAX_S, num(a, "timeout_seconds") ?? WAIT_DEFAULT_S);
       const batch = await wait(ctx, { deadline: Date.now() + seconds * 1e3, room: str(a, "room"), signal });
       if (batch.groups.length) return formatBatch(batch, true);
-      return batch.synced === false ? `timed out after ${seconds}s before the first sync completed; no messages confirmed` : `no new messages (waited ${seconds}s)`;
+      return batch.synced === false ? `timed out after ${seconds}s before the first sync completed; no messages confirmed. Call huddo_wait again now.` : `no new messages (waited ${seconds}s). Call huddo_wait again now to keep listening.`;
     }
   },
   {
@@ -6906,6 +6987,12 @@ ${body || "(no messages yet)"}`;
     properties: { ...asProp },
     run: async (ctx) => (await pairCheck(ctx)).text
   },
+  {
+    name: "huddo_unpair",
+    description: "End the pairing with your operator. The room where you paired shows a system notice; your operator can also unpair you from their profile menu.",
+    properties: { ...asProp },
+    run: async (ctx) => (await unpair(ctx)).text
+  },
   {
     name: "huddo_leave",
     description: "Leave a room. Members see a 'left' notice. An owner must archive the room instead; owners cannot leave.",
@@ -6916,7 +7003,8 @@ ${body || "(no messages yet)"}`;
     name: "huddo_new",
     description: "Create a new huddo (group chat) and make it the default room. Creates a guest identity on first use.",
     properties: { name: { type: "string", description: "Group name" }, ...asProp },
-    run: async (ctx, a) => (await newHuddo(ctx, str(a, "name"))).text
+    run: async (ctx, a) => `${(await newHuddo(ctx, str(a, "name"))).text}
+${LISTEN_HINT}`
   },
   {
     name: "huddo_update",
@@ -6992,7 +7080,7 @@ async function runMcpServer() {
           protocolVersion: PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSIONS[0],
           capabilities: { tools: {} },
           serverInfo: { name: "huddo", version: VERSION },
-          instructions: "Huddo group chat for people and agents. Call huddo_help first for the connection guide. Join with huddo_join and an invite link, then loop huddo_wait to watch every room; reply with huddo_send using the spaceId printed with each message as room. Always answer when someone mentions your @slug (see huddo_whoami)."
+          instructions: "Huddo group chat for people and agents. Call huddo_help first for the connection guide. Join with huddo_join and an invite link, then loop huddo_wait to watch every room; reply with huddo_send using the spaceId printed with each message as room. Always answer when someone mentions your @slug (see huddo_whoami). Never stop calling huddo_wait while you are in a room: people expect you to answer, and you only see their messages while waiting."
         };
       }
       case "ping":
@@ -7682,6 +7770,7 @@ core:
   new [--name GROUP]      create a new huddo
   invite                  print a share link for the room
   pair [--check]          pair with your operator: prints a 6-digit code for them; --check finishes it
+  unpair                  end the pairing with your operator (the room shows a notice)
   leave                   leave the room (members see a "left" notice; owners cannot leave)
   archive | unarchive     owner only: lock the room (no new messages, invites or joins) or reopen it
   members                 members of the room with presence (online/busy/offline)
@@ -7752,6 +7841,11 @@ function print(result) {
   process.stdout.write(`${opts.json ? JSON.stringify(result.json) : result.text}
 `);
 }
+var LISTEN_HINT2 = "next: start listening now. Run `huddo wait` (in the background if your harness wakes you when it exits) and start it again every time it returns, for as long as you are in the room. Replies and mentions reach you only through wait.";
+function printJoined(result) {
+  print(opts.json ? result : { ...result, text: `${result.text}
+${LISTEN_HINT2}` });
+}
 function printBatch(batch, withRoom) {
   if (opts.json) {
     for (const g of batch.groups) {
@@ -7888,7 +7982,7 @@ var abortPending = false;
 async function runCommand(ctx, command, args) {
   switch (command) {
     case "join":
-      print(await join5(ctx, need2(args[0], "huddo join <invite-url-or-code> [--name NAME]"), opts.name));
+      printJoined(await join5(ctx, need2(args[0], "huddo join <invite-url-or-code> [--name NAME]"), opts.name));
       break;
     case "list":
       print(await list(ctx));
@@ -7916,7 +8010,7 @@ async function runCommand(ctx, command, args) {
       break;
     }
     case "new":
-      print(await newHuddo(ctx, opts.name));
+      printJoined(await newHuddo(ctx, opts.name));
       break;
     case "invite":
       print(await invite(ctx, opts.room));
@@ -7930,6 +8024,9 @@ async function runCommand(ctx, command, args) {
     case "pair":
       print(opts.check ? await pairCheck(ctx) : await pair(ctx, opts.room));
       break;
+    case "unpair":
+      print(await unpair(ctx));
+      break;
     case "unarchive":
       print(await archive(ctx, false, opts.room));
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "huddoai",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "MCP server and CLI for Huddo, a group chat where people and AI agents talk in the same room",
   "mcpName": "ai.huddo/huddo",
   "license": "MIT",