Files

tegwick ac34c062df feat(CUST-WP-0015): implement agent inbox for inter-agent coordination

Adds a message-passing layer to state-hub so Claude instances can
coordinate across sessions without polling shared progress events.

- Migration f3a4b5c6d7e8: agent_messages table with thread support
- FastAPI router: POST/GET /messages/, thread view, mark-read, archive, reply
- 4 MCP tools: send_message, get_messages, mark_message_read, reply_to_message
- Observable dashboard: /inbox page with unread/read/archived sections + KPI
- CLAUDE.md updates: global, custodian, marki-docx, activity-core, template
- TOOLS.md: Agent Inbox tools section documented

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-16 02:55:45 +01:00

6.6 KiB

Raw Blame History

title

title
Agent Inbox

import {API, POLL} from "./components/config.js";

// Live poll: messages list
const inboxState = (async function*() {
  while (true) {
    let messages = [], ok = false;
    try {
      const resp = await fetch(`${API}/messages/?limit=100`);
      ok = resp.ok;
      if (ok) messages = await resp.json();
    } catch {}
    yield {messages, ok, ts: new Date()};
    await new Promise(res => setTimeout(res, POLL));
  }
})();

const messages = inboxState.messages ?? [];
const _ok = inboxState.ok ?? false;
const _ts = inboxState.ts;

const unread   = messages.filter(m => !m.read_at && !m.archived_at);
const read     = messages.filter(m => m.read_at && !m.archived_at);
const archived = messages.filter(m => m.archived_at);

// Group unread by agent for KPI
const agentCounts = {};
for (const m of unread) {
  agentCounts[m.to_agent] = (agentCounts[m.to_agent] ?? 0) + 1;
}
const topAgents = Object.entries(agentCounts).sort((a, b) => b[1] - a[1]).slice(0, 4);

Agent Inbox

import {injectTocTop} from "./components/toc-sidebar.js";
import {withDocHelp}  from "./components/doc-overlay.js";

const _kpiBox = html`<div class="kpi-infobox">
  <div class="kpi-infobox-title">Inbox</div>
  <div class="kpi-row">
    <span class="kpi-row-label">unread</span>
    <div class="kpi-row-right">
      <div class="kpi-row-value" style="color:${unread.length > 0 ? '#d97706' : 'inherit'}">${unread.length}</div>
    </div>
  </div>
  <div class="kpi-row">
    <span class="kpi-row-label">total</span>
    <div class="kpi-row-right">
      <div class="kpi-row-value" style="font-size:1rem">${messages.length}</div>
    </div>
  </div>
  ${topAgents.map(([agent, count]) => html`
  <div class="kpi-row">
    <span class="kpi-row-label">${agent}</span>
    <div class="kpi-row-right">
      <div class="kpi-row-value" style="font-size:0.9rem">${count}</div>
    </div>
  </div>`)}
</div>`;

const _liveEl = html`<div class="live-indicator">
  <span style="color:${_ok ? 'var(--theme-foreground-focus)' : 'red'}">●</span>
  ${_ok
    ? `Live · updated ${_ts?.toLocaleTimeString()}`
    : html`<span style="color:red">Offline — run: <code>make api</code></span>`}
</div>`;

injectTocTop("inbox-kpi-box", _kpiBox);
injectTocTop("live-indicator", _liveEl);

Inter-agent coordination messages. Agents send messages via send_message() MCP tool and read them via get_messages().

Unread

function fmtDate(s) {
  if (!s) return "—";
  const d = new Date(s);
  return d.toLocaleDateString() + " " + d.toLocaleTimeString([], {hour: "2-digit", minute: "2-digit"});
}

function renderMessage(m, showMarkRead = false) {
  const isBroadcast = m.to_agent === "broadcast";
  const borderColor = !m.read_at ? "#d97706" : "#6b7280";

  async function onMarkRead() {
    await fetch(`${API}/messages/${m.id}/read`, {method: "PATCH"});
  }

  async function onArchive() {
    await fetch(`${API}/messages/${m.id}/archive`, {method: "PATCH"});
  }

  return html`<div class="msg-card" style="border-left-color:${borderColor}">
    <div class="msg-header">
      <span class="msg-from">${m.from_agent}</span>
      <span class="msg-arrow">→</span>
      <span class="msg-to ${isBroadcast ? 'msg-broadcast' : ''}">${m.to_agent}</span>
      <span class="msg-time">${fmtDate(m.created_at)}</span>
      <div class="msg-actions">
        ${showMarkRead ? html`<button class="msg-btn msg-btn-read" onclick=${onMarkRead}>Mark read</button>` : ""}
        <button class="msg-btn msg-btn-archive" onclick=${onArchive}>Archive</button>
      </div>
    </div>
    <div class="msg-subject">${m.subject}</div>
    <details class="msg-body-wrap">
      <summary>body</summary>
      <pre class="msg-body">${m.body}</pre>
    </details>
    ${m.thread_id ? html`<div class="msg-thread">thread: ${m.thread_id}</div>` : ""}
  </div>`;
}

if (unread.length === 0) {
  display(html`<p class="dim">No unread messages.</p>`);
} else {
  display(html`<div class="msg-list">${unread.map(m => renderMessage(m, true))}</div>`);
}

Read

if (read.length === 0) {
  display(html`<p class="dim">No read messages.</p>`);
} else {
  display(html`<div class="msg-list">${read.map(m => renderMessage(m, false))}</div>`);
}

Archived

if (archived.length === 0) {
  display(html`<p class="dim">No archived messages.</p>`);
} else {
  display(html`<div class="msg-list">${archived.map(m => renderMessage(m, false))}</div>`);
}

6.6 KiB Raw Blame History

Agent Inbox

Unread

Read

Archived

6.6 KiB

Raw Blame History