agent-relay-server 0.94.5 → 0.94.6

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.94.5",
+    "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.5",
+  "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.5",
+  "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/maintenance/jobs.ts

@@ -120,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),

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,