@codeforbreakfast/commy-mcp 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeforbreakfast/commy-mcp",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "commy MCP server — the inter-agent communication substrate, runnable on node via npx.",
   "license": "Apache-2.0",
   "type": "module",

package/server.js

@@ -47088,6 +47088,36 @@ var wrapBotHttp = (inner, resolveDirectory, selfUserId) => ({
   delete: (path, schema, body) => inner.delete(path, schema, body)
 });
 
+// packages/zulip/permalink.ts
+var HASH_REPLACEMENTS = {
+  "%": ".",
+  "!": ".21",
+  "'": ".27",
+  "(": ".28",
+  ")": ".29",
+  "*": ".2A",
+  ".": ".2E"
+};
+var encodeHashComponent = (value5) => encodeURIComponent(value5).replace(/[%!'()*.]/g, (matched) => HASH_REPLACEMENTS[matched] ?? matched);
+var permalinkBase = (config2) => config2.hostHeader === undefined ? config2.realmUrl.replace(/\/+$/, "") : `https://${config2.hostHeader}`;
+var channelSlug = (channel) => `${channel.id}-${encodeHashComponent(channel.name.replaceAll(" ", "-"))}`;
+var channelPermalink = (base, channel) => `${base}/#narrow/channel/${channelSlug(channel)}`;
+var topicPermalink = (base, channel, topic) => `${channelPermalink(base, channel)}/topic/${encodeHashComponent(topic)}`;
+var messagePermalink = (base, channel, id3, topic) => topic === undefined ? `${channelPermalink(base, channel)}/near/${id3}` : `${topicPermalink(base, channel, topic)}/near/${id3}`;
+var withChannelPermalink = (base, channel) => ({ ...channel, permalink: channelPermalink(base, channel) });
+var buildMessageRef = (base, id3, channel, threadName3) => {
+  const decoratedChannel = withChannelPermalink(base, channel);
+  return threadName3 === undefined ? { id: id3, channel: decoratedChannel, permalink: messagePermalink(base, decoratedChannel, id3) } : {
+    id: id3,
+    channel: decoratedChannel,
+    thread: {
+      name: threadName3,
+      permalink: topicPermalink(base, decoratedChannel, threadName3)
+    },
+    permalink: messagePermalink(base, decoratedChannel, id3, threadName3)
+  };
+};
+
 // packages/zulip/events.ts
 var createMessageRefCache = (maxSize = 1e4) => {
   const map32 = new Map;
@@ -47177,16 +47207,12 @@ var extractMentions = (content, byName) => {
   }
   return results;
 };
-var decodeMessageRef = (message) => exports_Effect.gen(function* () {
+var decodeMessageRef = (message, base) => exports_Effect.gen(function* () {
   const id3 = yield* decodeMessageId(String(message.id));
   const channelId = yield* decodeChannelId(String(message.stream_id));
   const channelName = yield* decodeChannelName(message.display_recipient);
   const threadName3 = yield* decodeThreadName(message.subject);
-  return {
-    id: id3,
-    channel: { id: channelId, name: channelName },
-    thread: { name: threadName3 }
-  };
+  return buildMessageRef(base, id3, { id: channelId, name: channelName }, threadName3);
 });
 var decodeSenderIdentity = (message, directory) => {
   const cached4 = directory.byId.get(message.sender_id);
@@ -47198,9 +47224,9 @@ var decodeSenderIdentity = (message, directory) => {
     return { id: id3, name, kind: "human" };
   });
 };
-var messageToInboundEvents = (message, directory, boundIdentity) => exports_Effect.gen(function* () {
+var messageToInboundEvents = (message, directory, boundIdentity, base) => exports_Effect.gen(function* () {
   const sender = yield* decodeSenderIdentity(message, directory);
-  const ref = yield* decodeMessageRef(message);
+  const ref = yield* decodeMessageRef(message, base);
   const body = yield* decodeMessageBody(message.content);
   const ts = yield* decodeTimestamp(message.timestamp);
   const portMessage = {
@@ -47223,12 +47249,12 @@ var messageToInboundEvents = (message, directory, boundIdentity) => exports_Effe
 });
 var channelShapeSchema = exports_Schema.Struct({ stream_id: exports_Schema.Number });
 var decodeChannelShape = exports_Schema.decodeUnknownEither(channelShapeSchema);
-var mapMessageEvent = (raw3, directory, boundIdentity) => {
+var mapMessageEvent = (raw3, directory, boundIdentity, base) => {
   const message = raw3["message"];
   if (exports_Either.isLeft(decodeChannelShape(message))) {
     return exports_Effect.succeed([]);
   }
-  return decodeZulipMessageContent(message).pipe(exports_Effect.flatMap((parsed) => messageToInboundEvents(parsed, directory, boundIdentity)));
+  return decodeZulipMessageContent(message).pipe(exports_Effect.flatMap((parsed) => messageToInboundEvents(parsed, directory, boundIdentity, base)));
 };
 var reactionKind = (op) => op === "add" ? "reaction-added" : "reaction-removed";
 var decodeReactionIdentity = (reaction, directory) => {
@@ -47267,7 +47293,7 @@ var singleMessageResponseSchema = exports_Schema.Struct({
   result: exports_Schema.Literal("success"),
   messages: exports_Schema.Array(zulipMessageContentSchema)
 });
-var fetchMessageRef = (http, messageId) => http.get("/messages", singleMessageResponseSchema, {
+var fetchMessageRef = (http, messageId, base) => http.get("/messages", singleMessageResponseSchema, {
   anchor: messageId,
   num_before: 0,
   num_after: 0,
@@ -47277,7 +47303,7 @@ var fetchMessageRef = (http, messageId) => http.get("/messages", singleMessageRe
   const message = res.messages[0];
   if (message === undefined || message.id !== messageId)
     return exports_Effect.succeed(exports_Option.none());
-  return decodeMessageRef(message).pipe(exports_Effect.map(exports_Option.some));
+  return decodeMessageRef(message, base).pipe(exports_Effect.map(exports_Option.some));
 }));
 var describeError = (err) => messageOf(err);
 var markReplayed = (events) => events.map((ev) => {
@@ -47290,7 +47316,7 @@ var defaultRetrySchedule = exports_Schedule.exponential(exports_Duration.seconds
 var skipWithLog = (line) => exports_Effect.logInfo(line).pipe(exports_Effect.as([]));
 var processSingleEvent = (evt, directory, config2) => {
   if (evt.type === "message") {
-    return mapMessageEvent(evt, directory, config2.boundIdentity).pipe(exports_Effect.tap((events) => exports_Effect.sync(() => {
+    return mapMessageEvent(evt, directory, config2.boundIdentity, config2.permalinkBase).pipe(exports_Effect.tap((events) => exports_Effect.sync(() => {
       if (config2.messageRefCache !== undefined) {
         populateCacheFromInboundEvents(config2.messageRefCache, events);
       }
@@ -47308,7 +47334,7 @@ var processSingleEvent = (evt, directory, config2) => {
     if (cachedTarget !== undefined) {
       return eventsForTarget(cachedTarget).pipe(exports_Effect.catchTag("ParseError", (err) => skipWithLog(`commy zulip events: skipping reaction event id=${evt.id}: ${describeError(err)}`)));
     }
-    return fetchMessageRef(config2.http, reaction.message_id).pipe(exports_Effect.flatMap(exports_Option.match({
+    return fetchMessageRef(config2.http, reaction.message_id, config2.permalinkBase).pipe(exports_Effect.flatMap(exports_Option.match({
       onNone: () => exports_Effect.succeed([]),
       onSome: (target) => {
         cache.set(target.id, target);
@@ -47554,6 +47580,12 @@ class ReactivateForbidden extends exports_Data.TaggedError("ReactivateForbidden"
     return `cannot reactivate deactivated bot ${this.userId}: the minter is not an ` + `organization administrator, and POST /users/{id}/reactivate is admin-only. ` + `Pin this identity with COMMY_BOT_NAME so it is never deactivated on ` + `release, or grant the minter admin rights. Underlying realm ` + `error: ${this.cause.message}`;
   }
 }
+
+class AttachIdentityNotFound extends exports_Data.TaggedError("AttachIdentityNotFound") {
+  get message() {
+    return `attach mode: no provisioned bot named '${this.name}' on the realm. ` + `Provision the persona once and supply its stable api key before attaching.`;
+  }
+}
 var SHORT_NAME_PATTERN = /[^a-z0-9._-]/g;
 var sanitiseShortName = (name) => {
   const collapsed = name.toLowerCase().replace(SHORT_NAME_PATTERN, "-");
@@ -47741,7 +47773,7 @@ var zulipAdapter = (config2) => exports_Effect.gen(function* () {
     const body = yield* decodeMessageBody(m.content);
     const reactions = yield* mapHistoricalReactions(m.reactions, directory2);
     return {
-      ref: { id: m.id, channel, thread: { name: m.subject } },
+      ref: decorateMessageRef(m.id, channel, m.subject),
       sender,
       body,
       ts: m.ts,
@@ -47760,6 +47792,9 @@ var zulipAdapter = (config2) => exports_Effect.gen(function* () {
     })
   ], { concurrency: 2 }).pipe(exports_Effect.flatMap(([directory2, res]) => exports_Effect.forEach(res.messages, toHistoricalMessage).pipe(exports_Effect.map((historical) => historical.filter(inRange(range5))), exports_Effect.flatMap((inRangeMessages) => exports_Effect.forEach(inRangeMessages, (m) => mapHistoricalMessage(m, channel, directory2))))));
   const realmHost = new URL(config2.realmUrl).hostname;
+  const base = permalinkBase(config2);
+  const decorateChannel = (channel) => withChannelPermalink(base, channel);
+  const decorateMessageRef = (id3, channel, threadName3) => buildMessageRef(base, id3, channel, threadName3);
   const buildBotEmail = (shortName) => BotEmail(`${shortName}-bot@${realmHost}`);
   const findAnyBotByName = (name) => minterHttp.get("/users", usersSchema).pipe(exports_Effect.map((res) => exports_Option.fromNullable(res.members.find((u) => u.full_name === name && u.is_bot))));
   const mintBot = (name) => {
@@ -47793,6 +47828,18 @@ var zulipAdapter = (config2) => exports_Effect.gen(function* () {
       return reactivate.pipe(exports_Effect.flatMap(() => regenerateBotKey(existing)));
     }
   })));
+  const attachBot = (name, apiKey) => findAnyBotByName(name).pipe(exports_Effect.flatMap(exports_Option.match({
+    onNone: () => exports_Effect.fail(new AttachIdentityNotFound({ name })),
+    onSome: (existing) => BotEmail(existing.email).pipe(exports_Effect.map((email) => ({
+      userId: ZulipUserRef(existing.user_id),
+      apiKey,
+      email
+    })))
+  })));
+  const provideMintedFor = (name) => {
+    const attach = config2.attachIdentity;
+    return attach !== undefined && attach.name === name ? attachBot(name, exports_Redacted.value(attach.apiKey)) : acquireBot(name);
+  };
   const identity6 = {
     currentIdentity: () => requireBound().pipe(exports_Effect.map((b) => b.identity)),
     acquire: (name) => exports_SynchronizedRef.modifyEffect(boundRef, (current2) => exports_Option.match(current2, {
@@ -47805,7 +47852,7 @@ var zulipAdapter = (config2) => exports_Effect.gen(function* () {
         }
         return exports_Effect.die(new Error(`zulipAdapter: already bound to ${existing.acquiredName} — release() before acquiring ${name}`));
       },
-      onNone: () => acquireBot(name).pipe(exports_Effect.flatMap((minted) => exports_Effect.gen(function* () {
+      onNone: () => provideMintedFor(name).pipe(exports_Effect.flatMap((minted) => exports_Effect.gen(function* () {
         const innerHttp = yield* makeZulipHttp(buildHttpConfig(config2.realmUrl, minted.email, minted.apiKey, config2.hostHeader)).pipe(exports_Effect.provideService(exports_HttpClient.HttpClient, httpClient));
         const http = wrapBotHttp(innerHttp, recipientDirectory, minted.userId);
         const ident = {
@@ -47891,10 +47938,10 @@ var zulipAdapter = (config2) => exports_Effect.gen(function* () {
   }).pipe(exports_Effect.flatMap((res) => exports_Effect.gen(function* () {
     const map32 = new Map;
     for (const s of res.streams) {
-      map32.set(s.name, {
+      map32.set(s.name, decorateChannel({
         id: yield* decodeChannelId(String(s.stream_id)),
         name: yield* decodeChannelName(s.name)
-      });
+      }));
     }
     return map32;
   })));
@@ -47916,7 +47963,7 @@ var zulipAdapter = (config2) => exports_Effect.gen(function* () {
         to: effective.name,
         content: body,
         topic: thread === undefined ? "(no topic)" : thread.name
-      }).pipe(exports_Effect.flatMap((sent) => decodeMessageId(String(sent.id)).pipe(exports_Effect.map((id3) => thread === undefined ? { id: id3, channel: effective } : { id: id3, channel: effective, thread }))))))), exports_Effect.mapError((cause3) => cause3 instanceof UnknownChannel ? cause3 : new PublisherError({ operation: "post", cause: cause3 })));
+      }).pipe(exports_Effect.flatMap((sent) => decodeMessageId(String(sent.id)).pipe(exports_Effect.map((id3) => decorateMessageRef(id3, effective, thread?.name)))))))), exports_Effect.mapError((cause3) => cause3 instanceof UnknownChannel ? cause3 : new PublisherError({ operation: "post", cause: cause3 })));
     },
     edit: (message, body) => boundHttp().pipe(exports_Effect.flatMap((http) => http.patch(`/messages/${encodeURIComponent(message.id)}`, successSchema2, {
       content: body
@@ -48018,6 +48065,7 @@ var zulipAdapter = (config2) => exports_Effect.gen(function* () {
     }).pipe(exports_Effect.mapError((cause3) => new InboxError({ operation: "unsubscribe", cause: cause3 }))),
     events: () => exports_Stream.unwrap(exports_Effect.all([exports_SynchronizedRef.get(boundRef), exports_Ref.get(inboxRef)]).pipe(exports_Effect.map(([current2, state]) => inboxEvents({
       http: minterHttp,
+      permalinkBase: base,
       resolveDirectory: buildDirectoryLookup,
       mode: currentMode(state),
       messageRefCache,
@@ -48046,7 +48094,7 @@ var zulipAdapter = (config2) => exports_Effect.gen(function* () {
         exports_SynchronizedRef.get(boundRef)
       ], { concurrency: 2 }).pipe(exports_Effect.flatMap(([directory2, res, current2]) => exports_Effect.forEach(res.messages.filter((raw3) => raw3.timestamp >= since), (raw3) => {
         const { flags: _flags, ...message } = raw3;
-        return messageToInboundEvents(message, directory2, exports_Option.getOrUndefined(current2)?.identity);
+        return messageToInboundEvents(message, directory2, exports_Option.getOrUndefined(current2)?.identity, base);
       }).pipe(exports_Effect.map((perMessage) => {
         const out = [];
         for (const mapped of perMessage) {
@@ -48102,7 +48150,8 @@ var zulipAdapter = (config2) => exports_Effect.gen(function* () {
           return exports_Array.sort(threads, exports_Order.reverse(exports_Order.mapInput(exports_Order.number, (t) => t.lastPostTs)));
         })));
       }), exports_Effect.mapError((cause3) => new HistoryError({ operation: "recentThreads", cause: cause3 })));
-    }
+    },
+    messagePermalink: (id3, hint) => (hint === undefined ? fetchMessageRef(minterHttp, Number(id3), base).pipe(exports_Effect.map(exports_Option.flatMap((ref) => exports_Option.fromNullable(ref.permalink)))) : lookupChannel(hint.channel).pipe(exports_Effect.map(exports_Option.flatMap((channel) => exports_Option.fromNullable(buildMessageRef(base, id3, channel, hint.thread).permalink))))).pipe(exports_Effect.mapError((cause3) => new HistoryError({ operation: "messagePermalink", cause: cause3 })))
   };
   const reconcileMinter = () => reconcileMinterSubscriptions({
     listUnsubscribedPublicStreams: () => minterHttp.get("/streams", streamsListResponseSchema, {
@@ -55031,22 +55080,37 @@ var optionalBotName = (key) => optionalNonEmpty(key).pipe(exports_Config.mapOrFa
     onSome: (botName) => exports_Either.right(exports_Option.some(botName))
   })
 })));
+var optionalApiKey = (key) => {
+  const decode7 = exports_ParseResult.decodeUnknownEither(apiKeySchema);
+  return optionalNonEmpty(key).pipe(exports_Config.mapOrFail((option7) => exports_Option.match(option7, {
+    onNone: () => exports_Either.right(exports_Option.none()),
+    onSome: (raw3) => decode7(raw3).pipe(exports_Either.mapBoth({
+      onLeft: (issue2) => exports_ConfigError.InvalidData([key], exports_ParseResult.TreeFormatter.formatIssueSync(issue2)),
+      onRight: (value5) => exports_Option.some(exports_Redacted.make(value5))
+    }))
+  })));
+};
 var envConfig = exports_Config.all({
   realmUrl: requiredBrand("ZULIP_SITE", realmUrlSchema, (v) => v),
   minterEmail: requiredBrand("ZULIP_MINTER_EMAIL", botEmailSchema, (v) => v),
   minterApiKey: exports_Config.redacted(requiredBrand("ZULIP_MINTER_API_KEY", apiKeySchema, (v) => v)),
   botName: optionalBotName("COMMY_BOT_NAME"),
+  botApiKey: optionalApiKey("COMMY_BOT_API_KEY"),
   subscribe: optionalUserConfig("COMMY_SUBSCRIBE"),
   project: optionalNonEmpty("COMMY_PROJECT"),
   catchupWindowSeconds: optionalNonNegativeInt("COMMY_CATCHUP_WINDOW_SECONDS"),
   sessionId: optionalSessionId("CLAUDE_CODE_SESSION_ID")
-}).pipe(exports_Config.map((raw3) => {
+}).pipe(exports_Config.mapOrFail((raw3) => {
+  if (exports_Option.isSome(raw3.botApiKey) && exports_Option.isNone(raw3.botName)) {
+    return exports_Either.left(exports_ConfigError.InvalidData(["COMMY_BOT_API_KEY"], "COMMY_BOT_API_KEY requires COMMY_BOT_NAME — the key identifies which provisioned persona to attach to"));
+  }
   const project3 = exports_Option.flatMap(raw3.project, sanitiseProjectSlug);
-  return {
+  return exports_Either.right({
     realmUrl: raw3.realmUrl,
     minterEmail: raw3.minterEmail,
     minterApiKey: raw3.minterApiKey,
     ...exports_Option.match(raw3.botName, { onNone: () => ({}), onSome: (botName) => ({ botName }) }),
+    ...exports_Option.isSome(raw3.botName) && exports_Option.isSome(raw3.botApiKey) ? { attachIdentity: { name: raw3.botName.value, apiKey: raw3.botApiKey.value } } : {},
     ...exports_Option.match(raw3.subscribe, {
       onNone: () => ({}),
       onSome: (subscribe4) => ({ subscribe: subscribe4 })
@@ -55060,7 +55124,7 @@ var envConfig = exports_Config.all({
       onNone: () => ({}),
       onSome: (catchupWindowSeconds) => ({ catchupWindowSeconds })
     })
-  };
+  });
 }));
 var parseEnv = envConfig.pipe(exports_Effect.mapError((error2) => envConfigError(renderConfigError(error2))));
 var sanitiseProjectSlug = (raw3) => {
@@ -55121,7 +55185,8 @@ var ZulipAdapterLive = substrateAdapterLayer(exports_Effect.gen(function* () {
   return yield* zulipAdapter({
     realmUrl: parsed.realmUrl,
     minterEmail: parsed.minterEmail,
-    minterApiKey: parsed.minterApiKey
+    minterApiKey: parsed.minterApiKey,
+    ...parsed.attachIdentity === undefined ? {} : { attachIdentity: parsed.attachIdentity }
   });
 }));
 var subscribeFromEnv = (inbox, narrowSet, parsed) => {
@@ -55146,6 +55211,9 @@ var formatMessage = (event, botIdentityId) => {
     ["channel_name", ref.channel.name],
     ["thread", ref.thread?.name],
     ["message_id", ref.id],
+    ["permalink", ref.permalink],
+    ["channel_permalink", ref.channel.permalink],
+    ["thread_permalink", ref.thread?.permalink],
     ["sender_id", sender.id],
     ["sender_name", sender.name],
     ["sender_kind", sender.kind],
@@ -55164,6 +55232,7 @@ var formatReaction = (event, observedAt) => {
     ["target_message_id", event.target.id],
     ["target_channel_name", event.target.channel.name],
     ["target_thread", event.target.thread?.name],
+    ["target_permalink", event.target.permalink],
     ["reaction_emoji", event.emoji],
     ["reaction_action", action],
     ["by_id", event.by.id],
@@ -56898,7 +56967,7 @@ class Server extends Protocol {
 }
 
 // packages/mcp/mcp-server.ts
-var PLUGIN_VERSION = "0.12.0";
+var PLUGIN_VERSION = "0.14.0";
 var COMMY_INSTRUCTIONS = `**Canonical substrate.** commy is the inter-agent channel on this workstation. Where you also see \`claude-peers\`, \`agent-mail\`, or Discord MCP tools, prefer commy — claude-peers and Discord are retiring (comms-sxf); agent-mail is a mail-shaped substrate kept for specific flows. Don't fan the same message across substrates.
 
 **Channels.** Each project has one channel: \`#<project-slug>\` where the slug is resolved per session as \`COMMY_PROJECT\` env > git remote \`origin\` basename > git root basename. Sessions launched outside a git repo (e.g. \`/tmp\`, \`$HOME\`) have no project channel and should post to \`#general\` instead. Don't invent a channel name from a metaphor — never post to a literal \`#home\`, \`#project\`, or \`#<project>\`. Use \`list_channels\` to enumerate what actually exists in the realm; posting to a non-existent channel throws \`UnknownChannel\` rather than silently routing to Notification Bot.
@@ -56907,7 +56976,9 @@ var COMMY_INSTRUCTIONS = `**Canonical substrate.** commy is the inter-agent chan
 
 **Subscriptions.** Be on your project channel and \`#general\` only — not on other projects' channels. The workstation's boot-time defaults come from the plugin's \`COMMY_SUBSCRIBE\` userConfig (tokens: \`channel:<name>\`, \`thread:<channel>/<thread>\`, \`new-topics:<channel>\`, \`mentions\`); adjust the live set via \`subscribe\`/\`unsubscribe\` at runtime. Inbound matches arrive as \`<channel source="commy" ...>\` blocks. If one arrives from a channel you aren't subscribed to, treat it as background context and don't reply — only post into your project channel, into \`#general\`, or into threads you've explicitly joined. **Refer to peers by name** — the \`sender_name\` (and reaction \`by_name\`) in those blocks — never by a bare number; reserve numbers for message and bead ids, which otherwise collide with identity in a thread.
 
-**Tools.** \`post\` (channel; optionally thread or reply), \`react\`/\`unreact\` (emoji on a message), \`subscribe\`/\`unsubscribe\` (live target), \`read_channel\`/\`read_thread\` (history within a range), \`list_channels\` (enumerate channels in the realm), \`resolve\` (identity by name), \`current_identity\` (passive — never acquires), \`download_file\` (fetch a \`/user_uploads/...\` attachment to a temp file — use Read on the returned path to view images), \`upload_file\` (upload a local file by absolute path; returns a \`reference\` string to embed in a \`post\` body).
+**Links.** Every ref the substrate hands you carries a ready-to-click \`permalink\` — on \`post\` results, \`read_channel\`/\`read_thread\` messages (message \`permalink\` plus \`channel.permalink\` and \`thread.permalink\`), \`list_channels\` (channel \`permalink\`), and inbound \`<channel source="commy">\` frames (\`permalink\` / \`channel_permalink\` / \`thread_permalink\` meta, \`target_permalink\` on reaction frames). **Whenever you show a human a message, channel, or topic reference, render it as that clickable permalink — never a bare name or numeric id.** A human can click a permalink straight to the message; a bare \`#channel > topic\` or message number makes them hunt. When you hold only a message id (e.g. one cited elsewhere, with no permalink to hand), \`message_link(message_id, channel_name?, thread?)\` returns its \`{permalink}\`.
+
+**Tools.** \`post\` (channel; optionally thread or reply), \`react\`/\`unreact\` (emoji on a message), \`subscribe\`/\`unsubscribe\` (live target), \`read_channel\`/\`read_thread\` (history within a range), \`list_channels\` (enumerate channels in the realm), \`message_link\` (canonical permalink for a message id), \`resolve\` (identity by name), \`current_identity\` (passive — never acquires), \`download_file\` (fetch a \`/user_uploads/...\` attachment to a temp file — use Read on the returned path to view images), \`upload_file\` (upload a local file by absolute path; returns a \`reference\` string to embed in a \`post\` body).
 
 **session_id.** Pass your conversation's session id as the optional argument on \`post\`, \`edit_message\`, \`react\`, \`unreact\`, and \`current_identity\`. **Must be a UUID** (e.g. \`crypto.randomUUID()\`); anything else is rejected as malformed and the call routes to the "missing session_id" error rather than silently minting a \`cc-<garbage>\` identity (comms-uqf). In Claude Code the plugin's PreToolUse hook injects the harness session id automatically. The server uses it to derive the ephemeral \`cc-<8>\` bot identity for this conversation and to detect transitions between conversations.`;
 var buildMcpServer = () => new Server({ name: "commy", version: PLUGIN_VERSION }, {
@@ -57001,7 +57072,8 @@ var identityShape = (identity6) => ({
 });
 var channelShape = (channel) => ({
   id: channel.id,
-  name: channel.name
+  name: channel.name,
+  permalink: channel.permalink ?? null
 });
 var createCache = () => {
   const identityById = new Map;
@@ -57058,8 +57130,13 @@ var resolveMentions = (cache, mentionIds) => exports_Effect.forEach(mentionIds,
 }));
 var messageShape = (m) => ({
   id: m.ref.id,
-  channel: { id: m.ref.channel.id, name: m.ref.channel.name },
-  thread: m.ref.thread === undefined ? null : { name: m.ref.thread.name },
+  channel: {
+    id: m.ref.channel.id,
+    name: m.ref.channel.name,
+    permalink: m.ref.channel.permalink ?? null
+  },
+  thread: m.ref.thread === undefined ? null : { name: m.ref.thread.name, permalink: m.ref.thread.permalink ?? null },
+  permalink: m.ref.permalink ?? null,
   sender: identityShape(m.sender),
   body: m.body,
   ts: m.ts,
@@ -57124,6 +57201,11 @@ var ReadThreadArgs = exports_Schema.Struct({
   thread: exports_Schema.String,
   ...RangeArgs
 });
+var MessageLinkArgs = exports_Schema.Struct({
+  message_id: exports_Schema.String,
+  channel_name: exports_Schema.optional(exports_Schema.String),
+  thread: exports_Schema.optional(exports_Schema.String)
+});
 var PresenceArgs = exports_Schema.Struct({ identity_id: exports_Schema.String });
 var DownloadFileArgs = exports_Schema.Struct({ url_path: exports_Schema.String });
 var UploadFileArgs = exports_Schema.Struct({ path: exports_Schema.String });
@@ -57235,7 +57317,7 @@ var buildToolDefs = (deps, cache) => {
     },
     {
       name: "list_channels",
-      description: "List every channel the substrate is aware of, returning {id, name} for each. Use this for discovery instead of guessing channel names — posting to a non-existent channel throws UnknownChannel.",
+      description: "List every channel the substrate is aware of, returning {id, name, permalink} for each. Use this for discovery instead of guessing channel names — posting to a non-existent channel throws UnknownChannel. When you show a human a channel, link it by its permalink rather than a bare name.",
       inputSchema: emptyObjectSchema,
       handler: async () => {
         const channels = await runEdge(adapter4.directory.listChannels());
@@ -57246,7 +57328,7 @@ var buildToolDefs = (deps, cache) => {
     },
     {
       name: "post",
-      description: "Post a message to a channel by name. Optional thread (topic), mentions (identity ids the bot has seen), and reply_to (message id). To ping someone on Zulip, write the @**Name** markup inline in body where you want it rendered — the mentions array is notification metadata only and does NOT modify body. Returns {message_id, channel_id, channel_name, thread}.",
+      description: "Post a message to a channel by name. Optional thread (topic), mentions (identity ids the bot has seen), and reply_to (message id). To ping someone on Zulip, write the @**Name** markup inline in body where you want it rendered — the mentions array is notification metadata only and does NOT modify body. Returns {message_id, channel_id, channel_name, thread, permalink}. When you show a human this message afterwards, link it by the returned permalink — never a bare name or message id.",
       inputSchema: {
         type: "object",
         properties: {
@@ -57296,7 +57378,8 @@ var buildToolDefs = (deps, cache) => {
           message_id: ref.id,
           channel_id: ref.channel.id,
           channel_name: ref.channel.name,
-          thread: ref.thread === undefined ? null : { name: ref.thread.name }
+          thread: ref.thread === undefined ? null : { name: ref.thread.name },
+          permalink: ref.permalink ?? null
         };
       }
     },
@@ -57450,7 +57533,7 @@ var buildToolDefs = (deps, cache) => {
     },
     {
       name: "read_channel",
-      description: "Read recent messages from a channel by name. Returns {messages: Message[]} bounded by optional since/until/limit.",
+      description: "Read recent messages from a channel by name. Returns {messages: Message[]} bounded by optional since/until/limit. Each message carries a clickable permalink (and channel.permalink / thread.permalink) — when you cite one of these to a human, render it as that permalink, not a bare name or id.",
       inputSchema: {
         type: "object",
         properties: {
@@ -57475,7 +57558,7 @@ var buildToolDefs = (deps, cache) => {
     },
     {
       name: "read_thread",
-      description: "Read recent messages from a thread (topic) within a channel. Returns {messages: Message[]} bounded by optional since/until/limit.",
+      description: "Read recent messages from a thread (topic) within a channel. Returns {messages: Message[]} bounded by optional since/until/limit. Each message carries a clickable permalink (and channel.permalink / thread.permalink) — when you cite one of these to a human, render it as that permalink, not a bare name or id.",
       inputSchema: {
         type: "object",
         properties: {
@@ -57499,6 +57582,41 @@ var buildToolDefs = (deps, cache) => {
         return { messages: messages.map(messageShape) };
       }
     },
+    {
+      name: "message_link",
+      description: "Return the canonical clickable permalink for a message id: {permalink}. Use when you hold only an id (e.g. one cited elsewhere) and want the URL without re-deriving the narrow format — messages from post/read already carry a permalink. A message just posted or read is resolved from cache; otherwise pass channel_name (and thread) to build the link directly, or omit them to look the message up by id. Returns {permalink: null} when the message cannot be resolved.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          message_id: { type: "string", description: "Message id to link to" },
+          channel_name: {
+            type: "string",
+            description: "Channel the message lives in (lets the link be built without a lookup)"
+          },
+          thread: {
+            type: "string",
+            description: "Thread / topic the message lives in (sharpens the link to the topic)"
+          }
+        },
+        required: ["message_id"],
+        additionalProperties: false
+      },
+      handler: async (args2) => {
+        const permalink = await runEdge(exports_Effect.gen(function* () {
+          const parsed = yield* exports_Schema.decodeUnknown(MessageLinkArgs)(args2);
+          const id3 = yield* decodeMessageId(parsed.message_id);
+          const cached5 = cache.messageById.get(id3);
+          if (cached5?.permalink !== undefined)
+            return cached5.permalink;
+          const hint = parsed.channel_name === undefined ? undefined : {
+            channel: yield* decodeChannelName(parsed.channel_name),
+            ...parsed.thread === undefined ? {} : { thread: yield* decodeThreadName(parsed.thread) }
+          };
+          return exports_Option.getOrNull(yield* adapter4.history.messagePermalink(id3, hint));
+        }));
+        return { permalink };
+      }
+    },
     {
       name: "presence",
       description: "Return presence for the given identity id: online/idle/offline for humans, or 'unknown' for agents (bots have no presence concept — Zulip presence is human-only). Identity must already be cached via list_agents, list_humans, resolve, or current_identity — call one of those first when given a name.",