beehaven 0.8.19 → 0.8.20

package/dist/build-channel.js

@@ -53,9 +53,9 @@ export const PUBLIC_BUILD = true;
  * ⚠ REWRITTEN IN `dist/` AT BUILD TIME, like `PUBLIC_BUILD`. `unstamped` is what a source checkout
  * carries and what `tsx`/`vitest` see, and it is honest: nothing has stamped them.
  */
-export const BUILD_SHA = '42cf394385d8';
+export const BUILD_SHA = '046981bccb35-dirty';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-09-27T18:08Z';
+export const BUILD_TIME = '2026-09-29T05:23Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/cli.js

@@ -185,6 +185,7 @@ function printHelp() {
     beehaven mv <src> <dest>       Move, or rename
 
   Work:
+    beehaven inbox                 Messages to you from people and agents  (read · send · reply · done · who)
     beehaven ticket create "<t>"   File a card on a board  (list · move · edit · show · comment)
     beehaven board list            The boards you can file to  (create · delete · report · backlog)
     beehaven sprint list           Plan, run and close a sprint  (create · plan · start · complete)
@@ -1575,6 +1576,9 @@ async function run() {
             kind: { type: 'string' },
             tags: { type: 'string' },
             title: { type: 'string' },
+            // `beehaven inbox send <to> "…" --subject "…" --refs CLR-42,<doc id>` (WIB-1).
+            subject: { type: 'string' },
+            refs: { type: 'string' },
             source: { type: 'string' },
             info: { type: 'boolean', default: false },
             // #109 — `beehaven conversations export` flags.
@@ -6434,6 +6438,12 @@ complete -F _beehaven_completions beehaven`);
             await cmdMention(positionals[1] ?? '', positionals.slice(2), values);
             break;
         }
+        // WIB-1 — messages between the people and agents of a workspace.
+        case 'inbox': {
+            const { cmdInbox } = await import('./commands/inbox.js');
+            await cmdInbox(positionals[1] ?? '', positionals.slice(2), values);
+            break;
+        }
         case 'ticket':
         case 'board': {
             const { cmdTicket, cmdBoard } = await import('./commands/ticket.js');

package/dist/commands/agent.js

@@ -897,9 +897,17 @@ function printBrief(brief) {
      */
     const mentions = brief.workspace?.mentions ?? [];
     const voicemail = brief.workspace?.voicemail ?? [];
-    if (mentions.length || voicemail.length) {
+    /** WIB-1 — people and agents writing TO this agent. Oldest first; reading one clears it. */
+    const inbox = brief.workspace?.inboxThreads ?? [];
+    if (mentions.length || voicemail.length || inbox.length) {
         console.log('');
-        console.log(`  ${bold('Addressed to you')} ${dim(`(${mentions.length + voicemail.length})`)}`);
+        console.log(`  ${bold('Addressed to you')} ${dim(`(${mentions.length + voicemail.length + inbox.length})`)}`);
+        for (const t of inbox.slice(0, 5)) {
+            console.log(`    ${dim('·')} ${cyan('message')} from ${t.from}: “${t.subject}” ${dim(`${t.unread} unread · ${t.threadId}`)}`);
+            console.log(`      ${String(t.preview ?? '').replace(/\s+/g, ' ').slice(0, 120)}`);
+        }
+        if (inbox.length)
+            console.log(dim(`      Read with \`beehaven inbox read <id>\`, answer with \`beehaven inbox reply <id> "…"\`, then \`beehaven inbox done <id>\`.`));
         for (const v of voicemail.slice(0, 3)) {
             console.log(`    ${dim('·')} ${cyan('voicemail')} from ${v.from}: ${String(v.text ?? '').replace(/\s+/g, ' ').slice(0, 100)}`);
         }
@@ -912,7 +920,7 @@ function printBrief(brief) {
             console.log(dim(`      Act, reply with \`beehaven comment <ref> "…"\`, then \`beehaven mention ack <id>\`.`));
     }
     if (!sessions.length && !assigned.length && !pending.length && !memories.length && !focus.length) {
-        if (!mentions.length && !voicemail.length)
+        if (!mentions.length && !voicemail.length && !inbox.length)
             console.log(dim('     First visit — nothing to catch up on.'));
         return;
     }

package/dist/commands/help.js

@@ -113,7 +113,34 @@ const PAGES = {
             { cmd: 'beehaven mention who jin' },
             { cmd: 'beehaven mention resolve "cc @omni and @bob"' },
         ],
-        related: ['comment'],
+        related: ['comment', 'inbox'],
+    },
+    inbox: {
+        synopsis: 'beehaven inbox [box|read <id>|send <to> "…"|reply <id> "…"|done <id>|add|leave|who|count]',
+        description: 'Messages between the people and agents of this workspace — everyone can message everyone. You act as '
+            + 'whoever this terminal is signed in as: an agent (`beehaven agent login <name>`) has its OWN inbox, '
+            + 'separate from its owner\'s, and its unread threads are printed in its brief under "Addressed to you".\n\n'
+            + 'Reading a thread marks it read — that is the acknowledgement. Reply in the thread, then `done` it '
+            + '(archive); a new reply brings it back. Sending runs no AI: an agent you message reads it next session.\n\n'
+            + 'Boxes: inbox (default — threads someone else has written in), unread, starred, sent, archived, all. '
+            + '`<to>` takes the handles `beehaven inbox who` lists, comma-separated.',
+        flags: [
+            { name: '--search "<q>"', desc: 'On a box: only threads whose subject or messages contain it.' },
+            { name: '--subject "<s>"', desc: 'On send: the thread subject (defaults to the first line).' },
+            { name: '--refs <a,b>', desc: 'On send/reply: workspace items to link — ids, keys (CLR-42) or exact titles.' },
+            { name: '--as agent:<id>', desc: 'On a box/read: a person reading an agent they own. Read-only; marks nothing read.' },
+            { name: '--limit <n>', desc: 'On a box: how many threads (default 50).' },
+            { name: '--json', desc: 'Raw result.' },
+        ],
+        examples: [
+            { cmd: 'beehaven inbox' },
+            { cmd: 'beehaven inbox read it_m1x2_ab12cd34' },
+            { cmd: 'beehaven inbox send ada,pixel "Draft is in CLR-42 — can you review?" --refs CLR-42' },
+            { cmd: 'beehaven inbox reply it_m1x2_ab12cd34 "Done — see the second option."' },
+            { cmd: 'beehaven inbox done it_m1x2_ab12cd34' },
+            { cmd: 'beehaven inbox who' },
+        ],
+        related: ['mention', 'comment'],
     },
     ticket: {
         synopsis: 'beehaven ticket <create|list|move|edit|show|comment|comments|delete> [args]',

package/dist/commands/inbox.js

@@ -0,0 +1,208 @@
+/**
+ * `beehaven inbox` — messages between the people and agents of a workspace (WIB-1).
+ *
+ *   beehaven inbox [box]                      your threads — box: inbox (default) | unread |
+ *                                             starred | sent | archived | all   --search "…"
+ *   beehaven inbox read <threadId>            open a thread (marks it read)
+ *   beehaven inbox send <to> "message"        start a thread — <to> is one or more handles,
+ *                                             comma-separated: "ada,pixel"
+ *       --subject "…"   --refs CLR-42,<doc id>   (workspace items to link)
+ *   beehaven inbox reply <threadId> "message" answer in a thread
+ *   beehaven inbox done <threadId>            archive it — handled (a reply brings it back)
+ *   beehaven inbox archive|unarchive|star|unstar|mute|unmute|unread <threadId>
+ *   beehaven inbox add <threadId> <to>        bring more people or agents in
+ *   beehaven inbox leave <threadId>           stop receiving a thread
+ *   beehaven inbox who [query]                everyone you can message (people and agents)
+ *   beehaven inbox count                      unread messages and threads
+ *
+ * ⚠ YOU ACT AS WHOEVER THIS TERMINAL IS SIGNED IN AS. An agent (`beehaven agent login <name>`)
+ * has its own inbox — messages to it are not its owner's, and it cannot read anyone else's.
+ * ⚠ READING IS THE ACKNOWLEDGEMENT. There is no separate ack: `read` clears the unread count,
+ * and `done` takes it out of the inbox once you have acted.
+ */
+import { agentRpc as rpcOnce, getTimeout } from './workspace.js';
+const c = {
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    violet: (s) => `\x1b[35m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+/** ⚠ `rpcOnce` returns `{ error }` as a VALUE and never throws. */
+function failure(res) {
+    if (!res || typeof res !== 'object')
+        return 'no answer from the workspace';
+    if (typeof res.error === 'string' && res.error)
+        return res.error;
+    if (res.ok === false)
+        return String(res.message ?? res.code ?? 'the workspace refused the call');
+    return null;
+}
+function die(msg, hint) {
+    console.error(`  Error: ${msg}`);
+    if (hint)
+        console.error(c.dim(`  ${hint}`));
+    process.exit(1);
+}
+const ago = (ts) => {
+    const d = Date.now() - Number(ts || 0);
+    if (d < 60_000)
+        return 'just now';
+    if (d < 3_600_000)
+        return `${Math.round(d / 60_000)}m ago`;
+    if (d < 86_400_000)
+        return `${Math.round(d / 3_600_000)}h ago`;
+    return `${Math.round(d / 86_400_000)}d ago`;
+};
+const who = (p) => (p?.kind === 'agent' ? c.violet(String(p.name)) : String(p?.name ?? 'someone'));
+const list = (s) => s.split(',').map((x) => x.trim()).filter(Boolean);
+const BOXES = new Set(['inbox', 'unread', 'starred', 'sent', 'archived', 'all']);
+const MARKS = {
+    done: { archived: true, read: true },
+    archive: { archived: true },
+    unarchive: { archived: false },
+    star: { starred: true },
+    unstar: { starred: false },
+    mute: { muted: true },
+    unmute: { muted: false },
+    unread: { read: false },
+};
+async function call(action, input, values) {
+    const res = await rpcOnce(action, input, getTimeout(values));
+    const f = failure(res);
+    if (f)
+        die(f, res?.hint);
+    if (values.json) {
+        console.log(JSON.stringify(res, null, 2));
+        process.exit(0);
+    }
+    return res;
+}
+async function printList(box, values) {
+    const res = await call('inbox-list', {
+        box, ...(values.search ? { q: String(values.search) } : {}), ...(values.as ? { as: String(values.as) } : {}),
+        ...(values.limit ? { limit: Number(values.limit) } : {}),
+    }, values);
+    const threads = res.threads ?? [];
+    const counts = res.counts ?? {};
+    console.log('');
+    console.log(`  ${c.bold(box === 'inbox' ? 'Inbox' : box[0].toUpperCase() + box.slice(1))}${res.as ? c.dim(` — reading ${res.as}, read-only`) : ''} ${c.dim(`(${counts.unread ?? 0} unread in ${counts.threads ?? 0} thread${counts.threads === 1 ? '' : 's'})`)}`);
+    if (!threads.length) {
+        console.log(c.dim(box === 'inbox' ? '  Nothing waiting. Start one: beehaven inbox send <to> "…"  ·  who you can message: beehaven inbox who' : '  Nothing here.'));
+        return;
+    }
+    for (const t of threads) {
+        const people = (t.participants ?? []).map(who).join(', ') || c.dim('only you');
+        const flag = t.unread ? c.cyan(`● ${t.unread}`) : ' ';
+        console.log(`  ${flag} ${c.bold(t.subject)} ${c.dim('—')} ${people} ${c.dim(`· ${ago(t.updatedAt)}${t.starred ? ' · ★' : ''}${t.muted ? ' · muted' : ''}`)}`);
+        console.log(`      ${String(t.preview ?? '').slice(0, 110)} ${c.dim(t.id)}`);
+    }
+    if (res.nextBefore)
+        console.log(c.dim('  … more — narrow with --search or raise --limit'));
+    console.log(c.dim('  Open: beehaven inbox read <id>   Reply: beehaven inbox reply <id> "…"   Done: beehaven inbox done <id>'));
+}
+export async function cmdInbox(sub, rest, values) {
+    const s = sub || 'inbox';
+    if (BOXES.has(s))
+        return printList(s, values);
+    if (s === 'read' || s === 'open') {
+        const threadId = rest[0];
+        if (!threadId)
+            die('usage: beehaven inbox read <threadId>', 'ids are in: beehaven inbox');
+        const res = await call('inbox-thread', { threadId, ...(values.as ? { as: String(values.as) } : {}) }, values);
+        console.log('');
+        console.log(`  ${c.bold(res.thread?.subject ?? '')} ${c.dim(`— ${(res.participants ?? []).filter((p) => !p.you).map((p) => p.name + (p.left ? ' (left)' : '')).join(', ')}`)}`);
+        for (const m of res.messages ?? []) {
+            if (m.system) {
+                console.log(c.dim(`    · ${m.body} (${ago(m.createdAt)})`));
+                continue;
+            }
+            const from = m.mine ? c.green('you') : who(m.from ?? { name: m.fromName });
+            console.log('');
+            console.log(`  ${from} ${c.dim(`· ${ago(m.createdAt)}${m.edited ? ' · edited' : ''} · ${m.id}`)}`);
+            if (m.deleted) {
+                console.log(c.dim('    (deleted)'));
+                continue;
+            }
+            for (const line of String(m.body).split('\n'))
+                console.log(`    ${line}`);
+            for (const r of m.refs ?? [])
+                console.log(c.dim(`    ↳ ${r.key || r.kind}: ${r.title}${r.href ? `  ${r.href}` : ''}`));
+            const reactions = Object.entries(m.reactions ?? {}).map(([e, p]) => `${e} ${p.length}`).join('  ');
+            if (reactions)
+                console.log(`    ${reactions}`);
+        }
+        console.log('');
+        if (!res.as && !res.me?.left)
+            console.log(c.dim(`  Reply: beehaven inbox reply ${threadId} "…"   Done: beehaven inbox done ${threadId}`));
+        return;
+    }
+    if (s === 'send') {
+        const to = rest[0] || String(values.to ?? '');
+        const body = rest.slice(1).join(' ').trim() || String(values.body ?? '').trim();
+        if (!to || !body)
+            die('usage: beehaven inbox send <to> "message" [--subject "…"] [--refs CLR-42,…]', 'who you can message: beehaven inbox who');
+        const res = await call('inbox-send', {
+            to: list(to), body,
+            ...(values.subject ? { subject: String(values.subject) } : {}),
+            ...(values.refs ? { refs: list(String(values.refs)) } : {}),
+        }, values);
+        const names = (res.to ?? []).map(who).join(', ');
+        console.log(`  Sent to ${names} ${c.dim(res.threadId)}`);
+        if ((res.to ?? []).some((t) => t.kind === 'agent'))
+            console.log(c.dim('  Agents read it in their next brief — nothing runs until then.'));
+        return;
+    }
+    if (s === 'reply') {
+        const threadId = rest[0];
+        const body = rest.slice(1).join(' ').trim() || String(values.body ?? '').trim();
+        if (!threadId || !body)
+            die('usage: beehaven inbox reply <threadId> "message"');
+        await call('inbox-reply', { threadId, body, ...(values.refs ? { refs: list(String(values.refs)) } : {}) }, values);
+        console.log(`  Replied ${c.dim(threadId)}`);
+        return;
+    }
+    if (MARKS[s]) {
+        const ids = rest.flatMap(list);
+        if (!ids.length)
+            die(`usage: beehaven inbox ${s} <threadId>[,<threadId>…]`);
+        const res = await call('inbox-mark', { threadIds: ids, ...MARKS[s] }, values);
+        console.log(`  ${s === 'done' ? 'Done' : s[0].toUpperCase() + s.slice(1)} — ${res.count} thread${res.count === 1 ? '' : 's'} ${c.dim(`(${res.counts?.unread ?? 0} unread left)`)}`);
+        return;
+    }
+    if (s === 'add') {
+        const [threadId, to] = rest;
+        if (!threadId || !to)
+            die('usage: beehaven inbox add <threadId> <to>');
+        const res = await call('inbox-add', { threadId, to: list(to) }, values);
+        console.log(res.added?.length ? `  Added ${(res.added ?? []).map(who).join(', ')}` : c.dim('  Everyone named is already in it.'));
+        return;
+    }
+    if (s === 'leave') {
+        if (!rest[0])
+            die('usage: beehaven inbox leave <threadId>');
+        await call('inbox-leave', { threadId: rest[0] }, values);
+        console.log('  Left the conversation.');
+        return;
+    }
+    if (s === 'who') {
+        const res = await call('inbox-recipients', { ...(rest[0] ? { q: rest.join(' ') } : {}) }, values);
+        console.log('');
+        for (const r of res.recipients ?? []) {
+            console.log(`  ${c.cyan(r.handle.padEnd(18))} ${r.kind === 'agent' ? c.violet(r.name) : r.name}${r.kind === 'agent' ? c.dim(' · agent') : ''}${r.yours ? c.dim(' · yours') : ''}`);
+        }
+        if (!(res.recipients ?? []).length)
+            console.log(c.dim('  Nobody else is in this workspace yet.'));
+        return;
+    }
+    if (s === 'count') {
+        const res = await call('inbox-unread', {}, values);
+        console.log(`  ${res.unread} unread in ${res.threads} thread${res.threads === 1 ? '' : 's'}`);
+        for (const a of res.agents ?? [])
+            if (a.unread)
+                console.log(c.dim(`    ${a.name}: ${a.unread} unread`));
+        return;
+    }
+    die(`unknown inbox command "${s}"`, 'beehaven inbox [inbox|unread|starred|sent|archived|all] · read · send · reply · done · add · leave · who · count');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beehaven",
-  "version": "0.8.19",
+  "version": "0.8.20",
   "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
   "private": false,
   "type": "module",

package/skills/clearly-agent/SKILL.md

@@ -83,7 +83,8 @@ The brief carries: prior **sessions**, **lastActions**, **focus**, **assignedToM
 **memories**, **recents** (what you touched, with titles and whether you made or opened it), and
 **drafts** (your own unfiled work) — plus the workspace half: what changed since you were last
 here **and by whom**, inbox, notifications, messages, other agents — and, first, what is **addressed to
-you**: `voicemail` and `mentions` (both stay until acked).
+you**: `inboxThreads` (messages people and agents sent you — they stay until you read them),
+`voicemail` and `mentions` (both stay until acked). `waiting.inboxUnread` is the count.
 
 ⚠ **`changed[].by` is the useful field, not the timestamp.** "Four documents changed" is not
 actionable; "they changed three and you changed the fourth" tells you which to re-read.
@@ -120,6 +121,39 @@ item queued. Every comment/description write returns `mentions`, `agentsQueued`
 surface cannot carry is **refused**, never dropped. Over MCP: `clearly_write { type:"comment",
 target, content, fields }`, `clearly_read { type:"comment", target }`, and `target:"@me"` for mentions.
 
+## Inbox — people and agents message you, and you message them
+
+Everyone in a workspace can message everyone: people ↔ people, people ↔ agents, agents ↔ agents.
+**You have your own inbox**, separate from your owner's — a message to you is not a message to them,
+and you cannot read anyone else's. Unread threads are in your brief as `workspace.inboxThreads`
+(oldest first; the CLI prints them under **Addressed to you**). Sending runs no model: whoever you
+message reads it in their next session, so write a message that stands on its own.
+
+```bash
+beehaven inbox                                   # threads someone else wrote in (inbox-list)
+beehaven inbox read it_m1x2_ab12cd34             # open it — this IS the acknowledgement (marks read)
+beehaven inbox reply it_m1x2_ab12cd34 "Done — two options in CLR-42." --refs CLR-42
+beehaven inbox done it_m1x2_ab12cd34             # archive once handled; a new reply brings it back
+beehaven inbox send ada,vera "Can you review the pricing doc?" --subject "Pricing review" --refs "Pricing"
+beehaven inbox who                               # every handle you can put in <to> — people and agents
+```
+
+Over MCP, `type: "message"` on the same tools: `clearly_read { type: "message", target: "@inbox" }`
+lists your threads (`box`, `query`), `target: "@people"` lists who you can message, and a thread id
+opens it (marks read). `clearly_write { type: "message", fields: { to: ["ada"] }, content }` starts a
+thread; with `target: <threadId>` it replies. `clearly_edit { changes: { read | starred | muted } }`
+changes your view; `clearly_delete` archives (`restore: true` brings it back).
+
+⚠ **Answer in the thread, not in a new one.** `inbox-reply` keeps the context with the question;
+`inbox-send` starts a fresh conversation and the asker has to connect the two.
+⚠ **Link, don't paste.** `refs` takes ids, keys (CLR-42) or exact titles and renders as a chip the
+reader opens. A message is capped at 20,000 characters — put long work in a document and link it.
+⚠ **You can edit your own message (`inbox-message-edit`), not delete it** — deleting clears the text
+for good, and permanent deletion is human-only in this workspace. `to` refuses a handle that matches
+nobody (`unmatched`) or more than one (`ambiguous`); use one `beehaven inbox who` lists.
+⚠ Your owner can **read** your inbox (read-only — it never marks anything read, so you still find the
+work in your brief). Write as if they will.
+
 ## ⚠⚠ Your work is YOURS — this changes what everyone sees
 
 Anything you create is stamped `created_by: agent:<your-id>` and born **private**:

package/skills/index.json

@@ -74,6 +74,6 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "89e5a04a420defe3"
+    "sha": "94c30f43b217f3e9"
   }
 ]