agentmbx

1/**
2 * Claude Code 2.1.291 mod. The hooks sandbox imports nothing but relative
3 * files and "claude-code", and it has no Node built-ins.
4 *
5 * Session id: `session.start` is only `{ cwd }`. The binary sets
6 * `CLAUDE_CODE_SESSION_ID` on the process and on child env, and substitutes
7 * `${CLAUDE_SESSION_ID}`. Those two names are read with `$.env.get` (a string
8 * literal, which `claude plugin validate` can see). If both are missing or
9 * blank, the band says "unbound" and does not call status.
10 *
11 * Status: `$.http.fetch` against the local daemon, keyed by cli and session, asking for
12 * `mbx.status/v2` — the same snapshot the OpenCode sidebar reads. A daemon older than v0.5.17
13 * answers v1; `renderStatus` still tolerates a v1 body, so the band degrades rather than breaks.
14 * Documented init has no timeout; a throw, a non-OK response, or a body that is not an
15 * mbx.status/v1 or v2 snapshot renders "mbx: unavailable".
16 *
17 * Surfaces (T415): the AbovePrompt band shows one compact line with a `●` unread marker;
18 * `/mbx-status` opens a pane (on wide terminals) and always prints the full v2 sections, which
19 * is also the fallback where mods cannot draw (headless `claude -p`, a narrow terminal, or a
20 * render the engine refuses). A 5 s `$.clock.every` timer keeps `$.ui.status` under the prompt
21 * current — the persistent unread indicator — and asks for a redraw.
22 * https://code.claude.com/docs/en/plugins/mods/api
23 */
24
25const DAEMON_ORIGIN = "http://127.0.0.1:7373";
26const CACHE_MS = 2000;
27const PANE_ID = "mbx-status";
28const INDICATOR_MS = 5_000;
29
30/**
31 * @param {Record<string, string | undefined>} env
32 * @returns {string | null}
33 */
34export function resolveSessionId(env) {
35  const code = env.CLAUDE_CODE_SESSION_ID;
36  if (typeof code === "string" && code.trim()) return code.trim();
37  const alias = env.CLAUDE_SESSION_ID;
38  if (typeof alias === "string" && alias.trim()) return alias.trim();
39  return null;
40}
41
42/**
43 * Fixed daemon origin. The session id is only a query value. v2 is requested: the band reads the
44 * same mbx.status/v2 snapshot as the OpenCode sidebar (T414 AC1); renderStatus still tolerates a
45 * v1 body from a daemon older than v0.5.17.
46 * @param {string} sessionId
47 * @returns {string}
48 */
49export function statusRequestUrl(sessionId) {
50  const url = new URL("/v1/status", DAEMON_ORIGIN);
51  url.searchParams.set("cli", "claude");
52  url.searchParams.set("session", sessionId);
53  url.searchParams.set("schema", "mbx.status/v2");
54  if (url.origin !== DAEMON_ORIGIN || url.pathname !== "/v1/status") {
55    throw new Error("status url left the local daemon");
56  }
57  return url.toString();
58}
59
60/**
61 * Render one snapshot. This function does not fetch or derive counts.
62 * A missing session id is "unbound". Anything that is not a v1 or v2
63 * snapshot is "mbx: unavailable".
64 * @param {string | null} sessionId
65 * @param {unknown} snapshot
66 * @returns {string}
67 */
68export function renderStatus(sessionId, snapshot) {
69  if (!sessionId) return "unbound";
70  if (!snapshot || typeof snapshot !== "object") return "mbx: unavailable";
71  const row = /** @type {Record<string, unknown>} */ (snapshot);
72  if (row.schema !== "mbx.status/v1" && row.schema !== "mbx.status/v2") return "mbx: unavailable";
73  const identity = row.identity && typeof row.identity === "object"
74    ? /** @type {Record<string, unknown>} */ (row.identity)
75    : null;
76  if (!identity || identity.state === "unbound" || (identity.state !== "bound" && identity.state !== "ambiguous")) return "unbound";
77  if (identity.state === "ambiguous") return "ambiguous";
78  if (typeof identity.name !== "string" || !identity.name.trim()) return "unbound";
79  const role = typeof identity.role === "string" && identity.role ? ` (${identity.role})` : "";
80  const source = row.inbox && typeof row.inbox === "object"
81    ? /** @type {Record<string, unknown>} */ (row.inbox)
82    : row;
83  const lines = [
84    `mbx ${identity.name.trim()}${role}`,
85    `unread ${count(source.unread)}`,
86    `needs_reply ${count(source.needs_reply)}`,
87    `from_owner ${count(source.from_owner)}`,
88    `outbox_unsent ${count(source.outbox_unsent)}`,
89  ];
90  const policy = policyText(row);
91  if (policy) lines.push(`policy ${policy}`);
92  return lines.join("\n");
93}
94
95/**
96 * v1 carries policy at the top. v2 carries it on harness. Never pick a name from either.
97 * @param {Record<string, unknown>} row
98 * @returns {string}
99 */
100function policyText(row) {
101  const direct = joinPolicy(row.policy);
102  if (direct) return direct;
103  const harness = row.harness && typeof row.harness === "object"
104    ? /** @type {Record<string, unknown>} */ (row.harness)
105    : null;
106  return harness ? joinPolicy(harness.policy) : "";
107}
108
109/**
110 * @param {unknown} value
111 * @returns {string}
112 */
113function joinPolicy(value) {
114  if (typeof value === "string" && value.trim()) return value.trim();
115  if (!Array.isArray(value)) return "";
116  return value.filter((item) => typeof item === "string" && item.trim()).join(", ");
117}
118
119/**
120 * @param {unknown} value
121 * @returns {string}
122 */
123function count(value) {
124  return typeof value === "number" && Number.isFinite(value) ? String(value) : "0";
125}
126
127/**
128 * The one-line under-prompt indicator (`$.ui.status`). Null when there is
129 * nothing worth pinning: unbound, unavailable, or zero unread everywhere.
130 * Pure: renders one fetched snapshot, derives nothing.
131 * @param {unknown} snapshot
132 * @returns {string | null}
133 */
134export function statusLineText(snapshot) {
135  const sections = renderSections(snapshot);
136  if (!sections) return null;
137  const row = /** @type {Record<string, unknown>} */ (snapshot);
138  const inbox = row.inbox && typeof row.inbox === "object"
139    ? /** @type {Record<string, unknown>} */ (row.inbox)
140    : row;
141  const unread = typeof inbox.unread === "number" ? inbox.unread : 0;
142  const needsReply = typeof inbox.needs_reply === "number" ? inbox.needs_reply : 0;
143  const fromOwner = typeof inbox.from_owner === "number" ? inbox.from_owner : 0;
144  if (!unread && !needsReply && !fromOwner) return null;
145  const seg = [`${unread}↑`];
146  if (needsReply) seg.push(`${needsReply}↺`);
147  if (fromOwner) seg.push(`owner:${fromOwner}`);
148  return `mbx: ${seg.join(" ")}`;
149}
150
151/**
152 * The compact band line, with the unread marker T415 AC2 asks for: a `●`
153 * prefix while the fetched snapshot has unread mail. Pure.
154 * @param {string | null} sessionId
155 * @param {unknown} snapshot
156 * @returns {string}
157 */
158export function bandText(sessionId, snapshot) {
159  const text = renderStatus(sessionId, snapshot);
160  if (text.startsWith("mbx ") && statusLineText(snapshot)) return `● ${text}`;
161  return text;
162}
163
164/**
165 * One line per v2 section: identity, registration + lease, inbox, harness,
166 * cloud, devices, project (T415 AC1). The renderer is pure and derives
167 * nothing — every value is read from the one fetched snapshot. Returns null
168 * for a v1 body (the pane is a v2 surface; v1 falls back to the compact
169 * render) and for anything that is not a status snapshot.
170 * @param {unknown} snapshot
171 * @returns {string[] | null}
172 */
173export function renderSections(snapshot) {
174  if (!snapshot || typeof snapshot !== "object") return null;
175  const row = /** @type {Record<string, unknown>} */ (snapshot);
176  if (row.schema !== "mbx.status/v2") return null;
177  const identity = row.identity && typeof row.identity === "object"
178    ? /** @type {Record<string, unknown>} */ (row.identity)
179    : null;
180  const state = identity?.state;
181  if (!identity || state === "unbound") return ["mbx unbound"];
182  if (state === "ambiguous") {
183    const candidates = Array.isArray(identity.candidates) ? identity.candidates.length : 0;
184    return [`mbx ambiguous (${candidates} candidates)`];
185  }
186  if (state !== "bound" || typeof identity.name !== "string" || !identity.name.trim()) return ["mbx unbound"];
187  const role = typeof identity.role === "string" && identity.role ? `(${identity.role})` : "";
188  const lines = [`identity ${identity.name.trim()}${role}`];
189
190  const registration = row.registration && typeof row.registration === "object"
191    ? /** @type {Record<string, unknown>} */ (row.registration)
192    : null;
193  const lease = registration?.lease && typeof registration.lease === "object"
194    ? /** @type {Record<string, unknown>} */ (registration.lease)
195    : null;
196  lines.push(lease
197    ? `registration ${registration?.registered === true ? "registered" : "unregistered"} · lease ${String(lease.holder_cli)}/${String(lease.holder_session)}${lease.verified === true ? " verified" : " unverified"}`
198    : `registration ${registration?.registered === true ? "registered" : "not registered"} · no lease`);
199
200  const inbox = row.inbox && typeof row.inbox === "object"
201    ? /** @type {Record<string, unknown>} */ (row.inbox)
202    : {};
203  lines.push(`inbox ${count(inbox.unread)} unread · ${count(inbox.needs_reply)} needs reply · ${count(inbox.from_owner)} from owner · ${count(inbox.outbox_unsent)} unsent`);
204
205  const harness = row.harness && typeof row.harness === "object"
206    ? /** @type {Record<string, unknown>} */ (row.harness)
207    : null;
208  if (harness) {
209    const policy = joinPolicy(harness.policy);
210    const wake = typeof harness.wake_path === "string" ? harness.wake_path : "none";
211    lines.push(`harness ${String(harness.cli)} ${String(harness.session_id ?? "—")} · wake ${wake}${policy ? ` · policy ${policy}` : ""}`);
212  }
213
214  const cloud = row.cloud && typeof row.cloud === "object"
215    ? /** @type {Record<string, unknown>} */ (row.cloud)
216    : null;
217  if (cloud) {
218    const relay = cloud.relay && typeof cloud.relay === "object"
219      ? /** @type {Record<string, unknown>} */ (cloud.relay)
220      : null;
221    const relayText = relay?.url
222      ? `relay ${String(relay.state)} (${String(relay.url)})`
223      : `relay ${String(relay?.state ?? "unset")}`;
224    const keyAd = typeof cloud.key_ad_expiry === "string" ? ` · key ad until ${cloud.key_ad_expiry.slice(0, 10)}` : "";
225    const account = typeof cloud.account === "string" ? ` · account ${cloud.account}` : "";
226    lines.push(`cloud ${relayText}${keyAd}${account}`);
227  }
228
229  if (Array.isArray(row.devices)) {
230    if (row.devices.length === 0) lines.push("devices none paired");
231    for (const device of row.devices.slice(0, 8)) {
232      if (device && typeof device === "object") {
233        const d = /** @type {Record<string, unknown>} */ (device);
234        const last = typeof d.last_presence === "string" ? ` · seen ${d.last_presence.slice(0, 16).replace("T", " ")}` : "";
235        lines.push(`device ${String(d.host)} at ${String(d.address)} (${String(d.reachability)})${last}`);
236      }
237    }
238  }
239
240  const project = row.project && typeof row.project === "object"
241    ? /** @type {Record<string, unknown>} */ (row.project)
242    : null;
243  if (project) {
244    const members = Array.isArray(project.members) ? project.members.filter((m) => typeof m === "string").join(", ") : "";
245    lines.push(`project ${String(project.directory)} · lead ${String(project.lead ?? "—")} · members ${members}`);
246  } else {
247    lines.push("project none");
248  }
249  return lines;
250}
251
252/**
253 * The last snapshot the band or command fetched, keyed by the session it belongs to, for the
254 * pane to render. T308 AC2: never render another session's data — cleared on every failed or
255 * unavailable fetch and on any session-id change, and consumers compare the key.
256 * @type {{ sessionId: string, snapshot: unknown } | null}
257 */
258let lastStatus = null;
259
260/**
261 * The stored snapshot, only when it belongs to the given session; null otherwise.
262 * @param {string | null} sessionId
263 * @returns {unknown}
264 */
265export function currentSnapshot(sessionId) {
266  return sessionId && lastStatus && lastStatus.sessionId === sessionId ? lastStatus.snapshot : null;
267}
268
269/**
270 * @param {{ ok?: boolean, text?: unknown }} response
271 * @param {string} sessionId
272 * @returns {{ text: string, snapshot: unknown, raw: string | null }}
273 */
274function fromResponse(response, sessionId) {
275  if (!response || response.ok !== true || typeof response.text !== "string") {
276    lastStatus = null;
277    return { text: "mbx: unavailable", snapshot: null, raw: null };
278  }
279  try {
280    const snapshot = JSON.parse(response.text);
281    const text = renderStatus(sessionId, snapshot);
282    if (text === "mbx: unavailable") {
283      lastStatus = null;
284      return { text, snapshot: null, raw: null };
285    }
286    lastStatus = { sessionId, snapshot };
287    return { text, snapshot, raw: response.text };
288  } catch {
289    lastStatus = null;
290    return { text: "mbx: unavailable", snapshot: null, raw: null };
291  }
292}
293
294/**
295 * @param {{ sessionId: string | null, fetchImpl?: (url: string) => Promise<{ ok?: boolean, text?: unknown }> }} opts
296 * @returns {Promise<{ text: string, snapshot: unknown, raw: string | null }>}
297 */
298export async function readStatus(opts) {
299  const sessionId = opts.sessionId;
300  if (!sessionId) {
301    lastStatus = null;
302    return { text: "unbound", snapshot: null, raw: null };
303  }
304  if (!opts.fetchImpl) {
305    lastStatus = null;
306    return { text: "mbx: unavailable", snapshot: null, raw: null };
307  }
308  try {
309    const response = await opts.fetchImpl(statusRequestUrl(sessionId));
310    return fromResponse(response, sessionId);
311  } catch {
312    lastStatus = null;
313    return { text: "mbx: unavailable", snapshot: null, raw: null };
314  }
315}
316
317/** @type {{ sessionId: string, at: number, raw: string } | null} */
318let cache = null;
319
320/**
321 * @param {Record<string, string | undefined>} env
322 * @param {{ fetchImpl?: (url: string) => Promise<{ ok?: boolean, text?: unknown }>, now?: number }} [deps]
323 * @returns {Promise<string>}
324 */
325export async function statusText(env, deps = {}) {
326  const sessionId = resolveSessionId(env);
327  if (!sessionId) return "unbound";
328  const now = deps.now ?? 0;
329  if (cache && cache.sessionId === sessionId && now - cache.at < CACHE_MS) {
330    try {
331      return renderStatus(sessionId, JSON.parse(cache.raw));
332    } catch {
333      cache = null;
334    }
335  }
336  const result = await readStatus({ sessionId, fetchImpl: deps.fetchImpl });
337  if (result.raw) cache = { sessionId, at: now, raw: result.raw };
338  return result.text;
339}
340
341/** Test-only reset so one case cannot reuse another's snapshot. */
342export function resetStatusCache() {
343  cache = null;
344}
345
346/**
347 * @param {unknown} value
348 * @returns {string}
349 */
350function envString(value) {
351  return typeof value === "string" ? value : "";
352}
353
354/**
355 * Production read. `$` stays on this top-level function so `claude plugin validate`
356 * sees `$.env.get`, `$.clock.now`, and `$.http.fetch`.
357 * @param {{ env: { get: (name: string) => Promise<unknown> }, clock: { now: () => Promise<number> }, http: { fetch: (url: string) => Promise<{ ok?: boolean, text?: unknown }> } }} $
358 * @returns {Promise<{ band: string, sections: string[], snapshot: unknown }>}
359 */
360export async function loadStatus($) {
361  const env = {
362    CLAUDE_CODE_SESSION_ID: envString(await $.env.get("CLAUDE_CODE_SESSION_ID")),
363    CLAUDE_SESSION_ID: envString(await $.env.get("CLAUDE_SESSION_ID")),
364  };
365  const sessionId = resolveSessionId(env);
366  const now = await $.clock.now();
367  const band = await statusText(env, {
368    now: typeof now === "number" ? now : 0,
369    fetchImpl: (url) => $.http.fetch(url),
370  });
371  // the snapshot belongs to this session only (currentSnapshot keys by id; failures clear it)
372  const snapshot = currentSnapshot(sessionId);
373  const sections = renderSections(snapshot) ?? [band];
374  return { band, sections, snapshot };
375}
376
377/** Test-only reset so one case cannot reuse another's snapshot. */
378export function resetStatusState() {
379  resetStatusCache();
380  lastStatus = null;
381}
382
383/**
384 * Claude Code mod entry. Draws the AbovePrompt band, answers /mbx-status, and
385 * renders the full v2 sections in a pane the command opens.
386 * @param {(event: string, matcherOrHook: unknown, hook?: unknown) => unknown} on
387 */
388export function register(on) {
389  on("session.start", async ($, e, next) => {
390    await $.command.register({
391      name: "mbx-status",
392      description: "Show this session's AgentMBX status",
393    });
394    // The persistent unread indicator (T415 AC2): poll the same endpoint the band uses and
395    // keep one line under the prompt current; the invalidate keeps band and pane fresh. The
396    // callback closes over `$` (documented for timers); a failed poll leaves the old line.
397    $.clock.every(INDICATOR_MS, async () => {
398      try {
399        const { snapshot } = await loadStatus($);
400        const line = statusLineText(snapshot);
401        if (line) $.ui.status(line);
402        $.ui.invalidate("ui.render");
403      } catch { /* next tick */ }
404    });
405    return next(e);
406  });
407
408  on("command.run", { command: "mbx-status" }, async ($) => {
409    try {
410      const { sections } = await loadStatus($);
411      // The pane is the visual surface; the printed sections are the same content, so a session
412      // where mods cannot draw (headless, narrow terminal) still gets the full answer (AC3).
413      try {
414        const placed = await $.ui.open({ id: PANE_ID, title: "MBX", closeOnEscape: true });
415        if (placed && placed.isPlaced === false) {
416          $.ui.toast(`mbx: pane waiting for a wider terminal (${placed.reason ?? "narrow"}); the sections print below`);
417        }
418      } catch { /* pane unavailable: the printed sections below are the fallback */ }
419      return { text: sections.join("\n") };
420    } catch {
421      return { text: "mbx: unavailable" };
422    }
423  });
424
425  on("ui.render", { component: "AbovePrompt" }, async ($, e, next) => {
426    try {
427      if (e?.props?.hasSurvey) return next(e);
428      const { Text } = $.ui.resolve(e);
429      const env = {
430        CLAUDE_CODE_SESSION_ID: envString(await $.env.get("CLAUDE_CODE_SESSION_ID")),
431        CLAUDE_SESSION_ID: envString(await $.env.get("CLAUDE_SESSION_ID")),
432      };
433      const now = await $.clock.now();
434      await statusText(env, {
435        now: typeof now === "number" ? now : 0,
436        fetchImpl: (url) => $.http.fetch(url),
437      });
438      const sid = resolveSessionId(env);
439      return Text({ children: [bandText(sid, currentSnapshot(sid))] });
440    } catch {
441      return next(e);
442    }
443  });
444
445  on("ui.render", { component: "Pane" }, async ($, e, next) => {
446    try {
447      if (e.requestId !== PANE_ID) return next(e);
448      const { Box, Text } = $.ui.resolve(e);
449      // The pane must never show another session's snapshot either: resolve the current
450      // session id and read only the snapshot stored under it (T308 AC2).
451      const env = {
452        CLAUDE_CODE_SESSION_ID: envString(await $.env.get("CLAUDE_CODE_SESSION_ID")),
453        CLAUDE_SESSION_ID: envString(await $.env.get("CLAUDE_SESSION_ID")),
454      };
455      const sid = resolveSessionId(env);
456      const sections = renderSections(currentSnapshot(sid)) ?? ["mbx: unavailable"];
457      return Box({
458        flexDirection: "column",
459        children: sections.map((line, i) => Text({ key: `s${i}`, children: [line] })),
460      });
461    } catch {
462      return next(e);
463    }
464  });
465}
466