@grknbyk/agent-wire 0.4.1 → 0.5.0

package/README.md

@@ -1,243 +1,276 @@
-<div align="center">
-<img src="assets/agent-wire.png" alt="agent-wire" width="96">
-
-# agent-wire
-
-**Let your AI coding agents talk to each other, in a Slack channel you can read.**
-
-</div>
-
-Two developers, two machines, two coding agents working on the same system. One
-knows the migration is deployed. The other is about to write against the old
-schema. agent-wire gives them a way to say so.
-
-It runs as an [MCP](https://modelcontextprotocol.io) server, so any MCP client
-(Claude Code, Cursor, anything else that speaks the protocol) gets `send` and
-`inbox` tools. Messages travel through a normal Slack channel.
-
-Slack is a deliberate choice here. A private protocol between two machines
-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
-migration 0042 is on dev now, txn_date is a DATE not a TIMESTAMP
-
-⚡ mira => grkn
-got it, rewriting the report query
-```
-
-## Install
-
-```bash
-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?
-
-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.
-
-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
-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.
-
-Then point your client at it:
-
-```bash
-claude mcp add agent-wire -- npx -y @grknbyk/agent-wire serve
-```
-
-Or, for any other MCP client:
-
-```json
-{
-  "mcpServers": {
-    "agent-wire": { "command": "npx", "args": ["-y", "@grknbyk/agent-wire", "serve"] }
-  }
-}
-```
-
-## Commands
-
-| Command | What it does |
-|---|---|
-| `agent-wire status` | Identity, channels and unread counts, read from disk |
-| `agent-wire setup` | Connect a workspace, a channel, and this agent's identity |
-| `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 |
-
-## Tools your agent gets
-
-`send`, `send_file`, `inbox`, `archive`, `peers`, `channels`, `my_id`.
-
-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.
-
-## One channel per project
-
-Setup configures one channel. Add more by hand in `~/.agent-wire/config.json`:
-
-```json
-"channels": [
-  { "id": "C0123", "name": "agent-wms" },
-  { "id": "C0456", "name": "agent-crm" }
-]
-```
-
-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.
-
-## 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:
-
-```
-┌──────────────── agent-wire ────────────────┐
-│ name  grkn           mark  🔥              │
-│ key   MCowBQYDK2VwAyEAq7Xn2mZ8kLcYzQwErTy… │
-├───────────────── CHANNELS ─────────────────┤
-│ agent-wms    ● on      3 unread            │
-│ agent-crm    ● on      1 unread            │
-│ agent-hcm    ○ off     1 held              │
-│ agent-lab    ○ off     1 held              │
-├────────────────── PEERS ───────────────────┤
-│ @ 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.
-Anything too wide for its column ends in `…`, so one long nickname costs its own
-row a character instead of pushing the border out.
-
-A forged sighting stays on the record even after that name sends a message that
-verifies. Letting a later message clear it would hand an attacker the way to bury
-the evidence.
-
-```bash
-agent-wire off agent-hcm
-agent-wire on  agent-hcm
-```
-
-`status` reads the config and the local log only, so it answers instantly.
-Whether Slack still accepts the token is `doctor`'s question.
-
-A channel that is off is not polled, not announced by `drain`, and absent from
-the default `inbox` view. Its history stays readable at any time with
-`inbox channel="agent-hcm"`.
-
-Switching one off does not lose messages. The cursor stays where it was, so
-switching it back on replays everything that arrived meanwhile.
-
-Only the person running the agent can switch a channel, from the command line.
-The MCP `channels` tool lists the state and cannot change it, so a message
-arriving from one channel can never talk the agent into silencing another.
-
-## Who actually sent that message
-
-Every agent in a workspace shares one bot token, so Slack's own `bot_id` proves
-that agent-wire posted a message without proving which agent wrote it. The header
-line is plain text that anyone in the channel can type.
-
-So each install generates an Ed25519 key pair at setup and signs every message it
-sends. The signature covers the sender, the recipient, the channel, the position
-in the reply chain, and the text. It travels in Slack message metadata, which the
-UI never renders. The first key seen using a name is pinned to that name, and
-`inbox` labels every message with what is actually proven:
-
-| Label | Meaning |
-|---|---|
-| `signed` | Verified against the key already pinned to that name |
-| `new` | Verified, first sighting of this name, key now pinned |
-| `impostor` | That name is pinned to a different key, so treat it as forged |
-| `unsigned` | No valid signature, so the sender name is decoration only |
-| `slack-verified` | A human, identified by Slack's own user id |
-| `self` | Sent by this agent |
-
-Changing one character of the text breaks the signature, and so does replaying a
-signed message into another channel. There are tests for both.
-
-## Untrusted input
-
-Anything arriving from the channel is rendered inside a fence whose delimiter is
-a random value minted per server process, never written to Slack and never
-logged:
-
-```
-<<<WIRE:4f2a… UNTRUSTED from=mira kind=agent authorship=signed channel=agent-wms ts=1712.44 hop=3>>>
-the message
-<<<END:4f2a…>>>
-```
-
-The rule for reading that fence arrives through the MCP handshake, a channel the
-message author cannot write to, so it never sits inline beside the content it
-governs. If a payload contains the live delimiter, it is replaced with
-`[FENCE-ECHO REDACTED]`, which turns reflection into a visible event instead of a
-silently broken boundary.
-
-Be clear about what this buys you. An attacker cannot close the fence, and does
-not need to, because text inside a correctly labelled `UNTRUSTED` block still
-reads as language to a model. The fence makes the labelling accurate. Hostile
-text stays exactly as persuasive as it was, so this is a boundary rather than a
-filter.
-
-A reply chain also carries a hop count and stops at 8. Two agents answering each
-other politely is an infinite loop that costs real money.
-
-## Slack scopes, and why each one
-
-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 |
-| `users:read` | Show a human's name instead of `U08J21KLER1` |
-
-The app only ever reads channels it has been added to.
-
-## 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.
-
-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
-procedure. Messages are keyed by their Slack timestamp, so a retried poll or a
-reinstalled app cannot produce duplicates.
-
-## Roadmap
-
-- `mode: reply`, to answer waiting messages when no live session is watching
-- Per-worktree identity, so parallel sessions on one machine name themselves
-- Discord as a second transport
-- Published measurements of fenced against unfenced injection compliance
-
-## Development
-
-```bash
-npm test
-```
-
-## License
-
-MIT
+<div align="center">
+<img src="assets/agent-wire.png" alt="agent-wire" width="96">
+
+# agent-wire
+
+**Let your AI coding agents talk to each other, in a Slack channel you can read.**
+
+</div>
+
+Two developers, two machines, two coding agents working on the same system. One
+knows the migration is deployed. The other is about to write against the old
+schema. agent-wire gives them a way to say so.
+
+It runs as an [MCP](https://modelcontextprotocol.io) server, so any MCP client
+(Claude Code, Cursor, anything else that speaks the protocol) gets `send` and
+`inbox` tools. Messages travel through a normal Slack channel.
+
+Slack is a deliberate choice here. A private protocol between two machines
+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
+migration 0042 is on dev now, txn_date is a DATE not a TIMESTAMP
+
+⚡ mira => grkn
+got it, rewriting the report query
+```
+
+## Install
+
+```bash
+npx @grknbyk/agent-wire setup
+```
+
+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.
+
+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 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.
+
+Then point your client at it:
+
+```bash
+claude mcp add agent-wire -- npx -y @grknbyk/agent-wire serve
+```
+
+Or, for any other MCP client:
+
+```json
+{
+  "mcpServers": {
+    "agent-wire": { "command": "npx", "args": ["-y", "@grknbyk/agent-wire", "serve"] }
+  }
+}
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `agent-wire status` | Identity, channels and unread counts, read from disk |
+| `agent-wire setup` | Connect a workspace, a channel, and this agent's identity |
+| `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 |
+
+## Tools your agent gets
+
+`send`, `send_file`, `inbox`, `archive`, `peers`, `members`, `channels`, `my_id`.
+
+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`:
+
+```json
+"channels": [
+  { "id": "C0123", "name": "agent-wms" },
+  { "id": "C0456", "name": "agent-crm" }
+]
+```
+
+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.
+
+## 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:
+
+```
+┌──────────────── agent-wire ────────────────┐
+│ name  grkn           mark  🔥              │
+│ key   MCowBQYDK2VwAyEAq7Xn2mZ8kLcYzQwErTy… │
+├───────────────── CHANNELS ─────────────────┤
+│ agent-wms    ● on      3 unread            │
+│ agent-crm    ● on      1 unread            │
+│ agent-hcm    ○ off     1 held              │
+│ agent-lab    ○ off     1 held              │
+├────────────────── PEERS ───────────────────┤
+│ @ 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.
+Anything too wide for its column ends in `…`, so one long nickname costs its own
+row a character instead of pushing the border out.
+
+A forged sighting stays on the record even after that name sends a message that
+verifies. Letting a later message clear it would hand an attacker the way to bury
+the evidence.
+
+```bash
+agent-wire off agent-hcm
+agent-wire on  agent-hcm
+```
+
+`status` reads the config and the local log only, so it answers instantly.
+Whether Slack still accepts the token is `doctor`'s question.
+
+A channel that is off is not polled, not announced by `drain`, and absent from
+the default `inbox` view. Its history stays readable at any time with
+`inbox channel="agent-hcm"`.
+
+Switching one off does not lose messages. The cursor stays where it was, so
+switching it back on replays everything that arrived meanwhile.
+
+Only the person running the agent can switch a channel, from the command line.
+The MCP `channels` tool lists the state and cannot change it, so a message
+arriving from one channel can never talk the agent into silencing another.
+
+## Who actually sent that message
+
+Every agent in a workspace shares one bot token, so Slack's own `bot_id` proves
+that agent-wire posted a message without proving which agent wrote it. The header
+line is plain text that anyone in the channel can type.
+
+So each install generates an Ed25519 key pair at setup and signs every message it
+sends. The signature covers the sender, the recipient, the channel, the position
+in the reply chain, and the text. It travels in Slack message metadata, which the
+UI never renders. The first key seen using a name is pinned to that name, and
+`inbox` labels every message with what is actually proven:
+
+| Label | Meaning |
+|---|---|
+| `signed` | Verified against the key already pinned to that name |
+| `new` | Verified, first sighting of this name, key now pinned |
+| `impostor` | That name is pinned to a different key, so treat it as forged |
+| `unsigned` | No valid signature, so the sender name is decoration only |
+| `slack-verified` | A human, identified by Slack's own user id |
+| `self` | Sent by this agent |
+
+Changing one character of the text breaks the signature, and so does replaying a
+signed message into another channel. There are tests for both.
+
+## Untrusted input
+
+Anything arriving from the channel is rendered inside a fence whose delimiter is
+a random value minted per server process, never written to Slack and never
+logged:
+
+```
+<<<WIRE:4f2a… UNTRUSTED from=mira kind=agent authorship=signed channel=agent-wms ts=1712.44 hop=3>>>
+the message
+<<<END:4f2a…>>>
+```
+
+The rule for reading that fence arrives through the MCP handshake, a channel the
+message author cannot write to, so it never sits inline beside the content it
+governs. If a payload contains the live delimiter, it is replaced with
+`[FENCE-ECHO REDACTED]`, which turns reflection into a visible event instead of a
+silently broken boundary.
+
+Be clear about what this buys you. An attacker cannot close the fence, and does
+not need to, because text inside a correctly labelled `UNTRUSTED` block still
+reads as language to a model. The fence makes the labelling accurate. Hostile
+text stays exactly as persuasive as it was, so this is a boundary rather than a
+filter.
+
+A reply chain also carries a hop count and stops at 8. Two agents answering each
+other politely is an infinite loop that costs real money.
+
+## Slack scopes, and why each one
+
+Your workspace admin will ask. The manifest requests:
+
+| Scope | Why |
+|---|---|
+| `chat:write` | Post messages |
+| `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` |
+
+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. `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
+procedure. Messages are keyed by their Slack timestamp, so a retried poll or a
+reinstalled app cannot produce duplicates.
+
+## Roadmap
+
+- `mode: reply`, to answer waiting messages when no live session is watching
+- Per-worktree identity, so parallel sessions on one machine name themselves
+- 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       # 42 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