agent-coord-mcp 0.17.0 → 0.18.0

package/src/tools/registry.ts

@@ -48,6 +48,7 @@ import {
   updateJson,
   type RoomRegistry,
 } from "../store.js";
+import { recordAuthorityFor, resolveRole, roleInputSchema, type RoleArg } from "../roles.js";
 import {
   type AgentEntry,
   type AgentRegistry,
@@ -71,24 +72,82 @@ import {
 export const registerSchema = {
   agentId: z.string().min(1),
   project: z.string().optional(),
-  role: z.string().optional(),
+  role: roleInputSchema.optional(),
 };
 
-export async function registerTool(args: { agentId: string; project?: string; role?: string }) {
+// Work out what `role`/`roleId` should become, or why the update is refused.
+//
+// Rules (Phase 8 Task 4):
+//  - A DECLARED roleId is immutable. Re-declaring the same id is a no-op;
+//    declaring a different one is rejected.
+//  - displayName is always free to change — that is the whole point.
+//  - A plain string never freezes an id (it only sets the display name), so
+//    v1 agents that re-register under changing free text keep working exactly
+//    as before, and their id stays derived.
+export function resolveRoleUpdate(
+  agentId: string,
+  existing: AgentEntry | undefined,
+  input: RoleArg | undefined,
+): { ok: true; role?: string; roleId?: string } | { ok: false; error: string } {
+  if (input === undefined) return { ok: true, role: existing?.role, roleId: existing?.roleId };
+
+  const resolved = resolveRole(typeof input === "string" ? input : { ...input });
+  if (!resolved) return { ok: true, role: existing?.role, roleId: existing?.roleId };
+
+  const declared = typeof input === "object" && !!input.roleId;
+  if (existing?.roleId && declared && resolved.roleId !== existing.roleId) {
+    return {
+      ok: false,
+      error:
+        `roleId '${existing.roleId}' is frozen for agent '${agentId}'; rejected attempt to change it to '${resolved.roleId}'. ` +
+        `The display name is free to change — pass role.displayName instead.`,
+    };
+  }
+
+  // A bare string against an agent with a frozen id updates the name only.
+  const nextRole =
+    typeof input === "string" ? input : input.displayName ?? existing?.role ?? resolved.displayName;
+  return { ok: true, role: nextRole, roleId: declared ? resolved.roleId : existing?.roleId };
+}
+
+export async function registerTool(args: { agentId: string; project?: string; role?: RoleArg }) {
+  const before = await readJson<AgentRegistry>(AGENTS_FILE, {});
+  const roleUpdate = resolveRoleUpdate(args.agentId, before[args.agentId], args.role);
+  if (!roleUpdate.ok) return { ok: false as const, error: roleUpdate.error };
+
   const reg = await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
     const now = Date.now();
     const existing = current[args.agentId];
     current[args.agentId] = {
       agentId: args.agentId,
       project: args.project ?? existing?.project,
-      role: args.role ?? existing?.role,
+      role: roleUpdate.role,
+      // Only ever written when the caller declared one — absent stays absent,
+      // so an existing agents.json is never rewritten into a new shape.
+      ...(roleUpdate.roleId ? { roleId: roleUpdate.roleId } : {}),
       registeredAt: existing?.registeredAt ?? now,
       lastHeartbeat: now,
       capabilities: existing?.capabilities,
     };
     return current;
   });
-  return { ok: true, agent: reg[args.agentId] };
+  const entry = reg[args.agentId];
+  // Echo the record types this role may and may not emit. Record authority is
+  // otherwise invisible until the first typed send is refused mid-work — this
+  // is how an agent whose role owns `go`/`scope`/`verdict` finds out at
+  // onboarding that it has to declare that role.
+  const authority = recordAuthorityFor(entry);
+  return {
+    ok: true as const,
+    agent: entry,
+    resolvedRole: resolveRole(entry),
+    recordAuthority: {
+      ...authority,
+      ...(authority.mayNotEmit.length
+        ? { note: `this role may not emit ${authority.mayNotEmit.map((t) => `'${t}'`).join("/")} as a typed record — register with the owning role (e.g. role:{roleId:"coordinator"}) if it should. Text prefixes are unrestricted.` }
+        : {}),
+    },
+  };
 }
 
 // ---------- unregister ----------

package/src/tools/render.ts

@@ -0,0 +1,80 @@
+// 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;
+}

package/src/tools/scopes.ts

@@ -0,0 +1,177 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { AGENTS_FILE, ROOT, SCOPES_FILE, readJson } from "../store.js";
+import { resolveRole, roleMatches, slugifyRole } from "../roles.js";
+import type { AgentRegistry } from "./shared.js";
+
+// ---------- document write scopes (Phase 8 Task 4) ----------
+//
+// ADVISORY, AND THAT IS DELIBERATE. Nothing here can stop a write: agents edit
+// docs/QUEUE.md, DONE.md and WORKSTREAMS.md with ordinary file tools, which
+// never touch the bus, so there is no point at which the server could refuse
+// one. What this module gives you is:
+//
+//   list_scopes  — ask "who owns this document, may I write it?" BEFORE writing
+//   doctor       — detect, after the fact, that the last writer wasn't the owner
+//
+// Pre-emptive enforcement arrives with Task 5 (work state as data in the
+// store, where the bus IS the write path). Until then, do not describe a
+// declared scope as a guarantee — it is a convention with a smoke detector.
+
+// On-disk shape. Either the flat form:
+//   { "docs/QUEUE.md": {"owner": "aide", "mode": "exclusive"} }
+// or, when the documents don't live next to the bus's cwd:
+//   { "repo": "/path/to/repo", "documents": { ...same map... } }
+export type ScopeMode = "exclusive" | "append-only" | "shared";
+export type ScopeEntry = { owner: string; mode?: ScopeMode; note?: string };
+export type ScopesFile =
+  | Record<string, ScopeEntry>
+  | { repo?: string; documents: Record<string, ScopeEntry> };
+
+export type LoadedScopes = {
+  configured: boolean;
+  file: string;
+  repo: string;
+  documents: { path: string; owner: string; mode: ScopeMode; note?: string }[];
+};
+
+function isWrapped(raw: ScopesFile): raw is { repo?: string; documents: Record<string, ScopeEntry> } {
+  return typeof (raw as { documents?: unknown }).documents === "object" &&
+    (raw as { documents?: unknown }).documents !== null;
+}
+
+// Absent file → configured:false, empty document list. Never throws: a broken
+// scopes.json degrades to "nothing declared" rather than taking a tool down.
+export async function loadScopes(): Promise<LoadedScopes> {
+  const empty: LoadedScopes = { configured: false, file: SCOPES_FILE, repo: process.cwd(), documents: [] };
+  if (!existsSync(SCOPES_FILE)) return empty;
+  const raw = await readJson<ScopesFile | null>(SCOPES_FILE, null);
+  if (!raw || typeof raw !== "object") return empty;
+
+  const map = isWrapped(raw) ? raw.documents : (raw as Record<string, ScopeEntry>);
+  const repo = isWrapped(raw) && raw.repo ? raw.repo : process.cwd();
+  const documents = Object.entries(map ?? {})
+    .filter(([, e]) => e && typeof e === "object" && typeof e.owner === "string")
+    .map(([p, e]) => ({
+      path: p.replace(/^\.\//, ""),
+      owner: e.owner,
+      mode: (e.mode ?? "exclusive") as ScopeMode,
+      ...(e.note ? { note: e.note } : {}),
+    }));
+  return { configured: true, file: SCOPES_FILE, repo, documents };
+}
+
+// Does `agent` own `doc`? An owner is a roleId (matched through the same
+// resolution the rest of Task 4 uses) or a bare agentId, so a document can be
+// pinned to a role ("aide") or to one specific agent ("david-worker-2").
+export function ownsDocument(
+  agentId: string | undefined,
+  entry: { agentId?: string; role?: string; roleId?: string } | undefined,
+  owner: string,
+): boolean {
+  const target = slugifyRole(owner);
+  if (agentId && slugifyRole(agentId) === target) return true;
+  return roleMatches(entry, new Set([target]));
+}
+
+export const listScopesSchema = {
+  // Ask about one document instead of listing everything.
+  path: z.string().optional(),
+  // Whose write is being contemplated (defaults to nobody — a pure listing).
+  agentId: z.string().optional(),
+};
+
+export async function listScopesTool(args: { path?: string; agentId?: string }) {
+  const scopes = await loadScopes();
+  const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
+  const entry = args.agentId ? reg[args.agentId] : undefined;
+
+  // Every answer carries `advisory: true`. A caller that stores this verdict
+  // is storing an opinion, not a permission.
+  const base = {
+    ok: true as const,
+    advisory: true as const,
+    configured: scopes.configured,
+    file: scopes.file,
+    repo: scopes.repo,
+    note: scopes.configured
+      ? "declared scopes are advisory — the bus does not mediate file writes (Phase 8 Task 5)"
+      : `no ${path.basename(SCOPES_FILE)} in ${ROOT} — no document is owned, nothing is checked (opt-in)`,
+  };
+
+  if (args.path === undefined) {
+    return {
+      ...base,
+      documents: scopes.documents,
+      ...(args.agentId
+        ? { you: { agentId: args.agentId, role: resolveRole(entry) ?? null } }
+        : {}),
+    };
+  }
+
+  const wanted = args.path.replace(/^\.\//, "");
+  const doc = scopes.documents.find((d) => d.path === wanted);
+  if (!doc) {
+    return { ...base, path: wanted, owned: false, mayWrite: true, reason: "no scope declared for this document" };
+  }
+  const mine = args.agentId ? ownsDocument(args.agentId, entry, doc.owner) : false;
+  return {
+    ...base,
+    path: doc.path,
+    owned: true,
+    owner: doc.owner,
+    mode: doc.mode,
+    ...(doc.note ? { docNote: doc.note } : {}),
+    mayWrite: mine || doc.mode === "shared",
+    reason: mine
+      ? `'${args.agentId}' matches the declared owner '${doc.owner}'`
+      : doc.mode === "shared"
+        ? `declared shared — any agent may write, '${doc.owner}' is the maintainer`
+        : `owned by '${doc.owner}' (${doc.mode})${args.agentId ? `; '${args.agentId}' does not match` : ""} — coordinate before writing`,
+  };
+}
+
+// ---------- last-writer lookup (used by doctor's scope-drift check) ----------
+
+export type LastWriter = { author: string; email: string; commit: string; when: string };
+
+export function isGitRepo(repo: string): boolean {
+  if (!existsSync(repo)) return false;
+  const r = spawnSync("git", ["-C", repo, "rev-parse", "--is-inside-work-tree"], { encoding: "utf8" });
+  return r.status === 0 && String(r.stdout).trim() === "true";
+}
+
+// Last commit that touched `file`, or null if git has never seen it. Cheap
+// (`-1`), read-only, and confined to `repo`.
+export function lastWriterOf(repo: string, file: string): LastWriter | null {
+  const r = spawnSync(
+    "git",
+    ["-C", repo, "log", "-1", "--format=%an%x00%ae%x00%h%x00%aI", "--", file],
+    { encoding: "utf8" },
+  );
+  if (r.status !== 0) return null;
+  const line = String(r.stdout).trim();
+  if (!line) return null;
+  const [author = "", email = "", commit = "", when = ""] = line.split("\0");
+  return { author, email, commit, when };
+}
+
+// Map a commit author back to a bus agent. Git records humans (or one shared
+// machine account), not agent ids, so this only succeeds when the author name
+// or email local-part IS a registered agentId or its role id — which is the
+// honest limit of the check. Unmappable authors are reported as such by doctor
+// instead of being counted as drift.
+export function attributeWriter(writer: LastWriter, reg: AgentRegistry): { agentId: string; roleId?: string } | null {
+  const candidates = new Set(
+    [writer.author, writer.email.split("@")[0] ?? ""].map(slugifyRole).filter(Boolean),
+  );
+  for (const [agentId, entry] of Object.entries(reg)) {
+    const resolved = resolveRole(entry);
+    if (candidates.has(slugifyRole(agentId)) || (resolved && candidates.has(resolved.roleId))) {
+      return { agentId, ...(resolved ? { roleId: resolved.roleId } : {}) };
+    }
+  }
+  return null;
+}

package/src/tools/shared.ts

@@ -51,7 +51,16 @@ import {
 export type AgentEntry = {
   agentId: string;
   project?: string;
+  // DISPLAY NAME — free to change. Stays a plain string on disk so existing
+  // agents.json files, coord-chat's `/whois`, and every v1 reader keep working
+  // untouched.
   role?: string;
+  // FROZEN IDENTITY (Phase 8 Task 4). Optional and additive: when absent the id
+  // is derived from `role` at read time (resolveRole), which is what every
+  // pre-Task-4 entry does. Once DECLARED it is immutable — register rejects an
+  // attempt to change it — so a role can be renamed (curator → liaison → aide)
+  // without every id, skill and script that keys off it having to move.
+  roleId?: string;
   registeredAt: number;
   lastHeartbeat: number;
   capabilities?: string[];
@@ -72,10 +81,93 @@ export type TransportMarker = {
   // pusher — the class of bug that silently dropped /clear /compact in v0.8.1.
   // Absent on markers written by older versions (treated as "unknown, skip").
   scriptMtime?: number;
+  // Build identity (newest dist mtime, sampled at that server's module load)
+  // of the MCP server whose attach_agent stamped this marker. A marker
+  // stamped by a server predating the current on-disk build was written by
+  // attach/stamp logic the rebuild replaced — doctor's provenance check flags
+  // it for a session restart + re-attach. Absent on markers written by older
+  // versions (treated as "unknown, skip", deliberately mirroring scriptMtime).
+  serverBuildMtime?: number;
 };
 
 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;
+};
+
+// 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;
@@ -96,9 +188,37 @@ export type Message = {
   // Semantic weight of a room post (absent = chatter). Decisions get a longer
   // prune retention (decisionDays), survive live compaction while fresh, and
   // are surfaced verbatim in overflow digests.
+  //
+  // This field is on disk in every JSONL file, so it is the half of the old
+  // name collision that could not move. The pushers' *synthetic* channel tag
+  // ("DM" / "room #general"), read by injectLine and classifyTier, was also
+  // called `kind` until Phase 8 Task 3 renamed it to `tag` — it is
+  // process-local and never persisted, so renaming it cost no migration.
+  // The two no longer collide; see hooks/tmux-pusher.mjs's collectSource.
   kind?: "decision" | "status" | "chatter";
+  // Typed protocol record (Phase 8). Optional and additive; see MessageRecord.
+  record?: MessageRecord;
 };
 
+// THE retention predicate — one definition, three call sites (prune,
+// live compaction, overflow-digest quoting). It lived as three copies of
+// `e.kind === "decision"`, and they drifted: a v2 agent doing exactly what
+// Phase 8 asks — sending `record:{type:"decision"}` and omitting the legacy
+// `kind` — had its decisions compacted at chatter rate and dropped from
+// digests. A protocol whose correct usage loses data.
+//
+// MONOTONE, like the tier floor: `||` can only ever GRANT the long retention,
+// never remove it. So there is no cutover, no migration, and no existing file
+// whose behaviour changes — a legacy `kind:"decision"` keeps exactly the
+// retention it had. Two sources that can each override each other is the
+// disagreement this phase deletes; a source that can only raise is not that.
+//
+// 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 type StatusEntry = {
   id: string;
   ts: number;