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

package/docs/architecture.md

@@ -0,0 +1,403 @@
+# Architecture
+
+```
+OpenCode 2.2 (one plugin instance per location)
+  │  prompt hook ─────────┐
+  │  session.execution.* ─┤        ┌──────────── Runtime ────────────┐
+  │  tools.messaging.* ──────┼──────► │ sessions: key → state, address  │
+  │                       │        │ tool ops · inbound queue/session │
+  │  ◄── session.prompt ──┤        └──────────────┬──────────────────┘
+  │  ◄── session.synthetic┘                       │ DaemonConnection (only @joe-broadhead/messaging/ipc user)
+  │                                               ▼
+  │                                   $MESSAGING_HOME/run/agent.sock  (JSON-RPC NDJSON; the TUI: run/admin.sock)
+  │                                               │
+  └───────────────────────────────────────── messagingd ══ relay ══ teammates
+```
+
+## Source layout
+
+Each layer has one job and a fixed set of allowed imports. `test/architecture.test.ts` parses
+the TypeScript AST of `src/` and, when it exists, `dist/`, and fails on a violation.
+
+```
+src/
+  index.ts          Plugin.define: options → runtime → host surfaces → cleanup
+  tui.tsx           human console (`./tui`): /messaging registration and the secret dialog. Not an
+                    agent tool. Compiled to dist/tui.js by scripts/build-tui.mjs (Babel).
+  rpc.ts            public RPC contract (`./rpc`): Rpc.define + Zod, `wake` only
+  runtime.ts        orchestrator facade: wires the link to sessions and delivery; tool operations
+  runtime/
+    sessions.ts       session registry, lazy registration, busy/idle, re-registration
+    delivery.ts       inbound mail, wakes and their budget, held notes, mid-turn notes, setup note, the wake bridge
+  connection.ts     the daemon link: connect, autostart hook, reconnect, agent-method allowlist
+  host/             everything that imports @opencode/plugin
+    context.ts        host types derived once
+    tools.ts          namespace + tool adapters: validate, local checks, assert, runtime, render
+    permissions.ts    assert request builders; default rules (send ask, shell asks, home denies, DM read ask) via an agent transform
+    peers.ts          peer sessions (find or create, stored rules, quarantine folder) and the guard's evaluate and context hooks
+    sessions.ts       prompt hook, execution- and tool-event follower, HostBridge (prompt, note, workspace, peer sessions)
+    midturn.ts        tool hooks that put held notes into the next model-facing tool result
+    skills.ts         the opencode-messaging skill
+    rpc.ts            the RPC implementation
+  domain/           pure logic
+    contract.ts       Zod input/output schemas for every tool
+    config.ts         strict options schema and defaults
+    framing.ts        the untrusted-content fence
+    present.ts        daemon results → framed tool outputs
+    inbound.ts        delivery decision, wake prompts, notices, task notes, the mid-turn note
+    peers.ts          peer-turn policy: the guard's verdicts, stored rules, tool allowlist, session marker
+    setup.ts          the setup note for a machine that has not joined a team
+    managed.ts        Messaging by Jelly: the pinned realm, and the check of its messaging.json
+    budget.ts         per-peer wake budget (sliding window)
+    naming.ts         keys, session names, addresses, ids
+    records.ts        compact (drop undefined members)
+    errors.ts, version.ts
+  process/          the only spawn sites
+    daemon.ts         resolve and start messagingd; the identity.json presence check
+    clipboard.ts      copy a card, or a ticket on request, for the TUI (stdin, never argv, 2 s cap)
+    managed.ts        a home's state, the one config.json realm write, the messaging.json fetch (TUI only)
+    browser.ts        open Jelly ID's sign-in page on request (one https argument, no shell, never over SSH)
+  tui/              the TUI's helpers, compiled to dist/tui/
+    link.ts           the console's one daemon connection, its chat subscription and follow()
+    flows.ts          the console's screens and team flows, over a dialog port (no JSX)
+    server.ts         the console's configuration, from the server part's RPC `config`
+    managed.ts        Use Messaging by Jelly: check, write the realm, start the daemon, then Devices
+    console.ts        terminal-safe text: chat lines, person and room titles, team names
+    errors.ts         every error as `<code>: <what happened>. Next: <step>.`
+    people.ts         People: search, a person's page, their grant's switches (grant.*), the review list
+    requests.ts       Requests: request.list and request.answer
+    devices.ts        Devices: device.list (with via), sign in with Jelly, link this device, approve a new device, remove a device
+    login.ts          Sign in with Jelly: device.login, the link, code and fingerprint, device.login.status, cancel
+    notices.ts        Notices: notice.list and notice.ack, and the fixed text of toasts
+    status.ts         This device and /messaging-status
+    qr.ts             terminal QR codes
+skills/opencode-messaging/SKILL.md
+```
+
+| Layer | May import |
+|---|---|
+| `index.ts` | everything in this package |
+| `rpc.ts` | `@opencode/plugin/rpc`, `zod` |
+| `host/` | `@opencode/plugin`, `domain/`, `runtime.ts`, `rpc.ts` |
+| `runtime.ts`, `runtime/` | `runtime/`, `domain/`, `connection.ts`, `process/`, `@joe-broadhead/messaging/core` |
+| `connection.ts` | `domain/`, `@joe-broadhead/messaging/core`, `@joe-broadhead/messaging/ipc` |
+| `process/` | `domain/`, Node built-ins (the only `node:child_process` user) |
+| `domain/` | `domain/`, `zod`, `@joe-broadhead/messaging/core` (schemas only), `node:crypto`, `node:path` |
+| `tui` | `tui/`, `process/`, `domain/`, `@joe-broadhead/messaging/core`, `@joe-broadhead/messaging/ipc`, `uqr`, the host's `@opentui/solid` and `solid-js`, and `@opencode/plugin/tui` for types only; calls the human and admin tiers (`HUMAN_METHODS`, `ADMIN_METHODS`: `conv.*`, `person.send`, `people.*`, `grant.*`, `request.*`, `notice.*`, `device.*`, `channel.*`, `team.*`) on the admin socket. Everything else calls only `AGENT_METHODS`. |
+
+The plugin uses `@joe-broadhead/messaging/core` schemas and types only, never its protocol functions, so it does not
+depend on the core lane's implementation. Nothing imports `node:net`; only `@joe-broadhead/messaging/ipc` speaks
+the socket protocol.
+
+## Lifecycle
+
+- **Setup** (per location) does local work only:
+  1. validates the options;
+  2. builds the runtime;
+  3. registers the agent transform, the tools, the skill, the RPC, the prompt hook, and the
+     execution-event follower.
+
+  It never connects to the daemon, so it cannot fail because the daemon is missing.
+- **Cleanup** disposes every registration and stops the event follower. It then closes the daemon
+  link and waits up to 1 s for in-flight inbound work. It does not unregister sessions.
+- OpenCode evicts idle location instances after about an hour and reloads plugins when the config
+  is saved. Both run cleanup. The next prompt re-registers, and a catch-up note covers mail that
+  arrived in between. The new instance's wake budget starts empty.
+- After a build or a new tarball, restart OpenCode, both the server and the TUI: the package is
+  its bundles (`dist/`), and a running host keeps the modules it has loaded.
+
+## The daemon link
+
+`DaemonConnection` holds at most one `MessagingClient`.
+
+- `link()` is single-flight. On `daemon_unavailable`, an on-demand caller (prompt or tool) runs
+  the autostart hook: choose the daemon (`resolveDaemon`: `daemon.bin`, `daemon.node`, the platform
+  package's executable, else `dist/messagingd.js` under Node 22.15 or later), spawn, then poll the
+  endpoint every 100 ms for up to 8 s.
+- The connect timeout is 5 s. A missing daemon fails at once (`ENOENT`, `ECONNREFUSED`), and a
+  live one connects in the kernel at once, so the timeout mostly measures this process's own
+  event loop. A 1 s timeout turned a busy host into a false `daemon_unavailable`: Node runs the
+  expired timer before the completed connect. That would trigger a needless autostart, or leave a
+  session unregistered.
+- After the first successful connection, a drop schedules background reconnects with jittered
+  exponential backoff (0.5 s to 30 s). These never autostart.
+- Every new connection runs `onConnected` before it is handed out. The runtime then re-registers
+  every session it had registered, asking for the same name. It subscribes all their keys with one
+  `events.subscribe` call and queues a catch-up for each.
+- `Link.call` refuses any method not in `AGENT_METHODS`. It turns `MessagingError` and JSON-RPC
+  errors into code-prefixed tool errors (`daemon_unavailable: …`).
+
+## The `/messaging` console
+
+The TUI part is a separate entry (`./tui`) with its own connection, `ConsoleLink`
+(`src/tui/link.ts`), on the admin socket. It registers no session and never calls `inbox.*`:
+people's chats are the daemon's DMs and channels (spec §6.8), which need no session key, and an
+agent conversation (`agent:…`), which needs one, is not shown.
+
+- **Options.** OpenCode 2.2 gives the TUI part no options, so it never reads `context.options` or
+  resolves a home itself. `tui/server.ts` asks the plugin's server part over the RPC (`config`: the
+  resolved home and the daemon options), validates the answer with `loadConfig`, and only then makes
+  the link and the console. Without an answer, `/messaging` and `/messaging-status` say
+  `server_unavailable` and nothing connects, starts or writes; the next command asks again.
+- **Follow.** There is no badge and no poll. At setup, and after a team create, join or finished
+  pairing, `ConsoleLink.follow()` connects once, only if `identity.json` exists, and calls
+  `notice.subscribe` (without lines).
+  When the connection drops it reconnects with jittered backoff (0.5 s doubling to 30 s, unref'd)
+  while the file exists. Following never starts the daemon.
+- **Starting the daemon.** Every flow collects and checks its input first (a ticket must start
+  with `messaging1.`, a team card must decode), and Esc at any prompt ends it. Then create, join and
+  pair call `client({ start: true })`; every other action starts the daemon only on a machine that
+  has joined a team. Use Messaging by Jelly starts it once the realm is written (a fresh home chooses
+  between it and a self-hosted team first; nothing is written before the choice). Finish join never starts it. With `daemon.autostart: false` nothing starts it
+  and the message says to run `messaging daemon start`. The start uses `process/daemon.ts`, the
+  plugin's single implementation.
+- **Notices.** Each new connection of a device with an identity calls `notice.subscribe` once,
+  after the last notice it saw (`after`). A `notice` (a line from someone else or from the person's
+  own agents, a request, an alarm) becomes a toast and a notification for a blurred terminal in
+  fixed text with the sender's cleaned name, never a line. Of a replay, only the newest shows;
+  repeated ids are dropped.
+- **Screens.** People (`people.search`, `people.get`, `grant.list`, `grant.set.preview` then
+  `grant.set` with the whole merged grant), Requests (`request.list`, narrowed by `kind`: asks, message requests, suggestions; `request.answer`
+  with `once|always|decline|block`, `accept|decline|block`, or `decline` to dismiss), message requests from People
+  (`contact.request.preview` then `contact.request`, hosted realm only) and cards (`reach` from `contacts.list`,
+  `card.get`), Chats (DMs
+  and Me from `conv.list`, Channels, Search with `search`), Devices (`device.status`,
+  `device.list`; in a directory realm `device.link`, `device.approve.preview` then `device.approve`
+  with the code the person typed, `device.remove.preview` then `device.remove` for this device),
+  Notices (`notice.list`, `notice.ack`), Team and This device; `/messaging-status` prints
+  `daemon.status`, `daemon.health` and `device.status` in fixed text and never starts the daemon.
+  A room shows its latest 40 lines from `conv.read` (`kind: "lines"`), with delivery state on your
+  own lines and notices as system lines; picking a line replies in its thread (`person.send` with
+  the thread's root id), and "Write a message" starts a new one. Prepare to create calls `team.prepare` and
+  shows the machine id (copied only on request); Discard pending keys calls `team.pairCancel`
+  after a confirm. The daemon allows one purpose for pending keys at a time, and the console turns
+  its refusal into "choose Discard pending keys first". Finish join polls `team.claim` in 5 s steps for
+  up to 2 minutes behind a notice that stops the wait when closed.
+- **Secrets.** Team and admit cards are public and are copied as shown. An invite ticket is copied
+  only when the person picks "Show the ticket and copy it". The clipboard helper kills a copier
+  that has not finished within 2 s.
+- **Cleanup** stops following, closes the connection, and makes a running flow stop at its next step.
+
+## Before the machine has joined a team
+
+`hasIdentity` (`process/daemon.ts`) checks that `<home>/identity.json` is a regular file, with a
+`stat`. It never opens the file: no key material enters the OpenCode process, and the daemon,
+which reads the file, judges its contents. A team create or join writes the file, and a daemon
+started without one refuses every agent method with `no_identity`.
+
+- `ensure` (registration for prompts, tools and retries) checks the file before it connects. With
+  no file it throws `no_identity` at once: no connection, no autostart, no `session.register`. A
+  prompt only logs it, and a background retry follows `daemon_unavailable` only, so nothing loops.
+- The check runs on every call that is not yet registered, so a team joined from a terminal is
+  picked up by the next prompt or tool call, which then autostarts the daemon if needed.
+
+**Setup note.** When a tool call gets `no_identity` (from the file check or from the daemon), the
+runtime marks the session's setup note `held`. Prompts never do. Held, it waits for the session
+to be idle like any other note, then posts once with `session.synthetic` (`resume: false`,
+`delivery: "queue"`, metadata `delivery: "setup"`) and id `msg_messaging_s_<digest of sessionID>`.
+It becomes `done` whether or not the post succeeds, and also when the session registers after all
+(the user joined during the turn), so it is never posted stale or twice. The host keeps the first
+message with a given id, so a reloaded plugin cannot add a second note to the session either.
+
+The note goes to the transcript as well as the tool error going to the model. The error alone
+reaches the model, but in Code Mode a script decides what to do with it, and the model may
+paraphrase it. The note gives the user the exact commands, with `--home` when needed, and warns
+that the invite ticket belongs in the terminal and not in the chat.
+
+## Sessions
+
+- **Key:** `opencode:<sessionID>`.
+- **Name:** `session.name`, or the slug of the location directory's basename as the fallback.
+- **Peer sessions** (`host/peers.ts`) never register. The `prompt` hook skips a prompt whose
+  metadata says `turn: "peer"` and any session whose metadata marks it as a peer session; a tool
+  call from one uses its working session's key and link, scoped to the peer unless its latest wake
+  was trusted (every item `consent: "trusted"`, the daemon's decision; in memory only, so a reload
+  guards every peer session again).
+- **Agent:** `opencode`.
+- **Workspace:** `cwd` is the location. `repo` is the project's canonical directory basename,
+  sent only when OpenCode reports a VCS. `branch` comes from `vcs.get()` with a 1 s timeout and is
+  cached for 30 s.
+- **Tier:** `push` when `inbound.wake` is on, else `pull`.
+- **Host:** with wakes on, `session.register` includes `host: {kind: "opencode", location, sessionID, pid}`
+  so the daemon can reload this plugin for wake mail (spec §8.6). A location that is not an absolute
+  path is omitted, and registration still succeeds. The daemon's call is `messaging.opencode/wake`. The
+  handler checks the session belongs to this location (`session.get`), registers without starting the
+  daemon, fetches each named item with `inbox.get`, and decides it on the same inbound path as a live
+  event. Repeated and stale ids are no-ops. A session this process has not seen is treated as idle
+  until a prompt or execution event says otherwise.
+
+Registration is lazy: the first prompt (through the `prompt` hook, which never changes the
+prompt) or the first Messaging tool call, once the machine has joined a team. It is single-flight per session, retries once across a
+reconnect, and is followed by `events.subscribe` for the key. A tool call reports a failure to the
+model. A registration started by the `prompt` hook has nobody to report to. If it fails with
+`daemon_unavailable`, the runtime retries it in the background with the connection's backoff
+(0.5 s doubling to 30 s), never starting the daemon, until the session registers. One way this
+happens: the connect timed out because the host's event loop was too busy to see it complete.
+
+Busy/idle follows `session.execution.started` (busy) and `…succeeded | failed | interrupted`
+(idle). OpenCode 2.2 does not emit `session.status` or `session.idle`; the real-host suite
+confirmed this. A change made while `session.register` is in flight is sent with `session.update`
+once registration completes. A successful wake into the working session marks it busy; a wake into
+a peer session leaves the working session's state alone.
+
+A prompt overrides the events until the host confirms the prompt's work has ended. The `prompt`
+hook runs before the host starts the prompt's execution, and the events carry no execution id. An
+execution that ends in between therefore looks like the end of this prompt's work: an earlier
+execution settling, or one the host resumed when `opencode run --session` started. In the live
+re-run, that idle blip let a notice be queued for an item that the turn then read, and the model
+received it as new input after its answer. So, after a prompt hook:
+
+- the session stays busy, and execution events are held;
+- after 1 s, enough for the host to start the prompt's execution, the runtime calls
+  `session.wait`, which resolves once no execution is running;
+- if another prompt arrived meanwhile, it waits again;
+- then the session is idle.
+
+If `session.wait` fails, the last held event decides.
+
+## Inbound flow
+
+Events are handled one at a time per session, in order. Envelope ids already handled in this
+process (by an event, a catch-up or an `inbox` listing) are skipped.
+
+1. **`inbox` event, stage `delivered`.**
+
+   | Condition | What the plugin does |
+   |---|---|
+   | wake: the item's `wake`, `inbound.wake`, the session is idle, and the sender has wake budget | Add the item to the session's 2 s coalescing window (see below). |
+   | wake, but the sender is over its wake budget | As notify. |
+   | notify: `inbound.notify` | Hold the item for a note (see below). |
+   | otherwise | Nothing; the agent reads with `inbox`. |
+
+   **Wake budget.** `WakeBudget` (`domain/budget.ts`) gives each sender person
+   `inbound.wakeBudget.perPeer` wakes per sliding `windowMs` (default 6 per hour), shared by all
+   sessions of the process. Keying by person and not by address stops a sender from multiplying its
+   budget by opening sessions. A sender is charged once, when its first item enters a window; later
+   items from that person in the same window join for free.
+
+   **Coalescing window.** The first admitted wake opens a 2 s window for the session, and later
+   admitted wakes join it. When the window closes:
+
+   | Condition | What the plugin does |
+   |---|---|
+   | the session is busy, or its link changed | The items are held for notes (when `notify` is on). |
+   | otherwise | The items are grouped by sender person. Items from this machine's own person go to the working session. Each other person's items go to their peer session (`HostBridge.peerSession`, see "Peer turns" in security.md), which the host layer finds or creates; if that fails, they get notices in the working session. Each group then gets one wake as below, in its target session; the working session is marked busy only for its own wake. |
+   | one item | 1. `inbox.get {message: true}`, for the full message and its provenance, with no stage change.<br>2. `session.prompt` with id `msg_messaging_w_<envelopeId>` (idempotent), `delivery: "queue"`, metadata `{source, delivery: "wake", turn: "own" or "peer", peer, envelopeId, kind, taskId}`, and the text: a plugin line, the peer-turn line in a guarded peer session, then the preamble and the framed message.<br>3. Once the host admitted the prompt: `inbox.ack {stage: "handed_to_agent"}`, then `inbox.ack {stage: "read"}`. |
+   | several items | 1. One `session.prompt` with id `msg_messaging_w_<digest of the ids>`, metadata with `count`, `envelopeIds` and `taskIds`: a plugin line, the peer-turn line in a guarded peer session, the preamble, and a framed preview per item (oldest first, at most 10 shown). Nothing is read for the model.<br>2. Once the host admitted it: `inbox.ack {stage: "handed_to_agent"}` for each. |
+   | the prompt fails | Post a notice per item instead, and ack each `handed_to_agent` after its notice. |
+
+   Nothing changes an item's stage before the host has admitted the prompt (spec §8.2): a crash or a
+   refused prompt in between leaves the item at `delivered`, and the next catch-up shows it. The
+   cost is the other way round: a crash after the prompt and before the acks leaves an item that was
+   shown at `delivered`, so a catch-up note may repeat it.
+2. **`task` event with `origin: "peer"`.** A note for a requester task that reached a terminal or
+   interrupted state, or an executor task that the requester cancelled. `origin: "local"` events
+   (this session's own updates) are ignored. When a requested task ends, the note also lists the
+   session's follow-ups (`TaskRecord.followUps`, from the daemon's receipts) that did not reach
+   `read`: envelope id, send time, stage, and a fenced excerpt of at most 200 characters from the
+   task history; or one line saying all were read. Task notes are held like inbox notes until the
+   session is idle (or go into a tool result, see "Mid-turn notes"); the latest change per task wins. A held note is dropped if the agent has
+   looked at that task since the change (`task`, `tasks`, `task_update` or `task_cancel`).
+3. **Catch-up** after (re)registration. `inbox.list {unreadOnly: true}`; every item still at
+   `delivered` and not yet handled is held for a note.
+
+**Held notes.** Notices and catch-up notes are posted only while the session is idle. A note queued
+into a running turn reaches the model after a later step, when the model may already have read the
+item (the live test showed this: a stale note and an extra step). While the session is busy,
+items wait: the next model-facing tool result carries them (see "Mid-turn notes" below), or else
+the next `session.execution.*` idle event posts them. Immediately before posting, the
+plugin asks the daemon again: `inbox.get` for one item, `inbox.list {unreadOnly: true}` for
+several. Items no longer at `delivered` are dropped: they were read, or the `inbox` tool showed
+them. If nothing is left, no note is posted. Otherwise:
+
+- one item that arrived during a turn gets a notice: `session.synthetic` with id
+  `msg_messaging_n_<envelopeId>`, `resume: false`, `delivery: "queue"`, and a framed preview;
+- anything else gets one note (oldest first, at most 10 shown), with `delivery: "catch-up"` in its
+  metadata.
+
+Each posted item is then acked `handed_to_agent`. If the re-check fails, the items stay held for
+the next idle.
+
+**Mid-turn notes.** With `inbound.notify` and `inbound.midTurn` on, held items and held task
+notes go into the result of the busy session's next tool call instead of waiting for the turn to
+end. They are put inside a tool result, not posted as a separate message, so they cannot arrive
+after the model has moved on: the model reads them with the output of the call it just made.
+`test/host/after-hook.test.ts` pins what OpenCode 2.2 does; `host/midturn.ts` builds on it:
+
+1. `tool` hooks `execute.before` and `execute.after` count open calls per call id. Code Mode runs
+   its nested calls through the same hooks with the outer `execute` call's id, and their results go
+   back to the script, not to the model. Only the `execute.after` that closes the last open
+   `execute.before` of an id is a model-facing result. A call that started before the plugin loaded
+   is unknown and is left alone.
+2. A completed model-facing call that ran no Messaging tool (`messaging_*`, direct or nested) asks
+   `runtime.offer`. A Messaging tool's output is already Messaging's, and a note beside it could be read
+   as part of that output.
+3. `offer` takes every held item and task note at once (a parallel call of the same step finds
+   none), asks the daemon again as the idle path does (at most 1 s; on failure nothing is offered
+   and the notes stay held), and drops items no longer at `delivered`. It renders one note, oldest
+   item first, then task notes: at most 5 entries and 7,168 characters, always at least one; the
+   rest stay held and the note says how many. The entries are now *offered* under the call id.
+4. The hook appends the note to the result as its own text part (after the content; a result with
+   only structured output is first rendered as its JSON text, as the host would). The note starts
+   with a blank line and a plugin line that says it is not part of the tool output; previews are
+   fenced as in a catch-up note.
+5. The host then cuts the result to its output limits (keeping the head) and records it:
+   `session.tool.success` carries the recorded content per call id. If that content holds the whole
+   note, the items are acked `handed_to_agent` and the tasks count as seen. If the note was cut, the
+   call failed (`session.tool.failed`), or no event comes within 30 s, the entries go back to held,
+   for the next tool call or the next idle. An entry is never acked unless the model got it, so a
+   lost event can show an item twice but never hides one.
+
+The hook never throws: a failure leaves the result as the tool returned it. The setup note is
+never put into a tool result; it is for the user.
+
+The `inbox` tool, and a `read({ with })` page of an agent's mail, acknowledge the previews they show
+as `handed_to_agent`. `read({ id })` of a message uses `item.read`, which marks the item read. A
+`send` with `replyTo` finds the message with `inbox.get`, which changes nothing.
+
+## Tools
+
+The eight tools and their schemas are `AgentTool` in `@joe-broadhead/messaging/core` (spec §11), shared with
+`messaging-mcp`; `runtime/operations.ts` runs them. Each adapter in `host/tools.ts` follows the same
+steps:
+
+1. Re-validate the input with the contract schema.
+2. Run local checks that need no permission. For `send` (`planSend`), this is address parsing
+   (`parseToolAddress`), the guarded-turn allowance, what may go to whom, plus, with `replyTo`, an
+   `inbox.get` (the message must be from `to`) or a `task.get` (this session must be the requester
+   and the task's peer `to`). With `onBehalfOf`, it is a `task.get` that requires this session to be
+   the executor of a live task. For `task_update` and `task_cancel`, it is a `task.get` plus the
+   role, terminal-state and transition checks.
+3. Call `permission.assert`. `read` asserts the conversation: for `{ with }` the one named, for
+   `{ id }` the item's, found with `inbox.get` or `task.get`, neither of which change
+   anything.
+4. Call the runtime. `search` without `with` asserts after the daemon call instead: one assert per
+   conversation in the hits, keeping the hits of each that passes
+   ([security](security.md#chats-lines-posts-conversations-and-search)).
+5. Return `{ output, content, metadata }`:
+   - `output` matches the output schema, and Code Mode receives it as an object;
+   - `content` is compact JSON, capped at 128 KiB;
+   - `metadata` has the tool, small facts and the duration.
+
+## Testing
+
+| Layer | What | Where |
+|---|---|---|
+| Unit | options, names, framing (hostile content), inbound texts, wake budget, permission builders and the default-rule evaluation | `test/{config,naming,framing,inbound,permissions}.test.ts` |
+| Architecture | import boundaries; every agent-side `.call("…")` is in `AGENT_METHODS` and no non-agent method name appears outside the TUI | `test/architecture.test.ts` |
+| Fake host + fake daemon | tool registration, assert action/resource/save, deny propagation with no daemon call, output schemas, the chat tools (room asserts, search per room, post to a DM) | `test/tools.test.ts` |
+| Console | the TUI's link (no daemon start on connect, `notice.subscribe` once, follow, reconnect and resume, autostart off, close), its terminal-safe text and its toasts | `test/console.test.ts` |
+| Console flows | no start before input or on Esc, start rules, ticket and card checks, the ticket only in its dialog and copied on request, empty lists, Finish join, channel remove, notices; the fresh-home choice and Use Messaging by Jelly (exactly the pinned block, a refused messaging.json, never offered or written over), the realm by name in status | `test/tui-flows.test.ts` |
+| Managed realm | the pinned realm is its own `directoryRealmId` and a valid `DirectoryRealmConfig`; messaging.json mismatches refused; home states; the write keeps other fields and never overwrites | `test/managed.test.ts` |
+| TUI build | `build-tui.mjs` output has no JSX and imports only `@opentui/solid`, `@joe-broadhead/messaging/ipc` and compiled modules | `test/tui-build.test.ts` |
+| Fake daemon | lazy registration, reconnect, busy/idle; wake vs note, wake budget and coalescing, held notes, acks, catch-up, task notes, the wake bridge; tool operations; autostart, unavailability, no team identity (no start, `no_identity`, one setup note, a join between calls) | `test/{sessions,delivery,operations,autostart}.test.ts` (shared `test/fixtures/runtime.ts`) |
+| Entrypoint | setup with a fake context, no daemon contact, cleanup, skill and RPC contract, no autostart without a team | `test/plugin.test.ts` |
+| Real host | the embedded OpenCode 2.2.5 with a fake daemon: registries, ask/reject/once/always, configured allow/deny, the chat search and DM post rules, shell asks and home denies, note and wake, wake budget and coalescing, no team identity and a later join; Use Messaging by Jelly with the release's real daemon (a loopback realm: no test dials the deployment) | `test/host/` (Node ≥ 24, separate install) |
+| TUI types and build | `src/tui.tsx` type-checked against `@opencode/plugin/tui` and `@opentui/solid`, then compiled with Babel | `tsconfig.tui.json` and `scripts/build-tui.mjs`, run by `npm run compile` |
+| Packaged TUI | the installed `./tui` export under Bun: setup without and with a team, no slot, one subscription, the invite dialog rendered by `@opentui/solid`, cleanup | `npm run smoke:pack` (`scripts/smoke-tui-probe.mjs`) |
+
+The fake daemon (`test/fixtures/fake-daemon.ts`) is `recordingDaemon()` from `@joe-broadhead/messaging/ipc/testing`
+(every call recorded, a method with no handler refused), with minimal state (sessions, inbox, tasks, chat rooms). Its directory is the home, and by
+default it has joined a team (a stand-in `identity.json`). With `joined: false` it has no file,
+answers `daemon.status` without a team and refuses everything else with `no_identity`, until
+`join()`.