agent-coord-mcp 0.26.10 → 0.26.12

package/src/tools/registry.ts

@@ -83,6 +83,11 @@ export const registerSchema = {
   // token (tokens.json / coord-token) or force:true. Ignored once bound.
   token: z.string().optional(),
   force: z.boolean().optional(),
+  // PROSE-ONLY EXEMPTION (Phase 5.1 Task 12.8). `true` grants it, `false`
+  // revokes it, omitted leaves it exactly as it was — so an agent re-joining
+  // after a /clear does not silently drop an exemption it was granted, and a
+  // card that never heard of the flag cannot revoke one either.
+  proseOnly: z.union([z.boolean(), z.object({ reason: z.string().min(1) })]).optional(),
 };
 
 // Work out what `role`/`roleId` should become, or why the update is refused.
@@ -120,7 +125,12 @@ export function resolveRoleUpdate(
   return { ok: true, role: nextRole, roleId: declared ? resolved.roleId : existing?.roleId };
 }
 
-export async function registerTool(args: { agentId: string; project?: string; role?: RoleArg }) {
+export async function registerTool(args: {
+  agentId: string;
+  project?: string;
+  role?: RoleArg;
+  proseOnly?: boolean | { reason: string };
+}) {
   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 };
@@ -145,6 +155,23 @@ export async function registerTool(args: { agentId: string; project?: string; ro
       registeredAt: existing?.registeredAt ?? now,
       lastHeartbeat: now,
       capabilities: existing?.capabilities,
+      // Omitted → carried forward untouched. Only an explicit `false` revokes.
+      ...(args.proseOnly === undefined
+        ? existing?.proseOnly
+          ? { proseOnly: existing.proseOnly }
+          : {}
+        : args.proseOnly === false
+          ? {}
+          : {
+              proseOnly: {
+                since: existing?.proseOnly?.since ?? now,
+                ...(typeof args.proseOnly === "object" && args.proseOnly.reason
+                  ? { reason: args.proseOnly.reason }
+                  : existing?.proseOnly?.reason
+                    ? { reason: existing.proseOnly.reason }
+                    : {}),
+              },
+            }),
     };
     return current;
   });
@@ -163,10 +190,28 @@ export async function registerTool(args: { agentId: string; project?: string; ro
         `It keeps any authority its words carry (e.g. 'coord-qa' → 'qa'), but prefer the canonical id — ` +
         `role:{roleId:"<canonical>", displayName:"${entry.role ?? entry.roleId}"}.`
       : undefined;
+  // The exemption's own docs state the asymmetry, at the one moment the agent
+  // granting itself one is reading the response. An exemption whose cost is
+  // invisible to the agent holding it is how the rule decays.
+  const proseOnlyEcho = entry.proseOnly
+    ? {
+        proseOnly: {
+          ...entry.proseOnly,
+          asymmetry:
+            "GRANTED TO THE SENDER, PAID BY EVERY READER. An untyped message cannot be slimmed by the " +
+            "transport (hooks/tier.mjs slims only when record.type is present), so every multi-line message " +
+            "you send arrives in full in every reader's context — which is precisely the cost the typed-record " +
+            "rule exists to remove. This is opt-in and reviewed, not self-service: it is visible in list_agents " +
+            "and counted there, so if the exempt share climbs the drift is measurable. Drop it with " +
+            "proseOnly:false as soon as the model behind this agent can pick a record.type.",
+        },
+      }
+    : {};
   return {
     ok: true as const,
     ...(canonWarning ? { warning: canonWarning } : {}),
     agent: entry,
+    ...proseOnlyEcho,
     resolvedRole: resolveRole(entry),
     recordAuthority: {
       ...authority,
@@ -344,7 +389,22 @@ export async function listAgentsTool() {
         : undefined,
     };
   });
-  return { agents, evicted };
+  // COUNTED, so drift is measurable (Task 12.8). "No exemptions" and "I did not
+  // look" are different claims, so the block is always present and always
+  // carries its denominator — a bare list of ids would read as zero on a bus
+  // where the field had simply never been written.
+  const exempt = agents.filter((a) => a.proseOnly);
+  const proseOnly = {
+    exempt: exempt.map((a) => ({ agentId: a.agentId, since: a.proseOnly!.since, reason: a.proseOnly!.reason })),
+    count: exempt.length,
+    total: agents.length,
+    share: agents.length ? Number((exempt.length / agents.length).toFixed(3)) : 0,
+    note:
+      "prose-only agents are exempt from the typed-record rule on agent→agent sends. The exemption is " +
+      "granted to the SENDER and paid by every READER: their multi-line messages cannot be slimmed. " +
+      "A rising share means the rule is decaying.",
+  };
+  return { agents, evicted, proseOnly };
 }
 
 export async function loadLiveTransports(): Promise<Map<string, TransportMarker>> {

package/src/tools/shared.ts

@@ -73,6 +73,19 @@ export type AgentEntry = {
   registeredAt: number;
   lastHeartbeat: number;
   capabilities?: string[];
+  // PROSE-ONLY EXEMPTION from the typed-record rule (Phase 5.1 Task 12.8).
+  //
+  // Declared PER AGENT at register/join, never as a global env var: a global
+  // switch turns the rule off fleet-wide in one line and nobody notices, while
+  // a per-agent declaration is a statement ABOUT THAT AGENT and shows up in
+  // `list_agents` next to it. It exists so a model that cannot reliably pick a
+  // `record.type` is not locked off the bus — opt-in, never the default.
+  //
+  // THE ASYMMETRY: granted to the SENDER, paid by every READER. An untyped
+  // message cannot be slimmed by hooks/tier.mjs, so a prose-only agent spends
+  // OTHER agents' context on every multi-line send. That is why it is stamped,
+  // counted, and reviewed rather than self-service.
+  proseOnly?: { since: number; reason?: string };
 };
 
 export type TransportMarker = {

package/src/tools/transport.ts

@@ -944,12 +944,16 @@ export const joinSchema = {
   // token (tokens.json / coord-token) or force:true. Ignored once bound.
   token: z.string().optional(),
   force: z.boolean().optional(),
+  // Prose-only exemption from the typed-record rule — see registerSchema.
+  // Declared here too because `join` is the call every card actually makes.
+  proseOnly: z.union([z.boolean(), z.object({ reason: z.string().min(1) })]).optional(),
 };
 
 export async function joinTool(args: {
   agentId: string;
   project?: string;
   role?: RoleArg;
+  proseOnly?: boolean | { reason: string };
   attach?: boolean | { tmuxTarget?: string; includeRoom?: boolean; allowlist?: string[]; debounceMs?: number };
   readInbox?: boolean;
 }) {
@@ -957,6 +961,7 @@ export async function joinTool(args: {
     agentId: args.agentId,
     project: args.project,
     role: args.role,
+    proseOnly: args.proseOnly,
   });
   // A refused role update (frozen roleId) fails the whole join rather than
   // silently attaching a transport under the wrong identity.

package/src/typed-records.ts

@@ -0,0 +1,216 @@
+// Typed records become obligatory on agent→agent traffic (Phase 5.1 Task 12).
+//
+// THE MECHANISM ALREADY SHIPPED AND ADOPTION WAS THE WHOLE GAP.
+// `hooks/tier.mjs:injectLine` slims a multi-line message to *first line +
+// `[+N lines · record:<type> · retrieve_message id=<uuid>]`* — but ONLY when
+// `record.type` is a string. Measured on the groundwork room 2026-08-30: 206
+// messages, 175 multi-line, 33 typed, 33 slimmed; the coordinator had sent 101
+// and typed 0. The renderer was never the problem.
+//
+// SO THE RULE IS ENFORCED AT THE SEND, NOT THE RENDER. An untyped agent→agent
+// message must not be able to EXIST, or the next reader re-derives the type
+// from prose and we are back to parsing English. Prose is a second source of
+// truth about what a message meant.
+//
+// Three things this module is careful about, each one a stated acceptance
+// property rather than an implementation taste:
+//
+//  1. STAGED, WITH A NAMED DATE. Five fleets share this bus and 7 of 13 server
+//     processes predate 0.26.7. A refusal shipped before a verified restart
+//     rejects messages from agents that CANNOT comply — the sender gets an
+//     error it has no code path to satisfy. So: WARN until the cutover, REFUSE
+//     after it, and the warning names the date in every single message so the
+//     deadline arrives having been announced ~every send rather than once.
+//
+//  2. THE REFUSAL NAMES A TYPE THE SENDER MAY ACTUALLY USE. `go` and `scope`
+//     are coordinator-restricted and `verdict` is gate-runner-restricted
+//     (RECORD_AUTHORITY): the aide hit exactly this, being told to use `scope`
+//     by one check and refused it by another. Naming a forbidden type is
+//     unusable guidance, so every suggestion is filtered through what this
+//     sender's role may emit before it is offered.
+//
+//  3. `fyi` IS AN HONEST CATCH-ALL. If the nine types do not cover a legitimate
+//     send, agents mistype into whatever passes and the type becomes noise —
+//     which costs more than the untyped message did. Anything unrecognised
+//     suggests `fyi` and says so plainly, never a forced `decision`/`risk`.
+
+// The named cutover. Until this instant an untyped agent→agent send WARNS and
+// is stored; from it, the same send is refused.
+//
+// A DATE, NOT A VERSION, because the constraint being waited on is a fleet-wide
+// RESTART, and no version string on the wire can answer "has every server
+// restarted" — 0.26.7 is published while servers predating it still run. Time
+// is the only clock every one of those processes shares.
+export const TYPED_RECORD_CUTOVER_ISO = "2026-09-15T00:00:00.000Z";
+export const TYPED_RECORD_CUTOVER_MS = Date.parse(TYPED_RECORD_CUTOVER_ISO);
+
+export type TypedRecordMode = "warn" | "refuse";
+
+// `AGENT_COORD_TYPED_RECORDS=warn|refuse` overrides the date. It exists for two
+// callers and no others: tests (which must exercise both sides of a date that
+// has not arrived) and an operator who needs to pull the refusal back for a
+// fleet mid-incident. It is NOT the exemption — an exemption is per-agent and
+// visible (see `proseOnly`); this switch is fleet-wide and invisible, which is
+// exactly why it is not how a less capable model gets on the bus.
+export function typedRecordMode(now: number = Date.now()): TypedRecordMode {
+  const env = process.env.AGENT_COORD_TYPED_RECORDS;
+  if (env === "warn" || env === "refuse") return env;
+  return now >= TYPED_RECORD_CUTOVER_MS ? "refuse" : "warn";
+}
+
+// ---------- suggesting the type the sender should have used ----------
+
+// A rejection that says only "record required" costs a round trip; one that
+// says "looks like a `done` — it cites a PR" costs none. A FAILURE PATH MUST BE
+// MORE INFORMATIVE THAN THE SUCCESS PATH HERE, because it fires during a
+// migration, at agents that are mid-slice and did nothing wrong yesterday.
+//
+// Read from the text the fleet already writes: the six canonical prefixes are
+// in every card and on ~every message, so the type is usually already declared
+// in English one token in.
+const PREFIX_TYPES: Array<[RegExp, string, string]> = [
+  [/^\s*DONE\b/i, "done", "the message opens with the DONE: prefix"],
+  [/^\s*BLOCKER\b/i, "blocker", "the message opens with the BLOCKER: prefix"],
+  [/^\s*RISK\b/i, "risk", "the message opens with the RISK: prefix"],
+  [/^\s*FYI\b/i, "fyi", "the message opens with the FYI: prefix"],
+  [/^\s*AGENT_ACTION\b/i, "action", "the message opens with the AGENT_ACTION: prefix"],
+  [/^\s*DAVID_DECISION\b/i, "decision", "the message opens with the DAVID_DECISION: prefix"],
+  [/^\s*GO\b/i, "go", "the message opens with the GO: prefix"],
+  [/^\s*SCOPE(?:\s+CHANGE)?\b/i, "scope", "the message opens with the SCOPE: prefix"],
+];
+
+// Weaker than a prefix and only consulted when there is no prefix at all.
+const SHAPE_TYPES: Array<[RegExp, string, string]> = [
+  [/\b(PASS|FAIL)\b.*\b[0-9a-f]{7,40}\b/, "verdict", "it reads as a gate verdict over a commit sha"],
+  [/^\s*(PASS|FAIL)\b/, "verdict", "it opens with a PASS/FAIL gate result"],
+  [/(^|\s)(#\d+|[\w.-]+\/[\w.-]+#\d+|https:\/\/github\.com\/\S+\/pull\/\d+)/, "done", "it cites a PR"],
+];
+
+export type RecordSuggestion = {
+  type: string;
+  /** Why this type — quoted back to the sender so the guess is auditable. */
+  why: string;
+  /** Set when the best-fitting type is one this sender's role may not emit. */
+  downgradedFrom?: string;
+};
+
+/**
+ * The record type this message most likely should have carried, CONSTRAINED to
+ * what this sender is allowed to emit.
+ *
+ * `mayNotEmit` is the restricted set this role is refused (recordAuthorityFor).
+ * A suggestion landing in it is downgraded to `fyi` and the downgrade is
+ * reported rather than hidden — being quietly steered off `go` reads as the
+ * heuristic being bad, when in fact the role simply does not own that type.
+ */
+export function suggestRecordType(text: string, mayNotEmit: readonly string[] = []): RecordSuggestion {
+  const forbidden = new Set(mayNotEmit);
+  const firstLine = (text ?? "").split("\n", 1)[0] ?? "";
+
+  const hit =
+    PREFIX_TYPES.find(([re]) => re.test(firstLine)) ??
+    SHAPE_TYPES.find(([re]) => re.test(firstLine) || re.test(text ?? ""));
+
+  if (!hit) {
+    return {
+      type: "fyi",
+      why: "nothing in the text names a kind — 'fyi' is the honest catch-all and is never wrong on purpose",
+    };
+  }
+
+  const [, type, why] = hit;
+  if (forbidden.has(type)) {
+    return {
+      type: "fyi",
+      downgradedFrom: type,
+      why: `${why}, but '${type}' is restricted to roles this sender does not hold — 'fyi' carries the same slimming`,
+    };
+  }
+  return { type, why };
+}
+
+/**
+ * The one line of guidance appended to both the warning and the refusal. Same
+ * words either side of the cutover ON PURPOSE: an agent that reads it during
+ * the warn window has already been told the exact call that will keep working.
+ */
+export function typedRecordGuidance(s: RecordSuggestion): string {
+  const cite =
+    s.type === "done"
+      ? `, cites: [{kind:'pr', ref:'<owner/repo#N>'}]` // a `done` is refused without one anyway
+      : "";
+  return (
+    `looks like a '${s.type}' — ${s.why}. ` +
+    `Add record: {type:'${s.type}', payload:{summary:'<one line>'}${cite}} to this same call; ` +
+    `'text' is untouched by the record and your wording always wins.`
+  );
+}
+
+// ---------- measuring adoption, and the inverse failure ----------
+
+// SUCCESS IS THE TRAFFIC TABLE RE-MEASURED, NOT THIS TASK MERGED. The baseline
+// captured the day the rule was made: 212 room messages, 37 typed (17%),
+// 425,903 bytes sitting below line 1 — bytes every reader pays for and no
+// reader asked for.
+//
+// AND THE INVERSE FAILURE LOOKS EXACTLY LIKE SUCCESS ON A COVERAGE NUMBER. If
+// `fyi` becomes nearly everything, coverage reads ~100% while agents are
+// mistyping to get past the gate and the type has stopped carrying
+// information — that is the catch-all rule (12.5) failing, not holding. So the
+// distribution is reported alongside the percentage and is what the verdict
+// keys on. A coverage-only check would certify the failure it exists to catch.
+//
+// The threshold is deliberately generous: `fyi` IS the honest answer for a
+// large share of real traffic, so this fires on domination, not on presence.
+export const FYI_DOMINANCE_THRESHOLD = 0.75;
+
+export type TypedRecordStats = {
+  total: number;
+  typed: number;
+  coverage: number;
+  /** Bytes below the first line of UNTYPED messages — the cost still being paid. */
+  unslimmedBytes: number;
+  /** count by record.type, plus `untyped`. */
+  distribution: Record<string, number>;
+  fyiShareOfTyped: number;
+  verdict: "healthy" | "adopting" | "degenerate";
+  note: string;
+};
+
+/** `messages` is any array of stored messages ({text, record?}). */
+export function typedRecordStats(messages: ReadonlyArray<{ text?: string; record?: { type?: string } }>): TypedRecordStats {
+  const distribution: Record<string, number> = {};
+  let typed = 0;
+  let unslimmedBytes = 0;
+
+  for (const m of messages) {
+    const type = typeof m.record?.type === "string" ? m.record.type : undefined;
+    distribution[type ?? "untyped"] = (distribution[type ?? "untyped"] ?? 0) + 1;
+    if (type) {
+      typed++;
+      continue;
+    }
+    const text = m.text ?? "";
+    const nl = text.indexOf("\n");
+    if (nl !== -1) unslimmedBytes += Buffer.byteLength(text.slice(nl + 1), "utf8");
+  }
+
+  const total = messages.length;
+  const coverage = total ? typed / total : 0;
+  const fyiShareOfTyped = typed ? (distribution.fyi ?? 0) / typed : 0;
+
+  // Order matters: degeneracy is checked BEFORE coverage, or a room that is
+  // 100% `fyi` reports "healthy" — the exact misreading this guards.
+  const degenerate = typed >= 10 && fyiShareOfTyped > FYI_DOMINANCE_THRESHOLD;
+  const verdict = degenerate ? "degenerate" : coverage >= 0.95 ? "healthy" : "adopting";
+
+  const note = degenerate
+    ? `'fyi' is ${(fyiShareOfTyped * 100).toFixed(0)}% of typed messages — coverage looks solved while the type has ` +
+      `stopped carrying information. Agents are typing to pass the gate, which is 12.5 FAILING, not holding.`
+    : verdict === "healthy"
+      ? `${(coverage * 100).toFixed(0)}% typed with a spread distribution — the reader-side cost is paid down and the type still discriminates.`
+      : `${(coverage * 100).toFixed(0)}% typed; ${unslimmedBytes.toLocaleString("en-US")} bytes still sit below line 1 in untyped messages, ` +
+        `carried by every reader.`;
+
+  return { total, typed, coverage: Number(coverage.toFixed(3)), unslimmedBytes, distribution, fyiShareOfTyped: Number(fyiShareOfTyped.toFixed(3)), verdict, note };
+}