agent-relay-server 0.102.1 → 0.102.2

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.102.1",
+    "version": "0.102.2",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.102.1",
+  "version": "0.102.2",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",

package/runner/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.102.1",
+  "version": "0.102.2",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/db/channels.ts

@@ -284,7 +284,35 @@ function channelTargetHealth(binding: ChannelBinding, now: number = Date.now()):
   };
 }
 
+// #797 — outbound (egress-only) channel liveness. Bidirectional channels (e.g. Telegram)
+// have a backing pool agent that heartbeats, so their agent `lastSeen`/`status` track
+// reality. Outbound-only channels (e.g. ntfy) are just a channels-host daemon SSE
+// subscription with NO agent behind them to heartbeat — so the registration's `lastSeen`
+// goes stale and the offline sweep flips it offline even while the daemon's subscription is
+// live and delivery works. For these, liveness is "is the channels-host subscribed for this
+// channel agent on the SSE bus?", not heartbeat freshness. A late-bound probe (not a direct
+// import) because sse.ts imports the db barrel — sse registers this at startup, mirroring
+// `onWorkspaceChange`.
+type ChannelSubscriberProbe = (channelAgentId: string) => boolean;
+let channelSubscriberProbe: ChannelSubscriberProbe | null = null;
+export function setChannelSubscriberProbe(probe: ChannelSubscriberProbe | null): void {
+  channelSubscriberProbe = probe;
+}
+function hasActiveChannelSubscriber(channelAgentId: string): boolean {
+  try {
+    return channelSubscriberProbe ? channelSubscriberProbe(channelAgentId) : false;
+  } catch {
+    return false;
+  }
+}
+
 function rowToChannelSummary(row: any): ChannelSummary {
+  // Outbound channels report online iff their channels-host SSE subscription is active,
+  // overriding the heartbeat-derived agent status/ready (which is meaningless for an
+  // agentless egress channel). Inbound/bidirectional keep the backing agent's signal.
+  const subscriberLive = row.direction === "outbound" ? hasActiveChannelSubscriber(row.agent_id) : null;
+  const status: ChannelSummary["status"] = subscriberLive === null ? row.agent_status : (subscriberLive ? "online" : "offline");
+  const ready = subscriberLive === null ? row.agent_ready === 1 : subscriberLive;
   const binding = row.binding_id ? rowToChannelBinding({
     id: row.binding_id,
     channel_id: row.id,
@@ -308,8 +336,8 @@ function rowToChannelSummary(row: any): ChannelSummary {
     transport: row.transport,
     agentId: row.agent_id,
     accountId: row.account_id,
-    status: row.agent_status,
-    ready: row.agent_ready === 1,
+    status,
+    ready,
     direction: row.direction,
     target: binding ? bindingTargetToLegacyTarget(binding.target) : undefined,
     binding,

package/src/db/provider-quota-burn.ts

@@ -15,6 +15,17 @@ const WINDOW_NOMINAL_MS: Record<ProviderQuotaBurnRole, number> = {
 // observed rate (and burnRatio) back toward 0 instead of freezing the endpoint slope.
 const RECENCY_HALFLIFE_FRACTION = 0.25;
 
+// #798 — idle de-bias: once a provider's utilization has held flat for this long, any residual
+// forward-burn rate is a stale-burst artifact (the recency half-life decays it, but for the 7d
+// window — half-life ~42h — far too slowly: codex idle ~24h still projected ~1.07 at reset,
+// walking the band boundary tick-to-tick). When idle this long the forward-burn term is collapsed
+// so projectedUtilAtReset → current utilization. The threshold is absolute (NOT window-scaled): a
+// 5h window resets long before reaching it, so this only de-biases the slow-decaying 7d window;
+// shorter idle stretches keep the graceful #760 recency decay. The over-target avoid is preserved
+// by the position penalty in spawn-targets (a stable, position-based floor), not by this rate.
+const IDLE_FORWARD_COLLAPSE_MS = 6 * 3_600_000;
+const IDLE_UTILIZATION_EPSILON = 1e-9;
+
 type QuotaWindow = QuotaState["windows"][number];
 
 // Provider-agnostic: window role is expressed by name only. Each adapter uses the
@@ -80,6 +91,19 @@ function recencyWeightedRatePerMs(
   return Math.max(0, weightedDelta / weightedDt);
 }
 
+// #798 — when did utilization last differ from its current value? Scanning back from the newest
+// sample, the first sample that differs marks the last change; everything after it (up to now) is
+// the flat idle stretch. If every sample equals the current value the window has been flat since
+// the oldest sample. Samples are assumed sorted ascending by capturedAt.
+function lastUtilizationChangeAt(samples: Array<{ capturedAt: number; utilization: number }>, current: number): number {
+  for (let i = samples.length - 1; i >= 0; i--) {
+    if (Math.abs(samples[i]!.utilization - current) > IDLE_UTILIZATION_EPSILON) {
+      return samples[i + 1]?.capturedAt ?? samples[i]!.capturedAt;
+    }
+  }
+  return samples[0]?.capturedAt ?? 0;
+}
+
 function deriveProviderQuotaBurnWindow(input: {
   provider: string;
   currentWindow: QuotaWindow;
@@ -137,17 +161,25 @@ function deriveProviderQuotaBurnWindow(input: {
     ? [...samples, { capturedAt: input.now, utilization: utilizationNow }]
     : samples;
   const observedRatePerMs = recencyWeightedRatePerMs(rateSamples, input.now, halfLifeMs);
+  // #798 — idle de-bias: if utilization has held flat (no change vs. now) for IDLE_FORWARD_COLLAPSE_MS,
+  // treat the forward-burn term as a stale-burst artifact and collapse it to 0 so the projection
+  // pins to current utilization instead of walking the band boundary. lastChangeAt is the moment
+  // utilization last differed from the current value (the synthetic "still X as of now" interval is
+  // what makes a deduped idle stretch observable here).
+  const lastChangeAt = lastUtilizationChangeAt(samples, utilizationNow);
+  const effectiveRate = input.now - lastChangeAt >= IDLE_FORWARD_COLLAPSE_MS ? 0 : observedRatePerMs;
   // #760 (Defect 2) — pace against a configurable target (<100%); slack carries the underburn
   // signal. The query layer (spawn-targets) may re-derive these against a per-provider target;
   // the ingest-time values use the default so direct burn consumers (dashboard) have a number.
   const pace = quotaPaceMetrics({
     utilization: utilizationNow,
-    observedRatePerMs,
+    observedRatePerMs: effectiveRate,
     timeToResetMs,
     target: DEFAULT_QUOTA_TARGET_UTILIZATION,
   });
-  if (observedRatePerMs <= 0) {
-    // Idle (or decayed-to-idle): no projected wall, but slack still flags the headroom.
+  if (effectiveRate <= 0) {
+    // Idle (decayed-to-idle, or #798 idle-collapsed): no projected wall, but slack still flags the
+    // headroom (positive = underburn) or, when over target, the position the band-floor avoids.
     return {
       ...low,
       confidence: "high",
@@ -158,13 +190,13 @@ function deriveProviderQuotaBurnWindow(input: {
       target: pace.target,
     };
   }
-  const timeToWallMs = remainingQuota / observedRatePerMs;
+  const timeToWallMs = remainingQuota / effectiveRate;
   const projectedWallAt = input.now + timeToWallMs;
   return {
     ...low,
     confidence: "high",
     burnRatio: pace.burnRatio,
-    observedRatePerMs,
+    observedRatePerMs: effectiveRate,
     timeToWallMs,
     projectedWallAt,
     // #760 (Defect 2) — symmetric: negative means the wall lands AFTER reset (headroom left).

package/src/quota-band-transition.ts

@@ -14,17 +14,36 @@
 // at most one per RECOVERY_MIN_INTERVAL_MS — degradation is the actionable
 // signal; fleet-wake on recovery churn is suppressed.
 //
+// #798 — principled noisy-signal → discrete-state pipeline so a provider in a
+// steady state stops re-emitting band-change notifications:
+//   1. LOW-PASS (EMA): the raw penalty/slack jitters tick-to-tick (burnRatio
+//      recompute, shrinking timeToReset). An exponential moving average with a
+//      few-minute time constant is applied to the signal BEFORE it is thresholded
+//      into a band — killing the noise at the source, so a transient single-tick
+//      excursion never reaches the opposite band.
+//   2. SCHMITT (applyHysteresis): enter/exit thresholds with a gap on the band
+//      STATE (not just the routing weight — that's where #756 fell short).
+//   3. MIN-DWELL DEBOUNCE: the new band must hold DEBOUNCE_SAMPLES ticks before
+//      the human-facing notification fires.
+// The idle-projection de-bias + position penalty (db/provider-quota-burn.ts,
+// spawn-targets.ts) attack the same flap from the other end: an idle provider's
+// band is now position-pinned, so the input the pipeline sees is already stable.
+//
 // Called from handleProviderQuotaAdvisory in quota-advisory.ts so the check
 // runs on the same event hook as the utilization-threshold advisory — no
 // parallel delivery channel.
 import { emitRelayEvent } from "./events";
 import { routeNotification } from "./notification-router";
 import { getSpawnCapableAgentIds } from "./routing-policy-push";
-import { getProviderBandInfo, windowRecommendedAction } from "./spawn-targets";
+import { getProviderBandInfo, quotaBandFromSignal, windowRecommendedAction } from "./spawn-targets";
 import type { ProviderBandInfo, ProviderBandWindow, QuotaBand } from "./spawn-targets";
 import type { ProviderQuotaAdvisoryInput } from "./db/provider-quotas";
 
 const DEBOUNCE_SAMPLES = 3;
+// #798 — EMA time constant for the low-pass. "A few minutes": longer than the ~5-min poll-cadence
+// tick jitter (so noise is smoothed), far shorter than the 5h/7d utilization trend (so a genuine
+// quota move still surfaces within a poll or two). dt-based, so it is correct at any cadence.
+const EMA_TAU_MS = 6 * 60_000;
 // Penalty must drop this far below the band entry threshold before recovery is recognised.
 // #760: widened 0.05 → 0.10. Live evidence (Claude 7d parked at avoidLargeAt with burn×1.4)
 // showed the 0.05 deadband was too tight for real penalty jitter — it still ping-ponged
@@ -42,6 +61,22 @@ interface TransitionState {
   pendingBand: QuotaBand | null;
   pendingCount: number;
   lastTransitionAt: number;
+  // #798 — low-pass state: EMA of the noisy penalty/slack signal, plus the tick time it was last
+  // updated (to size the dt-based smoothing factor). null until the first high-confidence sample.
+  emaPenalty: number | null;
+  emaSlack: number | null;
+  emaUpdatedAt: number;
+}
+
+// #798 — dt-based EMA blend factor: 1 − e^(−dt/τ). dt = 0 (or first sample) → seed verbatim.
+function emaAlpha(dtMs: number): number {
+  if (!(dtMs > 0)) return 1;
+  return 1 - Math.exp(-dtMs / EMA_TAU_MS);
+}
+
+function emaStep(prev: number | null, value: number, dtMs: number): number {
+  if (prev === null) return value;
+  return prev + emaAlpha(dtMs) * (value - prev);
 }
 
 const bandState = new Map<string, TransitionState>();
@@ -73,17 +108,33 @@ export function processBandTransitions(input: ProviderQuotaAdvisoryInput): void
       pendingBand: null,
       pendingCount: 0,
       lastTransitionAt: 0,
+      emaPenalty: null,
+      emaSlack: null,
+      emaUpdatedAt: 0,
     };
 
-    // #756: asymmetric hysteresis — recovery needs penalty HYSTERESIS_MARGIN below the entry
-    // threshold of the current band to prevent ping-pong at a boundary. #760 extends this with a
-    // slack deadband for the "prefer" boundary.
-    const effectiveBand = applyHysteresis(window.band, window.penalty, window.slack, state.lastNotifiedBand, info.quotaBands, info.preferSlackAt);
+    // #798 (layer 1) — low-pass the noisy penalty/slack BEFORE thresholding, then re-classify the
+    // smoothed signal into a band. A transient one-tick excursion is averaged out, so it never
+    // reaches (and re-emits) the opposite band; a sustained move still crosses within a poll or two.
+    const dtMs = state.emaUpdatedAt > 0 ? input.now - state.emaUpdatedAt : 0;
+    const emaPenalty = emaStep(state.emaPenalty, window.penalty, dtMs);
+    const emaSlack = window.slack === null ? state.emaSlack : emaStep(state.emaSlack, window.slack, dtMs);
+    state.emaPenalty = emaPenalty;
+    state.emaSlack = emaSlack;
+    state.emaUpdatedAt = input.now;
+    // Persist immediately so the low-pass state survives every early-continue below (the state is
+    // then mutated in place by reference — the EMA must carry across ticks to smooth excursions).
+    bandState.set(key, state);
+    const smoothedBand = quotaBandFromSignal(emaPenalty, emaSlack, info.quotaBands, info.preferSlackAt);
+
+    // #756 (layer 2): asymmetric hysteresis — recovery needs penalty HYSTERESIS_MARGIN below the
+    // entry threshold of the current band to prevent ping-pong at a boundary. #760 extends this with
+    // a slack deadband for the "prefer" boundary. Operates on the smoothed signal.
+    const effectiveBand = applyHysteresis(smoothedBand, emaPenalty, emaSlack, state.lastNotifiedBand, info.quotaBands, info.preferSlackAt);
 
     if (effectiveBand === state.lastNotifiedBand) {
-      if (state.pendingBand !== null) {
-        bandState.set(key, { ...state, pendingBand: null, pendingCount: 0 });
-      }
+      state.pendingBand = null;
+      state.pendingCount = 0;
       continue;
     }
 

package/src/spawn-targets.ts

@@ -231,8 +231,7 @@ function spawnQuotaWindow(
   // recency-weighted rate projects no early wall) replaces the blunt utilization floor, which
   // used to hide a legitimate low-util-high-burst alarm. Operators may still opt back in.
   const utilizationFloor = providerCfg?.burnPenaltyUtilizationFloor ?? 0;
-  const rawPenalty = (earlyFraction ?? 0) * weight;
-  const penalty = quotaWindow.utilization < utilizationFloor ? 0 : rawPenalty;
+  const pacePenalty = (earlyFraction ?? 0) * weight;
 
   // #760 — re-derive the pace projection against the PER-PROVIDER target (the stored burn used
   // the default). Slack is the symmetric underburn signal; prefer flags a window with no
@@ -249,6 +248,19 @@ function spawnQuotaWindow(
     projectedUtilAtReset = pace.projectedUtilAtReset;
     slack = pace.slack;
   }
+
+  // #798 — position penalty: an idle provider whose (de-biased) projection lands AT/OVER target is
+  // already over-extended, but its forward-wall pace penalty is 0 (no burn) — so without this the
+  // band would flip to "normal" and route big jobs onto a near-exhausted provider. Derive a STABLE
+  // penalty from the overshoot magnitude (slack < 0 ⇒ projectedUtilAtReset − target), decoupled
+  // from the jittery forward-burn term. Gated to idle (observedRatePerMs collapsed to 0): an ACTIVE
+  // provider is still governed entirely by the pace penalty (effective = max of the two), so this
+  // adds a floor for the parked-high case WITHOUT changing active routing. Under-target idle ⇒ 0.
+  const idle = burnWindow.observedRatePerMs !== null && burnWindow.observedRatePerMs <= 0;
+  const overshoot = slack !== null ? Math.max(0, -slack) : 0;
+  const positionPenalty = idle ? Math.min(1, overshoot / Math.max(1e-9, 1 - target)) * weight : 0;
+  const rawPenalty = Math.max(pacePenalty, positionPenalty);
+  const penalty = quotaWindow.utilization < utilizationFloor ? 0 : rawPenalty;
   const prefer = !blockedNow && penalty === 0
     && quotaPenaltyBandFor(penalty) === "normal"
     && slack !== null && slack >= preferSlackAt;
@@ -349,6 +361,22 @@ function quotaPenaltyBandFor(
   return "normal";
 }
 
+// #798 — classify a (penalty, slack) signal into a band. The single home for the
+// penalty-ladder + prefer-overlay mapping, shared by getProviderBandInfo's per-window band and the
+// band-transition notifier, which re-classifies the EMA-smoothed signal before thresholding. The
+// prefer overlay mirrors spawnQuotaWindow: a normal-band window projected ≥ preferSlackAt under
+// target reads "prefer".
+export function quotaBandFromSignal(
+  penalty: number,
+  slack: number | null,
+  quotaBands: Partial<{ cautionAt: number; avoidLargeAt: number; hardAvoidAt: number }> | undefined,
+  preferSlackAt: number,
+): QuotaBand {
+  const base = quotaPenaltyBandFor(penalty, quotaBands);
+  if (base === "normal" && slack !== null && slack >= preferSlackAt) return "prefer";
+  return base;
+}
+
 function recommendedAction(input: { quotaPenaltyBand: SpawnQuotaBurnBand; blockedNow: boolean; prefer: boolean; slack: number | null; windows: SpawnQuotaBurnWindow[] }): string {
   if (input.blockedNow) {
     const hasSevenDayBlock = input.windows.some((window) => window.role === "7d" && window.blockedNow);

package/src/sse.ts

@@ -1,4 +1,4 @@
-import { getAgent, getOrchestrator, matchingDeliveryAgents, onWorkspaceChange, sendMessageWithResult } from "./db";
+import { getAgent, getOrchestrator, matchingDeliveryAgents, onWorkspaceChange, sendMessageWithResult, setChannelSubscriberProbe } from "./db";
 import { projectAgentStatusData } from "./agent-card-projection";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
 import { messageMatchesAgent, targetMatchesAgent } from "./agent-ref";
@@ -20,6 +20,17 @@ const SSE_RETRY_MS = 5_000;
 
 subscribeRelayEvents((event) => fanout(event));
 
+// #797 — let the db layer derive outbound-channel liveness from live SSE subscriptions.
+// A channel agent is "subscribed" iff the channels-host daemon holds an open
+// GET /api/events?for=<channelAgentId> stream (createSSEStream stores `for` as agentId).
+export function hasActiveSubscriber(agentId: string): boolean {
+  for (const conn of connections.values()) {
+    if (conn.agentId === agentId) return true;
+  }
+  return false;
+}
+setChannelSubscriberProbe(hasActiveSubscriber);
+
 export function createSSEStream(agentId: string | null): Response {
   let connId: string;