@tokenfactory/acc-runner 0.40.4 → 0.40.5

package/dist/companion-select.d.ts

@@ -0,0 +1,71 @@
+/**
+ * CC-3E FAILOVER-E2E — companion contention resolution: most-recent-heartbeat
+ * wins.
+ *
+ * When an operator has TWO companions registered for the same conversation
+ * (e.g. a laptop that went to sleep and a desktop that just came online, or a
+ * duplicate launch), only one should serve. Per-turn contention is already safe
+ * — `acc.claim_chat_turn` takes a per-conversation advisory lock, so exactly one
+ * companion wins each individual turn (see companion.ts §advisory lock). But the
+ * lock's winner is arbitrary; a stale companion whose host is asleep can still
+ * grab the lock first and then requeue on lease-expiry, adding a wasted hop per
+ * turn. This module is the PURE tiebreak the pump consults before racing for the
+ * lock: prefer the companion whose heartbeat is freshest (and drop ones whose
+ * heartbeat has gone stale entirely).
+ *
+ * The heartbeat-recency comparator mirrors the reviewer-routing "freshest wins"
+ * rule (api/_lib/reviewer/routing.ts) but for chat companions, which had no such
+ * tiebreak. Pure — the clock is passed in — so every ordering + staleness branch
+ * is unit-testable without real timers.
+ */
+import type { RunnerCapacityClass } from "./engines/types.js";
+/** A companion's last-known presence, as gathered from `identity:<user>` beats. */
+export interface CompanionPresence {
+    runnerId: string;
+    /** Epoch ms of this companion's most recent heartbeat. */
+    lastHeartbeatMs: number;
+    /** Last-reported host capacity. */
+    capacity: RunnerCapacityClass;
+    /** Engines still claimable on this companion at report time. */
+    availableEngineIds: string[];
+}
+/**
+ * Default staleness window: a companion whose last heartbeat is older than this
+ * is considered gone. Generous relative to the 4 s default beat cadence so a
+ * single missed beat (GC pause, brief network blip) does not evict a live host,
+ * but tight enough that a slept/crashed host stops winning within seconds.
+ */
+export declare const DEFAULT_HEARTBEAT_STALE_MS = 15000;
+export interface CompanionSelectOptions {
+    /** Current time (epoch ms). */
+    now: number;
+    /** Heartbeats older than this are dropped as gone. Default 15s. */
+    staleMs?: number;
+    /**
+     * Require the winner to still advertise claimable engines. Default true — a
+     * companion reporting an empty engine set has nothing to serve and should not
+     * win even if its heartbeat is the freshest.
+     */
+    requireEngines?: boolean;
+}
+/** True when a heartbeat is within the staleness window (i.e. the host is live). */
+export declare function isHeartbeatLive(presence: CompanionPresence, now: number, staleMs?: number): boolean;
+/** The eligible companions (live + non-empty engines when required), unranked. */
+export declare function eligibleCompanions(companions: readonly CompanionPresence[], opts: CompanionSelectOptions): CompanionPresence[];
+/**
+ * Pick the companion that should serve: the live one with the FRESHEST heartbeat.
+ * Ties (identical heartbeat ms — e.g. a replayed beat) break on `runnerId`
+ * lexicographically so the choice is deterministic. Returns null when no
+ * companion is eligible (all stale / no engines).
+ */
+export declare function pickFreshestCompanion(companions: readonly CompanionPresence[], opts: CompanionSelectOptions): CompanionPresence | null;
+/**
+ * Should THIS companion defer (yield) to a fresher peer? True when a different,
+ * eligible companion has a strictly newer heartbeat. Used by the pump to avoid
+ * racing for the claim lock when a fresher peer is present — the stale host backs
+ * off instead of winning the lock and then requeueing on lease-expiry.
+ */
+export declare function shouldDeferToPeer(self: CompanionPresence, peers: readonly CompanionPresence[], opts: CompanionSelectOptions): boolean;
+/** Parse an ISO-8601 heartbeat timestamp to epoch ms (NaN-safe → 0). */
+export declare function heartbeatMsFromIso(ts: string | null | undefined): number;
+//# sourceMappingURL=companion-select.d.ts.map

package/dist/companion-select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"companion-select.d.ts","sourceRoot":"","sources":["../src/companion-select.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,eAAe,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,gEAAgE;IAChE,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD,MAAM,WAAW,sBAAsB;IACrC,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,iBAAiB,EAC3B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,MAAmC,GAC3C,OAAO,CAET;AAED,kFAAkF;AAClF,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,SAAS,iBAAiB,EAAE,EACxC,IAAI,EAAE,sBAAsB,GAC3B,iBAAiB,EAAE,CAQrB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,SAAS,iBAAiB,EAAE,EACxC,IAAI,EAAE,sBAAsB,GAC3B,iBAAiB,GAAG,IAAI,CAS1B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,SAAS,iBAAiB,EAAE,EACnC,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAGT;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAIxE"}

package/dist/companion-select.js

@@ -0,0 +1,58 @@
+/**
+ * Default staleness window: a companion whose last heartbeat is older than this
+ * is considered gone. Generous relative to the 4 s default beat cadence so a
+ * single missed beat (GC pause, brief network blip) does not evict a live host,
+ * but tight enough that a slept/crashed host stops winning within seconds.
+ */
+export const DEFAULT_HEARTBEAT_STALE_MS = 15_000;
+/** True when a heartbeat is within the staleness window (i.e. the host is live). */
+export function isHeartbeatLive(presence, now, staleMs = DEFAULT_HEARTBEAT_STALE_MS) {
+    return now - presence.lastHeartbeatMs <= Math.max(0, staleMs);
+}
+/** The eligible companions (live + non-empty engines when required), unranked. */
+export function eligibleCompanions(companions, opts) {
+    const staleMs = opts.staleMs ?? DEFAULT_HEARTBEAT_STALE_MS;
+    const requireEngines = opts.requireEngines ?? true;
+    return companions.filter((c) => {
+        if (!isHeartbeatLive(c, opts.now, staleMs))
+            return false;
+        if (requireEngines && c.availableEngineIds.length === 0)
+            return false;
+        return true;
+    });
+}
+/**
+ * Pick the companion that should serve: the live one with the FRESHEST heartbeat.
+ * Ties (identical heartbeat ms — e.g. a replayed beat) break on `runnerId`
+ * lexicographically so the choice is deterministic. Returns null when no
+ * companion is eligible (all stale / no engines).
+ */
+export function pickFreshestCompanion(companions, opts) {
+    const eligible = eligibleCompanions(companions, opts);
+    if (eligible.length === 0)
+        return null;
+    return eligible.reduce((best, c) => {
+        if (c.lastHeartbeatMs !== best.lastHeartbeatMs) {
+            return c.lastHeartbeatMs > best.lastHeartbeatMs ? c : best;
+        }
+        return c.runnerId < best.runnerId ? c : best;
+    });
+}
+/**
+ * Should THIS companion defer (yield) to a fresher peer? True when a different,
+ * eligible companion has a strictly newer heartbeat. Used by the pump to avoid
+ * racing for the claim lock when a fresher peer is present — the stale host backs
+ * off instead of winning the lock and then requeueing on lease-expiry.
+ */
+export function shouldDeferToPeer(self, peers, opts) {
+    const winner = pickFreshestCompanion([self, ...peers], opts);
+    return !!winner && winner.runnerId !== self.runnerId;
+}
+/** Parse an ISO-8601 heartbeat timestamp to epoch ms (NaN-safe → 0). */
+export function heartbeatMsFromIso(ts) {
+    if (!ts)
+        return 0;
+    const n = Date.parse(ts);
+    return Number.isFinite(n) ? n : 0;
+}
+//# sourceMappingURL=companion-select.js.map

package/dist/companion-select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"companion-select.js","sourceRoot":"","sources":["../src/companion-select.ts"],"names":[],"mappings":"AAiCA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC;AAejD,oFAAoF;AACpF,MAAM,UAAU,eAAe,CAC7B,QAA2B,EAC3B,GAAW,EACX,UAAkB,0BAA0B;IAE5C,OAAO,GAAG,GAAG,QAAQ,CAAC,eAAe,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,kBAAkB,CAChC,UAAwC,EACxC,IAA4B;IAE5B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,0BAA0B,CAAC;IAC3D,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC;IACnD,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QAC7B,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC;YAAE,OAAO,KAAK,CAAC;QACzD,IAAI,cAAc,IAAI,CAAC,CAAC,kBAAkB,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACtE,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,UAAwC,EACxC,IAA4B;IAE5B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IACtD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QACjC,IAAI,CAAC,CAAC,eAAe,KAAK,IAAI,CAAC,eAAe,EAAE,CAAC;YAC/C,OAAO,CAAC,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7D,CAAC;QACD,OAAO,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/C,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAuB,EACvB,KAAmC,EACnC,IAA4B;IAE5B,MAAM,MAAM,GAAG,qBAAqB,CAAC,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;IAC7D,OAAO,CAAC,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,CAAC;AACvD,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,kBAAkB,CAAC,EAA6B;IAC9D,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,CAAC;IAClB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenfactory/acc-runner",
-  "version": "0.40.4",
+  "version": "0.40.5",
   "description": "Agent Control Center local runner. Spawns Claude Code sessions assigned via ACC.",
   "license": "UNLICENSED",
   "private": false,