agent-coord-mcp 0.19.1 → 0.24.0

package/src/tools/messaging.ts

@@ -1,6 +1,6 @@
 import { adjustCursors } from "./admin.js";
 import { RECORD_AUTHORITY, resolveRole, roleMatches } from "../roles.js";
-import { ARCHIVE_STATUS_FILE, archiveJsonl, archiveInboxFile, archiveRoomFile } from "../store.js";
+import { ARCHIVE_STATUS_FILE, ARCHIVE_INBOX_DIR, ARCHIVE_ROOMS_DIR, archiveJsonl, archiveInboxFile, archiveRoomFile } from "../store.js";
 import { randomUUID } from "node:crypto";
 import { existsSync, openSync, watch } from "node:fs";
 import { promises as fsp } from "node:fs";
@@ -168,8 +168,40 @@ export const sendMessageSchema = {
   text: z.string().min(1).optional(),
   kind: z.enum(["decision", "status", "chatter"]).optional(),
   record: messageRecordSchema.optional(),
+  // Additive reply link. Validated in the tool (malformed → {ok:false};
+  // unknown → store + warn) so the rejection shape matches identity-binding
+  // / unknown-recipient, not a schema throw. Existing records unchanged.
+  inReplyTo: z.string().optional(),
 };
 
+const MESSAGE_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+async function messageIdExists(id: string): Promise<boolean> {
+  const files: string[] = [];
+  for (const n of await listInboxFiles()) files.push(path.join(INBOX_DIR, n));
+  files.push(ROOM_FILE);
+  if (existsSync(ROOMS_DIR)) {
+    for (const n of await fsp.readdir(ROOMS_DIR)) {
+      if (n.endsWith(".jsonl")) files.push(path.join(ROOMS_DIR, n));
+    }
+  }
+  if (existsSync(ARCHIVE_INBOX_DIR)) {
+    for (const n of await fsp.readdir(ARCHIVE_INBOX_DIR)) {
+      if (n.endsWith(".jsonl")) files.push(path.join(ARCHIVE_INBOX_DIR, n));
+    }
+  }
+  if (existsSync(ARCHIVE_ROOMS_DIR)) {
+    for (const n of await fsp.readdir(ARCHIVE_ROOMS_DIR)) {
+      if (n.endsWith(".jsonl")) files.push(path.join(ARCHIVE_ROOMS_DIR, n));
+    }
+  }
+  for (const f of files) {
+    const entries = await readJsonl<Message>(f);
+    if (entries.some((m) => m.id === id)) return true;
+  }
+  return false;
+}
+
 export async function sendMessageTool(args: {
   from: string;
   to?: string;
@@ -177,6 +209,7 @@ export async function sendMessageTool(args: {
   text?: string;
   kind?: "decision" | "status" | "chatter";
   record?: MessageRecord;
+  inReplyTo?: string;
 }) {
   // Record authority first — a sender who may not emit this type is refused
   // before any other check runs, so a rejected record writes nothing anywhere.
@@ -211,6 +244,28 @@ export async function sendMessageTool(args: {
     };
   }
 
+  let replyWarning: string | undefined;
+  if (args.inReplyTo !== undefined) {
+    if (!MESSAGE_ID_RE.test(args.inReplyTo)) {
+      return {
+        ok: false as const,
+        error: `inReplyTo '${args.inReplyTo}' is not a message id (expected uuid)`,
+      };
+    }
+    if (!(await messageIdExists(args.inReplyTo))) {
+      replyWarning =
+        `inReplyTo '${args.inReplyTo}' is not a known message — reply stored but no matching parent may exist`;
+    }
+  }
+
+  // The tmux pusher's injection guard (hooks/tmux-pusher.mjs `shouldInject`)
+  // never types leading-slash text into a pane — only `send_command`'s
+  // allowlist goes in raw. The message is still stored and readable, so say so
+  // here instead of letting the sender assume it landed on screen.
+  const slashWarning = /^\s*\//.test(text)
+    ? "text starts with '/' — stored, but tmux-push transports never type leading-slash text into a pane (injection guard); prefix it (e.g. `AGENT_ACTION: run /<skill> …`) or use `send_command` for /clear and /compact"
+    : undefined;
+
   // DM → inbox. Otherwise resolve the channel (default `general`), make sure it
   // exists in the registry, and tag the message with its channel.
   if (args.to) {
@@ -221,6 +276,7 @@ export async function sendMessageTool(args: {
       to: args.to,
       text,
       ...(args.record ? { record: args.record } : {}),
+      ...(args.inReplyTo ? { inReplyTo: args.inReplyTo } : {}),
     };
     const target = inboxFile(args.to);
     await appendJsonl(target, msg);
@@ -228,9 +284,10 @@ export async function sendMessageTool(args: {
     // typo'd recipient shouldn't vanish silently — surface a warning when the
     // target isn't a known agent so the caller can catch the mistake.
     const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
-    const warning = reg[args.to]
+    const recipientWarning = reg[args.to]
       ? undefined
       : `recipient '${args.to}' is not a registered agent — message stored in their inbox but no one may be listening`;
+    const warning = [recipientWarning, replyWarning, slashWarning].filter(Boolean).join("; ") || undefined;
     return { ok: true, id: msg.id, target, room: undefined, warning };
   }
 
@@ -244,11 +301,13 @@ export async function sendMessageTool(args: {
     text,
     ...(args.kind ? { kind: args.kind } : {}),
     ...(args.record ? { record: args.record } : {}),
+    ...(args.inReplyTo ? { inReplyTo: args.inReplyTo } : {}),
   };
   const target = roomFile(chan);
   await appendJsonl(target, msg);
   await maybeCompactRoom(chan);
-  return { ok: true, id: msg.id, target, room: chan };
+  const roomWarning = [replyWarning, slashWarning].filter(Boolean).join("; ") || undefined;
+  return { ok: true, id: msg.id, target, room: chan, ...(roomWarning ? { warning: roomWarning } : {}) };
 }
 
 // ---------- live compaction (self-limiting streams) ----------

package/src/tools/render.ts

@@ -1,80 +1 @@
-// Typed record → the text layout the fleet already reads (Phase 8 Task 3.3).
-//
-// Every consumer downstream of a message — hooks/tier.mjs's prefix table, the
-// UI's alert parser, a human reading a tmux pane — reads `text`. Phase 8 adds
-// `record` alongside it, so the rendering must reproduce the byte layout those
-// consumers already expect. Nothing downstream changes while agents migrate.
-//
-// This is a pure function of the record: no clock, no I/O, no registry. It
-// never sees `from`, `to`, or anything the sender could use it to forge.
-
-import type { DecisionPayload, MessageRecord, SummaryPayload, VerdictPayload } from "./shared.js";
-
-// The case-sensitive prefixes at byte 0 of `text`, exactly as classifyTier
-// matches them. `decision` is absent because it renders as a multi-line block,
-// not a one-liner.
-const PREFIX: Record<string, string> = {
-  blocker: "BLOCKER",
-  risk: "RISK",
-  done: "DONE",
-  fyi: "FYI",
-  action: "AGENT_ACTION",
-  go: "GO",
-  scope: "SCOPE CHANGE",
-  // `verdict` has no prefix in the v1 vocabulary — it is new in Phase 8. A gate
-  // PASS/FAIL was previously posted as prose, which is why verdicts could not
-  // be routed. Rendering it under its own prefix gives it one.
-  verdict: "VERDICT",
-};
-
-function isNonEmpty(v: unknown): v is string {
-  return typeof v === "string" && v.trim().length > 0;
-}
-
-// The playbook's decision packet (§Decision Packet Format), byte-for-byte —
-// the UI parses this into a clickable decision card, and a layout that drifts
-// still alerts loudly but loses the card. Returns null when any of the five
-// fields is missing, so the caller can reject rather than emit a half packet.
-function renderDecision(p: DecisionPayload): string | null {
-  if (!isNonEmpty(p.title) || !isNonEmpty(p.context)) return null;
-  if (!isNonEmpty(p.recommendation) || !isNonEmpty(p.ifNoAction)) return null;
-  if (!Array.isArray(p.options) || p.options.length === 0) return null;
-  if (!p.options.every(isNonEmpty)) return null;
-  return [
-    `DAVID_DECISION: ${p.title}`,
-    `Context: ${p.context}`,
-    "Options:",
-    ...p.options.map((o, i) => `${i + 1}. ${o}`),
-    `Recommendation: ${p.recommendation}`,
-    `If no action: ${p.ifNoAction}`,
-  ].join("\n");
-}
-
-// `VERDICT: PASS <sha> — <notes>`. The sha is not optional in the rendering:
-// a verdict that doesn't name the commit it was issued against is
-// unfalsifiable the moment the branch moves.
-function renderVerdict(p: VerdictPayload): string | null {
-  if (p.result !== "pass" && p.result !== "fail") return null;
-  if (!isNonEmpty(p.headRefOid)) return null;
-  const head = `${PREFIX.verdict}: ${p.result.toUpperCase()} ${p.headRefOid}`;
-  return isNonEmpty(p.notes) ? `${head} — ${p.notes}` : head;
-}
-
-// Render a record to its text form, or null when the payload can't support one
-// (absent, or missing a field the layout needs). Null is not an error here —
-// the caller decides whether a record without a rendering is fatal, and it only
-// is when there's no author-supplied `text` to fall back on.
-export function renderRecord(record: MessageRecord): string | null {
-  if (!record || typeof record.type !== "string") return null;
-  const payload = record.payload as unknown;
-  if (payload === undefined || payload === null) return null;
-  if (typeof payload !== "object" || Array.isArray(payload)) return null;
-
-  if (record.type === "decision") return renderDecision(payload as DecisionPayload);
-  if (record.type === "verdict") return renderVerdict(payload as VerdictPayload);
-
-  const prefix = PREFIX[record.type];
-  if (!prefix) return null;
-  const { summary } = payload as SummaryPayload;
-  return isNonEmpty(summary) ? `${prefix}: ${summary}` : null;
-}
+export { renderRecord, PREFIX } from "@davidbalzan/groundwork-seam/protocol";

package/src/tools/shared.ts

@@ -1,3 +1,12 @@
+import type {
+  Citation,
+  DecisionPayload,
+  MessageRecord,
+  MessageRecordType,
+  SummaryPayload,
+  SummaryRecordType,
+  VerdictPayload,
+} from "@davidbalzan/groundwork-seam/protocol";
 import { randomUUID } from "node:crypto";
 import { existsSync, openSync, watch } from "node:fs";
 import { promises as fsp } from "node:fs";
@@ -92,82 +101,16 @@ export type TransportMarker = {
 
 export type AgentRegistry = Record<string, AgentEntry>;
 
-// Where a claim can be independently verified. The point is that a consumer
-// resolves the ref (gh, git, fs) instead of trusting the message body — a
-// `done` record whose PR ref doesn't exist is a false claim, not a typo.
-export type Citation = {
-  kind: "pr" | "file" | "commit" | "url";
-  ref: string;
+export type {
+  Citation,
+  MessageRecordType,
+  DecisionPayload,
+  VerdictPayload,
+  SummaryPayload,
+  SummaryRecordType,
+  MessageRecord,
 };
 
-// The protocol vocabulary the fleet already speaks. Today these live as
-// case-sensitive prefixes at byte 0 of `text` (hooks/tier.mjs), parsed a
-// second time by the UI for alert priority — so a greeting before the prefix
-// silently downgrades a production blocker, and the two parsers can disagree
-// about the same message. As a field there is nothing to mis-parse.
-export type MessageRecordType =
-  | "blocker"   // BLOCKER:        work cannot continue
-  | "decision"  // DAVID_DECISION: the human must decide
-  | "risk"      // RISK:           quality/security/cost/product risk
-  | "done"      // DONE:           completed work, must cite
-  | "fyi"       // FYI:            no action needed
-  | "action"    // AGENT_ACTION:   another agent can handle it
-  | "go"        // GO:             a work order
-  | "scope"     // SCOPE CHANGE:   amends a contract in flight
-  | "verdict";  // (new) a gate PASS/FAIL — has no prefix today
-
-// The five fields of the playbook's decision packet (§Decision Packet Format).
-// Named to match that layout because `renderRecord` reproduces it byte-for-byte
-// — the UI parses the rendering into a clickable decision card.
-export type DecisionPayload = {
-  title: string;
-  context: string;
-  options: string[];
-  recommendation: string;
-  ifNoAction: string;
-};
-
-// A gate verdict. `headRefOid` pins WHICH commit was gated: a PASS that doesn't
-// name the sha it was issued against is unfalsifiable once the branch moves.
-export type VerdictPayload = {
-  result: "pass" | "fail";
-  headRefOid: string;
-  notes?: string;
-};
-
-// Everything else carries prose. One line, because these render as
-// `<PREFIX>: <summary>` and a paragraph in a tmux pane is a wall, not a status.
-export type SummaryPayload = { summary: string };
-
-// Message types whose payload is just a summary.
-export type SummaryRecordType = "blocker" | "risk" | "fyi" | "action" | "go" | "scope";
-
-// Structured counterpart to `text`, NOT a replacement: `text` is the rendering,
-// and a tmux pane can only receive text. A v1 agent that has never heard of
-// `record` omits it entirely and behaves byte-identically.
-//
-// `payload` stays OPTIONAL on every arm — Phase 8 is additive, so no new
-// required field may appear on the wire. What is pinned is the shape *if* a
-// payload is supplied: a `decision` carrying three of its five fields is
-// structurally wrong for the type it claims and is rejected, while a payload
-// with extra unknown keys passes through untouched (a v3 sender must not be
-// broken by a v2 server, and stripping would silently drop data on the way to
-// disk).
-//
-// `cites` is likewise optional here. `done` requires a PR citation, but that is
-// enforced in sendMessageTool as a plain {ok:false,error} rather than a schema
-// rejection — see the identity-binding precedent in src/server.ts.
-//
-// UNTRUSTED, exactly like `from`. A peer can claim any type here, so trust
-// decisions (the SCOPE countersignature, gate-runner routing) must still
-// resolve the sender against the registry — typed is not the same as
-// authenticated, and `record` must never become a path to setting `urgent`.
-export type MessageRecord =
-  | { type: "decision"; payload?: DecisionPayload; cites?: Citation[] }
-  | { type: "verdict"; payload?: VerdictPayload; cites?: Citation[] }
-  | { type: "done"; payload?: SummaryPayload; cites?: Citation[] }
-  | { type: SummaryRecordType; payload?: SummaryPayload; cites?: Citation[] };
-
 export type Message = {
   id: string;
   ts: number;
@@ -198,6 +141,10 @@ export type Message = {
   kind?: "decision" | "status" | "chatter";
   // Typed protocol record (Phase 8). Optional and additive; see MessageRecord.
   record?: MessageRecord;
+  // Additive reply link (optional). A DM that answers a DAVID_DECISION
+  // (or any other message) carries the parent message id so consumers can
+  // mark the packet answered. Absent on every v1/v2 message — those stay valid.
+  inReplyTo?: string;
 };
 
 // THE retention predicate — one definition, three call sites (prune,
@@ -215,9 +162,7 @@ export type Message = {
 //
 // Deliberately structural about `record`: it takes anything with the two
 // fields, so status entries and archive rows can be passed without a cast.
-export function isDecision(e: { kind?: string; record?: { type?: string } } | null | undefined): boolean {
-  return e?.kind === "decision" || e?.record?.type === "decision";
-}
+export { isDecision } from "@davidbalzan/groundwork-seam/protocol";
 
 export type StatusEntry = {
   id: string;

package/src/tools/transport.ts

@@ -5,7 +5,7 @@ import { roleInputSchema, type RoleArg } from "../roles.js";
 import { attributeWriter, isGitRepo, lastWriterOf, loadScopes, ownsDocument } from "./scopes.js";
 import { sendMessageTool, readMessagesTool } from "./messaging.js";
 import { randomUUID } from "node:crypto";
-import { existsSync, openSync, watch } from "node:fs";
+import { existsSync, openSync, readFileSync, watch } from "node:fs";
 import { promises as fsp } from "node:fs";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -699,6 +699,63 @@ function resolvePusherPath(): string {
   return path.resolve(here, "..", "..", "hooks", "tmux-pusher.mjs");
 }
 
+/** Running server package + optional git identity. `fromDir` is a test seam. */
+export function resolveServerIdentity(fromDir?: string): {
+  path: string;
+  version: string;
+  branch?: string;
+  sha?: string;
+} {
+  const start = fromDir ?? path.dirname(fileURLToPath(import.meta.url));
+  let dir = start;
+  let pkgFile: string | undefined;
+  for (let i = 0; i < 8; i++) {
+    const candidate = path.join(dir, "package.json");
+    if (existsSync(candidate)) {
+      pkgFile = candidate;
+      break;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  const pkgPath = pkgFile ?? path.resolve(start, "..", "..", "package.json");
+  const pkgDir = path.dirname(pkgPath);
+  let version = "unknown";
+  try {
+    const raw = JSON.parse(readFileSync(pkgPath, "utf8")) as { version?: string };
+    if (typeof raw.version === "string" && raw.version) version = raw.version;
+  } catch {
+    /* leave unknown — never invent a version */
+  }
+
+  const out: { path: string; version: string; branch?: string; sha?: string } = {
+    path: pkgDir,
+    version,
+  };
+
+  dir = pkgDir;
+  let gitRoot: string | undefined;
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(path.join(dir, ".git"))) {
+      gitRoot = dir;
+      break;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  if (gitRoot && isGitRepo(gitRoot)) {
+    const branch = spawnSync("git", ["-C", gitRoot, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+    const sha = spawnSync("git", ["-C", gitRoot, "rev-parse", "HEAD"], { encoding: "utf8" });
+    const b = branch.status === 0 ? String(branch.stdout).trim() : "";
+    const s = sha.status === 0 ? String(sha.stdout).trim() : "";
+    if (b) out.branch = b;
+    if (s) out.sha = s;
+  }
+  return out;
+}
+
 // Freshness basis for the stale-pusher-script mechanism: the newest mtime
 // across the pusher's source dir (hooks/*.mjs), NOT just the entry file. The
 // pusher imports submit.mjs / tier.mjs / roles.mjs, so a fix touching only an
@@ -1586,18 +1643,34 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
     });
   }
 
-  // 10. Environment sanity. Report only.
+  // 10. Environment sanity. Report only. Path + version come from the running
+  // module's package.json so a stale/decoy bin is named (LESSONS #35). Git
+  // identity is walk-up-to-.git + rev-parse (kit monorepo root); omitted
+  // entirely when there is no checkout — never invented.
   {
     const tmuxProbe = spawnSync("tmux", ["-V"]);
     const tmuxOk = tmuxProbe.status === 0;
+    const ident = resolveServerIdentity();
+    const loc = ident.branch && ident.sha
+      ? `path=${ident.path} version=${ident.version} ${ident.branch}@${ident.sha.slice(0, 12)}`
+      : `path=${ident.path} version=${ident.version}`;
+    const items = [
+      `root=${ROOT}`,
+      `execPath=${process.execPath}`,
+      `inTmux=${!!process.env.TMUX_PANE}`,
+      `path=${ident.path}`,
+      `version=${ident.version}`,
+    ];
+    if (ident.branch) items.push(`branch=${ident.branch}`);
+    if (ident.sha) items.push(`sha=${ident.sha}`);
     findings.push({
       check: "environment",
       level: tmuxOk ? "ok" : "warn",
       detail: tmuxOk
-        ? `root=${ROOT}; node=${process.execPath}; tmux=${(tmuxProbe.stdout ?? "").toString().trim() || "present"}`
-        : `root=${ROOT}; node=${process.execPath}; tmux NOT on PATH — the tmux-push transport will not work`,
+        ? `root=${ROOT}; node=${process.execPath}; ${loc}; tmux=${(tmuxProbe.stdout ?? "").toString().trim() || "present"}`
+        : `root=${ROOT}; node=${process.execPath}; ${loc}; tmux NOT on PATH — the tmux-push transport will not work`,
       fixable: false,
-      items: [`root=${ROOT}`, `execPath=${process.execPath}`, `inTmux=${!!process.env.TMUX_PANE}`],
+      items,
     });
   }