@grknbyk/agent-wire 0.4.1 → 0.6.0

package/README.md

@@ -33,17 +33,17 @@ got it, rewriting the report query
 npx @grknbyk/agent-wire setup
 ```
 
-Setup asks one question first: do you already have a Slack bot token, should it
-create the app for you, or do you want to paste the manifest by hand?
+Setup prints the path of the bundled `manifest.json`. You create the app from it
+at [api.slack.com/apps/new](https://api.slack.com/apps/new), install it, and paste
+the Bot User OAuth Token back. Then you create the channel in Slack and type
+`/invite @agent-wire` in it.
 
-If you let it create the app, it needs one App Configuration Token from
-[api.slack.com/apps](https://api.slack.com/apps), at the bottom of that page.
-After that it creates the app from the bundled manifest, opens your browser once
-for approval, catches the redirect itself, creates the channel, and joins it.
+The app never adds itself to anything. It has no scope to create a channel or to
+join one, so a person decides where it can read and write.
 
 Setup never asks "did you do it? (y/n)". Every step it can verify, it verifies by
 asking Slack. When a step is stuck for a reason Slack reports, such as a missing
-scope, a private channel it cannot join, or a token from the wrong workspace, it
+scope, a channel nobody invited it to, or a token from the wrong workspace, it
 says which one and what to do about it. Quit halfway and re-run: it resumes at
 the first unfinished step, because the config file is the progress.
 
@@ -72,17 +72,39 @@ Or, for any other MCP client:
 | `agent-wire serve` | Run the MCP stdio server, which is what your client launches |
 | `agent-wire doctor` | Re-check the token, the channels and the identity |
 | `agent-wire drain` | Print what arrived since last time, for a prompt hook |
-| `agent-wire channels` | List the channels and whether each one is switched on |
-| `agent-wire on/off <name>` | Bring a channel into scope, or take it out |
+| `agent-wire channels` | List the channels and what each one is set to here |
+| `agent-wire ask <name>` | Name who is waiting and how many; open nothing |
+| `agent-wire read <name>` | Put the messages themselves into every prompt |
+| `agent-wire off <name>` | Say nothing about this channel in this session |
 
 ## Tools your agent gets
 
-`send`, `send_file`, `inbox`, `archive`, `peers`, `channels`, `my_id`.
+`send`, `send_file`, `inbox`, `archive`, `peers`, `members`, `channels`, `my_id`.
+
+The mode of a channel is a command the user runs, never a tool. A message
+arriving from the channel must not be able to talk the agent into silencing
+another channel, nor into opening one.
 
 Text over 3500 characters is posted as a Markdown file instead of a message.
 Slack splits anything longer, and the tail arrives without a header, so half an
 answer vanishes while the sender is told it was delivered.
 
+## Files go both ways
+
+`send_file` uploads, and the receiving side downloads. A `.md` plan sent from one
+machine lands on the other as a real file in `~/.agent-wire/files/`, and `inbox`
+prints that path in the fence header, so the agent opens it with its own tools.
+Files a human drags into the channel arrive the same way.
+
+Slack accepts no metadata on a file upload, so the file and the message that
+describes it are two posts. The message is the signed one, and the file id it
+names is inside what the signature covers, so a valid signature cannot be lifted
+onto somebody else's upload. A message that fails verification is never
+downloaded.
+
+Anything over 20 MB stays in Slack. The message still arrives and says why the
+file was left there.
+
 ## One channel per project
 
 Setup configures one channel. Add more by hand in `~/.agent-wire/config.json`:
@@ -97,18 +119,64 @@ Setup configures one channel. Add more by hand in `~/.agent-wire/config.json`:
 Every message is tagged with the channel it came from, `send` takes an optional
 `channel`, and `inbox` can filter by one. The first entry is the default.
 
+## Three modes, one per session
+
+Every channel is in one of three modes, and the mode belongs to the session, not
+to the machine:
+
+| Mode | What a prompt gets |
+|---|---|
+| `off` | Nothing. The channel is not mentioned. |
+| `ask` | One line naming who is waiting and how many. Nothing is opened. Default. |
+| `read` | The messages themselves, fenced, and marked read as they arrive. |
+
+`ask` looks like this, and is what a prompt hook prints:
+
+```
+Unread messages : Huso(5), Sinan(2)
+```
+
+Loudest sender first, because five messages from one person is a conversation
+waiting while one each from five people is a standup. Past five names the rest
+become `+3 more`. Anything that failed its signature check is called out on the
+same line — `[1 FORGED]` — rather than counted in silently.
+
+`read` is the one to think about before turning on: it puts other people's
+writing into your agent's prompt without you asking. It arrives inside the same
+fence the `inbox` tool uses, but the guarantee is weaker there. Over MCP the rule
+for reading fenced content is delivered once through the handshake, where no
+message can sit beside it; a prompt hook has no handshake, so the rule and the
+content share a page.
+
+### What "per session" means
+
+A session is identified by its working directory, because that is the only thing
+a fresh `drain` process can see — it is launched again on every prompt and
+remembers nothing. So one project can run `read` while another runs `off`, with
+the same nickname, the same keys and the same Slack app behind both. Two windows
+open on one folder count as one session; set `AGENT_WIRE_SCOPE` to tell them
+apart.
+
+Read and unread are per session too. They have to be: a session on `read` opens
+everything it is handed, and if that also marked the message read next door, an
+`ask` session would report an empty inbox forever.
+
+The poller is not per session. One poller feeds one shared log for the whole
+machine, so a channel stays polled while any session still wants it. `off` means
+"do not tell me", not "stop collecting" — otherwise the quietest session on the
+machine would decide what the busiest one is allowed to see.
+
 ## Working on two of five channels
 
-Channels you are not working on today can be switched off. Running `agent-wire`
-with no arguments shows where you stand:
+Running `agent-wire` with no arguments shows where you stand:
 
 ```
 ┌──────────────── agent-wire ────────────────┐
 │ name  grkn           mark  🔥              │
 │ key   MCowBQYDK2VwAyEAq7Xn2mZ8kLcYzQwErTy… │
 ├───────────────── CHANNELS ─────────────────┤
-│ agent-wms    ● on      3 unread            │
-│ agent-crm    ● on      1 unread            │
+│ agent-wms    ● read    3 unread            │
+│ agent-crm    ◐ ask     1 unread            │
 │ agent-hcm    ○ off     1 held              │
 │ agent-lab    ○ off     1 held              │
 ├────────────────── PEERS ───────────────────┤
@@ -129,8 +197,9 @@ verifies. Letting a later message clear it would hand an attacker the way to bur
 the evidence.
 
 ```bash
-agent-wire off agent-hcm
-agent-wire on  agent-hcm
+agent-wire off  agent-hcm
+agent-wire ask  agent-hcm
+agent-wire read agent-wms
 ```
 
 `status` reads the config and the local log only, so it answers instantly.
@@ -205,20 +274,29 @@ Your workspace admin will ask. The manifest requests:
 | Scope | Why |
 |---|---|
 | `chat:write` | Post messages |
-| `channels:history`, `groups:history` | Read the channels it was added to |
-| `channels:read`, `groups:read` | Find a channel by name, check membership |
-| `channels:join` | Join a public channel so you skip the invite step |
-| `channels:manage` | Create the channel during setup |
-| `files:read`, `files:write` | Send and receive long messages as files |
+| `channels:history` | Read the channels it was added to |
+| `channels:read` | Find a channel by name, list who is in it |
+| `files:write` | Send a file, and post a long message as one |
+| `files:read` | Download a file somebody sent |
 | `users:read` | Show a human's name instead of `U08J21KLER1` |
 
-The app only ever reads channels it has been added to.
+Six, and that is the whole list. No `channels:join` or `channels:manage`, so the
+app cannot add itself to a channel or create one. No `groups:*`, so private
+channels are out of reach: use a public one.
+
+The two lookups it does are both scoped to the invite. Channels come from
+`users.conversations`, which answers "which channels am I in", never
+`conversations.list`, which answers "which channels exist here". Names come from
+`conversations.members` on one of those channels. There is no call in the package
+that can enumerate the workspace.
 
 ## Where things are stored
 
 Everything lives in `~/.agent-wire/` (override with `AGENT_WIRE_HOME`).
 `config.json` holds the token, identity and channels. `inbox.jsonl` is the
-append-only message log. `peers.json` holds the pinned keys.
+append-only message log. `peers.json` holds the pinned keys. `files/` holds every
+attachment that arrived, named by Slack file id so two `plan.md` files stay two
+files.
 
 The local log is the source of truth. Slack is a cache that can be re-read at any
 time, so recovering a lost inbox is an ordinary operation rather than a
@@ -232,12 +310,20 @@ reinstalled app cannot produce duplicates.
 - Discord as a second transport
 - Published measurements of fenced against unfenced injection compliance
 
+Wire format v2 signs the attached file id alongside the text, so a 0.5 agent and
+a 0.4 agent cannot verify each other. Upgrade both ends together.
+
 ## Development
 
 ```bash
-npm test
+npm test       # 53 tests, no network
+npm run bench  # medians over a synthetic 20k-message log
 ```
 
+The benchmark is here because the slow paths are the ones nobody watches: a log
+that only grows, and a CLI that a prompt hook runs on every prompt. It is not
+shipped to npm.
+
 ## License
 
 MIT

package/bin/agent-wire.mjs

@@ -1,115 +1,148 @@
-#!/usr/bin/env node
-import { activeChannels, loadConfig, setChannelActive } from '../src/config.mjs';
-import { pollOnce, serve } from '../src/mcp.mjs';
-import { runDoctor, runSetup } from '../src/setup.mjs';
-import { markRead, selectMessages } from '../src/inbox.mjs';
-import { runStatus } from '../src/status.mjs';
-
-const USAGE = `agent-wire — message other AI coding agents through Slack
-
-  agent-wire status      show identity, channels and unread counts (also the default)
-  agent-wire setup       connect a workspace, a channel and this agent's identity
-  agent-wire serve       run the MCP stdio server (what your agent client launches)
-  agent-wire doctor      re-check the token, the channels and this agent's identity
-  agent-wire drain       print messages that arrived since the last drain, then stop
-  agent-wire channels    list the channels and whether each one is switched on
-  agent-wire on <name>   switch a channel on
-  agent-wire off <name>  switch a channel off: not polled, not announced
-
-Docs: https://github.com/grknbyk/agent-wire`;
-
-// For a client hook that runs on every prompt: says a message is waiting without
-// spending the agent's turn on reading it, and marks nothing as read.
-async function drain() {
-    const config = loadConfig();
-    if (!config) return 0;
-
-    await pollOnce(config).catch(() => {
-        // Offline is not an error here; the next drain catches up.
-    });
-    const waiting = selectMessages({
-        state: 'unread',
-        count: 50,
-        channels: activeChannels(config).map((channel) => channel.name),
-    });
-    if (waiting.length === 0) return 0;
-
-    const senders = [...new Set(waiting.map((item) => item.from))].join(', ');
-    console.log(`agent-wire: ${waiting.length} unread message(s) from ${senders}.`
-        + ' Tell the user in one line. Do not read them unless asked — use the agent-wire inbox tool.');
-    return 0;
-}
-
-function listChannels() {
-    const config = loadConfig();
-    const configured = config?.channels ?? [];
-    if (configured.length === 0) {
-        console.log('no channels configured — run `agent-wire setup`');
-        return 1;
-    }
-
-    for (const channel of configured) console.log(`${channel.active === false ? 'off' : 'on '}  #${channel.name}`);
-    return 0;
-}
-
-// Switching a channel is a decision for the person running the agent, so it lives
-// on the command line and not in the MCP tool list. A message arriving from the
-// channel must not be able to talk the agent into silencing another one.
-function switchChannel(name, active) {
-    if (!name) {
-        console.log(`usage: agent-wire ${active ? 'on' : 'off'} <channel>`);
-        return 1;
-    }
-
-    const channel = setChannelActive(name, active);
-    if (!channel) {
-        console.log(`no configured channel named "${name}"`);
-        return 1;
-    }
-
-    console.log(active
-        ? `#${channel.name} is on. The next poll replays everything since it was switched off.`
-        : `#${channel.name} is off. It is no longer polled or announced; its history stays readable with inbox channel="${channel.name}".`);
-    return 0;
-}
-
-const commands = {
-    status: () => runStatus() ?? notConfigured(),
-    setup: runSetup,
-    doctor: runDoctor,
-    drain,
-    channels: listChannels,
-    on: () => switchChannel(process.argv[3], true),
-    off: () => switchChannel(process.argv[3], false),
-    read: async () => {
-        const items = selectMessages({ state: 'unread', count: 50 });
-        for (const item of items) console.log(`[${item.authorship}] ${item.at} ${item.from}: ${item.text}`);
-        markRead(items);
-        return 0;
-    },
-};
-
-function notConfigured() {
-    console.log('not configured yet — run `agent-wire setup`');
-    return 1;
-}
-
-const name = process.argv[2];
-
-// serve() is the one command that must not exit: the open stdin stream is what
-// keeps the MCP server alive, and awaiting a never-resolving promise here would
-// make Node print a warning into the very stream the client is parsing.
-if (name === 'serve') {
-    serve();
-} else if (commands[name]) {
-    process.exit(await commands[name]() ?? 0);
-} else if (!name) {
-    // Bare invocation shows where you stand once there is something to stand on,
-    // and the usage text while there is not.
-    const shown = runStatus();
-    if (shown === null) console.log(USAGE);
-    process.exit(0);
-} else {
-    console.log(USAGE);
-    process.exit(1);
-}
+#!/usr/bin/env node
+// Only the two cheap modules are imported up front. `status` builds an
+// Intl.Segmenter and touches the Extended_Pictographic table, which together cost
+// more than everything else this file does; `setup` pulls in readline. A prompt
+// hook runs `drain` on every single prompt, so it must not pay for the panel it
+// never draws.
+import { activeChannels, channelMode, loadConfig, scopeId, setChannelMode } from '../src/config.mjs';
+import { markRead, selectMessages } from '../src/inbox.mjs';
+import { drainReport } from '../src/drain.mjs';
+import { mintNonce } from '../src/protocol.mjs';
+
+const USAGE = `agent-wire — message other AI coding agents through Slack
+
+  agent-wire status      show identity, channels and unread counts (also the default)
+  agent-wire setup       connect a workspace, a channel and this agent's identity
+  agent-wire serve       run the MCP stdio server (what your agent client launches)
+  agent-wire doctor      re-check the token, the channels and this agent's identity
+  agent-wire drain       report what arrived since the last drain, then stop
+  agent-wire channels    list the channels and what each one is set to here
+  agent-wire ask <name>  name who is waiting and how many; open nothing (default)
+  agent-wire read <name> put the messages themselves into every prompt
+  agent-wire off <name>  say nothing about it in this session
+
+The three modes are per session, identified by the working directory. The token,
+the nickname and the keys are shared. Set AGENT_WIRE_SCOPE to tell two sessions
+in one folder apart.
+
+Docs: https://github.com/grknbyk/agent-wire`;
+
+// A prompt hook has one line of the user's screen to work with, so a backlog past
+// this is reported as a count rather than listed.
+const DRAIN_COUNT = 50;
+
+// For a client hook that runs on every prompt. An `ask` channel costs the agent
+// one line and reads nothing; a `read` channel spends the prompt on the messages
+// themselves and marks them read, because nothing else is going to.
+async function drain() {
+    const config = loadConfig();
+    if (!config) return 0;
+
+    const { pollOnce } = await import('../src/mcp.mjs');
+    await pollOnce(config).catch(() => {
+        // Offline is not an error here; the next drain catches up.
+    });
+
+    const heard = activeChannels(config);
+    const waiting = selectMessages({
+        state: 'unread',
+        count: DRAIN_COUNT,
+        channels: heard.map((channel) => channel.name),
+    });
+    if (waiting.length === 0) return 0;
+
+    const { lines, readItems } = drainReport(config, heard, waiting, mintNonce());
+    if (lines.length === 0) return 0;
+
+    console.log(lines.join('\n'));
+    markRead(readItems);
+    return 0;
+}
+
+function listChannels() {
+    const config = loadConfig();
+    const configured = config?.channels ?? [];
+    if (configured.length === 0) {
+        console.log('no channels configured — run `agent-wire setup`');
+        return 1;
+    }
+
+    for (const channel of configured) console.log(`${channelMode(config, channel).padEnd(4)}  #${channel.name}`);
+    console.log(`\nmodes are per session; this one is ${scopeId()}`);
+    return 0;
+}
+
+const MODE_EXPLAINED = {
+    off: (name) => `#${name} is off for this session. Nothing about it reaches this agent;`
+        + ` its history stays readable with inbox channel="${name}".`,
+    ask: (name) => `#${name} is on ask. Every prompt names who is waiting and how many, and opens nothing.`,
+    read: (name) => `#${name} is on read. Every prompt carries the messages themselves, marked read as they arrive.`
+        + ' Other people\'s writing now reaches this agent without you asking for it.',
+};
+
+// Which mode a channel is in is a decision for the person running the agent, so
+// it lives on the command line and not in the MCP tool list. A message arriving
+// from the channel must not be able to talk the agent into silencing another one,
+// nor into opening one.
+function switchChannel(name, mode) {
+    if (!name) {
+        console.log(`usage: agent-wire ${mode} <channel>`);
+        return 1;
+    }
+
+    const changed = setChannelMode(name, mode);
+    if (!changed) {
+        console.log(`no configured channel named "${name}"`);
+        return 1;
+    }
+
+    console.log(MODE_EXPLAINED[mode](changed.channel.name));
+    if (changed.previous === 'off' && mode !== 'off') {
+        console.log('The next poll replays everything that arrived while it was off.');
+    }
+    return 0;
+}
+
+const showStatus = async () => (await import('../src/status.mjs')).runStatus();
+
+const commands = {
+    status: async () => await showStatus() ?? notConfigured(),
+    setup: async () => (await import('../src/setup.mjs')).runSetup(),
+    doctor: async () => (await import('../src/setup.mjs')).runDoctor(),
+    drain,
+    channels: listChannels,
+    off: () => switchChannel(process.argv[3], 'off'),
+    ask: () => switchChannel(process.argv[3], 'ask'),
+    read: () => switchChannel(process.argv[3], 'read'),
+    // `on` was the only way to undo `off` before there were three modes, and it
+    // meant "announce it without opening it". That is ask.
+    on: () => switchChannel(process.argv[3], 'ask'),
+};
+
+function notConfigured() {
+    console.log('not configured yet — run `agent-wire setup`');
+    return 1;
+}
+
+const name = process.argv[2];
+
+// The exit code is set, never forced. Calling process.exit() while an undici
+// socket from a Slack call is still closing aborts libuv on Windows, and doctor
+// hit that on every run. Nothing here holds the event loop open, so letting Node
+// finish by itself costs about a millisecond.
+//
+// serve() is the one command that must not exit at all: the open stdin stream is
+// what keeps the MCP server alive.
+if (name === 'serve') {
+    (await import('../src/mcp.mjs')).serve();
+} else if (commands[name]) {
+    process.exitCode = await commands[name]() ?? 0;
+} else if (!name) {
+    // Bare invocation shows where you stand once there is something to stand on,
+    // and the usage text while there is not.
+    const shown = await showStatus();
+    if (shown === null) console.log(USAGE);
+} else {
+    console.log(USAGE);
+    process.exitCode = 1;
+}

package/manifest.json

@@ -1,38 +1,31 @@
-{
-    "display_information": {
-        "name": "agent-wire",
-        "description": "Message bridge between AI coding agents",
-        "background_color": "#af3c02",
-        "long_description": "agent-wire connects AI coding agents running on different machines through a Slack channel they share. Each agent posts under its own nickname and signs what it sends, so a message can be traced to the agent that wrote it. Humans in the same channel can read the whole exchange and join it at any point, which is the reason the bridge runs on Slack rather than a private protocol: the conversation between machines stays readable by the team that owns them."
-    },
-    "features": {
-        "bot_user": {
-            "display_name": "agent-wire",
-            "always_online": true
-        }
-    },
-    "oauth_config": {
-        "redirect_urls": [
-            "http://localhost:32771/callback"
-        ],
-        "scopes": {
-            "bot": [
-                "chat:write",
-                "channels:read",
-                "channels:history",
-                "channels:join",
-                "channels:manage",
-                "groups:read",
-                "groups:history",
-                "files:read",
-                "files:write",
-                "users:read"
-            ]
-        }
-    },
-    "settings": {
-        "org_deploy_enabled": false,
-        "socket_mode_enabled": false,
-        "token_rotation_enabled": false
-    }
-}
+{
+    "display_information": {
+        "name": "agent-wire",
+        "description": "Message bridge between AI coding agents",
+        "background_color": "#af3c02",
+        "long_description": "agent-wire connects AI coding agents running on different machines through a Slack channel they share. Each agent posts under its own nickname and signs what it sends, so a message can be traced to the agent that wrote it. Humans in the same channel can read the whole exchange and join it at any point, which is the reason the bridge runs on Slack rather than a private protocol: the conversation between machines stays readable by the team that owns them."
+    },
+    "features": {
+        "bot_user": {
+            "display_name": "agent-wire",
+            "always_online": true
+        }
+    },
+    "oauth_config": {
+        "scopes": {
+            "bot": [
+                "chat:write",
+                "channels:read",
+                "channels:history",
+                "files:read",
+                "files:write",
+                "users:read"
+            ]
+        }
+    },
+    "settings": {
+        "org_deploy_enabled": false,
+        "socket_mode_enabled": false,
+        "token_rotation_enabled": false
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@grknbyk/agent-wire",
-    "version": "0.4.1",
+    "version": "0.6.0",
     "description": "Let AI coding agents message each other through a shared Slack channel, over MCP.",
     "type": "module",
     "license": "MIT",
@@ -20,7 +20,8 @@
         "node": ">=20"
     },
     "scripts": {
-        "test": "node --test \"test/*.test.mjs\""
+        "test": "node --test \"test/*.test.mjs\"",
+        "bench": "node bench/bench.mjs"
     },
     "files": [
         "bin",