agentmash 0.3.0

package/mcp/render.mjs

@@ -0,0 +1,358 @@
+// Turning coordination-server payloads into text an agent can act on.
+//
+// Two rules shape everything here:
+//
+//   1. An empty room and an unreachable server must never read the same. The
+//      first is an answer; the second is the absence of one, and saying
+//      "nobody is working on anything" when we simply could not ask is the
+//      single worst thing these tools could do.
+//   2. The agent is the reader. Prose beats a row dump — it says who, what
+//      they are doing, on which branch, and what to do about it.
+
+import { normalizePath } from './coordination.mjs';
+
+const MAX_SESSIONS = 12;
+const MAX_FILES_PER_SESSION = 8;
+const MAX_CONTESTED = 20;
+/** /activity caps its event list; past this we can't promise the window is complete. */
+const EVENT_PAGE_SIZE = 150;
+
+export function ago(iso) {
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return 'recently';
+  const minutes = Math.max(0, Math.round((Date.now() - then) / 60_000));
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return `${minutes} min ago`;
+  const hours = Math.round(minutes / 60);
+  return hours < 24 ? `${hours} h ago` : `${Math.round(hours / 24)} d ago`;
+}
+
+function windowText(minutes) {
+  return minutes < 120 ? `${minutes} min` : `${Math.round(minutes / 60)} hours`;
+}
+
+function roomName(data, coordination) {
+  return data?.label ? `"${data.label}"` : `room ${coordination.room}`;
+}
+
+function truncationNote(data) {
+  return Array.isArray(data?.events) && data.events.length >= EVENT_PAGE_SIZE
+    ? '\nThis room is busy enough that the server truncated its event list, so the picture may be partial.'
+    : '';
+}
+
+/**
+ * What a tool says when it could not get an answer. Every branch states the
+ * failure, then states explicitly that the correct reading is "unknown".
+ */
+export function renderUnavailable(coordination, answer, subject) {
+  const unknown =
+    `Treat ${subject} as UNKNOWN. This is not the same as "nobody is working on anything" — ` +
+    'AgentMash could not ask. Carry on as you would without it, and be careful with files that look shared.';
+
+  switch (answer.reason) {
+    case 'disabled':
+      return (
+        'AgentMash is switched off in this environment (AGENTMASH_DISABLE=1), so no coordination data is ' +
+        `available.\n\n${unknown}`
+      );
+    case 'not_configured':
+      return (
+        'This repo is not connected to an AgentMash room: no room id in .claude/agentmash/config.json and no ' +
+        `AGENTMASH_ROOM in the environment.\n\n${unknown}\n\n` +
+        'Someone on the team can connect it with `npx agentmash init` (or `npx agentmash join <id>`), commit ' +
+        '.claude/, and everyone else picks it up on the next pull.'
+      );
+    case 'timeout':
+      return (
+        `The AgentMash coordination server at ${coordination.url} did not answer within ` +
+        `${coordination.timeoutMs} ms.\n\n${unknown}`
+      );
+    case 'unauthorized':
+      return (
+        `The AgentMash coordination server at ${coordination.url} does not recognise room ` +
+        `${coordination.room}. The room may have been reset, or this repo's config may point at the wrong ` +
+        `server.\n\n${unknown}\n\n\`npx agentmash doctor\` will say which.`
+      );
+    default:
+      return (
+        `The AgentMash coordination server at ${coordination.url} is unreachable ` +
+        `(${answer.detail}).\n\n${unknown}`
+      );
+  }
+}
+
+function describeSession(session, coordination) {
+  const you = session.developer === coordination.developer ? ' (you)' : '';
+  const branch = session.git_branch ? ` · branch ${session.git_branch}` : '';
+  const ended = session.ended ? ' · session has ended' : '';
+  const lines = [`${session.developer}${you} — last edit ${ago(session.last_touched)}${branch}${ended}`];
+  if (session.task_hint) lines.push(`  working on: "${session.task_hint}"`);
+
+  const files = Array.isArray(session.files) ? session.files : [];
+  if (files.length) {
+    const shown = files.slice(0, MAX_FILES_PER_SESSION).map((f) => {
+      return f.change_summary ? `${f.file_path} (${f.change_summary})` : f.file_path;
+    });
+    const more = files.length - shown.length;
+    lines.push(`  touched: ${shown.join(', ')}${more > 0 ? ` and ${more} more` : ''}`);
+  }
+  return lines.join('\n');
+}
+
+export function renderWhoIsWorking(data, coordination, { minutes, includeSelf }) {
+  const all = Array.isArray(data?.sessions) ? data.sessions : [];
+  const sessions = includeSelf ? all : all.filter((s) => s.developer !== coordination.developer);
+  const room = roomName(data, coordination);
+
+  if (sessions.length === 0) {
+    return (
+      `Nobody${includeSelf ? '' : ' else'} has been active in ${room} in the last ${windowText(minutes)}. ` +
+      'The coordination server answered normally, so this is a real "no one", not a failure to reach it.\n\n' +
+      `You are ${coordination.developer}. Teammates who are idle, or who were working before this window, ` +
+      'will not appear — call this again with a larger `minutes` to look further back.'
+    );
+  }
+
+  const shown = sessions.slice(0, MAX_SESSIONS);
+  const header =
+    `${sessions.length} ${sessions.length === 1 ? 'person has' : 'people have'} been active in ${room} in the ` +
+    `last ${windowText(minutes)}` +
+    (includeSelf ? '.' : `, not counting you (${coordination.developer}).`);
+
+  const parts = [header, shown.map((s) => describeSession(s, coordination)).join('\n\n')];
+  if (sessions.length > shown.length) parts.push(`…and ${sessions.length - shown.length} more.`);
+
+  // Stated intent sits beside observed activity: a teammate who has claimed a
+  // module but not written to it yet is exactly who this answer exists to name.
+  const claims = (Array.isArray(data?.claims) ? data.claims : []).filter(
+    (c) => includeSelf || c.developer !== coordination.developer
+  );
+  if (claims.length) {
+    parts.push(
+      'Claimed right now (stated intent, not yet necessarily written):\n' +
+        claims
+          .slice(0, 8)
+          .map((c) => `- ${c.developer}: ${(c.paths || []).slice(0, 3).join(', ')} — "${c.task}"`)
+          .join('\n')
+    );
+  }
+
+  const hot = Array.isArray(data?.hot_files) ? data.hot_files : [];
+  if (hot.length) {
+    const names = hot.slice(0, 5).map((h) => `${h.file_path} (${h.developers.join(', ')})`);
+    parts.push(`Already touched by more than one person: ${names.join('; ')}.`);
+  }
+  parts.push(
+    'Before you edit anything on this list, read what changed there first, and prefer work that does not ' +
+      'reshape the same interfaces.'
+  );
+  return parts.join('\n\n') + truncationNote(data);
+}
+
+/** Matches an exact file, or anything beneath a directory. */
+function underPath(filePath, target) {
+  const file = normalizePath(filePath);
+  return file === target || file.startsWith(`${target}/`);
+}
+
+export function renderPathActivity(data, coordination, { target, minutes, includeSelf }) {
+  const all = Array.isArray(data?.sessions) ? data.sessions : [];
+  const room = roomName(data, coordination);
+  const hits = [];
+  for (const session of all) {
+    if (!includeSelf && session.developer === coordination.developer) continue;
+    const files = (Array.isArray(session.files) ? session.files : []).filter((f) =>
+      underPath(f.file_path, target)
+    );
+    if (files.length) hits.push({ session, files });
+  }
+
+  if (hits.length === 0) {
+    return (
+      `Nobody${includeSelf ? '' : ' else'} has touched \`${target}\` in the last ${windowText(minutes)} ` +
+      `(${room}). The coordination server answered normally, so this is a real "no one".\n\n` +
+      'It is safe to plan work here on that basis, bearing in mind that only edits made through a ' +
+      "teammate's Claude Code agent are reported — hand edits and other tools are invisible to AgentMash."
+    );
+  }
+
+  const people = hits.length === 1 ? '1 person has' : `${hits.length} people have`;
+  const parts = [`${people} touched \`${target}\` in the last ${windowText(minutes)} (${room}).`];
+  for (const { session, files } of hits) {
+    const you = session.developer === coordination.developer ? ' (you)' : '';
+    const branch = session.git_branch ? ` · branch ${session.git_branch}` : '';
+    const task = session.task_hint ? `\n  working on: "${session.task_hint}"` : '';
+    const lines = files
+      .slice(0, MAX_FILES_PER_SESSION)
+      .map((f) => `  ${f.file_path} — ${ago(new Date(f.ts).toISOString())}${f.change_summary ? ` — ${f.change_summary}` : ''}`);
+    parts.push(`${session.developer}${you}${branch}${task}\n${lines.join('\n')}`);
+  }
+  parts.push(
+    'Read their changes before you edit these files, and say so in your plan if your work would collide ' +
+      'with what they are doing.'
+  );
+  return parts.join('\n\n') + truncationNote(data);
+}
+
+// ── claims ─────────────────────────────────────────────────────────────────
+
+function minutesUntil(iso) {
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return null;
+  return Math.max(0, Math.round((then - Date.now()) / 60_000));
+}
+
+function scopeText(paths, max = 4) {
+  const list = Array.isArray(paths) ? paths : [];
+  const shown = list.slice(0, max).join(', ');
+  return list.length > max ? `${shown} and ${list.length - max} more` : shown || 'this scope';
+}
+
+function claimLine(c, coordination) {
+  const you = c.developer === coordination.developer ? ' (you)' : '';
+  const symbols = c.symbols?.length ? ` · symbols ${c.symbols.slice(0, 4).join(', ')}` : '';
+  const left = minutesUntil(c.expires_at);
+  return (
+    `${c.developer}${you} — ${scopeText(c.paths)}${symbols}\n` +
+    `  for: "${c.task}"\n` +
+    `  claimed ${ago(c.created_at)}${left !== null ? `, ${left} min left` : ''}`
+  );
+}
+
+/** What claim_work says back. The overlap branch is the whole point of the tool. */
+export function renderClaimResult(data, coordination, { paths, task }) {
+  const claim = data?.claim;
+  const overlaps = Array.isArray(data?.overlaps) ? data.overlaps : [];
+  const left = minutesUntil(claim?.expires_at);
+  const head =
+    `Claimed ${scopeText(paths)} for "${task}" as ${coordination.developer}` +
+    (claim?.id ? ` (id ${claim.id}${left !== null ? `, ${left} min` : ''}).` : '.');
+
+  if (overlaps.length === 0) {
+    return (
+      head +
+      '\n\nNo one else has claimed anything in this scope. Go ahead. Call release_claim when you finish — ' +
+      'otherwise it lapses on its own, and ends with your session.'
+    );
+  }
+
+  const lines = overlaps.slice(0, 5).map((o) => {
+    const on = o.overlap?.paths?.length
+      ? o.overlap.paths.join(', ')
+      : o.overlap?.symbols?.length
+        ? `the symbols ${o.overlap.symbols.join(', ')}`
+        : 'this scope';
+    return `- ${o.developer} has ${on} for "${o.task}" (claimed ${ago(o.created_at)})`;
+  });
+  return (
+    head +
+    `\n\nOVERLAP — ${overlaps.length === 1 ? 'someone else has' : `${overlaps.length} people have`} already claimed part of this:\n` +
+    lines.join('\n') +
+    '\n\nYour claim stands, but split the work before you write anything: take the files and symbols they ' +
+    'have not claimed, or build on top of what they land rather than changing it. If your task genuinely needs ' +
+    'their scope, say so in your reply so the overlap is visible to both of you, and keep your edits out of the ' +
+    'parts they named.'
+  );
+}
+
+export function renderClaims(data, coordination, { includeSelf }) {
+  const all = Array.isArray(data?.claims) ? data.claims : [];
+  const claims = includeSelf ? all : all.filter((c) => c.developer !== coordination.developer);
+  if (claims.length === 0) {
+    return (
+      `Nothing is claimed right now${includeSelf ? '' : ' by anyone else'} in ${roomName(data, coordination)}. ` +
+      'The coordination server answered normally, so this is a real "nothing", not a failure to reach it.'
+    );
+  }
+  return (
+    `${claims.length} live claim${claims.length === 1 ? '' : 's'}${includeSelf ? '' : ' by other people'}:\n\n` +
+    claims.slice(0, 20).map((c) => claimLine(c, coordination)).join('\n\n') +
+    '\n\nA claim is stated intent, not a lock: work outside these scopes where you can, and build on top of ' +
+    'them where you cannot.'
+  );
+}
+
+// ── collisions ─────────────────────────────────────────────────────────────
+
+/**
+ * get_collisions: the same brief the Stop hook gives, phrased as an answer
+ * rather than an interruption. `brief` is the hooks' buildReconciliationBrief,
+ * passed in so this file stays free of hook imports.
+ */
+export function renderCollisions(data, coordination, { minutes, brief }) {
+  const collisions = Array.isArray(data?.collisions) ? data.collisions : [];
+  const mode = data?.reconcile_mode ?? 'approve';
+  if (collisions.length === 0) {
+    return (
+      `No unresolved collisions involving you (${coordination.developer}) in ${roomName(data, coordination)} in the ` +
+      `last ${windowText(minutes)}. The coordination server answered normally, so this is a real "none", not a ` +
+      'failure to reach it.'
+    );
+  }
+  if (mode === 'off') {
+    return (
+      `${collisions.length} file${collisions.length === 1 ? '' : 's'} you changed ${
+        collisions.length === 1 ? 'was' : 'were'
+      } also changed by a teammate: ${collisions.map((c) => c.file_path).join(', ')}. This room has reconciliation ` +
+      'switched off, so nothing will prompt you about it — but a merge is still coming, and reading their version ' +
+      'first is still the cheap option.'
+    );
+  }
+  const heading =
+    `${collisions.length} unresolved collision${collisions.length === 1 ? '' : 's'} involving you in ` +
+    `${roomName(data, coordination)}:`;
+  return brief({ collisions, mode, showHints: true, heading }) ?? heading;
+}
+
+export function renderResolved(data, { filePath, outcome, url }) {
+  const r = data?.resolution;
+  const how =
+    outcome === 'pr'
+      ? `as a pull request${url ? ` (${url})` : ''}, waiting for a human to approve it`
+      : outcome === 'merged'
+        ? 'as a direct merge'
+        : outcome === 'no_conflict'
+          ? 'as not actually conflicting'
+          : 'as dismissed';
+  const who = Array.isArray(r?.developers) && r.developers.length ? ` between ${r.developers.join(' and ')}` : '';
+  return `Recorded: the collision on ${filePath}${who} is resolved ${how}. The room will not prompt about it again unless someone edits the file after this.`;
+}
+
+export function renderRelease(data, { claimId }) {
+  const n = Number(data?.released ?? 0);
+  if (claimId) {
+    return n > 0 ? `Released ${claimId}.` : `${claimId} was already released or has expired — nothing to do.`;
+  }
+  return n > 0
+    ? `Released ${n} claim${n === 1 ? '' : 's'} held by this session.`
+    : 'This session holds no live claims — nothing to release.';
+}
+
+export function renderContestedFiles(data, coordination, { minutes }) {
+  const hot = Array.isArray(data?.hot_files) ? data.hot_files : [];
+  const room = roomName(data, coordination);
+
+  if (hot.length === 0) {
+    return (
+      `No file in ${room} has been edited by more than one person in the last ${windowText(minutes)}. ` +
+      'The coordination server answered normally, so this is a real "none".\n\n' +
+      'That does not mean the room is idle — use who_is_working_on_what to see who is here.'
+    );
+  }
+
+  const rows = hot.slice(0, MAX_CONTESTED).map((h) => {
+    const who = h.developers.map((d) => (d === coordination.developer ? `${d} (you)` : d));
+    return `  ${h.file_path} — ${who.join(', ')} — last edit ${ago(h.last_touched)}`;
+  });
+  const more = hot.length - rows.length;
+
+  return (
+    `${hot.length} file${hot.length === 1 ? '' : 's'} in ${room} ${hot.length === 1 ? 'has' : 'have'} been ` +
+    `edited by more than one person in the last ${windowText(minutes)}:\n\n${rows.join('\n')}` +
+    (more > 0 ? `\n  …and ${more} more.` : '') +
+    `\n\n${hot.length === 1 ? 'This is where' : 'These are where'} a collision is most likely. Read the ` +
+    'recent changes before editing them, and consider whether your task can avoid them entirely.' +
+    truncationNote(data)
+  );
+}