@grknbyk/agent-wire 0.13.2 → 0.13.4

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
 ```
 
@@ -254,15 +254,15 @@ Running `agent-wire` with no arguments shows where you stand:
 │ agent-hcm    ○ off     1 held              │
 │ agent-lab    ○ off     1 held              │
 ├────────────────── PEERS ───────────────────┤
-│ @ Zoë         * kai         * mira         │
-│ * warehouse-… * robin       ! nox          │
+│ + Zoë         @ kai         @ mira         │
+│ @ warehouse-… @ robin       ! nox          │
 ├────────────────── STATE ───────────────────┤
 │ workspace Acme       poll  14s ago         │
 └────────────────────────────────────────────┘
 ```
 
-The peers section lists everyone this agent has heard from: `*` for an agent,
-`@` for a human typing in the channel, `!` for a name that has been forged.
+The peers section lists everyone this agent has heard from: `@` for an agent,
+`+` for a human typing in the channel, `!` for a name that has been forged.
 Anything too wide for its column ends in `…`, so one long nickname costs its own
 row a character instead of pushing the border out.
 
@@ -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,23 @@ 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. `@` is the character you already type to call an agent,
+so it means the same thing in both places. People get `+` because Slack's
+markdown gives it no meaning, while `*` would open a bold run and `~` a struck
+one on a line the sender does not control.
+
+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.2",
+    "version": "0.13.4",
     "description": "Let AI coding agents message each other through a shared Slack channel, over MCP.",
     "type": "module",
     "license": "MIT",

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, channel: target.name });
+    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,
     });
@@ -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, channel: target.name }),
+        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,

package/src/protocol.mjs

@@ -68,8 +68,26 @@ 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}`;
+// @ is the character a person types to call an agent, so it means agent here too
+// and one name carries one meaning in both places. People get +, which Slack gives
+// no markdown meaning: * would open a bold run and ~ a struck one, on a line the
+// sender does not control.
+//
+// One name often belongs to both, the agent "sinan" and the colleague Sinan, and
+// saying which one a message went to is the whole point of the marker.
+//
+// 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`;
 
     // Shipped once without this: a call site forgot the channel, the handle went out
@@ -81,8 +99,10 @@ export function formatMessage({ mark, from, to, text, ref, channel }) {
     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}))?$/;
+// A sender is never marked now, but 0.13.3 marked it with a *, so the pattern
+// still allows one, and the recipient still accepts * for the same reason. Markers
+// are stripped rather than kept: routing reads the signed payload, not this line.
+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');
@@ -137,10 +157,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 } : {}),
         });

package/src/status.mjs

@@ -109,7 +109,8 @@ function unreadByChannel() {
 // reader already associates with a machine and a person, and `!` is the one that
 // stops the eye. All three are ASCII, so no terminal draws them double-width and
 // tips a row over its border.
-const peerMark = (peer) => (peer.everForged ? '!' : peer.kind === 'human' ? '@' : '*');
+// The same two the header uses: @ calls an agent, + is a person.
+const peerMark = (peer) => (peer.everForged ? '!' : peer.kind === 'human' ? '+' : '@');
 
 export function renderStatus(config) {
     const counts = unreadByChannel();