agent-coord-mcp 0.26.5 → 0.26.7

package/src/tools/away.ts

@@ -0,0 +1,121 @@
+/*
+ * `coord_away` — Phase 5 Task 4.1/4.2.
+ *
+ * WHAT THIS IS NOT: a way to hand the coordinator's judgement to someone else.
+ * A duty officer keeps the lane MOVING while the coordinator is away; it does
+ * not inherit the authority to decide what the lane is for. The distinction is
+ * the whole point, so it is enforced as an ALLOWLIST rather than a denylist:
+ * a new tool added tomorrow is refused by default, and someone must decide, in
+ * writing, that a duty officer may call it.
+ *
+ * A denylist would have the opposite failure — every tool anyone forgets to
+ * list is silently granted — which is the same shape as an empty check rollup
+ * scoring green (kit#125): absence read as permission.
+ *
+ * ENFORCEMENT LIVES IN `addTool`, THE SINGLE PATH EVERY TOOL IS REGISTERED
+ * THROUGH, for the reason kit#125 folded the check into the merge call: a
+ * guard repeated at call sites is a guard someone forgets at one call site,
+ * and the forgotten one looks identical to the guarded ones from outside.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { ROOT } from "../store.js";
+
+const awayFile = () => path.join(ROOT, "coord-away.json");
+
+/**
+ * WHAT A DUTY OFFICER MAY DO: move claimed work along and report.
+ *
+ * Deliberately absent, each for its own reason rather than by omission:
+ *   `merge`          — merging is a judgement about whether work is DONE.
+ *   `register`/`join` w/ coordinator role — see `secondCoordinatorRefusal`.
+ *   grow-fleet verbs — a stand-in does not get to change the fleet's shape.
+ *   CANON writes     — canon outlives the absence that created the stand-in.
+ */
+export const DUTY_OFFICER_ALLOWLIST = ["next_unblocked", "claim", "land", "stall_check", "stall_clock_status", "post_status", "send_message", "read_messages", "status", "heartbeat", "list_work"] as const;
+
+export type AwayState = { on: boolean; project: string; coordinatorId: string; dutyOfficerId: string; until?: string; at: string };
+
+export function readAway(): Record<string, AwayState> {
+  const f = awayFile();
+  if (!existsSync(f)) return {};
+  try {
+    return JSON.parse(readFileSync(f, "utf8")) as Record<string, AwayState>;
+  } catch {
+    return {};
+  }
+}
+
+function writeAway(state: Record<string, AwayState>): void {
+  mkdirSync(ROOT, { recursive: true });
+  writeFileSync(awayFile(), `${JSON.stringify(state, null, 2)}\n`);
+}
+
+/**
+ * The refusal a duty officer gets, or null if the call is allowed.
+ *
+ * Only the DUTY OFFICER is constrained. Everyone else's lane is unchanged:
+ * `coord-away` is not a freeze on the project, and a worker whose tools stop
+ * working because the coordinator stepped out would simply stop calling them.
+ */
+export function awayRefusal(state: Record<string, AwayState>, agentId: string | undefined, tool: string): string | null {
+  if (!agentId) return null;
+  const held = Object.values(state).find((s) => s.on && s.dutyOfficerId === agentId);
+  if (!held) return null;
+  if ((DUTY_OFFICER_ALLOWLIST as readonly string[]).includes(tool)) return null;
+  return `'${tool}' is not on the duty-officer allowlist. You are standing in for '${held.coordinatorId}' on '${held.project}' while coord-away is ON: a duty officer keeps the lane MOVING and does not inherit the authority to decide what it is for. Allowed: ${DUTY_OFFICER_ALLOWLIST.join(", ")}. If this genuinely needs doing, it needs ${held.coordinatorId} back or David — not a wider allowlist added in the moment.`;
+}
+
+/**
+ * 4.2 — a SECOND coordinator may not join while the first is away.
+ *
+ * Not a lock for its own sake: two coordinators is the condition under which
+ * two GOs can be issued for one lane, and the absent one cannot see the other
+ * arrive. The duty officer exists precisely so the seat is not empty, so a
+ * second claimant is a fleet-shape change, which is the category `coord_away`
+ * refuses by construction.
+ */
+export function secondCoordinatorRefusal(state: Record<string, AwayState>, agentId: string, roleId: string | undefined): string | null {
+  if (roleId !== "coordinator") return null;
+  const held = Object.values(state).find((s) => s.on && s.coordinatorId !== agentId);
+  if (!held) return null;
+  return `coord-away is HELD on '${held.project}' by '${held.coordinatorId}' (duty officer '${held.dutyOfficerId}'). A second coordinator cannot join until it is RELEASED — two coordinators is the condition under which one lane gets two GOs, and the absent one cannot see the second arrive.`;
+}
+
+export const coordAwaySchema = {
+  project: z.string().min(1),
+  on: z.boolean(),
+  coordinatorId: z.string().min(1),
+  dutyOfficerId: z.string().optional(),
+  until: z.string().optional(),
+};
+
+export async function coordAwayTool(args: { project: string; on: boolean; coordinatorId: string; dutyOfficerId?: string; until?: string }) {
+  const state = readAway();
+  const prior = state[args.project];
+
+  if (args.on) {
+    // A STAND-IN WITH NO NAME IS AN EMPTY SEAT DESCRIBED AS COVERED, which is
+    // strictly worse than a seat everyone can see is empty.
+    if (!args.dutyOfficerId) return { ok: false as const, error: `coord-away ON requires a dutyOfficerId. Turning it on without naming a stand-in reports the lane as covered while leaving it uncovered.` };
+    if (args.dutyOfficerId === args.coordinatorId) return { ok: false as const, error: `'${args.coordinatorId}' cannot be its own duty officer.` };
+    if (prior?.on && prior.coordinatorId !== args.coordinatorId) return { ok: false as const, error: `coord-away is already HELD on '${args.project}' by '${prior.coordinatorId}'. Release it first.` };
+    state[args.project] = { on: true, project: args.project, coordinatorId: args.coordinatorId, dutyOfficerId: args.dutyOfficerId, until: args.until, at: new Date().toISOString() };
+    writeAway(state);
+    return {
+      ok: true as const,
+      state: state[args.project],
+      allowlist: DUTY_OFFICER_ALLOWLIST,
+      announce: `AGENT_ACTION: coord-away ON — '${args.coordinatorId}' away${args.until ? ` until ${args.until}` : ""}; '${args.dutyOfficerId}' is duty officer, limited to: ${DUTY_OFFICER_ALLOWLIST.join(", ")}. A second coordinator cannot join until released.`,
+    };
+  }
+
+  // RELEASE IS THE COORDINATOR'S. A duty officer releasing its own limits is
+  // the limit not existing — the one call it must not be able to make.
+  if (!prior?.on) return { ok: false as const, error: `coord-away is not on for '${args.project}' — nothing to release.` };
+  if (prior.coordinatorId !== args.coordinatorId) return { ok: false as const, error: `coord-away on '${args.project}' is held by '${prior.coordinatorId}' and only they can release it. A stand-in that can lift its own limits does not have any.` };
+  state[args.project] = { ...prior, on: false, at: new Date().toISOString() };
+  writeAway(state);
+  return { ok: true as const, state: state[args.project], announce: `AGENT_ACTION: coord-away RELEASED on '${args.project}' — '${prior.coordinatorId}' is back; '${prior.dutyOfficerId}' stands down.` };
+}

package/src/tools/events.ts

@@ -0,0 +1,199 @@
+/*
+ * Event subscriptions — stop relying on someone CHOOSING to tell you.
+ *
+ * The bus is almost entirely direct messaging: an agent learns something
+ * happened because another agent decided to say so. Every miss this week was a
+ * missing NOTIFICATION rather than a missing capability — two mergeable PRs sat
+ * 17 hours because nobody told the coordinator to gate, the console's trigger
+ * ran zero times because nothing woke it, and `stall_check` runs only when a
+ * human types it.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { ROOT } from "../store.js";
+
+const subsFile = () => path.join(ROOT, "subscriptions.json");
+
+export type SubKind = "task" | "phase" | "item" | "pr";
+export type Subscription = {
+  id: string;
+  agentId: string;
+  kind: SubKind;
+  target: string;
+  createdAt: number;
+  /** null until this subscription has been EVALUATED at least once. */
+  lastEvaluatedAt: number | null;
+  lastEventAt: number | null;
+  /** Idempotency keys already delivered, for 6.4. */
+  delivered: string[];
+};
+
+export function readSubs(): Subscription[] {
+  const f = subsFile();
+  if (!existsSync(f)) return [];
+  try {
+    return (JSON.parse(readFileSync(f, "utf8")).subscriptions ?? []) as Subscription[];
+  } catch {
+    return [];
+  }
+}
+
+function writeSubs(subs: Subscription[]): void {
+  mkdirSync(ROOT, { recursive: true });
+  writeFileSync(subsFile(), `${JSON.stringify({ subscriptions: subs }, null, 2)}\n`);
+}
+
+/**
+ * 6.3 — A SUBSCRIPTION THAT NEVER FIRES MUST BE DISTINGUISHABLE FROM ONE NEVER
+ * REGISTERED, so never-evaluated is an ERROR rather than a quiet zero.
+ *
+ * We hit the absence of this rule twice in two days: the console's standing
+ * trigger and `stall_check`'s clock both looked healthy while never running. A
+ * subscription with no last-evaluated mark has produced no evidence of
+ * anything, and "no events" is the same output a broken subscription gives.
+ */
+export function subscriptionHealth(s: Subscription): { level: "ok" | "error"; detail: string } {
+  if (s.lastEvaluatedAt === null)
+    return {
+      level: "error",
+      detail: `never evaluated — this subscription has produced no evidence it is wired to anything. "No events yet" and "never ran" are the same output, and only one of them is healthy.`,
+    };
+  return {
+    level: "ok",
+    detail: s.lastEventAt
+      ? `last evaluated ${new Date(s.lastEvaluatedAt).toISOString()}, last event ${new Date(s.lastEventAt).toISOString()}`
+      : `last evaluated ${new Date(s.lastEvaluatedAt).toISOString()}, no events yet — evaluated and quiet, which is different from never run`,
+  };
+}
+
+/**
+ * 6.4 — DELIVERY IS AT-LEAST-ONCE BY DESIGN. Safe for a reader, DOUBLE
+ * EXECUTION for an executor: a callback that triggers work must carry a key, or
+ * the same merge lands twice. The key is derived from the EVENT, never from the
+ * delivery attempt, so a retry produces the same key.
+ */
+export const eventKey = (kind: SubKind, target: string, ref: string): string =>
+  createHash("sha256").update(`${kind}:${target}:${ref}`).digest("hex").slice(0, 16);
+
+export type RecordEvent = { kind: SubKind; target: string; ref: string; summary: string };
+
+/**
+ * 6.2 — EVENTS ARE DERIVED FROM THE RECORD, NEVER PARALLEL TO IT.
+ *
+ * Enforced here rather than promised in a comment: the event's `ref` must
+ * already be present in the record document before anything is emitted. An
+ * event stream that can say "task X complete" while DONE.md does not is a
+ * second source of truth, and record-vs-state divergence is the defect this
+ * fleet hit most this week. ADR-003 keeps markdown authoritative, and this must
+ * not quietly reopen it.
+ *
+ * So the ordering is not a convention: emission READS the record, and an event
+ * whose cause is not in the record cannot be emitted at all.
+ */
+export function eventIsDerived(recordText: string, ev: RecordEvent): { ok: true } | { ok: false; error: string } {
+  if (!ev.ref) return { ok: false, error: `event for ${ev.kind} ${ev.target} carries no ref — nothing ties it to a record entry` };
+  if (!String(recordText).includes(ev.ref))
+    return {
+      ok: false,
+      error:
+        `refusing to emit ${ev.kind} ${ev.target}: its ref ${ev.ref} is NOT in the record. ` +
+        `An event that exists without the record change that caused it is a second source of truth — ` +
+        `the stream would claim something the authoritative document does not.`,
+    };
+  return { ok: true };
+}
+
+/** Subscriptions matching an event. Exact target match; no wildcards yet. */
+export const matching = (subs: Subscription[], ev: RecordEvent): Subscription[] =>
+  subs.filter((s) => s.kind === ev.kind && s.target === ev.target);
+
+export type Delivery = { subscriptionId: string; agentId: string; key: string; status: "delivered" | "duplicate-suppressed" };
+
+/**
+ * Evaluate every subscription against one event and return what to deliver.
+ *
+ * EVALUATION IS RECORDED EVEN WHEN NOTHING MATCHES — that is 6.3's whole point.
+ * A subscription only learns it is alive by being evaluated, so the mark is
+ * written for every subscription of that kind, not only the ones that fired.
+ */
+export function evaluate(subs: Subscription[], ev: RecordEvent, now: number): { subs: Subscription[]; deliveries: Delivery[] } {
+  const key = eventKey(ev.kind, ev.target, ev.ref);
+  const deliveries: Delivery[] = [];
+  const next = subs.map((s) => {
+    if (s.kind !== ev.kind) return s;
+    const evaluated = { ...s, lastEvaluatedAt: now };
+    if (s.target !== ev.target) return evaluated;
+    if (s.delivered.includes(key)) {
+      deliveries.push({ subscriptionId: s.id, agentId: s.agentId, key, status: "duplicate-suppressed" });
+      return evaluated;
+    }
+    deliveries.push({ subscriptionId: s.id, agentId: s.agentId, key, status: "delivered" });
+    return { ...evaluated, lastEventAt: now, delivered: [...s.delivered, key].slice(-200) };
+  });
+  return { subs: next, deliveries };
+}
+
+/* ── verbs ─────────────────────────────────────────────────────────────────── */
+
+export const subscribeSchema = {
+  agentId: z.string().min(1),
+  kind: z.enum(["task", "phase", "item", "pr"]),
+  target: z.string().min(1),
+};
+
+export async function subscribeTool(args: { agentId: string; kind: SubKind; target: string }) {
+  const subs = readSubs();
+  const dupe = subs.find((s) => s.agentId === args.agentId && s.kind === args.kind && s.target === args.target);
+  if (dupe) return { ok: true as const, subscription: dupe, note: "already subscribed — returning the existing registration rather than a second one" };
+  const sub: Subscription = {
+    id: randomUUID(),
+    agentId: args.agentId,
+    kind: args.kind,
+    target: args.target,
+    createdAt: Date.now(),
+    lastEvaluatedAt: null,
+    lastEventAt: null,
+    delivered: [],
+  };
+  writeSubs([...subs, sub]);
+  return { ok: true as const, subscription: sub, health: subscriptionHealth(sub) };
+}
+
+export const unsubscribeSchema = { agentId: z.string().min(1), id: z.string().min(1) };
+
+export async function unsubscribeTool(args: { agentId: string; id: string }) {
+  const subs = readSubs();
+  const sub = subs.find((s) => s.id === args.id);
+  if (!sub) return { ok: false as const, error: `no subscription '${args.id}'` };
+  // Another agent's subscription is not yours to remove: silently dropping
+  // someone else's notification is how a miss is manufactured.
+  if (sub.agentId !== args.agentId) return { ok: false as const, error: `subscription '${args.id}' belongs to '${sub.agentId}', not '${args.agentId}'` };
+  writeSubs(subs.filter((s) => s.id !== args.id));
+  return { ok: true as const, removed: sub };
+}
+
+export const listSubscriptionsSchema = { agentId: z.string().optional() };
+
+export async function listSubscriptionsTool(args: { agentId?: string }) {
+  const all = readSubs();
+  const subs = args.agentId ? all.filter((s) => s.agentId === args.agentId) : all;
+  const rows = subs.map((s) => ({ ...s, health: subscriptionHealth(s) }));
+  const neverEvaluated = rows.filter((r) => r.health.level === "error");
+  return {
+    ok: neverEvaluated.length === 0,
+    // Population beside the verdict, always: "no subscriptions" and "none
+    // listed for you" are different claims.
+    population: { listed: rows.length, total: all.length },
+    subscriptions: rows,
+    ...(neverEvaluated.length
+      ? { error: `${neverEvaluated.length} of ${rows.length} subscription(s) have NEVER been evaluated — they have produced no evidence of being wired to anything.` }
+      : {}),
+  };
+}
+
+/** Persist an evaluation. Callers do this after a record write, never before. */
+export function commitEvaluation(next: Subscription[]): void {
+  writeSubs(next);
+}

package/src/tools/index.ts

@@ -6,3 +6,6 @@ export * from "./transport.js";
 export * from "./admin.js";
 export * from "./scopes.js";
 export * from "./work.js";
+export * from "./records.js";
+export * from "./worktrees.js";
+export * from "./stall.js";