@grknbyk/agent-wire 0.13.1 → 0.13.3

package/README.md

@@ -20,10 +20,10 @@ produces a conversation nobody can audit. In a channel, the humans who own those
 agents read the whole exchange, scroll back through it, and step in by typing.
 
 ```
-🔥 grkn => mira
+🔥 grkn => *mira
 migration 0042 is on dev now, txn_date is a DATE not a TIMESTAMP
 
-⚡ mira => grkn
+⚡ mira => *grkn
 got it, rewriting the report query
 ```
 
@@ -398,8 +398,9 @@ do with it:
 | `nobody` | A human wrote without naming any agent | Read it as context, stay quiet |
 
 Slack has no real mention for an agent, so `@grkn` is ordinary text that
-agent-wire looks for itself. The match is literal and case-insensitive, and it
-stops at a word boundary, so `@grkn` does not fire for `@grknbyk`.
+agent-wire looks for itself. `*grkn` calls it too, since that is the marker the
+header uses. The match is literal and case-insensitive, and it stops at a word
+boundary, so neither form fires for `@grknbyk`.
 
 Nothing is filtered by this. Every message still arrives, still goes in the
 inbox, and is still readable. It only decides who speaks first. Your own
@@ -411,11 +412,18 @@ Every message carries a handle at the right edge of its header line, padded to
 column 60 so a scrolled channel has one straight edge to read down:
 
 ```
-🔥 grkn => sinan                           wms-agents@k7m2pq
-🚀 hakan-akduman => all                    wms-agents@zpbxdf
-🛰️ mehmet-emin-kaya => hakan-akduman       wms-agents@8g88zm
+🔥 grkn => *sinan                          wms-agents@k7m2pq
+🚀 hakan-akduman => @Sinan                 wms-agents@zpbxdf
+🛰️ mehmet-emin-kaya => all                 wms-agents@8g88zm
 ```
 
+The recipient carries the same two markers the status panel uses: `*` for an
+agent, `@` for a person. One name often belongs to both, the agent `sinan` and
+the colleague Sinan, and without the marker you cannot tell which one a line was
+addressed to. A name that is neither a pinned agent nor a resolved Slack user
+stays bare, because a marker there would be a guess. The sender is never marked:
+every one of these lines was written by an agent.
+
 To point your agent at one line you scrolled past, say "wms-agents@k7m2pq oku".
 It fetches that message whatever channel it came from and whether it was already
 read, which saves copying a Slack timestamp.

package/bin/agent-wire.mjs

@@ -22,6 +22,7 @@ const USAGE = `agent-wire — message other AI coding agents through Slack
   agent-wire off <name>  say nothing about it in this session
   agent-wire version     print the installed version, which is what a bug report needs
   agent-wire update      install the newest published version, cache and all
+  agent-wire help        print this
 
 The three modes belong to one session, identified by the client's session id when
 it publishes one and by the working directory otherwise. The token, the nickname
@@ -201,8 +202,18 @@ const commands = {
     version: showVersion,
     '--version': showVersion,
     '-v': showVersion,
+    // Asking for the usage text is not a mistake, so it prints and exits 0. The
+    // same text after a wrong command is a complaint and exits 1.
+    help: showUsage,
+    '--help': showUsage,
+    '-h': showUsage,
 };
 
+function showUsage() {
+    console.log(USAGE);
+    return 0;
+}
+
 function notConfigured() {
     console.log('not configured yet — run `agent-wire setup`');
     return 1;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@grknbyk/agent-wire",
-    "version": "0.13.1",
+    "version": "0.13.3",
     "description": "Let AI coding agents message each other through a shared Slack channel, over MCP.",
     "type": "module",
     "license": "MIT",

package/src/inbox.mjs

@@ -160,9 +160,13 @@ export const findByTs = (ts) => readInbox().find((item) => item.ts === ts) ?? nu
 
 // Newest first: a ref is short enough to collide eventually, and the one a person
 // just read off the channel is the recent one.
-export const findByRef = (ref) => readInbox()
-    .filter((item) => item.ref === String(ref).replace(/^@/, '').toLowerCase())
-    .at(-1) ?? null;
+export function findByRef(handle) {
+    const [channel, ref] = String(handle).toLowerCase().split('@');
+    const wanted = ref ?? channel;
+    return readInbox()
+        .filter((item) => item.ref === wanted && (!ref || !channel || item.channel === channel))
+        .at(-1) ?? null;
+}
 
 export const readCursor = (channelId) => readJsonCached(paths.cursors, {})[channelId] ?? null;
 

package/src/mcp.mjs

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'node:url';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 
-import { MODES, activeChannels, channelMode, findChannel, loadConfig, paths, pollableChannels, scopeId } from './config.mjs';
+import { MODES, activeChannels, channelMode, findChannel, loadConfig, paths, pollableChannels, readJson, scopeId } from './config.mjs';
 import { DEFAULT_COUNT, appendMessages, archive, findByRef, findByTs, markRead, readCursor, selectMessages, writeCursor } from './inbox.mjs';
 import { FINGERPRINT_CHARS, listPeers, signMessage } from './identity.mjs';
 import { refusalFor } from './manners.mjs';
@@ -249,6 +249,21 @@ function chainOf(replyTo) {
     return { conv: parent.conv ?? parent.ts, hop: (Number(parent.hop) || 1) + 1 };
 }
 
+// A name is an agent once a key has been pinned to it, a human once Slack has
+// resolved it under that name, and unmarked while it is neither. The agent
+// "sinan" and the person Sinan share a name here, so the header has to say which
+// one a message was addressed to.
+function recipientKind(config, to) {
+    if (to === 'all') return 'all';
+
+    const wanted = String(to).toLowerCase();
+    if (wanted === String(config.nickname).toLowerCase()) return 'agent';
+    if (listPeers().some((peer) => peer.name.toLowerCase() === wanted)) return 'agent';
+
+    const humans = Object.values(readJson(paths.users, {}));
+    return humans.some((name) => String(name).toLowerCase() === wanted) ? 'human' : 'unknown';
+}
+
 async function sendText(config, { to, text, channel, replyTo }) {
     const target = findChannel(config, channel);
     if (!target) return `no such channel: ${channel ?? '(none configured)'}`;
@@ -262,7 +277,9 @@ async function sendText(config, { to, text, channel, replyTo }) {
 
     const client = slackClient(config.bot_token);
     const ref = mintRef();
-    const rendered = formatMessage({ mark: config.mark, from: config.nickname, to, text, ref });
+    const rendered = formatMessage({
+        mark: config.mark, from: config.nickname, to, toKind: recipientKind(config, to), text, ref, channel: target.name,
+    });
     const signature = signMessage(config.private_key, {
         channel: target.id, from: config.nickname, to, conv: chain.conv, hop: chain.hop, text,
     });
@@ -279,7 +296,7 @@ async function sendText(config, { to, text, channel, replyTo }) {
     if (!posted.ok) return `Slack rejected it (${posted.reason})`;
 
     recordOwnMessage(config, { ts: posted.ts, target, to, text, chain, ref });
-    return `delivered to ${to} in #${target.name} as @${ref}`;
+    return `delivered to ${to} in #${target.name} as ${target.name}@${ref}`;
 }
 
 // Our own sent messages go into the local log too, so the log is a complete
@@ -319,7 +336,9 @@ async function postFile(config, { to, path, note, target, chain, logText }) {
     });
     const posted = await postMessage(client, {
         channel: target.id,
-        rendered: formatMessage({ mark: config.mark, from: config.nickname, to, text, ref }),
+        rendered: formatMessage({
+            mark: config.mark, from: config.nickname, to, toKind: recipientKind(config, to), text, ref, channel: target.name,
+        }),
         signature,
         publicKey: config.public_key,
         from: config.nickname,
@@ -351,7 +370,7 @@ async function sendLongText(config, { to, text, target, chain }) {
     unlinkSync(path);
     if (!result.ok) return result.message;
 
-    return `delivered to ${to} in #${result.channelName} as @${result.ref} — ${text.length} characters, sent as a file`;
+    return `delivered to ${to} in #${result.channelName} as ${result.channelName}@${result.ref} — ${text.length} characters, sent as a file`;
 }
 
 async function call(name, args, session) {
@@ -454,7 +473,7 @@ async function call(name, args, session) {
         });
         if (!result.ok) return result.message;
 
-        return `sent ${result.name} to ${args.to} in #${result.channelName} as @${result.ref}`;
+        return `sent ${result.name} to ${args.to} in #${result.channelName} as ${result.channelName}@${result.ref}`;
     }
 
     if (name === 'archive') return `archived ${archive(args.ts)} message(s)`;

package/src/protocol.mjs

@@ -68,17 +68,38 @@ export function displayWidth(text) {
 // one line costs less than losing a character of somebody's name.
 export const HEADER_WIDTH = 60;
 
-export function formatMessage({ mark, from, to, text, ref, channel }) {
-    const left = `${mark ? `${mark} ` : ''}${from} => ${to}`;
+// The status panel already reads * for an agent and @ for a human, so the header
+// borrows the same two characters rather than inventing a third vocabulary. One
+// name can belong to both (the agent "sinan" and the person Sinan), and the whole
+// point of the marker is that the header says which one a message went to.
+//
+// Only the recipient is marked. Every header line was written by an agent, so a
+// marker on the sender would have been the one field that can never vary.
+//
+// A name nobody has placed stays bare. Guessing "human" for an unknown recipient
+// would put the marker on exactly the messages it is least sure about.
+const RECIPIENT_MARK = { agent: '*', human: '@' };
+
+export const addressLine = ({ from, to, toKind }) =>
+    `${from} => ${to === 'all' ? 'all' : `${RECIPIENT_MARK[toKind] ?? ''}${to}`}`;
+
+export function formatMessage({ mark, from, to, toKind, text, ref, channel }) {
+    const left = `${mark ? `${mark} ` : ''}${addressLine({ from, to, toKind })}`;
     if (!ref) return `${left}\n${toSlackText(text)}\n`;
 
-    const handle = `${channel ?? ''}@${ref}`;
+    // Shipped once without this: a call site forgot the channel, the handle went out
+    // bare, and every test still passed because they all called this directly.
+    if (!channel) throw new TypeError(`formatMessage: ref ${ref} with no channel to put in front of it`);
+
+    const handle = `${channel}@${ref}`;
     const gap = Math.max(1, HEADER_WIDTH - displayWidth(left) - handle.length);
     return `${left}${' '.repeat(gap)}${handle}\n${toSlackText(text)}\n`;
 }
 
-// Rejects "*" as a sender so a bold-wrapped line cannot file a message under "*".
-const HEADER = /^(?:(?<mark>\S+)\s+)?(?<from>[^\s=*]+)\s*=>\s*(?<to>\S+?)(?:\s+(?<refChannel>[a-z0-9][\w.-]*)?@(?<ref>[a-z2-9]{4,12}))?$/;
+// The leading * on a sender is ours; a *bold* line is not, which is why the name
+// after it still cannot contain one. The recipient's own marker is stripped by the
+// pattern rather than kept, because the payload is what routing reads.
+const HEADER = /^(?:(?<mark>\S+)\s+)?\*?(?<from>[^\s=*]+)\s*=>\s*[@*]?(?<to>\S+?)(?:\s+(?<refChannel>[a-z0-9][\w.-]*)?@(?<ref>[a-z2-9]{4,12}))?$/;
 
 export function parseMessage(raw) {
     const lines = fromSlackText(String(raw ?? '').replace(/\r\n/g, '\n')).trim().split('\n');
@@ -133,10 +154,12 @@ export function addressee(item, myNickname) {
     }
 
     const text = String(item.text).toLowerCase();
-    const tag = `@${myNickname.toLowerCase()}`;
-    for (let at = text.indexOf(tag); at !== -1; at = text.indexOf(tag, at + 1)) {
-        const after = text[at + tag.length];
-        if (after === undefined || !CONTINUES.test(after)) return 'you';
+    for (const prefix of ['@', '*']) {
+        const tag = `${prefix}${myNickname.toLowerCase()}`;
+        for (let at = text.indexOf(tag); at !== -1; at = text.indexOf(tag, at + 1)) {
+            const after = text[at + tag.length];
+            if (after === undefined || !CONTINUES.test(after)) return 'you';
+        }
     }
     return 'nobody';
 }

package/src/slack.mjs

@@ -317,6 +317,11 @@ export async function pollChannel(client, channel, { since, myNickname }) {
         const history = await client.form('conversations.history', {
             channel: channel.id,
             limit: PAGE_LIMIT,
+            // Without this Slack returns no metadata at all, so every message
+            // another agent signed arrives looking like a bare bot post and is
+            // dropped two lines below. Humans were unaffected, which is why the
+            // log looked healthy while no peer was ever seen.
+            include_all_metadata: true,
             ...(since ? { oldest: since } : {}),
             ...(cursor ? { cursor } : {}),
         });