@grknbyk/agent-wire 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gürkan Bıyık
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+<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

package/bin/agent-wire.mjs

@@ -0,0 +1,115 @@
+#!/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);
+}

package/manifest.json

@@ -0,0 +1,38 @@
+{
+    "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
+    }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+    "name": "@grknbyk/agent-wire",
+    "version": "0.4.0",
+    "description": "Let AI coding agents message each other through a shared Slack channel, over MCP.",
+    "type": "module",
+    "license": "MIT",
+    "author": "Gürkan Bıyık <gurkan.biyik@outlook.com>",
+    "homepage": "https://github.com/grknbyk/agent-wire",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/grknbyk/agent-wire.git"
+    },
+    "bugs": {
+        "url": "https://github.com/grknbyk/agent-wire/issues"
+    },
+    "bin": {
+        "agent-wire": "bin/agent-wire.mjs"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "scripts": {
+        "test": "node --test \"test/*.test.mjs\""
+    },
+    "files": [
+        "bin",
+        "src",
+        "assets",
+        "manifest.json"
+    ],
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "slack",
+        "ai-agents",
+        "agent-communication",
+        "claude-code",
+        "cursor"
+    ]
+}

package/src/config.mjs

@@ -0,0 +1,68 @@
+// Everything agent-wire stores lives in one directory so a broken install can be
+// inspected, backed up, or deleted as a unit.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const HOME = process.env.AGENT_WIRE_HOME || join(homedir(), '.agent-wire');
+
+export const paths = {
+    config: join(HOME, 'config.json'),
+    inbox: join(HOME, 'inbox.jsonl'),
+    states: join(HOME, 'states.json'),
+    cursors: join(HOME, 'cursors.json'),
+    peers: join(HOME, 'peers.json'),
+    users: join(HOME, 'users.json'),
+    files: join(HOME, 'files'),
+    pollLock: join(HOME, 'poll.lock'),
+};
+
+export const readJson = (file, fallback) => (existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : fallback);
+
+// Write to a sibling then rename: a config half-written by a killed setup run is
+// how an install becomes unrecoverable, and rename is atomic on every platform we
+// target. The temp name carries the pid so two runs cannot share it.
+export function writeJson(file, value) {
+    mkdirSync(HOME, { recursive: true });
+    const tempFile = `${file}.${process.pid}.tmp`;
+    writeFileSync(tempFile, JSON.stringify(value, null, 2));
+    renameSync(tempFile, file);
+}
+
+export const loadConfig = () => readJson(paths.config, null);
+
+export const saveConfig = (config) => writeJson(paths.config, config);
+
+// Setup writes after every completed step, so the config IS the resume state and
+// there is no second progress file to disagree with it.
+export function patchConfig(patch) {
+    const merged = { ...(loadConfig() ?? { version: 1 }), ...patch };
+    saveConfig(merged);
+    return merged;
+}
+
+export const defaultChannel = (config) => config.channels?.[0] ?? null;
+
+// A channel is active unless it was explicitly switched off, so a config written
+// before this option existed keeps every channel on.
+export const activeChannels = (config) => (config.channels ?? []).filter((channel) => channel.active !== false);
+
+// Switching a channel off leaves its cursor where it is, so switching it back on
+// replays everything that arrived meanwhile instead of losing it.
+export function setChannelActive(name, active) {
+    const config = loadConfig();
+    if (!config) return null;
+
+    const channel = findChannel(config, name);
+    if (!channel) return null;
+
+    channel.active = active;
+    saveConfig(config);
+    return channel;
+}
+
+export function findChannel(config, wanted) {
+    if (!wanted) return defaultChannel(config);
+    const name = String(wanted).replace(/^#/, '').toLowerCase();
+    return config.channels?.find((c) => c.name.toLowerCase() === name || c.id === wanted) ?? null;
+}

package/src/identity.mjs

@@ -0,0 +1,73 @@
+// Every agent in a workspace shares one bot token, so Slack's own bot_id proves
+// only "agent-wire posted this" — not which agent did. The header line is plain
+// text anyone in the channel can type, so it cannot carry identity either.
+// Each install therefore signs what it sends with its own Ed25519 key and
+// publishes the public half alongside the message. A nickname is bound to the
+// first key seen using it (trust on first use); a later message claiming that
+// nickname with a different key is reported, not believed.
+import { createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto';
+
+import { paths, readJson, writeJson } from './config.mjs';
+
+const DER_PRIVATE = { type: 'pkcs8', format: 'der' };
+const DER_PUBLIC = { type: 'spki', format: 'der' };
+
+export function generateKeypair() {
+    const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+    return {
+        privateKey: privateKey.export(DER_PRIVATE).toString('base64'),
+        publicKey: publicKey.export(DER_PUBLIC).toString('base64'),
+    };
+}
+
+// Signed over the fields a forger would want to change: who sent it, who it is
+// for, which channel it belongs to, and where it sits in a reply chain. Channel
+// is included so a signed message cannot be replayed into a different channel.
+export const signingPayload = ({ channel, from, to, conv, hop, text }) =>
+    Buffer.from(`agent-wire/v1\n${channel}\n${from}\n${to}\n${conv}\n${hop}\n${text}`, 'utf8');
+
+export function signMessage(privateKeyBase64, fields) {
+    const privateKey = createPrivateKey({ key: Buffer.from(privateKeyBase64, 'base64'), ...DER_PRIVATE });
+    return sign(null, signingPayload(fields), privateKey).toString('base64');
+}
+
+function verifySignature(publicKeyBase64, signature, fields) {
+    try {
+        const publicKey = createPublicKey({ key: Buffer.from(publicKeyBase64, 'base64'), ...DER_PUBLIC });
+        return verify(null, signingPayload(fields), publicKey, Buffer.from(signature, 'base64'));
+    } catch {
+        // A malformed key or signature is a failed verification, not a crash: the
+        // bytes came from a Slack message and anyone in the channel can shape them.
+        return false;
+    }
+}
+
+const loadPeers = () => readJson(paths.peers, {});
+
+// Verdicts, in the order they are decided:
+//   "signed"    — signature valid and the key matches the one pinned to this name
+//   "new"       — signature valid, first time this name appears, key now pinned
+//   "impostor"  — signature valid but the name is pinned to a DIFFERENT key
+//   "unsigned"  — no signature, or the signature does not verify
+export function checkAuthorship({ from, publicKey, signature, ...fields }) {
+    if (!publicKey || !signature) return { verdict: 'unsigned' };
+    if (!verifySignature(publicKey, signature, { from, ...fields })) return { verdict: 'unsigned' };
+
+    const peers = loadPeers();
+    const pinned = peers[from];
+    if (pinned && pinned.publicKey !== publicKey) return { verdict: 'impostor', pinnedSince: pinned.firstSeen };
+    if (pinned) return { verdict: 'signed' };
+
+    peers[from] = { publicKey, firstSeen: new Date().toISOString() };
+    writeJson(paths.peers, peers);
+    return { verdict: 'new' };
+}
+
+export const forgetPeer = (name) => {
+    const peers = loadPeers();
+    delete peers[name];
+    writeJson(paths.peers, peers);
+};
+
+export const listPeers = () => Object.entries(loadPeers())
+    .map(([name, peer]) => ({ name, firstSeen: peer.firstSeen, fingerprint: peer.publicKey.slice(0, 12) }));

package/src/inbox.mjs

@@ -0,0 +1,76 @@
+// The local log is the source of truth, not the Slack channel. Slack history is a
+// cache we can re-read at any time, so a full re-scan is an ordinary idempotent
+// operation rather than a recovery procedure.
+//
+// inbox.jsonl is append-only and keyed by the Slack timestamp, which is unique per
+// channel and survives a re-install. Message state lives in a separate file so the
+// append-only log never has to be rewritten in place.
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+
+import { HOME, paths, readJson, writeJson } from './config.mjs';
+
+const storageKey = (item) => `${item.channel}:${item.ts}`;
+
+export function readInbox() {
+    if (!existsSync(paths.inbox)) return [];
+    return readFileSync(paths.inbox, 'utf8').split('\n').filter(Boolean)
+        .map((line) => { try { return JSON.parse(line); } catch { return null; } })
+        .filter(Boolean);
+}
+
+export const stateOf = (states, item) => states[storageKey(item)] ?? 'unread';
+
+// The Slack timestamp is the idempotency key: a retried poll, an overlapping
+// window, or a re-installed app all replay the same ts, and a duplicate the human
+// has to clean up by hand is the failure that generates support noise.
+export function appendMessages(items) {
+    if (items.length === 0) return 0;
+
+    const seen = new Set(readInbox().map(storageKey));
+    const fresh = items.filter((item) => !seen.has(storageKey(item)));
+    if (fresh.length === 0) return 0;
+
+    mkdirSync(HOME, { recursive: true });
+    appendFileSync(paths.inbox, fresh.map((item) => JSON.stringify(item)).join('\n') + '\n');
+    return fresh.length;
+}
+
+// `channel` names one channel explicitly and overrides everything. `channels`
+// is the caller's allow-list, which is how switched-off channels stay out of the
+// default view without being deleted from the log.
+export function selectMessages({ state = 'unread', count = 20, channel = null, channels = null } = {}) {
+    const states = readJson(paths.states, {});
+    const visible = readInbox().filter((item) => {
+        if (channel) return item.channel === channel;
+        if (channels) return channels.includes(item.channel);
+        return true;
+    });
+    const wanted = state === 'all' ? visible : visible.filter((item) => stateOf(states, item) === state);
+    return wanted.slice(-count);
+}
+
+export function markRead(items) {
+    const states = readJson(paths.states, {});
+    for (const item of items) states[storageKey(item)] = 'read';
+    writeJson(paths.states, states);
+}
+
+export function archive(ts) {
+    const states = readJson(paths.states, {});
+    const targets = ts
+        ? readInbox().filter((item) => item.ts === ts)
+        : readInbox().filter((item) => stateOf(states, item) === 'read');
+    for (const item of targets) states[storageKey(item)] = 'archived';
+    writeJson(paths.states, states);
+    return targets.length;
+}
+
+export const findByTs = (ts) => readInbox().find((item) => item.ts === ts) ?? null;
+
+export const readCursor = (channelId) => readJson(paths.cursors, {})[channelId] ?? null;
+
+export function writeCursor(channelId, ts) {
+    const cursors = readJson(paths.cursors, {});
+    cursors[channelId] = ts;
+    writeJson(paths.cursors, cursors);
+}