@kvsm/blether 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,69 @@
+# Blether
+
+Agent-to-agent communication for distributed teams of human developers.
+
+Each developer's coding agent can message the agents of their teammates, on other machines, to give a heads-up before a change, ask the owner of some code instead of guessing, or say that something they were waiting on has landed. Messages are asynchronous: they wait in a mailbox until the receiving agent reads them. They're signed by the sending device and end-to-end encrypted, so the relay that carries them never sees what was said.
+
+> **Status:** early development. Expect breaking changes, and read [Safety](https://github.com/kvsm/blether#safety) before letting agents act on what they receive.
+
+This package contains:
+
+- **`blether`**: the CLI developers use to manage their identity, teams, agents and Approval Policy. Agents can't change any of those.
+- **`blether-bridge`**: a local MCP server that gives an agent its Blether tools.
+- **The Claude Code plugin**: the bridge, new-mail notices, and the `/blether:connect` and `/blether:setup` skills.
+
+Teams also need a relay, which holds each agent's mailbox. It's published as the Docker image [`ghcr.io/kvsm/blether-relay`](https://github.com/kvsm/blether/blob/main/docs/self-hosting.md).
+
+## Quickstart
+
+You need Node 24, and an invite link from a teammate whose team already has a relay.
+
+```sh
+npm install -g @kvsm/blether
+blether claude install                 # adds the plugin to Claude Code (the CLI and VS Code)
+
+blether init --name <name>             # your identity, once per developer
+blether join <invite>                  # prints "Joined <team>."
+blether agent create <team> web        # an agent you own: a named mailbox
+
+cd ~/code/web-app                      # each project an agent works in
+blether use <team> web                 # sessions started here act as "web"
+```
+
+Start a new Claude Code session in the project and run `/blether:connect`. Claude can now message your teammates' agents, and is told when messages arrive. Sessions you don't connect leave Blether out entirely.
+
+By default Claude asks you before it sends any message, and before it acts on any request it receives. `blether policy` shows your Approval Policy, and `blether help` lists every command.
+
+To start a team or run a relay, see [Getting started](https://github.com/kvsm/blether#getting-started).
+
+## Other agents
+
+Any agent that speaks MCP can use the bridge. Add it to the agent's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "blether": { "command": "blether-bridge" }
+  }
+}
+```
+
+The bridge acts as the agent named in the project's `.blether/session.json`, which `blether use` writes. For guidance on when and how to message teammates, give the agent the skill at `$(npm root -g)/@kvsm/blether/plugin/skills/blether/SKILL.md`.
+
+## Updating
+
+```sh
+npm install -g @kvsm/blether@latest
+blether --version                      # shows the version now installed
+blether claude install                 # if you use Claude Code: updates the plugin to match
+```
+
+Then start new agent sessions: a running session keeps the bridge it started with. Your identity, teams and projects are left as they are. See [Updating](https://github.com/kvsm/blether#updating) for the details.
+
+## Documentation
+
+The [README on GitHub](https://github.com/kvsm/blether#readme) covers how Blether works, what agents can do, the safety controls (Approval Policy, sending limits, the secret check and escalations), managing devices and teams, and configuration. [Hosting a relay](https://github.com/kvsm/blether/blob/main/docs/self-hosting.md) covers running one for your team.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kvsm/blether",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Agent-to-agent communication for distributed teams of human developers: the blether CLI, the bridge (an MCP server), and the Claude Code plugin.",
   "keywords": [
     "agents",
@@ -10,6 +10,8 @@
     "messaging"
   ],
   "license": "MIT",
+  "homepage": "https://github.com/kvsm/blether#readme",
+  "bugs": "https://github.com/kvsm/blether/issues",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kvsm/blether.git"
@@ -29,8 +31,8 @@
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.31.0",
     "esbuild": "^0.28.2",
-    "@blether/bridge": "0.0.0",
-    "@blether/relay": "0.0.0"
+    "@blether/bridge": "0.2.0",
+    "@blether/relay": "0.2.0"
   },
   "publishConfig": {
     "access": "public"

package/plugin/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "blether",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "displayName": "Blether",
-  "description": "Message your teammates' coding agents through Blether: the bridge, push delivery, and skills for when and how to reach out.",
+  "description": "Message your teammates' coding agents through Blether: the bridge, new-mail notices, and skills for when and how to reach out.",
   "author": {
     "name": "Kev Smith"
   },
@@ -14,14 +14,9 @@
       "command": "node",
       "args": ["${CLAUDE_PLUGIN_ROOT}/dist/bridge.js"],
       "env": {
-        "BLETHER_PROJECT_DIR": "${CLAUDE_PROJECT_DIR}"
+        "BLETHER_PROJECT_DIR": "${CLAUDE_PROJECT_DIR}",
+        "BLETHER_CONNECT": "manual"
       }
     }
-  },
-  "channels": [
-    {
-      "server": "blether",
-      "displayName": "Blether"
-    }
-  ]
+  }
 }

package/plugin/dist/bridge.js

@@ -36959,6 +36959,9 @@ var DeviceGrant = external_exports.object({
   teams: external_exports.array(external_exports.object({ name: TeamName, id: external_exports.string(), relayUrl: external_exports.url() }))
 });
 
+// ../protocol/dist/version.js
+var BLETHER_VERSION = "0.2.0";
+
 // ../protocol/dist/wire.js
 var AudienceHint = external_exports.object({
   audience: external_exports.union([external_exports.object({ kind: external_exports.literal("agent") }), Audience]),
@@ -37573,9 +37576,79 @@ var SentLog = class {
   }
 };
 
+// ../bridge/dist/inbox-file.js
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync5, renameSync, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join5 } from "node:path";
+var InboxState = external_exports.object({
+  /** Changes each time a bridge starts, so a watcher can tell a restart from new mail. */
+  session: external_exports.string(),
+  /** Messages that have arrived since this bridge started, counting up. */
+  arrivals: external_exports.number().int().min(0),
+  unread: external_exports.number().int().min(0),
+  /** Who the waiting messages are from, oldest first, each once. */
+  from: external_exports.array(external_exports.string()),
+  /** The latest arrival's sender, if any has arrived this session. */
+  lastFrom: external_exports.string().optional(),
+  updatedAt: external_exports.string(),
+  /** Set when the bridge disconnected this session from the relay. */
+  closed: external_exports.boolean().optional()
+});
+function inboxPath(home, team, agent) {
+  if (!/^[A-Za-z0-9_-]+$/.test(team + agent)) {
+    throw new Error("Bad team or agent name.");
+  }
+  return join5(home, "inbox", `${team}.${agent}.json`);
+}
+var InboxFile = class {
+  path;
+  now;
+  /** Identifies this connection, so a watch can tell when it has ended. */
+  session = randomUUID2();
+  arrivals = 0;
+  lastFrom;
+  closed = false;
+  constructor(path2, now = () => /* @__PURE__ */ new Date()) {
+    this.path = path2;
+    this.now = now;
+  }
+  /** Records an arrival (from `from`), then the mailbox as it now stands. */
+  arrived(from, unread, senders) {
+    this.arrivals++;
+    if (from)
+      this.lastFrom = from;
+    this.write(unread, senders);
+  }
+  /** Records that this session has disconnected, so its watch stops. */
+  close() {
+    this.write(0, [], true);
+    this.closed = true;
+  }
+  /** Records the mailbox as it now stands, after a read or at start-up. */
+  write(unread, senders, closed = false) {
+    if (this.closed)
+      return;
+    const state = {
+      session: this.session,
+      arrivals: this.arrivals,
+      unread,
+      from: senders,
+      ...this.lastFrom ? { lastFrom: this.lastFrom } : {},
+      updatedAt: this.now().toISOString(),
+      ...closed ? { closed } : {}
+    };
+    mkdirSync5(join5(this.path, ".."), { recursive: true });
+    const temp = `${this.path}.${process.pid}.tmp`;
+    writeFileSync5(temp, `${JSON.stringify(state)}
+`);
+    renameSync(temp, this.path);
+  }
+};
+
 // ../bridge/dist/session-file.js
-import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "node:fs";
-import { dirname, join as join5, resolve } from "node:path";
+import { existsSync as existsSync6, mkdirSync as mkdirSync6, readFileSync as readFileSync6, writeFileSync as writeFileSync6 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname, join as join6, resolve } from "node:path";
 var SessionFileContents = external_exports.object({
   team: external_exports.string().min(1),
   agent: AgentName
@@ -37584,16 +37657,21 @@ var DIR = ".blether";
 var FILE = "session.json";
 var SessionFileError = class extends Error {
 };
+function isBletherHome(dir, bletherHome) {
+  const same = (a2, b2) => process.platform === "win32" ? resolve(a2).toLowerCase() === resolve(b2).toLowerCase() : resolve(a2) === resolve(b2);
+  const candidate = join6(dir, DIR);
+  return same(candidate, bletherHome) || same(candidate, join6(homedir2(), DIR));
+}
 function findSessionFile(start, bletherHome) {
   let dir = resolve(start);
   for (; ; ) {
-    const candidate = join5(dir, DIR);
-    const path2 = join5(candidate, FILE);
-    if (resolve(candidate) !== resolve(bletherHome) && existsSync5(path2)) {
+    const candidate = join6(dir, DIR);
+    const path2 = join6(candidate, FILE);
+    if (!isBletherHome(dir, bletherHome) && existsSync6(path2)) {
       return { path: path2, contents: readSessionFile(path2) };
     }
     const parent = dirname(dir);
-    if (existsSync5(join5(dir, ".git")) || parent === dir)
+    if (existsSync6(join6(dir, ".git")) || parent === dir)
       return void 0;
     dir = parent;
   }
@@ -37601,7 +37679,7 @@ function findSessionFile(start, bletherHome) {
 function readSessionFile(path2) {
   let raw;
   try {
-    raw = JSON.parse(readFileSync5(path2, "utf8"));
+    raw = JSON.parse(readFileSync6(path2, "utf8"));
   } catch (error62) {
     throw new SessionFileError(`${path2} isn't valid JSON (${error62.message}). Write it again with \`blether use <team> <agent>\`.`);
   }
@@ -37613,7 +37691,7 @@ function readSessionFile(path2) {
 }
 
 // ../bridge/dist/relay-connection.js
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 
 // ../../node_modules/.pnpm/ws@8.22.0/node_modules/ws/wrapper.mjs
 var import_stream = __toESM(require_stream(), 1);
@@ -37676,6 +37754,7 @@ var RelayConnection = class _RelayConnection {
    */
   identity;
   arrivalListeners = /* @__PURE__ */ new Set();
+  readListeners = /* @__PURE__ */ new Set();
   constructor(socket, credentials, scope, witness, readMessages) {
     this.socket = socket;
     this.credentials = credentials;
@@ -37774,7 +37853,7 @@ var RelayConnection = class _RelayConnection {
     if (devices.length === 0) {
       throw new RelayError("untrusted-reply", `Couldn't find the devices of ${to}'s developer to encrypt for.`);
     }
-    const id = randomUUID2();
+    const id = randomUUID3();
     const envelope = sealMessage({
       id,
       team: scope.team,
@@ -37825,7 +37904,7 @@ var RelayConnection = class _RelayConnection {
   }
   /** The `limit` messages this agent sent most recently, newest first. */
   listSent(limit = 20) {
-    const requestId = randomUUID2();
+    const requestId = randomUUID3();
     return this.request(this.listings, requestId, {
       type: "list-sent",
       requestId,
@@ -37841,6 +37920,11 @@ var RelayConnection = class _RelayConnection {
     const from = this.unread.map((item) => item.kind === "lost" ? "lost-message notices" : item.from);
     return [...new Set(from)];
   }
+  /** Calls `listener` after each mailbox read. Returns a function that unsubscribes. */
+  onRead(listener) {
+    this.readListeners.add(listener);
+    return () => this.readListeners.delete(listener);
+  }
   /** Calls `listener` whenever a new message arrives. Returns a function that unsubscribes. */
   onArrival(listener) {
     this.arrivalListeners.add(listener);
@@ -37866,6 +37950,8 @@ var RelayConnection = class _RelayConnection {
     if (read.length > 0 && this.socket.readyState === import_websocket.default.OPEN) {
       this.write({ type: "read", ids: read });
     }
+    for (const listener of this.readListeners)
+      listener();
     return items;
   }
   /** A message read earlier in this session, by id. */
@@ -37887,7 +37973,7 @@ var RelayConnection = class _RelayConnection {
   }
   /** Starts a team whose log is `log`, returning it as the relay stored it. */
   async createTeam(log) {
-    const requestId = randomUUID2();
+    const requestId = randomUUID3();
     const reply = await this.request(this.teamRequests, requestId, {
       type: "create-team",
       requestId,
@@ -37897,7 +37983,7 @@ var RelayConnection = class _RelayConnection {
   }
   /** The names of team `id`'s agents that have a session connected. */
   getPresence(id) {
-    const requestId = randomUUID2();
+    const requestId = randomUUID3();
     return this.request(this.presenceRequests, requestId, {
       type: "get-presence",
       requestId,
@@ -37921,7 +38007,7 @@ var RelayConnection = class _RelayConnection {
   }
   /** Fetches team `id`'s log and verifies it. */
   async getTeam(id) {
-    const requestId = randomUUID2();
+    const requestId = randomUUID3();
     const reply = await this.request(this.teamRequests, requestId, {
       type: "get-team",
       requestId,
@@ -37931,7 +38017,7 @@ var RelayConnection = class _RelayConnection {
   }
   /** Appends `entry` to team `id`'s log, returning the verified result. */
   async appendTeam(id, entry) {
-    const requestId = randomUUID2();
+    const requestId = randomUUID3();
     const reply = await this.request(this.teamRequests, requestId, {
       type: "append-team",
       requestId,
@@ -38197,7 +38283,7 @@ function take(map2, key) {
 }
 
 // ../bridge/dist/server.js
-import { randomUUID as randomUUID3 } from "node:crypto";
+import { randomUUID as randomUUID4 } from "node:crypto";
 
 // ../../node_modules/.pnpm/zod@4.6.5/node_modules/zod/v3/helpers/util.js
 var util;
@@ -51027,7 +51113,7 @@ var CLAUDE_CHANNEL = "claude/channel";
 var CLAUDE_CHANNEL_NOTIFICATION = "notifications/claude/channel";
 function createSetupProblemServer(problem, { takeOver } = {}) {
   const explanation = `Blether isn't working in this session: ${problem}`;
-  const server2 = new McpServer({ name: "blether", version: "0.0.0" }, {
+  const server2 = new McpServer({ name: "blether", version: BLETHER_VERSION }, {
     instructions: `${explanation} Blether's messaging tools are unavailable until this is fixed. If your developer asks about Blether, or you need to message another agent, tell them this and suggest the fix.`,
     // Declared up front so a session that takes its agent over can still
     // receive channel notices.
@@ -51057,9 +51143,59 @@ function createSetupProblemServer(problem, { takeOver } = {}) {
   }
   return server2;
 }
+function createDormantServer(connect2) {
+  const server2 = new McpServer({ name: "blether", version: BLETHER_VERSION }, { capabilities: { experimental: { [CLAUDE_CHANNEL]: {} } } });
+  const offerConnect = () => {
+    const connectTool = server2.registerTool("connect", {
+      title: "Connect to Blether",
+      description: "Connects this session to Blether, so you can message the agents of other developers on your team. Call it only when your developer runs /blether:connect or asks you to connect to Blether."
+    }, async () => {
+      let connected;
+      try {
+        connected = await connect2(server2);
+      } catch (error62) {
+        return {
+          ...text(`Couldn't connect to Blether: ${error62.message}`),
+          isError: true
+        };
+      }
+      connectTool.remove();
+      const disconnectTool = server2.registerTool("disconnect", {
+        title: "Disconnect from Blether",
+        description: "Disconnects this session from Blether. Call it only when your developer runs /blether:disconnect or asks you to."
+      }, async () => {
+        const result = await connected.disconnect();
+        disconnectTool.remove();
+        offerConnect();
+        return text(result);
+      });
+      return text(connected.result);
+    });
+  };
+  offerConnect();
+  return server2;
+}
+function removableTools(server2, install) {
+  const added = [];
+  const register = server2.registerTool.bind(server2);
+  server2.registerTool = ((...args) => {
+    const tool = register(...args);
+    added.push(tool);
+    return tool;
+  });
+  try {
+    install();
+  } finally {
+    delete server2.registerTool;
+  }
+  return () => {
+    for (const tool of added.splice(0))
+      tool.remove();
+  };
+}
 function createBridgeServer(relay, { policy = STRICTEST_POLICY, escalations, now = () => /* @__PURE__ */ new Date(), scanSecrets = scanForSecrets, sentLog, server: existing } = {}) {
   const pendingAtStart = escalations?.pending().length ?? 0;
-  const server2 = existing ?? new McpServer({ name: "blether", version: "0.0.0" }, {
+  const server2 = existing ?? new McpServer({ name: "blether", version: BLETHER_VERSION }, {
     instructions: [
       INSTRUCTIONS,
       ...escalations ? [
@@ -51144,7 +51280,7 @@ function createBridgeServer(relay, { policy = STRICTEST_POLICY, escalations, now
       if (approval !== "approved") {
         return respond(`Not sent: ${approval}`, true);
       }
-      const fanout = randomUUID3();
+      const fanout = randomUUID4();
       const sendOne = async (recipient) => {
         const receipt = await relay.send(recipient, body, {
           audience,
@@ -51466,6 +51602,8 @@ var REFUSAL_FIXES = {
   "identity-conflict": () => "The relay holds a different history for your identity than this device does. Don't add devices from two places at once; ask for help before going further."
 };
 async function startBridge(env = process.env, log = (line) => console.error(line)) {
+  if (env.BLETHER_CONNECT === "manual")
+    return startDormant(env, log);
   try {
     const { server: server2, connection } = await connect(env, log);
     return {
@@ -51500,7 +51638,65 @@ async function startBridge(env = process.env, log = (line) => console.error(line
     };
   }
 }
-async function connect(env, log) {
+function startDormant(env, log) {
+  let connected;
+  const disconnect = async () => {
+    const opened = connected;
+    connected = void 0;
+    if (!opened)
+      return;
+    opened.removeTools();
+    try {
+      opened.inbox.close();
+    } catch {
+    }
+    await opened.connection.close();
+  };
+  const server2 = createDormantServer(async (server3) => {
+    let opened;
+    try {
+      opened = await connect(env, log, server3);
+    } catch (error62) {
+      if (error62 instanceof SetupProblem) {
+        throw new Error(error62.message, { cause: error62 });
+      }
+      throw error62;
+    }
+    connected = opened;
+    log(`blether bridge connected as ${opened.agent}`);
+    return {
+      result: connectedGuidance(opened),
+      disconnect: async () => {
+        await disconnect();
+        log("blether bridge disconnected");
+        return "Disconnected from Blether. Your watch stops by itself, and Blether's tools are gone until your developer runs /blether:connect again.";
+      }
+    };
+  });
+  return {
+    server: server2,
+    close: async () => {
+      await server2.close();
+      await disconnect();
+    }
+  };
+}
+function connectedGuidance({ agent, team, inbox, pendingEscalations }) {
+  const path2 = inbox.path.split("\\").join("/");
+  const watch = `blether watch --inbox "${path2}" --session ${inbox.session}`;
+  return [
+    `Connected to Blether: you are ${agent} in team ${team.name}.`,
+    INSTRUCTIONS,
+    ...pendingEscalations > 0 ? [
+      `${pendingEscalations} escalation(s) from earlier sessions are waiting for your developer: call list_escalations and raise them with your developer.`
+    ] : [],
+    "",
+    "Now:",
+    "1. Call read_mailbox.",
+    `2. Start a watch, so you hear about new mail between prompts: use the Monitor tool (load it with ToolSearch first if it's deferred) with the command: ${watch} \u2014 the description "Blether mail for ${agent}", and timeout_ms 1800000. Each line it prints means new mail: call read_mailbox. When the watch expires, start it again. If it stops by itself (this session disconnected, or another session took the agent over), don't.`
+  ].join("\n");
+}
+async function connect(env, log, into) {
   const home = env.BLETHER_HOME ?? defaultBletherHome();
   let session;
   try {
@@ -51547,13 +51743,13 @@ async function connect(env, log) {
 Messages are end-to-end encrypted; the relay sees only who messaged whom, and when.`);
   const found = { store, credentials, team, agent: agent.data, log };
   try {
-    return await open2(found, false);
+    return await open2(found, into !== void 0, into);
   } catch (error62) {
     if (!(error62 instanceof RelayError)) {
       throw new SetupProblem(`Couldn't connect to the relay at ${team.relayUrl}: ${error62.message}. Is it running? Start it, then restart this session.`);
     }
     const fix = REFUSAL_FIXES[error62.code]?.(agent.data, team.name);
-    throw new SetupProblem(`The relay refused this session (${error62.code}): ${error62.message}${fix ? ` ${fix}` : ""}`, error62.code === "agent-in-use" ? async (server2) => (await open2(found, true, server2)).connection : void 0);
+    throw new SetupProblem(`The relay refused this session (${error62.code}): ${error62.message}${fix ? ` ${fix}` : ""}`, error62.code === "agent-in-use" && !into ? async (server2) => (await open2(found, true, server2)).connection : void 0);
   }
 }
 async function open2({ store, credentials, team, agent, log }, takeover, server2) {
@@ -51567,13 +51763,43 @@ async function open2({ store, credentials, team, agent, log }, takeover, server2
   if (relay.identity && relay.identity.length > credentials.identity.length) {
     store.saveIdentity(relay.identity);
   }
-  const bridge = createBridgeServer(relay, {
+  const inbox = new InboxFile(inboxPath(store.home, team.id, agent));
+  keepInboxFile(relay, inbox);
+  const escalations = new EscalationStore(store.home, team.id, agent);
+  const options = {
     policy: new PolicyStore(store.home).load(),
-    escalations: new EscalationStore(store.home, team.id, agent),
-    sentLog: new SentLog(store.home, team.id, agent),
-    ...server2 ? { server: server2 } : {}
-  });
-  return { server: bridge, connection: relay };
+    escalations,
+    sentLog: new SentLog(store.home, team.id, agent)
+  };
+  let bridge;
+  let removeTools = () => {
+  };
+  if (server2) {
+    bridge = server2;
+    removeTools = removableTools(server2, () => createBridgeServer(relay, { ...options, server: server2 }));
+  } else {
+    bridge = createBridgeServer(relay, options);
+  }
+  return {
+    server: bridge,
+    connection: relay,
+    agent,
+    team,
+    inbox,
+    removeTools,
+    pendingEscalations: escalations.pending().length
+  };
+}
+function keepInboxFile(relay, inbox) {
+  const attempt = (write) => {
+    try {
+      write();
+    } catch {
+    }
+  };
+  relay.onArrival((item) => attempt(() => inbox.arrived(item.kind === "lost" ? void 0 : item.from, relay.unreadCount, relay.unreadFrom())));
+  relay.onRead(() => attempt(() => inbox.write(relay.unreadCount, relay.unreadFrom())));
+  void relay.settled().then(() => attempt(() => inbox.write(relay.unreadCount, relay.unreadFrom())));
 }
 
 // ../bridge/dist/bin.js

package/plugin/dist/cli.js

@@ -27617,6 +27617,9 @@ function parseDeviceGrant(text) {
   }
 }
 
+// ../protocol/dist/version.js
+var BLETHER_VERSION = "0.2.0";
+
 // ../protocol/dist/wire.js
 var AudienceHint = external_exports.object({
   audience: external_exports.union([external_exports.object({ kind: external_exports.literal("agent") }), Audience]),
@@ -28007,6 +28010,7 @@ var RelayConnection = class _RelayConnection {
    */
   identity;
   arrivalListeners = /* @__PURE__ */ new Set();
+  readListeners = /* @__PURE__ */ new Set();
   constructor(socket, credentials, scope, witness, readMessages) {
     this.socket = socket;
     this.credentials = credentials;
@@ -28172,6 +28176,11 @@ var RelayConnection = class _RelayConnection {
     const from = this.unread.map((item) => item.kind === "lost" ? "lost-message notices" : item.from);
     return [...new Set(from)];
   }
+  /** Calls `listener` after each mailbox read. Returns a function that unsubscribes. */
+  onRead(listener) {
+    this.readListeners.add(listener);
+    return () => this.readListeners.delete(listener);
+  }
   /** Calls `listener` whenever a new message arrives. Returns a function that unsubscribes. */
   onArrival(listener) {
     this.arrivalListeners.add(listener);
@@ -28197,6 +28206,8 @@ var RelayConnection = class _RelayConnection {
     if (read.length > 0 && this.socket.readyState === import_websocket.default.OPEN) {
       this.write({ type: "read", ids: read });
     }
+    for (const listener of this.readListeners)
+      listener();
     return items;
   }
   /** A message read earlier in this session, by id. */
@@ -28695,6 +28706,7 @@ var PolicyStore = class {
 
 // ../bridge/dist/session-file.js
 import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
 import { dirname, join as join4, resolve } from "node:path";
 var SessionFileContents = external_exports.object({
   team: external_exports.string().min(1),
@@ -28703,7 +28715,17 @@ var SessionFileContents = external_exports.object({
 var DIR = ".blether";
 var FILE = "session.json";
 var GITIGNORE = "# Written by `blether use`: this developer's own agent for the project.\n*\n";
-function writeSessionFile(projectDir, contents) {
+var SessionFileError = class extends Error {
+};
+function isBletherHome(dir, bletherHome) {
+  const same = (a2, b2) => process.platform === "win32" ? resolve(a2).toLowerCase() === resolve(b2).toLowerCase() : resolve(a2) === resolve(b2);
+  const candidate = join4(dir, DIR);
+  return same(candidate, bletherHome) || same(candidate, join4(homedir2(), DIR));
+}
+function writeSessionFile(projectDir, contents, bletherHome) {
+  if (isBletherHome(projectDir, bletherHome)) {
+    throw new SessionFileError(`${resolve(projectDir)} is your home directory, where Blether keeps your identity, not a project. Run "blether use" from the project's root, or give it --dir <project>.`);
+  }
   const dir = join4(projectDir, DIR);
   mkdirSync4(dir, { recursive: true });
   const ignore = join4(dir, ".gitignore");
@@ -28715,9 +28737,71 @@ function writeSessionFile(projectDir, contents) {
   return path;
 }
 
+// ../bridge/dist/inbox-file.js
+import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync5, renameSync, writeFileSync as writeFileSync5 } from "node:fs";
+var InboxState = external_exports.object({
+  /** Changes each time a bridge starts, so a watcher can tell a restart from new mail. */
+  session: external_exports.string(),
+  /** Messages that have arrived since this bridge started, counting up. */
+  arrivals: external_exports.number().int().min(0),
+  unread: external_exports.number().int().min(0),
+  /** Who the waiting messages are from, oldest first, each once. */
+  from: external_exports.array(external_exports.string()),
+  /** The latest arrival's sender, if any has arrived this session. */
+  lastFrom: external_exports.string().optional(),
+  updatedAt: external_exports.string(),
+  /** Set when the bridge disconnected this session from the relay. */
+  closed: external_exports.boolean().optional()
+});
+function readInboxState(path) {
+  if (!existsSync5(path))
+    return void 0;
+  try {
+    return InboxState.parse(JSON.parse(readFileSync5(path, "utf8")));
+  } catch {
+    return void 0;
+  }
+}
+function unreadSummary(state) {
+  if (!state || state.unread === 0)
+    return void 0;
+  return `\u{1F4EC} ${state.unread} unread Blether message${state.unread === 1 ? "" : "s"} (from ${state.from.join(", ")}). Call read_mailbox to read them.`;
+}
+
+// ../bridge/dist/watch.js
+function watchInbox(path, session, emit, end, { intervalMs = 1e3 } = {}) {
+  let arrivals;
+  let timer;
+  let stopped = false;
+  const stop = () => {
+    stopped = true;
+    clearInterval(timer);
+  };
+  const check2 = () => {
+    const state = readInboxState(path);
+    if (!state)
+      return;
+    if (state.session !== session || state.closed) {
+      stop();
+      end(state.session === session ? "disconnected" : "taken-over");
+      return;
+    }
+    const summary = unreadSummary(state);
+    const arrived = arrivals !== void 0 && state.arrivals > arrivals;
+    if (summary && (arrivals === void 0 || arrived)) {
+      emit(arrived && state.lastFrom ? `New Blether message from ${state.lastFrom}. ${summary}` : summary);
+    }
+    arrivals = state.arrivals;
+  };
+  check2();
+  if (!stopped)
+    timer = setInterval(check2, intervalMs);
+  return stop;
+}
+
 // ../bridge/dist/claude-install.js
 import { spawn } from "node:child_process";
-import { existsSync as existsSync5 } from "node:fs";
+import { existsSync as existsSync6 } from "node:fs";
 import { dirname as dirname2, join as join5, resolve as resolve2 } from "node:path";
 import { fileURLToPath } from "node:url";
 var PLUGIN_ID = "blether@blether";
@@ -28737,7 +28821,7 @@ var runClaude = (args) => new Promise((resolvePromise, reject) => {
 function packageRoot(from = dirname2(fileURLToPath(import.meta.url))) {
   let dir = resolve2(from);
   for (; ; ) {
-    if (existsSync5(join5(dir, ".claude-plugin", "marketplace.json")))
+    if (existsSync6(join5(dir, ".claude-plugin", "marketplace.json")))
       return dir;
     const parent = dirname2(dir);
     if (parent === dir)
@@ -28801,6 +28885,9 @@ Commands:
   agent delete <team> <name>         Delete one of your agents (or any, as Team Admin)
   use <team> <agent> [--dir <path>]  Make sessions started in this project (or <path>) act as <agent>
   claude install                     Install (or update) the Blether plugin in Claude Code
+  watch --inbox <path> --session <id>
+                                     Print a line whenever a connected session's agent gets mail
+                                     (the bridge gives its agent this command when it connects)
   escalations                        List messages your agents are holding for your decision
   status                             One line for your Claude Code status line: escalations waiting
   policy                             Show your Approval Policy on this device
@@ -28810,6 +28897,7 @@ Commands:
                                      outgoing: ask | ask-others | free
                                      incoming: ask | ask-impactful | free
                                      limits: most messages an agent sends in the window
+  --version                          Show which version of Blether is installed
 
 Set BLETHER_HOME to keep Blether's files somewhere other than ~/.blether.`;
 var CliError = class extends Error {
@@ -28917,6 +29005,8 @@ ${USAGE}`);
     }
     case "use":
       return use(rest, ctx);
+    case "watch":
+      return watch(rest, ctx);
     case "claude": {
       const [sub] = rest;
       if (sub === "install")
@@ -28937,6 +29027,11 @@ ${USAGE}`);
     case "-h":
       ctx.io.out(USAGE);
       return command === void 0 ? 1 : 0;
+    case "version":
+    case "--version":
+    case "-v":
+      ctx.io.out(BLETHER_VERSION);
+      return 0;
     default:
       throw new CliError(`Unknown command: ${command}
 
@@ -28950,7 +29045,7 @@ function init(args, { store, io }) {
   });
   const name = DeveloperName.safeParse(values.name);
   if (!name.success) {
-    throw new CliError('Give your name, as teammates will see it: blether init --name "Kev"');
+    throw new CliError("Give your name, as teammates will see it: blether init --name <name>");
   }
   if (store.exists()) {
     throw new CliError(`There is already a Blether identity in ${store.home}. Run \`blether whoami\` to see it.`);
@@ -29427,6 +29522,27 @@ async function agentDelete(args, ctx) {
   ctx.io.out(`Deleted agent ${name} from ${record2.name}. Unread messages to it are lost, and their senders will be told. The name can be used again.`);
   return 0;
 }
+async function watch(args, ctx) {
+  const { values } = parseArgs({
+    args,
+    options: { inbox: { type: "string" }, session: { type: "string" } }
+  });
+  if (!values.inbox || !values.session) {
+    throw new CliError("Usage: blether watch --inbox <path> --session <id>");
+  }
+  const ended = await new Promise((resolve3) => {
+    const stop = watchInbox(values.inbox, values.session, ctx.io.out, (why) => resolve3(why === "taken-over" ? "Blether watch stopped: another session took over this agent." : "Blether watch stopped: this session disconnected from Blether."));
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+      process.once(signal, () => {
+        stop();
+        resolve3("");
+      });
+    }
+  });
+  if (ended)
+    ctx.io.out(ended);
+  return 0;
+}
 async function claudeInstall(ctx) {
   const root = "packageRoot" in ctx ? ctx.packageRoot : packageRoot();
   if (!root) {
@@ -29439,7 +29555,6 @@ async function claudeInstall(ctx) {
     throw new CliError(missing ? "Couldn't run `claude`. Install Claude Code, or check it's on your PATH." : error62.message);
   }
   ctx.io.out("Start a new Claude Code session to use it, and run /blether:setup in each project.");
-  ctx.io.out(`For push delivery, start sessions with: claude --dangerously-load-development-channels plugin:${PLUGIN_ID}`);
   return 0;
 }
 async function use(args, ctx) {
@@ -29463,10 +29578,14 @@ async function use(args, ctx) {
   if (agent.owner !== me2) {
     throw new CliError(`${name} belongs to another developer. Use one of yours (blether agent list ${record2.name}), or create one.`);
   }
-  const path = writeSessionFile(values.dir ?? ctx.cwd ?? process.cwd(), {
-    team: record2.name,
-    agent: name
-  });
+  let path;
+  try {
+    path = writeSessionFile(values.dir ?? ctx.cwd ?? process.cwd(), { team: record2.name, agent: name }, ctx.store.home);
+  } catch (error62) {
+    if (error62 instanceof SessionFileError)
+      throw new CliError(error62.message);
+    throw error62;
+  }
   ctx.io.out(`Sessions started in this project will act as ${name} in ${record2.name}.`);
   ctx.io.out(`Wrote ${path}; it's ignored by git, since the agent is yours. Restart any session already running here.`);
   return 0;

package/plugin/skills/blether/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: blether
-description: Message teammates' agents through Blether. Use before a change that affects code or interfaces another developer owns, when you need an answer only another developer's agent has, when your work blocks or unblocks someone, or when a Blether message arrives that needs a reply.
+description: Message teammates' agents through Blether, in a session the developer has connected with /blether:connect. Once connected, use before a change that affects code or interfaces another developer owns, when you need an answer only another developer's agent has, when your work blocks or unblocks someone, or when a Blether message arrives that needs a reply.
 ---
 
 # Working with your team through Blether
 
 Blether connects you to the agents of the other developers on your team. Each agent works for its own developer, in its own project. The bridge's tools (`list_agents`, `send_message`, `read_mailbox`, `sent_messages`) do the carrying, and each tool result says how to handle what it returns. This skill is about **when** to reach out and **how to write** so the other agent can act without coming back to you.
 
+Blether is used only in sessions the developer connects (`/blether:connect`). If the bridge's messaging tools aren't available, this session isn't connected: carry on without Blether, don't connect on your own, and don't bring it up.
+
 ## When to send
 
 - **Heads-up before you change something others depend on**: an API shape, a shared schema, a config key, a library version, a file layout. Send it before you commit, saying what changes and when, so their agent can adapt or object.

package/plugin/skills/connect/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: connect
+description: Connect this session to Blether, so it can message teammates' agents and hear about new mail.
+disable-model-invocation: true
+---
+
+# Connect this session to Blether
+
+The developer wants this session to use Blether. Until now the bridge has stayed out of it.
+
+1. Call the bridge's `connect` tool (`mcp__plugin_blether_blether__connect`; load it with ToolSearch first if it's deferred).
+2. If it fails, tell the developer what it says. If no agent is chosen for this project, offer `/blether:setup`.
+3. If it connects, do what its result says: read the mailbox, then start the watch with the Monitor tool, exactly as given.
+4. Tell the developer in two or three lines: which agent this session is, what's waiting in the mailbox, and that you'll hear about new mail while connected. If another session was using the agent, it has been disconnected.

package/plugin/skills/disconnect/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: disconnect
+description: Disconnect this session from Blether, so it stops messaging teammates' agents and hearing about new mail.
+disable-model-invocation: true
+---
+
+# Disconnect this session from Blether
+
+Call the bridge's `disconnect` tool (`mcp__plugin_blether_blether__disconnect`; load it with ToolSearch first if it's deferred). The watch stops by itself. Tell the developer in one line that the session is disconnected, and that `/blether:connect` connects it again.

package/plugin/skills/setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup
-description: Set up Blether for this project - identity, team, agent, push delivery and status line.
+description: Set up Blether for this project - identity, team, agent and status line - and connect this session.
 disable-model-invocation: true
 ---
 
@@ -37,17 +37,20 @@ Then run `use <team> <agent>` in the project root. It writes `.blether/session.j
 
 Done when `use` reports the agent for this project.
 
-## 4. Reload and check
+## 4. Connect and check
 
-Tell the developer to restart this session (or run `/mcp` and reconnect the `blether` server) so the bridge picks up the project's agent.
+Setting Blether up is a request to use it, so connect this session: call the bridge's `connect` tool (`mcp__plugin_blether_blether__connect`; load it with ToolSearch first if it's deferred). It reads the project's agent when called, so there's no need to restart.
 
-Done when the bridge's `list_agents` shows the roster. If the bridge offers only `blether_status`, it couldn't start: call it, and fix what it says.
+Done when it connects and its result's instructions are followed (read the mailbox, start the watch). If it fails, fix what it says.
 
-## 5. Push delivery and visibility
+## 5. How it works, and visibility
 
-Explain these two options and set up the ones they want:
+Tell them how Blether works from now on:
+
+- **Sessions start without Blether.** The bridge stays out of every session until they run `/blether:connect`. A connected session can message teammates' agents and hears about new mail through a watch; `/blether:disconnect` ends that. Only one session can be connected as an agent at a time: connecting another takes the agent over.
+
+Offer this option and set it up if they want it:
 
-- **Push delivery (channels)**: new messages can wake the session instead of waiting for the next mailbox check. Channels are a research preview, so Claude Code needs starting with `claude --dangerously-load-development-channels plugin:blether@blether`. Without it, nothing breaks; messages wait in the mailbox.
 - **Status line**: `blether status` prints a count of messages agents are holding for the developer's decision. Offer to add it to `statusLine` in `~/.claude/settings.json`, merging with any status line they already have.
 
 Finish with a one-paragraph summary: who they are, which team, which agent this project acts as, and what's enabled.