agent-relay-server 0.94.4 → 0.94.6

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.94.4",
+    "version": "0.94.6",
     "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.94.4",
+  "version": "0.94.6",
   "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.94.4",
+  "version": "0.94.6",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/agent-busy-health.ts

@@ -38,6 +38,13 @@ function activeWork(agent: AgentCard): ActiveWorkLike[] {
   return Array.isArray(agent.meta?.activeWork) ? agent.meta.activeWork as ActiveWorkLike[] : [];
 }
 
+function hasLiveToolOrSubprocessWork(works: ActiveWorkLike[]): boolean {
+  return works.some((work) => {
+    const kind = stringValue(work.kind);
+    return Boolean(kind && kind !== "provider-turn");
+  });
+}
+
 function thresholdFor(kind: BusyHealthKind): number {
   if (kind === "startup") return STUCK_BUSY_STARTUP_MS;
   if (kind === "reconnect") return STUCK_BUSY_RECONNECT_MS;
@@ -70,13 +77,17 @@ function classifyBusy(agent: AgentCard, now: number): { kind: BusyHealthKind; wo
 export function deriveAgentBusyHealth(agent: AgentCard, now: number = Date.now()): AgentBusyHealth | undefined {
   const classified = classifyBusy(agent, now);
   if (!classified) return undefined;
+  const works = activeWork(agent);
   const thresholdMs = thresholdFor(classified.kind);
   const activeWorkStartedAt = Math.max(0, classified.startedAt);
   const activeWorkAgeMs = Math.max(0, now - activeWorkStartedAt);
   const lastProviderEventAt = numberValue(agent.meta?.lastProviderEventAt);
   const lastProgressAt = lastProviderEventAt ?? activeWorkStartedAt;
   const staleForMs = Math.max(0, now - lastProgressAt);
-  const stuck = activeWorkAgeMs >= thresholdMs && staleForMs >= thresholdMs;
+  const stuck =
+    !hasLiveToolOrSubprocessWork(works) &&
+    activeWorkAgeMs >= thresholdMs &&
+    staleForMs >= thresholdMs;
   const work = classified.work;
   return {
     status: stuck ? "stuck-busy" : "ok",

package/src/db/delivery.ts

@@ -422,6 +422,23 @@ export function resolveQueuedPolicyMessages(policyName: string, agentId: string)
  * Returns the flushed messages so callers can emit `message.available` / `message.new` /
  * `message.delivery_updated` events.
  */
+/**
+ * Distinct direct (agent) targets that have messages still parked at
+ * `queued` older than `minAgeMs`. Backstop for #706: the primary recovery is
+ * flush-on-availability, but if that event is ever missed a queued message is
+ * invisible (pollMessages excludes `queued`) until it expires. The periodic
+ * resweep uses this to re-resolve such messages once the target is available.
+ */
+export function listStaleQueuedDirectTargets(now: number = Date.now(), minAgeMs = 60_000): string[] {
+  const rows = getDb().query(`
+    SELECT DISTINCT to_target FROM messages
+    WHERE delivery_status = 'queued'
+      AND to_target IS NOT NULL
+      AND COALESCE(queued_at, created_at) <= ?
+  `).all(now - minAgeMs) as Array<{ to_target: string }>;
+  return rows.map((row) => row.to_target);
+}
+
 export function resolveQueuedDirectMessages(agentId: string): Message[] {
   const rows = getDb().query(`
     SELECT m.id
@@ -451,6 +468,21 @@ export function resolveQueuedDirectMessages(agentId: string): Message[] {
   return ids.map((id) => getMessage(id)).filter((message): message is Message => Boolean(message));
 }
 
+/**
+ * Count messages that expired undelivered at max_age within the trailing
+ * `windowMs` (default 24h). Surfaces silent channel data loss (#706) — a queued
+ * message that died without ever reaching its recipient — as a health signal.
+ */
+export function countExpiredUndeliveredMessages(now: number = Date.now(), windowMs = 86_400_000): number {
+  return (getDb().query(`
+    SELECT COUNT(*) as c FROM messages
+    WHERE delivery_status = 'dead'
+      AND delivery_poison_reason = 'queued message expired'
+      AND delivery_updated_at IS NOT NULL
+      AND delivery_updated_at >= ?
+  `).get(now - windowMs) as { c: number }).c;
+}
+
 export function expireQueuedMessages(now: number = Date.now()): Message[] {
   const rows = getDb().query(`
     SELECT id FROM messages

package/src/db/stats.ts

@@ -16,6 +16,7 @@ import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_ME
 import { matchAgents } from "../agent-ref";
 import { listAgents } from "./agents.ts";
 import { listChannels } from "./channels.ts";
+import { countExpiredUndeliveredMessages } from "./delivery.ts";
 import { messageTaskClosed } from "./claim-sql.ts";
 import { getDb } from "./connection.ts";
 import type {
@@ -466,6 +467,37 @@ export function getHealth(now: number = Date.now()): HealthReport {
       : undefined,
   });
 
+  // A channel bridge (e.g. Telegram) that is registered but stale or not-ready
+  // is silently NOT delivering — channel messages queue against it (#706). The
+  // binding-target health above can read "ok" while the bridge itself is wedged,
+  // so check the bridge agent's own liveness to avoid green-washing a down bridge.
+  const channelBridges = listAgents().filter((agent) =>
+    agent.id !== "user" && agent.id !== "system" &&
+    (agent.kind === "channel" || agent.meta?.kind === "channel"));
+  const staleChannelBridges = channelBridges.filter((agent) =>
+    agent.status !== "offline" && agent.lastSeen <= now - STALE_TTL_MS);
+  const notReadyChannelBridges = channelBridges.filter((agent) =>
+    agent.status !== "offline" && !agent.ready && agent.lastSeen > now - STALE_TTL_MS);
+  const unhealthyChannelBridges = [...staleChannelBridges, ...notReadyChannelBridges];
+  checks.push({
+    name: "channel-bridge-liveness",
+    status: staleChannelBridges.length > 0 ? "error" : notReadyChannelBridges.length > 0 ? "warn" : "ok",
+    count: unhealthyChannelBridges.length,
+    detail: unhealthyChannelBridges.length > 0
+      ? `${unhealthyChannelBridges.length} channel bridge(s) not delivering: ${unhealthyChannelBridges.slice(0, 3).map((a) => `${a.id} (status=${a.status}, ready=${a.ready})`).join("; ")}`
+      : undefined,
+  });
+
+  const expiredUndelivered = countExpiredUndeliveredMessages(now);
+  checks.push({
+    name: "expired-undelivered-messages",
+    status: expiredUndelivered > 0 ? "warn" : "ok",
+    count: expiredUndelivered,
+    detail: expiredUndelivered > 0
+      ? `${expiredUndelivered} queued message(s) expired undelivered at max_age in the last 24h (silent data loss)`
+      : undefined,
+  });
+
   const rootTokenRuntimeAgents = listAgents().filter((agent) => {
     if (agent.status === "offline") return false;
     if (agent.id === "user" || agent.id === "system") return false;

package/src/maintenance/jobs.ts

@@ -10,6 +10,7 @@ import {
   expireQueuedMessages,
   getAgent,
   listAgents,
+  listStaleQueuedDirectTargets,
   pruneOrphanedSharedWorkspaces,
   pruneOfflineAgents,
   pruneOldMessages,
@@ -22,6 +23,8 @@ import {
   runDbMaintenance,
   sweepArtifacts,
 } from "../db";
+import { isAgentUnavailable } from "../db/agent-predicates";
+import { flushQueuedDirectMessages } from "../services/managed-running";
 import { notifyAgentOffline } from "../agent-lifecycle-events";
 import { diagnoseAgentDeath } from "../agent-death-diagnosis";
 import { autoMergeCleanFastForwards } from "../workspace-auto-merge";
@@ -117,7 +120,6 @@ export function runStuckBusyWatchdog(input: { now?: number } = {}): Record<strin
     const messages = routeNotification({
       type: "agent.stuck_busy",
       scope: { agentId: agent.id, parent: agent.spawnedBy, teamId: agent.teamId },
-      recipients: ["user"],
       message: {
         subject: "Agent stuck busy",
         body: stuckBusyBody(agent.id, health),
@@ -193,10 +195,35 @@ export const definitions: MaintenanceJobDefinition[] = [
     runOnStart: true,
     handler() {
       const messages = expireQueuedMessages();
-      for (const message of messages) emitMessageExpired(message);
+      for (const message of messages) {
+        // Silent data loss is the worst failure mode here (#706): a queued
+        // message died without ever reaching its recipient. Surface it loudly.
+        console.warn(`[delivery] message ${message.id} to ${message.to} (kind=${message.kind}) expired undelivered after max_age — silent data loss`);
+        emitMessageExpired(message);
+      }
       return { expiredQueuedMessageIds: messages.map((message) => message.id) };
     },
   },
+  {
+    id: "queued-message-resweep",
+    title: "Queued message re-sweep",
+    description: "Re-resolve long-queued direct messages whose target agent is available again — safety net for a missed flush-on-recovery event (#706).",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: true,
+    handler() {
+      const reswept: Record<string, number> = {};
+      for (const target of listStaleQueuedDirectTargets()) {
+        const agent = getAgent(target);
+        // Only flush to a target that is actually available now; otherwise the
+        // message belongs in the queue (this is hooked to agent availability,
+        // not pool-slot reclaim).
+        if (!agent || isAgentUnavailable(agent)) continue;
+        const flushed = flushQueuedDirectMessages(target);
+        if (flushed.length > 0) reswept[target] = flushed.length;
+      }
+      return { resweptTargets: reswept };
+    },
+  },
   {
     id: "command-expiration",
     title: "Command expiration",

package/src/notification-router.ts

@@ -203,6 +203,10 @@ function routingReason(
 ): string {
   if (!settingsEnabled) return "notifications are disabled for this recipient by settings";
   if (matchedRule === "author") return "you are the author";
+  if (matchedRule === "targeted-at-user") return "you are directly targeted";
+  if (matchedRule === "spawned-by-user") return "you directly spawned this agent";
+  if (matchedRule === "spawn-parent-of") return "you are the subject agent's spawn parent";
+  if (matchedRule === "thread-participant") return "you are a participant in this thread";
   if (matchedRule === "spawn-parent") return "you are the spawn parent";
   if (matchedRule === "subject-agent") return "you are the notification subject";
   if (matchedRule === "same-team") return scope.teamId ? `same team ${scope.teamId}` : "same team";

package/src/notification-rules.ts

@@ -1,5 +1,6 @@
 import type { AgentCard } from "./types";
-import { listAgents } from "./db";
+import { canonicalHumanAgentId, isHumanAgentId } from "agent-relay-sdk";
+import { getAgent, getThread, listAgents } from "./db";
 import { isAgentOnline } from "./agent-ref";
 import { notificationEnabledFor } from "./notification-settings-store";
 import type { NotificationType, NotificationScope } from "./notification-types";
@@ -40,6 +41,31 @@ interface AudienceMember {
   matchedRule: string;
 }
 
+function sameAddress(a: string | undefined, b: string | undefined): boolean {
+  if (!a || !b) return false;
+  if (isHumanAgentId(a) || isHumanAgentId(b)) return canonicalHumanAgentId(a) === canonicalHumanAgentId(b);
+  return a === b;
+}
+
+function subjectParent(scope: NotificationScope): string | undefined {
+  if (scope.parent) return scope.parent;
+  return scope.agentId ? getAgent(scope.agentId)?.spawnedBy : undefined;
+}
+
+function threadParticipantIds(scope: NotificationScope): Set<string> {
+  const ids = new Set<string>();
+  for (const id of scope.participants ?? []) {
+    if (id.trim()) ids.add(id);
+  }
+  if (typeof scope.threadId === "number" && Number.isSafeInteger(scope.threadId) && scope.threadId > 0) {
+    for (const message of getThread(scope.threadId)) {
+      ids.add(message.from);
+      ids.add(message.to);
+    }
+  }
+  return ids;
+}
+
 /**
  * Predicate library — the reusable building blocks each type composes its default audience from.
  * Each factory returns a single-concern rule. `deliver` includes the agent; `abstain` leaves the
@@ -47,6 +73,38 @@ interface AudienceMember {
  * shape #443 builds on). Compose them ordered: later rules override earlier (see {@link evaluateAudience}).
  */
 export const audiencePredicates = {
+  /** A human directly targeted by the message/chat event. */
+  targetedAtUser: (): NotificationRule => ({
+    name: "targeted-at-user",
+    evaluate: (a, { scope }) => {
+      if (!isHumanAgentId(a.id)) return "abstain";
+      const target = scope.to ?? scope.target;
+      return sameAddress(a.id, target) ? "deliver" : "abstain";
+    },
+  }),
+  /** A human directly spawned the subject agent. Depth-1 only; grandchildren abstain. */
+  spawnedByUser: (): NotificationRule => ({
+    name: "spawned-by-user",
+    evaluate: (a, { scope }) => {
+      if (!isHumanAgentId(a.id)) return "abstain";
+      return sameAddress(a.id, subjectParent(scope)) ? "deliver" : "abstain";
+    },
+  }),
+  /** The subject agent's spawn-parent, deriving it from `scope.agentId` when needed. */
+  spawnParentOf: (): NotificationRule => ({
+    name: "spawn-parent-of",
+    evaluate: (a, { scope }) => (sameAddress(a.id, subjectParent(scope)) ? "deliver" : "abstain"),
+  }),
+  /** Any participant in the message/chat thread. */
+  threadParticipant: (): NotificationRule => ({
+    name: "thread-participant",
+    evaluate: (a, { scope }) => {
+      for (const participant of threadParticipantIds(scope)) {
+        if (sameAddress(a.id, participant)) return "deliver";
+      }
+      return "abstain";
+    },
+  }),
   /** The agent whose work the notification is about — delivered even when offline (store-ahead #234). */
   author: (): NotificationRule => ({
     name: "author",
@@ -96,14 +154,15 @@ export const audiencePredicates = {
 } as const;
 
 /**
- * The candidate pool for rule evaluation: every registered agent EXCEPT the pseudo-identities
- * (`system`/`user`) and channel agents, which are never wake-notification recipients. Offline agents
- * stay IN the pool deliberately — a store-ahead rule (author/spawn-parent) must be able to select an
- * offline target; per-rule `onlineOnly` gates the cases that need liveness (e.g. on-repo-root fan-out).
+ * The candidate pool for rule evaluation: every registered agent EXCEPT `system` and channel agents,
+ * which are never wake-notification recipients. Human sinks stay in the pool so human-surface rules
+ * can decide when `user` belongs in an audience. Offline agents stay IN deliberately — a store-ahead
+ * rule (author/spawn-parent) must be able to select an offline target; per-rule `onlineOnly` gates
+ * the cases that need liveness (e.g. on-repo-root fan-out).
  */
 export function audienceCandidates(): AgentCard[] {
   return listAgents().filter(
-    (a) => a.id !== "system" && a.id !== "user" && a.kind !== "channel" && a.meta?.kind !== "channel",
+    (a) => a.id !== "system" && a.kind !== "system" && a.kind !== "channel" && a.meta?.kind !== "channel",
   );
 }
 
@@ -190,3 +249,25 @@ export function __resetAudienceRules(): void {
   for (const [type, rules] of defaultAudienceRegistry) audienceRegistry.set(type, rules);
   subscriptionRules = [];
 }
+
+const SPAWN_LIFECYCLE_AUDIENCE_TYPES = [
+  "agent.ready",
+  "agent.exited",
+  "agent.spawn_failed",
+  "agent.spawn_recovered",
+] as const satisfies readonly NotificationType[];
+
+for (const type of SPAWN_LIFECYCLE_AUDIENCE_TYPES) {
+  registerDefaultAudienceRules(type, [audiencePredicates.spawnParentOf(), audiencePredicates.spawnedByUser()]);
+}
+
+registerDefaultAudienceRules("agent.stuck_busy", [
+  audiencePredicates.spawnParentOf(),
+  audiencePredicates.spawnedByUser(),
+]);
+
+registerDefaultAudienceRules("message.new", [
+  audiencePredicates.targetedAtUser(),
+  audiencePredicates.spawnedByUser(),
+  audiencePredicates.threadParticipant(),
+]);

package/src/notification-types.ts

@@ -1,4 +1,5 @@
 export type NotificationType =
+  | "message.new"
   | "landed-failure"
   | "branch.landed"
   | "agent.ready"
@@ -31,6 +32,16 @@ export type NotificationType =
  * All optional because each emitter fills the fields it has in scope at the call site.
  */
 export interface NotificationScope {
+  /** Message sender for message/chat audience evaluation. */
+  from?: string;
+  /** Message target for message/chat audience evaluation. */
+  to?: string;
+  /** Alias for `to` used by audience preview clients that describe the primary target. */
+  target?: string;
+  /** Message thread id for thread participant audience evaluation. */
+  threadId?: number;
+  /** Pre-resolved thread participants when the caller already has the thread membership. */
+  participants?: string[];
   /** The agent whose work the notification concerns (branch author, workspace owner). */
   author?: string;
   /** The agent the notification is primarily about (lifecycle subject, advisory target). */
@@ -56,6 +67,7 @@ const MINUTES = 60 * 1000;
  * obligation is `null` (never auto-expires). Only genuinely now-or-never pings get a short default.
  */
 export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
+  "message.new": null,
   "landed-failure": null,
   "branch.landed": null,
   "agent.ready": null,

package/src/services/managed-running.ts

@@ -17,7 +17,7 @@ import { getManagedAgentState, updateManagedAgentState } from "../config-store";
 import { emitRelayEvent } from "../events";
 import { emitMessageAvailable, emitMessageDeliveryUpdated, emitNewMessage } from "../sse";
 import type { AuthContext } from "./auth-context";
-import type { ManagedAgentState } from "../types";
+import type { ManagedAgentState, Message } from "../types";
 
 interface ManagedRunningInput {
   policyName?: string;
@@ -135,14 +135,16 @@ function recordManagedTransition(
  * transitions back to available: heartbeat stale→idle, re-registration after restart/compact, or
  * rate-limit resume. Emits the same `message.available` / `message.new` / `message.delivery_updated`
  * events that the policy flush emits so SSE subscribers and the dashboard react identically.
- * No-op when there are no queued direct messages.
+ * No-op when there are no queued direct messages. Returns the flushed messages so
+ * callers (e.g. the resweep safety net, #706) can report how many were recovered.
  */
-export function flushQueuedDirectMessages(agentId: string): void {
+export function flushQueuedDirectMessages(agentId: string): Message[] {
   const available = resolveQueuedDirectMessages(agentId);
-  if (!available.length) return;
+  if (!available.length) return [];
   emitMessageAvailable("direct", agentId, available);
   for (const message of available) {
     emitNewMessage(message);
     emitMessageDeliveryUpdated(message);
   }
+  return available;
 }