hivecode-mcp 0.14.1 → 0.14.3

package/hive-busy.js

@@ -1,88 +1,88 @@
-// SELF-DECLARED BUSY: "I am mid-task, do not expect an answer this second."
-//
-// WHY THIS IS STATE AND NOT A MESSAGE. The obvious design is an auto-reply: someone @s you
-// while you are working, you post "busy, will get back to you". Eight agents and one broadcast
-// is eight of those, each of which is itself a message in the room; if the acknowledgements are
-// addressed they wake the sender, who is also busy, who acknowledges back. That is a spam
-// channel with extra steps, and this room has already been through it once -- a conflict
-// notification loop put 56 copies of one line into chat and 306 of 2,314 lines were that loop.
-//
-// So nobody announces anything. The busy agent sets a flag and keeps working, and the
-// INFORMATION IS HANDED TO THE SENDER AT SEND TIME instead: hive_say reports the recipient's
-// state in its own return value. Same fact, delivered faster than a reply could arrive, and it
-// adds zero messages to the room. The interrupted agent is never made to interrupt itself in
-// order to be polite.
-//
-// The `controls` map is deliberately not reused. That is mission control -- a HUMAN sets
-// running/paused there -- and an agent writing its own state into the same entry would clobber
-// a human's pause with a self-report. Different author, different authority, different map.
-//
-// TTL, for the same reason claims have one: an agent that dies mid-task must not leave a
-// permanent "busy" flag behind that quietly teaches the whole room to stop talking to it. A
-// stale flag is worse than no flag, because everyone believes it.
-
-/** Default life of a busy flag. Long enough for real work, short enough that a crash clears. */
-export const DEFAULT_TTL = 10 * 60 * 1000
-
-/**
- * The ceiling, and it is the load-bearing one.
- *
- * The whole point of a TTL here is that a crashed agent cannot leave the room believing it is
- * permanently busy. Without a cap, `ttl: Infinity` -- or a caller passing milliseconds where it
- * meant minutes -- reinstates exactly the failure the TTL exists to prevent, and it fails
- * silently: everyone simply stops expecting an answer, forever, and nothing looks broken.
- *
- * An hour is past the point where "busy" is still true. Beyond that the agent is stuck, and the
- * room is better off treating it as free and finding out.
- */
-export const MAX_TTL = 60 * 60 * 1000
-
-/** An entry as stored: { what, since, ttl }. `since` is unix ms, matching hive-coord's claims. */
-
-/** Live, or expired/absent? Pure, so the TTL is testable on a virtual clock. */
-export function isBusy(entry, now = Date.now()) {
-  if (!entry || typeof entry !== 'object') return false
-  const since = Number(entry.since) || 0
-  // Clamped on READ as well as on write, and this is the side that matters: the entry arrives
-  // over the wire from another client, which may be an older build, a different version, or
-  // simply wrong. Trusting a ttl we did not create is how one peer gets to pin the whole room.
-  const ttl = Math.min(MAX_TTL, Math.max(1000, Number(entry.ttl) || DEFAULT_TTL))
-  return since > 0 && now - since < ttl
-}
-
-/** Build an entry. `what` is free text -- what they are doing, for the sender to read. */
-export function makeBusy(what, { ttl = DEFAULT_TTL, now = Date.now() } = {}) {
-  // Clamped at BOTH ends. 0/NaN/absent falls back to the default; anything above the ceiling is
-  // brought down to it, so no caller -- and no bad arithmetic in a caller -- can mint a flag
-  // that outlives the work it describes.
-  const want = Number(ttl) || DEFAULT_TTL
-  return { what: String(what || 'working').slice(0, 200), since: now, ttl: Math.min(MAX_TTL, Math.max(1000, want)) }
-}
-
-/** How long they have been at it, in words a sender can act on. */
-export function busyFor(entry, now = Date.now()) {
-  const ms = Math.max(0, now - (Number(entry && entry.since) || now))
-  const s = Math.round(ms / 1000)
-  if (s < 90) return s + 's'
-  const m = Math.round(s / 60)
-  return m < 90 ? m + 'm' : Math.round(m / 60) + 'h'
-}
-
-/**
- * The line hive_say hands back to a sender about one recipient.
- *
- * Returns '' when there is nothing worth saying, so callers can drop it with a falsy check --
- * silence is the right output for "they are here and free", which is the common case and does
- * not need a sentence.
- *
- * @param {string} name        the recipient
- * @param {object|null} entry  their busy entry, if any
- * @param {boolean} present    are they actually in the room right now
- */
-export function describeRecipient(name, entry, present, now = Date.now()) {
-  // ABSENCE OUTRANKS BUSY, and it is the more useful of the two: a message to someone who left
-  // is not delayed, it is unread forever, and the sender is the only one who can notice.
-  if (!present) return `@${name} is NOT in the room — nobody will read that. hive_members lists who is here.`
-  if (isBusy(entry, now)) return `@${name} has been busy ${busyFor(entry, now)} (${entry.what}) — expect a delay, they are not idle waiting on you.`
-  return ''
-}
+// SELF-DECLARED BUSY: "I am mid-task, do not expect an answer this second."
+//
+// WHY THIS IS STATE AND NOT A MESSAGE. The obvious design is an auto-reply: someone @s you
+// while you are working, you post "busy, will get back to you". Eight agents and one broadcast
+// is eight of those, each of which is itself a message in the room; if the acknowledgements are
+// addressed they wake the sender, who is also busy, who acknowledges back. That is a spam
+// channel with extra steps, and this room has already been through it once -- a conflict
+// notification loop put 56 copies of one line into chat and 306 of 2,314 lines were that loop.
+//
+// So nobody announces anything. The busy agent sets a flag and keeps working, and the
+// INFORMATION IS HANDED TO THE SENDER AT SEND TIME instead: hive_say reports the recipient's
+// state in its own return value. Same fact, delivered faster than a reply could arrive, and it
+// adds zero messages to the room. The interrupted agent is never made to interrupt itself in
+// order to be polite.
+//
+// The `controls` map is deliberately not reused. That is mission control -- a HUMAN sets
+// running/paused there -- and an agent writing its own state into the same entry would clobber
+// a human's pause with a self-report. Different author, different authority, different map.
+//
+// TTL, for the same reason claims have one: an agent that dies mid-task must not leave a
+// permanent "busy" flag behind that quietly teaches the whole room to stop talking to it. A
+// stale flag is worse than no flag, because everyone believes it.
+
+/** Default life of a busy flag. Long enough for real work, short enough that a crash clears. */
+export const DEFAULT_TTL = 10 * 60 * 1000
+
+/**
+ * The ceiling, and it is the load-bearing one.
+ *
+ * The whole point of a TTL here is that a crashed agent cannot leave the room believing it is
+ * permanently busy. Without a cap, `ttl: Infinity` -- or a caller passing milliseconds where it
+ * meant minutes -- reinstates exactly the failure the TTL exists to prevent, and it fails
+ * silently: everyone simply stops expecting an answer, forever, and nothing looks broken.
+ *
+ * An hour is past the point where "busy" is still true. Beyond that the agent is stuck, and the
+ * room is better off treating it as free and finding out.
+ */
+export const MAX_TTL = 60 * 60 * 1000
+
+/** An entry as stored: { what, since, ttl }. `since` is unix ms, matching hive-coord's claims. */
+
+/** Live, or expired/absent? Pure, so the TTL is testable on a virtual clock. */
+export function isBusy(entry, now = Date.now()) {
+  if (!entry || typeof entry !== 'object') return false
+  const since = Number(entry.since) || 0
+  // Clamped on READ as well as on write, and this is the side that matters: the entry arrives
+  // over the wire from another client, which may be an older build, a different version, or
+  // simply wrong. Trusting a ttl we did not create is how one peer gets to pin the whole room.
+  const ttl = Math.min(MAX_TTL, Math.max(1000, Number(entry.ttl) || DEFAULT_TTL))
+  return since > 0 && now - since < ttl
+}
+
+/** Build an entry. `what` is free text -- what they are doing, for the sender to read. */
+export function makeBusy(what, { ttl = DEFAULT_TTL, now = Date.now() } = {}) {
+  // Clamped at BOTH ends. 0/NaN/absent falls back to the default; anything above the ceiling is
+  // brought down to it, so no caller -- and no bad arithmetic in a caller -- can mint a flag
+  // that outlives the work it describes.
+  const want = Number(ttl) || DEFAULT_TTL
+  return { what: String(what || 'working').slice(0, 200), since: now, ttl: Math.min(MAX_TTL, Math.max(1000, want)) }
+}
+
+/** How long they have been at it, in words a sender can act on. */
+export function busyFor(entry, now = Date.now()) {
+  const ms = Math.max(0, now - (Number(entry && entry.since) || now))
+  const s = Math.round(ms / 1000)
+  if (s < 90) return s + 's'
+  const m = Math.round(s / 60)
+  return m < 90 ? m + 'm' : Math.round(m / 60) + 'h'
+}
+
+/**
+ * The line hive_say hands back to a sender about one recipient.
+ *
+ * Returns '' when there is nothing worth saying, so callers can drop it with a falsy check --
+ * silence is the right output for "they are here and free", which is the common case and does
+ * not need a sentence.
+ *
+ * @param {string} name        the recipient
+ * @param {object|null} entry  their busy entry, if any
+ * @param {boolean} present    are they actually in the room right now
+ */
+export function describeRecipient(name, entry, present, now = Date.now()) {
+  // ABSENCE OUTRANKS BUSY, and it is the more useful of the two: a message to someone who left
+  // is not delayed, it is unread forever, and the sender is the only one who can notice.
+  if (!present) return `@${name} is NOT in the room — nobody will read that. hive_members lists who is here.`
+  if (isBusy(entry, now)) return `@${name} has been busy ${busyFor(entry, now)} (${entry.what}) — expect a delay, they are not idle waiting on you.`
+  return ''
+}

package/hive-coord.js

@@ -1,110 +1,110 @@
-// hive-coord.js — the Hive coordination layer (v0 prototype).
-//
-// The bet: AI coding agents work fast and BLIND — they collide because, unlike a human
-// team, they have no way to coordinate BEFORE they edit. Merging (ICR) cleans up after a
-// collision. This prevents the collision in the first place.
-//
-// The design is a real hive: NO central controller, no conductor, no extra agent. Order
-// emerges from each agent following one local rule against a shared medium — exactly how
-// bees coordinate via traces in the environment (stigmergy), and how millions of Ethernet
-// devices share one wire with no master (carrier-sense / collision-detect / backoff).
-//
-// The shared medium is a CRDT map living IN the codebase doc (a Y.Map in Hivecode; a plain
-// Map in tests). Each region of work (a file, or a unit) can hold one CLAIM:
-//     { by: agentId, intent: string, at: time, ttl: ms }
-//
-// An agent's entire protocol — no coordinator anywhere:
-//   1. SENSE   — read the shared map. Is my target region claimed and fresh?
-//   2. FLOW    — if taken, move to open space (pick another free region). This is the
-//                emergent load-balancing: agents spread across the codebase on their own.
-//   3. CLAIM   — write my claim to the free region.
-//   4. VERIFY  — re-read (collision-detect): if a concurrent claim beat mine, BACK OFF and
-//                retry later. (Like Ethernet: listen, send, detect collision, back off.)
-//   5. RELEASE — when done, delete my claim and (optionally) leave a "done" trace.
-//
-// EVAPORATION: claims carry a TTL. A crashed or stalled agent's claim simply expires, and
-// the region frees itself — no central garbage collector, no deadlock. (The pheromone fades.)
-//
-// `shared` is any object with get(key)/set(key,val)/delete(key)/entries() — so the same
-// code runs on a JS Map (tests) and a Yjs Y.Map (production). `now` is injectable so tests
-// can drive a deterministic virtual clock.
-
-export function makeCoordinator(shared, self, opts = {}) {
-  const ttl = opts.ttl != null ? opts.ttl : 5000
-  // A holder may RENEW its own claim, because a long edit should not lose the file mid-write.
-  // But renewal cannot be unbounded, or the lease stops being a lease. MEASURED on a 12-agent
-  // run: one agent re-claimed site/pricing.md eight times and legal/terms.md seven times and
-  // released twice, and since `claim` reset `at` on every call the 60s TTL never once elapsed.
-  // Six other agents sensed a live owner for the whole run; sixteen messages asked it to let go.
-  // `since` records the FIRST acquisition and survives renewal, so what caps a claim is total
-  // hold time rather than time since the holder last touched it.
-  const maxHold = opts.maxHold != null ? opts.maxHold : ttl * 3
-  const now = opts.now || (() => Date.now())
-  const held = (c) => now() - (c.since != null ? c.since : c.at) // total, across renewals
-  const cap = (c) => (c.maxHold != null ? c.maxHold : maxHold)
-  const overheld = (c) => !!c && held(c) >= cap(c)
-  const expired = (c) => !c || (now() - c.at) >= c.ttl || overheld(c)
-
-  // SENSE: the live, non-expired claim on a region (or null if open).
-  const sense = (region) => { const c = shared.get(region); return expired(c) ? null : c }
-
-  // Is this region open to ME? (free, expired, or already mine)
-  const free = (region) => { const c = shared.get(region); return expired(c) || c.by === self }
-
-  // A renewal keeps the original `since`; a fresh acquisition starts a new one. Claims written
-  // before `since` existed fall back to `at`, so an older room stays readable.
-  const claim = (region, intent) => {
-    const prev = shared.get(region)
-    const renewing = !!prev && prev.by === self && !expired(prev)
-    shared.set(region, {
-      by: self, intent, at: now(), ttl, maxHold,
-      since: renewing ? (prev.since != null ? prev.since : prev.at) : now(),
-    })
-  }
-  const release = (region) => { const c = shared.get(region); if (c && c.by === self) shared.delete(region) }
-
-  // ACQUIRE one region: sense → claim → verify. Returns true iff I now hold it *as far as this
-  // replica can tell*, which is a weaker statement than it looks and the caller must know it.
-  //
-  // THE VERIFY IS LOCAL, AND THAT IS ITS LIMIT. `claim()` writes into this replica's copy of the
-  // map and the re-read below sees that write immediately -- before it has reached the relay or
-  // any peer. So the check catches only a claim that had ALREADY propagated when I wrote. Fire
-  // three agents at one region in the same tick and all three are told yes; the CRDT then
-  // converges to a single winner a moment later, by which time all three have started editing.
-  // Measured 5/5 trials, three agents, every one of them granted.
-  //
-  // That is not a bug in this function -- a synchronous call cannot wait for a network -- but a
-  // lock that says yes to three callers is not a lock, so anything that is about to WRITE must
-  // use `claimSettled()` in sync.js, which re-reads the holder after the claim has round-tripped
-  // through the relay. This stays as the optimistic fast path for sensing and for flow.
-  const acquire = (region, intent) => {
-    const c = shared.get(region)
-    if (c && !expired(c) && c.by !== self) return false // sensed an owner → defer
-    // Once total hold is exhausted the region is open to everyone — INCLUDING the outgoing
-    // holder, which could then win the re-claim race indefinitely and starve the waiters that
-    // maxHold exists to admit. So the overrunning holder stands down for a full maxHold, which
-    // is a window every waiter is guaranteed to poll inside. A single-ttl cooldown was tried
-    // first and is NOT enough: the holder just waits it out and opens a fresh `since`.
-    // The bar lapses on its own, so a file nobody else wants returns to its owner.
-    if (c && c.by === self && overheld(c) && held(c) < 2 * cap(c)) return false
-    claim(region, intent)
-    const after = shared.get(region)
-    return !(after && after.by !== self) // verify: did my claim survive?
-  }
-
-  // FLOW to open space: try my preferred regions in order, take the first I can acquire.
-  // This is what makes the swarm spread out with nobody assigning work.
-  const acquireAny = (candidates, intent) => {
-    for (const r of candidates) if (acquire(r, intent)) return r
-    return null
-  }
-
-  // Everything currently claimed (live), as a snapshot — for awareness / a Control Room.
-  const board = () => {
-    const out = []
-    for (const [region, c] of shared.entries()) if (!expired(c)) out.push({ region, ...c })
-    return out
-  }
-
-  return { sense, free, claim, release, acquire, acquireAny, board }
-}
+// hive-coord.js — the Hive coordination layer (v0 prototype).
+//
+// The bet: AI coding agents work fast and BLIND — they collide because, unlike a human
+// team, they have no way to coordinate BEFORE they edit. Merging (ICR) cleans up after a
+// collision. This prevents the collision in the first place.
+//
+// The design is a real hive: NO central controller, no conductor, no extra agent. Order
+// emerges from each agent following one local rule against a shared medium — exactly how
+// bees coordinate via traces in the environment (stigmergy), and how millions of Ethernet
+// devices share one wire with no master (carrier-sense / collision-detect / backoff).
+//
+// The shared medium is a CRDT map living IN the codebase doc (a Y.Map in Hivecode; a plain
+// Map in tests). Each region of work (a file, or a unit) can hold one CLAIM:
+//     { by: agentId, intent: string, at: time, ttl: ms }
+//
+// An agent's entire protocol — no coordinator anywhere:
+//   1. SENSE   — read the shared map. Is my target region claimed and fresh?
+//   2. FLOW    — if taken, move to open space (pick another free region). This is the
+//                emergent load-balancing: agents spread across the codebase on their own.
+//   3. CLAIM   — write my claim to the free region.
+//   4. VERIFY  — re-read (collision-detect): if a concurrent claim beat mine, BACK OFF and
+//                retry later. (Like Ethernet: listen, send, detect collision, back off.)
+//   5. RELEASE — when done, delete my claim and (optionally) leave a "done" trace.
+//
+// EVAPORATION: claims carry a TTL. A crashed or stalled agent's claim simply expires, and
+// the region frees itself — no central garbage collector, no deadlock. (The pheromone fades.)
+//
+// `shared` is any object with get(key)/set(key,val)/delete(key)/entries() — so the same
+// code runs on a JS Map (tests) and a Yjs Y.Map (production). `now` is injectable so tests
+// can drive a deterministic virtual clock.
+
+export function makeCoordinator(shared, self, opts = {}) {
+  const ttl = opts.ttl != null ? opts.ttl : 5000
+  // A holder may RENEW its own claim, because a long edit should not lose the file mid-write.
+  // But renewal cannot be unbounded, or the lease stops being a lease. MEASURED on a 12-agent
+  // run: one agent re-claimed site/pricing.md eight times and legal/terms.md seven times and
+  // released twice, and since `claim` reset `at` on every call the 60s TTL never once elapsed.
+  // Six other agents sensed a live owner for the whole run; sixteen messages asked it to let go.
+  // `since` records the FIRST acquisition and survives renewal, so what caps a claim is total
+  // hold time rather than time since the holder last touched it.
+  const maxHold = opts.maxHold != null ? opts.maxHold : ttl * 3
+  const now = opts.now || (() => Date.now())
+  const held = (c) => now() - (c.since != null ? c.since : c.at) // total, across renewals
+  const cap = (c) => (c.maxHold != null ? c.maxHold : maxHold)
+  const overheld = (c) => !!c && held(c) >= cap(c)
+  const expired = (c) => !c || (now() - c.at) >= c.ttl || overheld(c)
+
+  // SENSE: the live, non-expired claim on a region (or null if open).
+  const sense = (region) => { const c = shared.get(region); return expired(c) ? null : c }
+
+  // Is this region open to ME? (free, expired, or already mine)
+  const free = (region) => { const c = shared.get(region); return expired(c) || c.by === self }
+
+  // A renewal keeps the original `since`; a fresh acquisition starts a new one. Claims written
+  // before `since` existed fall back to `at`, so an older room stays readable.
+  const claim = (region, intent) => {
+    const prev = shared.get(region)
+    const renewing = !!prev && prev.by === self && !expired(prev)
+    shared.set(region, {
+      by: self, intent, at: now(), ttl, maxHold,
+      since: renewing ? (prev.since != null ? prev.since : prev.at) : now(),
+    })
+  }
+  const release = (region) => { const c = shared.get(region); if (c && c.by === self) shared.delete(region) }
+
+  // ACQUIRE one region: sense → claim → verify. Returns true iff I now hold it *as far as this
+  // replica can tell*, which is a weaker statement than it looks and the caller must know it.
+  //
+  // THE VERIFY IS LOCAL, AND THAT IS ITS LIMIT. `claim()` writes into this replica's copy of the
+  // map and the re-read below sees that write immediately -- before it has reached the relay or
+  // any peer. So the check catches only a claim that had ALREADY propagated when I wrote. Fire
+  // three agents at one region in the same tick and all three are told yes; the CRDT then
+  // converges to a single winner a moment later, by which time all three have started editing.
+  // Measured 5/5 trials, three agents, every one of them granted.
+  //
+  // That is not a bug in this function -- a synchronous call cannot wait for a network -- but a
+  // lock that says yes to three callers is not a lock, so anything that is about to WRITE must
+  // use `claimSettled()` in sync.js, which re-reads the holder after the claim has round-tripped
+  // through the relay. This stays as the optimistic fast path for sensing and for flow.
+  const acquire = (region, intent) => {
+    const c = shared.get(region)
+    if (c && !expired(c) && c.by !== self) return false // sensed an owner → defer
+    // Once total hold is exhausted the region is open to everyone — INCLUDING the outgoing
+    // holder, which could then win the re-claim race indefinitely and starve the waiters that
+    // maxHold exists to admit. So the overrunning holder stands down for a full maxHold, which
+    // is a window every waiter is guaranteed to poll inside. A single-ttl cooldown was tried
+    // first and is NOT enough: the holder just waits it out and opens a fresh `since`.
+    // The bar lapses on its own, so a file nobody else wants returns to its owner.
+    if (c && c.by === self && overheld(c) && held(c) < 2 * cap(c)) return false
+    claim(region, intent)
+    const after = shared.get(region)
+    return !(after && after.by !== self) // verify: did my claim survive?
+  }
+
+  // FLOW to open space: try my preferred regions in order, take the first I can acquire.
+  // This is what makes the swarm spread out with nobody assigning work.
+  const acquireAny = (candidates, intent) => {
+    for (const r of candidates) if (acquire(r, intent)) return r
+    return null
+  }
+
+  // Everything currently claimed (live), as a snapshot — for awareness / a Control Room.
+  const board = () => {
+    const out = []
+    for (const [region, c] of shared.entries()) if (!expired(c)) out.push({ region, ...c })
+    return out
+  }
+
+  return { sense, free, claim, release, acquire, acquireAny, board }
+}