agent-coord-mcp 0.26.18 → 0.26.20

package/dist/tools/events.js

@@ -0,0 +1,234 @@
+/*
+ * 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";
+import { EVENT_KINDS, EVENT_KIND_IDS } from "./event-kinds.js";
+const subsFile = () => path.join(ROOT, "subscriptions.json");
+// Re-exported so every existing importer keeps its import path. The vocabulary
+// itself is defined beside the emitters (record-events.ts) — Task 9.2: a kind
+// that can be subscribed to but never emitted is unsatisfiable BY CONSTRUCTION
+// only if the enum cannot be widened without an emitter.
+export { EVENT_KINDS, EVENT_KIND_IDS };
+export function readSubs() {
+    const f = subsFile();
+    if (!existsSync(f))
+        return [];
+    try {
+        return (JSON.parse(readFileSync(f, "utf8")).subscriptions ?? []);
+    }
+    catch {
+        return [];
+    }
+}
+function writeSubs(subs) {
+    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) {
+    const iso = (n) => new Date(n).toISOString();
+    // THREE STATES, BECAUSE THERE ARE THREE FACTS. They were two, and the
+    // collapse cost a week: an `item` subscriber read `error — never evaluated`
+    // the whole time, because `evaluate()` only touches subscriptions whose kind
+    // matches the event and no `item` event had fired. The wiring was fine. The
+    // health field said it was dead, and the agent holding it believed the field.
+    //
+    // Same shape as `alive` swallowing `heartbeatFresh`, and as
+    // `stall_clock_status` reporting green while covering nothing: one field
+    // answering two questions always answers the easier one.
+    if (s.lastScannedAt === undefined && s.lastEvaluatedAt === null) {
+        // Written before this field existed AND never evaluated. Absent is UNKNOWN,
+        // never "never scanned" — inventing a scan nobody observed is the failure
+        // this phase is about, and asserting one never happened is the same error
+        // pointed the other way.
+        return {
+            level: "unknown",
+            detail: "predates scan tracking and has never been evaluated — whether the machinery has run for it CANNOT be determined from this record. " +
+                "It will resolve to ok or error on the next scan; until then this is an absence of evidence, not evidence of absence.",
+        };
+    }
+    if (!s.lastScannedAt) {
+        return {
+            level: "error",
+            detail: "NEVER SCANNED — no scan has run with this subscription registered, so it has produced no evidence of being wired to anything. " +
+                "This is the state that means broken.",
+        };
+    }
+    if (s.lastEvaluatedAt === null) {
+        // THE STATE THAT USED TO READ AS BROKEN. The machinery ran and nothing of
+        // this kind happened, which is a healthy idle watch.
+        return {
+            level: "ok",
+            detail: `scanned ${iso(s.lastScannedAt)}, never evaluated — the machinery RAN and no '${s.kind}' event has occurred yet. ` +
+                "Scanned-and-quiet is healthy; it is not the same as never run, and those shared a field until now.",
+        };
+    }
+    return {
+        level: "ok",
+        detail: s.lastEventAt
+            ? `scanned ${iso(s.lastScannedAt)}, last evaluated ${iso(s.lastEvaluatedAt)}, last event ${iso(s.lastEventAt)}`
+            : `scanned ${iso(s.lastScannedAt)}, last evaluated ${iso(s.lastEvaluatedAt)}, no events yet`,
+    };
+}
+/**
+ * 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, target, ref) => createHash("sha256").update(`${kind}:${target}:${ref}`).digest("hex").slice(0, 16);
+/**
+ * 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, ev) {
+    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, ev) => subs.filter((s) => s.kind === ev.kind && s.target === ev.target);
+/**
+ * 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.
+ */
+/**
+ * Record that a scan RAN, for every live subscription regardless of kind.
+ *
+ * Called once per scan — including a scan that produced NO events, which is
+ * exactly the case that starved the old field: no events of your kind means
+ * `evaluate` never touches you, and a subscription that is never touched cannot
+ * be told from one that is not wired to anything.
+ */
+export function markScanned(subs, now) {
+    return subs.map((s) => ({ ...s, lastScannedAt: now }));
+}
+export function evaluate(subs, ev, now) {
+    const key = eventKey(ev.kind, ev.target, ev.ref);
+    const deliveries = [];
+    const next = subs.map((s) => {
+        // Every subscription observed this scan, whatever its kind.
+        const scanned = { ...s, lastScannedAt: now };
+        if (s.kind !== ev.kind)
+            return scanned;
+        const evaluated = { ...scanned, 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(EVENT_KIND_IDS),
+    target: z.string().min(1),
+};
+export async function subscribeTool(args) {
+    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, subscription: dupe, note: "already subscribed — returning the existing registration rather than a second one" };
+    const sub = {
+        id: randomUUID(),
+        agentId: args.agentId,
+        kind: args.kind,
+        target: args.target,
+        createdAt: Date.now(),
+        // EXPLICIT null, never left absent. `null` means "we know no scan has run
+        // for this"; `undefined` means "this record predates the field and we
+        // cannot say". A subscription created now is the first case, and writing it
+        // explicitly is what keeps a brand-new registration from being reported as
+        // unknowable.
+        lastScannedAt: null,
+        lastEvaluatedAt: null,
+        lastEventAt: null,
+        delivered: [],
+    };
+    writeSubs([...subs, sub]);
+    return { ok: true, subscription: sub, health: subscriptionHealth(sub) };
+}
+export const unsubscribeSchema = { agentId: z.string().min(1), id: z.string().min(1) };
+export async function unsubscribeTool(args) {
+    const subs = readSubs();
+    const sub = subs.find((s) => s.id === args.id);
+    if (!sub)
+        return { ok: false, 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, error: `subscription '${args.id}' belongs to '${sub.agentId}', not '${args.agentId}'` };
+    writeSubs(subs.filter((s) => s.id !== args.id));
+    return { ok: true, removed: sub };
+}
+export const listSubscriptionsSchema = { agentId: z.string().optional() };
+export async function listSubscriptionsTool(args) {
+    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");
+    const undetermined = rows.filter((r) => r.health.level === "unknown");
+    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 SCANNED — no scan has run with them registered, so they have produced no evidence of being wired to anything.` }
+            : {}),
+        ...(undetermined.length
+            ? {
+                undetermined: `${undetermined.length} of ${rows.length} subscription(s) predate scan tracking and cannot be judged yet — they resolve on the next scan. Reported rather than counted as either healthy or broken.`,
+            }
+            : {}),
+    };
+}
+/** Persist an evaluation. Callers do this after a record write, never before. */
+export function commitEvaluation(next) {
+    writeSubs(next);
+}
+//# sourceMappingURL=events.js.map

package/dist/tools/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/tools/events.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.js

@@ -0,0 +1,14 @@
+export * from "./shared.js";
+export * from "./registry.js";
+export * from "./rooms.js";
+export * from "./messaging.js";
+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";
+export * from "./events.js";
+export * from "./record-events.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC"}

package/dist/tools/logwatch.js

@@ -0,0 +1,85 @@
+/*
+ * Task 8 — a watch over an append-only log, keyed on FILE OFFSET.
+ *
+ * A WATCH MUST NOT BE ABLE TO CONSUME. This is Task 7.1's rule at its second
+ * caller, not a second fix: the read cursor records what the AGENT has taken
+ * delivery of, and only the agent reading may advance it. A pusher typing into
+ * a pane is a reader; a watch waiting for traffic is a reader; neither may
+ * consume on the agent's behalf.
+ *
+ * So this keeps its OWN position — `lastLineSeen` — and never touches
+ * `cursors/<id>.json`. A watch that advanced the read cursor would reproduce
+ * exactly the defect Task 7 removed, one component over: the message would be
+ * marked consumed by something that only looked at it.
+ *
+ * WHY THIS DOES NOT VIOLATE 6.2 (8.5). "Events are derived from the record,
+ * never parallel to it." The room and inbox JSONL logs ARE the record — they
+ * are the authoritative store, not a projection of one. `land`'s events are
+ * derived from a document write; these are derived from the log itself. Both
+ * read the authoritative artifact and neither maintains a second source of
+ * truth. The test for a violation is whether the stream could assert something
+ * the record does not, and it cannot: every event here IS a line in the log,
+ * identified by its offset in that log.
+ *
+ * Keyed on OFFSET rather than timestamp or id, because an offset is a property
+ * of the log itself. Two lines can share a `ts`, an id can be rewritten, and a
+ * clock can disagree with another clock — a line's position cannot.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { ROOT } from "../store.js";
+export const logFileFor = (kind, target) => kind === "room" ? path.join(ROOT, "rooms", `${target}.jsonl`) : path.join(ROOT, "inbox", `${target}.jsonl`);
+/** Parsed lines of a log. Malformed lines are SKIPPED but still counted. */
+export function readLog(file) {
+    if (!existsSync(file))
+        return { entries: [], total: 0 };
+    const lines = readFileSync(file, "utf8").split("\n").filter((l) => l.trim());
+    const entries = [];
+    for (const l of lines) {
+        try {
+            entries.push(JSON.parse(l));
+        }
+        catch {
+            // A malformed line still OCCUPIES an offset. Skipping it without counting
+            // would shift every subsequent line's position by one and silently
+            // re-report the whole tail.
+            entries.push(null);
+        }
+    }
+    return { entries, total: lines.length };
+}
+/**
+ * Lines appended since `lastLineSeen`.
+ *
+ * A TRUNCATED LOG IS NOT A QUIET ONE. If the file is SHORTER than the watch's
+ * position, something rewrote or pruned it — reporting "no new lines" would be
+ * indistinguishable from a healthy quiet period. It is surfaced instead.
+ */
+export function newLines(watch, log) {
+    if (log.total < watch.lastLineSeen)
+        return { events: [], truncated: true, total: log.total };
+    const events = [];
+    for (let i = watch.lastLineSeen; i < log.total; i++) {
+        events.push({ kind: watch.kind, target: watch.target, offset: i, line: log.entries[i] ?? null });
+    }
+    return { events, truncated: false, total: log.total };
+}
+/** 8.3 — health, identical in shape to the record subscriptions, plus lastLineSeen. */
+export function watchHealth(w) {
+    if (w.lastEvaluatedAt === null)
+        return {
+            level: "error",
+            detail: `never evaluated — this watch has produced no evidence it is attached to anything. "No lines yet" and "never ran" are the same output, and only one of them is healthy.`,
+        };
+    return {
+        level: "ok",
+        detail: `last evaluated ${new Date(w.lastEvaluatedAt).toISOString()}, reported up to line ${w.lastLineSeen}`,
+    };
+}
+export const logWatchSchema = {
+    agentId: z.string().min(1),
+    kind: z.enum(["room", "inbox"]),
+    target: z.string().min(1),
+};
+//# sourceMappingURL=logwatch.js.map

package/dist/tools/logwatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logwatch.js","sourceRoot":"","sources":["../../src/tools/logwatch.ts"],"names":[],"mappings":"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"}