@joe-broadhead/opencode-messaging 0.0.0-stage → 0.4.0

package/docs/configuration.md

@@ -0,0 +1,397 @@
+# Configuration
+
+Options go in the `options` object of the plugin's `plugins` entry in `opencode.json(c)`. Every
+option is optional.
+
+OpenCode does not validate plugin options. The plugin does, with a strict schema: an unknown or
+misspelled key, or a value of the wrong type, fails plugin setup. The error names the key, for
+example `opencode-messaging: invalid plugin options: daemon: Unrecognized key: "autostrat"`.
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "/Users/you/opencode-messaging",
+      "options": {
+        "home": "/Users/you/.messaging",
+        "daemon": { "autostart": true, "node": "/usr/local/bin/node" },
+        "session": { "name": "api-work" },
+        "inbound": { "wake": true, "notify": true, "wakeBudget": { "perPeer": 6, "windowMs": 3600000 } },
+      },
+    },
+  ],
+}
+```
+
+**The `/messaging` TUI takes these options from the server part.** OpenCode 2.2 loads the plugin's
+TUI part without the `options` of `opencode.json(c)`. So the TUI never reads its own options, and never
+resolves a home from the terminal's `$MESSAGING_HOME` or `~/.messaging`: it asks the plugin's server
+part, over the plugin's RPC (`messaging.opencode`, method `config`), for the home it resolved and its
+`daemon` options, and uses those. Nothing to repeat in `cli.json`; options there are ignored.
+
+If the server part cannot be reached (it is not in `opencode.json(c)`, a bad option stopped it, or it
+does not answer within 10 s), `/messaging` and `/messaging-status` say so
+(`server_unavailable: …`) and do nothing: no connection, no daemon start, no file written, in any home.
+The next command asks again. The live acceptance of 0.3.0 found the old fallback on OpenCode 2.2.5,
+where a console started a daemon in `~/.messaging` while the configured home was elsewhere
+(`docs/testing/live-acceptance.md`); the packaged-TUI smoke test now proves that path starts nothing.
+
+## Options
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `home` | absolute path | `$MESSAGING_HOME`, else `~/.messaging` | The Messaging home. The plugin's tools use the daemon's agent endpoint, `<home>/run/agent.sock` (on Windows the pointer file `<home>\run\agent.pipe`, which names a named pipe); the `/messaging` TUI its admin endpoint, `<home>/run/admin.sock` (`admin.pipe`). |
+| `daemon.autostart` | boolean | `true` | Start `messagingd` when the socket does not answer and this machine has created or joined a team (`<home>/identity.json` exists). |
+| `daemon.bin` | absolute path | this platform's `messagingd` executable, else `dist/messagingd.js` (see [which daemon runs](#which-daemon-runs)) | The daemon to run: a `messagingd` executable, or a `messagingd.js` (ending in `.js`, `.mjs` or `.cjs`), which runs under Node. |
+| `daemon.node` | absolute path or a bare command on `PATH` | the host's own Node, else `node` on `PATH` | The Node executable (≥ 22.15) that runs `messagingd.js`. Setting it chooses `dist/messagingd.js` over the platform executable. |
+| `session.name` | session name (`[a-z0-9][a-z0-9._-]{0,63}`) | slug of the OpenCode directory's basename | The address name: the session's address is `person/<name>@<label>`. The folder name is only the fallback. The daemon adds `-2`, `-3`, … when the name is taken on this machine. |
+| `inbound.wake` | boolean | `true` | Wake an idle session for mail when the sender asks for it. This also selects the `push` delivery tier (`pull` when false). |
+| `inbound.notify` | boolean | `true` | Post a transcript note for mail that does not wake the session, and for task changes. |
+| `inbound.midTurn` | boolean | `true` | With `notify`: while the session works, put those notes into the result of its next tool call instead of holding them until the turn ends. |
+| `inbound.wakeBudget.perPeer` | integer, 1–1000 | `6` | Wakes one teammate may cause in this OpenCode process per window. Over it, their mail gets a note instead. |
+| `inbound.wakeBudget.windowMs` | integer, 60000–86400000 | `3600000` (1 h) | The sliding window of the wake budget, in milliseconds. |
+
+### `home`
+
+The plugin uses the first one that is set: the `home` option, then the `MESSAGING_HOME` environment
+variable of the OpenCode server, then `~/.messaging`. Every client on the machine (this plugin, the
+`messaging` CLI, the MCP server) must use the same home to talk to the same daemon.
+
+### `daemon`
+
+The plugin connects on first use: the first prompt in a session, or the first Messaging tool call.
+Plugin setup never connects. If the endpoint does not answer, `autostart` is true and the machine
+has joined a team (see [before a team](#before-the-machine-has-joined-a-team)), the plugin starts
+the daemon.
+
+#### Which daemon runs
+
+The plugin picks the first that applies (`src/process/daemon.ts`, the one place that decides):
+
+1. **`daemon.bin`**, when you set it: a `.js`, `.mjs` or `.cjs` file runs under Node (below), anything
+   else is run as an executable.
+2. **`daemon.node`**, when you set it: the bundled `dist/messagingd.js` under that Node.
+3. **The platform executable.** The self-contained `messagingd` (the daemon compiled with Bun: no
+   Node, no install step) from this machine's package, which npm installs as one of the plugin's
+   `optionalDependencies`:
+
+   | Platform | Package | Executable |
+   |---|---|---|
+   | macOS arm64 | `@joe-broadhead/messaging-bin-darwin-arm64` | `bin/messagingd` |
+   | macOS x64 | `@joe-broadhead/messaging-bin-darwin-x64` | `bin/messagingd` |
+   | Linux arm64, glibc | `@joe-broadhead/messaging-bin-linux-arm64-gnu` | `bin/messagingd` |
+   | Linux x64, glibc | `@joe-broadhead/messaging-bin-linux-x64-gnu` | `bin/messagingd` |
+   | Windows x64 | `@joe-broadhead/messaging-bin-win32-x64` | `bin/messagingd.exe` (not code-signed; see [Windows](#windows)) |
+
+   Each is pinned at exactly the messaging release the plugin is built against (0.4.0), and npm
+   installs only the one whose `os` and `cpu` match. The plugin finds it from its own install
+   location the way Node resolves a package, and admits it only when the package is that version,
+   the executable is a regular file (not a link) with owner read and execute and no permission
+   outside 0755, and its SHA-256 is the one the plugin pins for that platform (the release's
+   `SHA256SUMS`). An installed package that fails a check is an error (`daemon_unavailable`, naming the
+   package and what failed), never a silent fallback. On Linux the plugin also checks for glibc
+   itself, because npm's lockfile does not record `libc`.
+4. **`dist/messagingd.js` under Node 22.15 or later**, when this platform has no package (musl,
+   Windows on arm64, any other platform) or npm did not install it (for
+   example `--omit=optional`, or a tarball unpacked without its platform package). The Node is the
+   executable OpenCode runs on, when that is plain Node 22.15 or newer (nothing is looked up on
+   `PATH`, so a `node` planted earlier on `PATH` is never run); otherwise `node` from OpenCode's
+   `PATH`, which the plugin first asks for its version (`node --version`). Stock OpenCode runs on Bun,
+   so this is the `PATH` case.
+5. Otherwise tools fail with `daemon_unavailable`, naming the platform, the package that is missing
+   or the Node that was found, and the remedy: reinstall the plugin so npm installs its optional
+   dependency, install Node 22.15 or later, or set `daemon.node` or `daemon.bin`.
+
+Set `daemon.node` to an absolute path to avoid the `PATH` lookup in case 4.
+
+The process has these properties:
+
+- The process is detached and outlives OpenCode. On Windows it opens no console window.
+- It has no stdio. Its `cwd` is the home, or your home directory if the Messaging home does not exist yet.
+- `MESSAGING_HOME` is set to the home.
+- It gets an allowlisted environment: `PATH`, `HOME`, user and locale variables, `TMPDIR`, `XDG_*`,
+  proxy variables, `NODE_EXTRA_CA_CERTS`, `MESSAGING_LOG_LEVEL` and `MESSAGING_IDENTITY_STORE` (on
+  Windows also `SystemRoot`, `USERPROFILE`, `TEMP` and the other variables Windows programs need).
+  Provider API keys, `NODE_OPTIONS` and other OpenCode secrets are not passed, and neither is any
+  `BUN_*` variable, which the platform executable (a Bun runtime) would otherwise read
+  (`BUN_BE_BUN=1` makes it act as `bun`). `messaging daemon start` uses the same list.
+- The plugin never signals it. It is stopped with `messaging daemon stop` (`daemon.stop` over the admin
+  endpoint), on every platform.
+
+The plugin then waits up to 8 s for the socket. One OpenCode process starts the daemon at most
+once per home every 10 s. The daemon's own lock prevents a second instance.
+
+One home has one daemon. The plugin starts its own only when nothing answers on the socket. A
+daemon of another Messaging version that answers there (a `messaging` installed apart from the plugin,
+or an older plugin's) is never replaced: tools fail with `daemon_mismatch`, naming both versions,
+until you stop it with `messaging daemon stop`; the next tool call then starts the plugin's.
+
+The plugin never starts the daemon where it runs as its own user (docs/self-hosting.md, "The
+daemon under its own user"): when `MESSAGING_DAEMON_UID` names another uid, when the home belongs to
+another user, or when the home is 0710, as `messagingd` leaves it for `ipc.agentGroup`. Tools then
+fail with `daemon_unavailable` and say so; the operator starts the daemon. Windows has no uid or
+mode, so there the plugin checks neither: the daemon checks the home's ACL itself, and the client
+library refuses an endpoint another user could write. Windows has no separate-user layout, so a set
+`MESSAGING_DAEMON_UID` still refuses.
+
+#### Windows
+
+The client libraries the plugin bundles speak the Windows daemon's endpoints: named pipes of random
+names behind owner-only pointer files (`<home>\run\agent.pipe`, `admin.pipe`). The plugin registers
+OpenCode's directory (`C:\…`) as the wake location as it is. The shell asks before `messaging.exe` and
+`messagingd.exe` too.
+
+On Windows x64 the plugin runs `messagingd.exe` from `@joe-broadhead/messaging-bin-win32-x64`
+(case 3; no mode is checked there, Windows has none: the file's ACL is the installer's). It is not
+code-signed, which matters on a person's machine:
+
+- **Smart App Control** (Windows 11, when it is on in enforcement mode) blocks an unsigned executable
+  of unknown reputation however it arrived, with no per-app override, so `messagingd.exe` does not
+  start there until it is signed; tools then fail with `daemon_unavailable`. Set `daemon.node` to use
+  `dist/messagingd.js` under Node instead. Most machines that were not freshly installed, and managed
+  ones, have it off.
+- **Microsoft Defender Antivirus** scans every executable; a new, unsigned one is more often the
+  subject of a heuristic detection. Report a detection to Microsoft as a false positive with the
+  sha256 from the messaging release's `SHA256SUMS`.
+- **SmartScreen** assesses only files with a Mark of the Web. npm writes none, so an installed
+  package runs without a prompt.
+
+If the connection drops, the plugin reconnects in the background with backoff (0.5 s, doubling
+up to 30 s). If a session cannot register on its first prompt because the daemon is unreachable,
+the plugin retries that registration in the background with the same backoff until it succeeds.
+Without the retry, the session would get no mail and no wakes until your next prompt. Background
+reconnects and retries never start the daemon, so a daemon you stopped stays stopped until the next
+prompt or tool call. Once you start it yourself, waiting sessions register on their own. Set
+`autostart: false` to manage `messagingd` yourself.
+
+When the daemon cannot be reached, every tool fails with a `daemon_unavailable` error, whose remedy
+says to start it.
+
+#### Before the machine has joined a team
+
+A daemon without a team refuses every call an agent can make, so the plugin does nothing with
+one. Until `<home>/identity.json` exists (`messaging team create` or `messaging team join` writes it):
+
+- **Prompts** do nothing beyond a file check: no connection, no daemon start, no note. If you
+  never use Messaging, you never see it.
+- **Tools** fail with `no_identity`, whose remedy tells the model to ask you to set Messaging up.
+  Nothing starts the daemon, whatever `autostart` says. A daemon that is running but has no team is
+  reported the same way.
+- **One setup note.** The first Messaging tool call that gets `no_identity` in a session holds one
+  transcript note for you (like the [inbound](#inbound) notes: no model turn, posted once the turn
+  ends). It gives the commands to run in a terminal: `messaging daemon start`, then
+  `messaging team create …` or `messaging team join - --label <machine>` with an invite ticket from a team
+  admin (`messaging team invite <you>`). The commands carry `--home <home>` when the plugin's home is
+  not `~/.messaging`. A session gets at most one such note. Its id is fixed per session, so the host
+  keeps only the first even after a plugin reload. Prompts never post it.
+- **Joining needs no reload.** The plugin checks for the file on every prompt and tool call. After
+  `messaging team join`, the next call registers the session. With `autostart` on, it also starts
+  the daemon if it is not running.
+
+The plugin only checks that `identity.json` exists. It never opens the file, so it never holds the
+machine's keys, and the daemon remains the judge of the file's contents. `autostart` stays a
+boolean: starting a daemon that has no team would not help an agent, and `messaging daemon start`
+covers creating and joining.
+
+#### The `/messaging` console
+
+The TUI part uses the server part's `home`, `daemon.autostart`, `daemon.node` and `daemon.bin`,
+over the plugin's RPC (see the note at the top of this page), validated with the same schema. A bad
+option stops the server part, and the console then says it cannot reach it. It never starts the
+daemon just to connect. With `autostart` on, it starts it, with the same `<node> <bin>` rule, to
+create, join or ask to join a team once the input is complete, to use
+[Messaging by Jelly](#messaging-by-jelly) once it has written the realm, and for other actions only
+once this machine has joined a team or has a realm. With `autostart: false` it never starts it and tells you to run
+`messaging daemon start`. Once this machine is in a team, the TUI keeps one connection for chat
+notices and reconnects when the daemon restarts; it never starts the daemon for that.
+
+### `session.name`
+
+Each OpenCode session registers as its own Messaging session with the key `opencode:<sessionID>`.
+Its address is `person/<name>@<label>`, with `<name>` from this setting; the slug of the folder
+name is only the fallback. Set it when the folder does not say what the session is for (a Jelly
+agent's folder is always `workspace`). Peer sessions never register: they use the address of the
+session the teammate wrote to. All sessions in one directory request the same name, so
+the second becomes `name-2`. Registration repeats after a reconnect and asks for the name the
+session already holds, so its address stays stable. The plugin never unregisters a session. The
+daemon keeps a session addressable for 24 h after its client goes away.
+
+### `inbound`
+
+| `wake` | `notify` | Session idle, sender asked to wake | Otherwise |
+|---|---|---|---|
+| true | true | wake prompt | transcript note |
+| true | false | wake prompt | nothing (the agent pulls with `inbox`) |
+| false | true | transcript note | transcript note |
+| false | false | nothing | nothing |
+
+- A **wake prompt** starts a model turn. Its text is a line written by the plugin, followed by the
+  framed message. Wakes that arrive within 2 s of the first are combined into one prompt that lists
+  every item with a framed preview; the agent reads the ones it wants.
+- The **wake budget** limits the turns one teammate can start. Each person gets
+  `wakeBudget.perPeer` wakes per sliding `wakeBudget.windowMs` (default 6 per hour), counted across
+  all sessions of this OpenCode process. The key is the sender's person name, not its session
+  address, because a sender can open as many sessions as it likes. A combined prompt costs each
+  sender in it one wake, counted when its first item enters the 2 s window. Over budget, the item is
+  handled as if it did not ask to wake: a transcript note when `notify` is on, otherwise nothing.
+  The daemon's loop guard does not limit wakes; see [security.md](security.md#residual-risks).
+- A **transcript note** (`session.synthetic` with `resume: false`, `delivery: "queue"`) never
+  starts a turn. The model sees it during the session's next turn. Notes are posted only while
+  the session is idle. Mail that arrives during a turn goes into the next tool result (see
+  `midTurn`) or else waits until the turn ends, and anything the agent has read or listed by then
+  is dropped from the note.
+- **`midTurn`** (default `true`, only with `notify`): mail and task notes that arrive while the
+  session works go into the result of its next tool call, after the tool's own output, instead of
+  waiting for the turn to end. At most 5 items and 7,168 characters per tool result; the rest
+  follow in later results or the idle note. A call that ran a Messaging tool gets none. An item counts
+  as handed to the agent only once OpenCode has recorded the result with the note in it. Set it to
+  `false` to keep every tool result exactly as the tool returned it.
+- A wake prompt is acknowledged only after OpenCode has admitted it. If it fails, the plugin posts
+  a note instead, whatever `notify` says, and acknowledges the item once the note is posted. A
+  crash in between leaves the item unread, and the next catch-up shows it.
+- A **wake from another person never runs in this session**. It runs in a peer session; see
+  [peer turns](#peer-turns). Mail from your own other sessions wakes this session as before, and
+  mail that arrives while this session works still goes into its next tool result.
+- A session counts as busy from a prompt until OpenCode reports that the prompt's work has ended,
+  so no note is queued into a turn that is about to start.
+- `notify` also controls task notes: a requester hears when a task ends (completed, failed,
+  rejected or cancelled) or waits for input or auth; an executor hears when the requester cancels.
+  When a task ends, the requester's note also names its follow-up messages the executor did not
+  read. The `task` tool shows every follow-up with its stage.
+  Only peer-caused changes produce notes; this session's own updates do not.
+- Mail that arrived while the session was not subscribed is rolled into one catch-up note when the
+  session registers or reconnects, posted at the next idle.
+
+The daemon has its own policy: `inbound.wake` in `$MESSAGING_HOME/config.json` (`"team"` or
+`"never"`). A wake happens only when both allow it.
+
+With `inbound.wake` on, each session registers a `host`: this location's directory, the OpenCode
+session id, and the server's pid. If OpenCode unloads the plugin while wake mail arrives, the
+daemon can ask that server to load this location again and call `messaging.opencode/wake`. Turn the
+daemon's `wake.bridge` off to stop that. The plugin still decides each item with the idle check,
+the wake budget and coalescing above.
+
+### Peer turns
+
+When a teammate's agent wakes a session, the plugin runs that turn in a **peer session**, never in
+the working session the teammate addressed:
+
+- One peer session per working session and teammate (person), titled `Messaging: <person>`. The
+  plugin creates it on the first wake and reuses it for later ones. Its tools use the working
+  session's Messaging address, so replies come from the address the teammate wrote to. It never
+  registers an address of its own.
+- Each wake prompt is tagged in its metadata with `turn: "peer"`, the `peer` person, and the
+  envelope (`envelopeId`, or `envelopeIds` for a combined prompt) and task ids.
+- Unless the daemon says the wake is `trusted`, the turn is **guarded**: it can read the project and
+  write only under `.messaging-peers/<person>/` in this directory. Its tools are read, glob, grep,
+  edit, write, skill and Code Mode; it cannot run the shell, use the web or another plugin's tools,
+  start subagents, ask questions, or reach outside the project. Messaging sends go only back to that
+  person, and Messaging reads show only what concerns them. Nothing waits for you: a step that would ask is refused, and
+  the model is told to say so in its reply. [security.md](security.md#peer-turns) has the details.
+- The plugin creates `.messaging-peers/` with a `.gitignore` that ignores everything in it.
+- Your own other sessions (the same person) are not peers: their wakes run in the working session.
+
+**Trust is a grant, not an option.** You trust a person with `messaging grant <person> --trust 30d`
+(or `/messaging` → People): the daemon then marks their items `consent: "trusted"` until the grant
+expires (spec §6.9; at most `LIMITS.trustMaxMs`). A wake whose every item is `trusted` runs
+unguarded in their peer session, with the same rights as the session they addressed, under your
+normal permission rules, and nobody is there to answer an ask. Its prompt says the limits of any
+earlier guarded turn in that session no longer apply. The next wake that is not trusted makes that
+peer session guarded again, and its prompt says the limits hold now. The plugin keeps no trust of its own: after OpenCode
+reloads it, every peer session is guarded until its next trusted wake. No tool, agent or teammate
+can trust anyone. Trust only someone whose machine you would let run commands in this project.
+The 0.1 option `inbound.trusted` is gone; a configuration that still sets it is refused.
+
+## Messaging by Jelly
+
+The managed deployment is a directory realm (spec §15.8) whose identity this release pins
+(`MESSAGING_BY_JELLY` in `src/domain/managed.ts`); see
+[security.md](security.md#messaging-by-jelly-the-pinned-realm) for why and how to check it. There is
+no plugin option for it: the realm is not configurable, and the plugin never writes a realm except
+from the `/messaging` console.
+
+**In the console.** A home is *fresh* when it has no `identity.json`, its `config.json` (if any)
+names no `realm`, `relay` or `person`, and it has no `pairing.json`. `/messaging` on a fresh home
+asks first: "Use Messaging by Jelly", then "Create or join a team (self-host)". Picking Messaging by
+Jelly and confirming:
+
+1. reads `https://msg.toqanjelly.ai/.well-known/messaging.json` (5 s, no redirects). A `200` whose
+   `kind`, `url`, `issuer`, `resource`, `key` or `realm` differs from the pinned realm (or whose
+   `url`, `issuer` and `key` give another realm id) is refused: nothing is written and the daemon is
+   not started. Its `orgDomains` may differ; the pinned default is written. No answer, a redirect or
+   another status leaves the pinned realm to stand on its own;
+2. adds `realm` to `config.json`, keeping its other fields (the home is created 0700 and the file
+   0600 if they do not exist). It checks the home is still fresh just before the file is renamed into
+   place, so a realm, a team or an identity written meanwhile is never overwritten;
+3. starts the daemon (when `daemon.autostart` allows), which makes this device's keys once and
+   reports `realm: "directory"`, `binding: "none"`;
+4. opens Devices, where **Sign in with Jelly** (in the browser at Jelly ID) or **Link this device**
+   (approved from a device that already has Jelly) makes this computer one of your devices.
+
+`/messaging-status` and This device then read `Realm: Messaging by Jelly (directory)`, with the
+binding; while the daemon is stopped, the realm line still shows from `config.json`.
+
+**By hand, without the TUI.** Put this in `~/.messaging/config.json` (or `$MESSAGING_HOME/config.json`)
+**before the daemon first starts in that home**, in a home that has no `identity.json`, no
+`pairing.json` and no `relay` or `person` in its config:
+
+```json
+{
+  "realm": {
+    "kind": "directory",
+    "url": "wss://msg.toqanjelly.ai/v1/connect",
+    "issuer": "https://id.toqanjelly.ai",
+    "resource": "https://msg.toqanjelly.ai",
+    "key": "Qp_RqcZhpEjtYqI8ybcUMo07ubT9bBb-8JnXpjnledg",
+    "orgDomains": ["prosus.com"]
+  }
+}
+```
+
+Then `messaging daemon start`, and sign in (`messaging login`, or the TUI's Devices, Sign in with
+Jelly), or link the device from the TUI (Devices, Link this device) or with
+`messaging devices link`. Check the key out of band first
+([security.md](security.md#checking-the-key-out-of-band)). A home's realm never changes: to leave it,
+move the home aside and start again. A `messaging` CLI command that writes this block is a later item.
+
+## Permission rules
+
+Messaging tools use two OpenCode permission actions: `messaging.send` and `messaging.read`. Configure them
+with normal `permissions` rules. [security.md](security.md) gives the resource formats and the
+default behaviour. A line to a person asserts `messaging.send` on `<person>` and `<person>/` (so a
+deny on `<person>/*` covers it), a post on `#<channel>`, and `read` and `search` assert
+`messaging.read` on the conversation (`person:<person>`, `agent:<person>/<agent>` or
+`channel:<name>`). In the example below, the `*` deny also blocks every line and post, because no
+rule allows a person or a channel.
+
+The plugin also adds defaults for the agent's own tools. `shell` asks before running any
+`messaging` or `messagingd` command, and any command that names the Messaging home or its `identity.json`
+and `messaging.db` files. `read`, `edit` and `external_directory` are denied under the Messaging home.
+These defaults go after every broad allow (`*`, or an action allowed on `*`), so they hold for
+agents without a base rule too; your specific rules come after them and win. See
+[security.md](security.md#the-agents-shell-and-the-messaging-home).
+
+```jsonc
+{
+  "permissions": [
+    // Only alice's agents: deny everything, then allow alice (the last matching rule wins).
+    { "action": "messaging.send", "resource": "*", "effect": "deny" },
+    { "action": "messaging.send", "resource": "alice/*", "effect": "allow" },
+    // Hide the contacts tool's results.
+    { "action": "messaging.read", "resource": "contacts", "effect": "deny" },
+    // Let the agent read the person's DM lines with bob without asking; keep it out of the hr channel.
+    { "action": "messaging.read", "resource": "person:bob", "effect": "allow" },
+    { "action": "messaging.read", "resource": "channel:hr", "effect": "deny" },
+    // Let the shell list the inbox without asking (the plugin's default asks for every messaging command).
+    { "action": "shell", "resource": "messaging inbox*", "effect": "allow" },
+  ],
+}
+```
+
+## Debugging
+
+Set `MESSAGING_PLUGIN_DEBUG=1` in the OpenCode server's environment. The plugin then writes event
+names and error codes to stderr: registration (`no_identity` before a team), reconnects,
+autostart, acks. It never writes
+message text, names, ids, or tokens. When the server runs inside the TUI process, stderr paints over
+the terminal UI, so set it only for `opencode serve` or the host suite.