agent-relay-server 0.6.0 → 0.6.1

package/package.json

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

package/public/dashboard.js

@@ -1147,6 +1147,11 @@
 
   function getChannelCards() {
     return [...(this.channels || [])].sort((a, b) => {
+      const healthRank = { error: 0, warning: 1, ok: 2 };
+      const aHealth = a.targetHealth?.status || "ok";
+      const bHealth = b.targetHealth?.status || "ok";
+      const healthDiff = (healthRank[aHealth] ?? 2) - (healthRank[bHealth] ?? 2);
+      if (healthDiff !== 0) return healthDiff;
       const readyDiff = Number(Boolean(b.ready)) - Number(Boolean(a.ready));
       if (readyDiff !== 0) return readyDiff;
       const statusDiff = String(a.status || "").localeCompare(String(b.status || ""));
@@ -1290,6 +1295,11 @@
           { label: "Run reaper", icon: "ti-broom", api: "POST", path: "/system/reap" },
           { label: "Show stale", icon: "ti-filter", view: "agents", preset: "offline_stale" }
         );
+      } else if (check.name === "channel-delivery-targets") {
+        base.actions.unshift(
+          { label: "Open channels", icon: "ti-messages", view: "channels" },
+          { label: "Run reaper", icon: "ti-broom", api: "POST", path: "/system/reap" }
+        );
       } else if (check.name === "expired-message-claims" || check.name === "expired-task-claims" || check.name === "offline-claimed-tasks") {
         base.actions.unshift(
           { label: "Run reaper", icon: "ti-broom", api: "POST", path: "/system/reap" },
@@ -1306,6 +1316,7 @@
     if (check.name === "expired-message-claims") return "Claimable messages may be stuck until the reaper releases expired claims.";
     if (check.name === "expired-task-claims") return "Tasks can appear owned by agents that no longer hold a live lease.";
     if (check.name === "offline-claimed-tasks") return "Offline agents are still shown as owners for active work.";
+    if (check.name === "channel-delivery-targets") return "Inbound channel messages may be accepted but routed to no live delivery agent.";
     return "Relay health is degraded for this check.";
   }
 
@@ -1660,6 +1671,8 @@
 
   function channelPresence(channel) {
     if (!channel) return { label: "unknown", tone: "secondary", icon: "ti-plug-off" };
+    if (channel.targetHealth?.status === "error") return { label: "target broken", tone: "danger", icon: "ti-alert-triangle" };
+    if (channel.targetHealth?.status === "warning") return { label: "target warning", tone: "warning", icon: "ti-alert-circle" };
     if (channel.status === "offline") return { label: "offline", tone: "secondary", icon: "ti-plug-off" };
     if (!channel.ready) return { label: "not ready", tone: "warning", icon: "ti-loader" };
     if (channel.status === "busy") return { label: "busy", tone: "warning", icon: "ti-activity" };

package/public/index.html

@@ -339,8 +339,8 @@
               <div class="card-body">
                 <div class="d-flex align-items-center">
                   <div>
-                    <div class="text-secondary small">Total Agents</div>
-                    <div class="h1 mb-0" x-text="stats.agents ?? 0"></div>
+                    <div class="text-secondary small">Agents</div>
+                    <div class="h1 mb-0" x-text="onlineCount"></div>
                   </div>
                   <i class="ti ti-robot ms-auto stat-card"></i>
                 </div>
@@ -352,10 +352,10 @@
               <div class="card-body">
                 <div class="d-flex align-items-center">
                   <div>
-                    <div class="text-secondary small">Active</div>
-                    <div class="h1 mb-0 text-success" x-text="onlineCount"></div>
+                    <div class="text-secondary small">Busy</div>
+                    <div class="h1 mb-0 text-warning" x-text="busyAgentCount"></div>
                   </div>
-                  <i class="ti ti-circle-check ms-auto stat-card"></i>
+                  <i class="ti ti-activity ms-auto stat-card"></i>
                 </div>
               </div>
             </div>
@@ -859,6 +859,8 @@ agent-relay-orchestrator</pre>
         <div class="d-flex align-items-center mb-3 gap-2 flex-wrap">
           <h2 class="page-title mb-0">Channels</h2>
           <span class="badge bg-success-lt" x-show="channelCards.filter((item) => item.ready).length > 0" x-text="channelCards.filter((item) => item.ready).length + ' ready'"></span>
+          <span class="badge bg-danger-lt" x-show="channelCards.filter((item) => item.targetHealth?.status === 'error').length > 0" x-text="channelCards.filter((item) => item.targetHealth?.status === 'error').length + ' target issue' + (channelCards.filter((item) => item.targetHealth?.status === 'error').length === 1 ? '' : 's')"></span>
+          <span class="badge bg-warning-lt" x-show="channelCards.filter((item) => item.targetHealth?.status === 'warning').length > 0" x-text="channelCards.filter((item) => item.targetHealth?.status === 'warning').length + ' target warning' + (channelCards.filter((item) => item.targetHealth?.status === 'warning').length === 1 ? '' : 's')"></span>
           <div class="ms-auto d-flex gap-2 align-items-center">
             <button class="btn btn-sm btn-ghost-secondary" @click="fetchChannels()">
               <i class="ti ti-refresh"></i>
@@ -887,6 +889,12 @@ agent-relay-orchestrator</pre>
                         <span class="badge bg-cyan-lt" x-text="channel.direction"></span>
                         <span class="badge bg-secondary-lt" x-text="displayTarget(channel.target || channel.agentId)"></span>
                       </div>
+                      <div class="alert py-2 px-2 mt-2 mb-0"
+                           :class="channel.targetHealth?.status === 'error' ? 'alert-danger' : 'alert-warning'"
+                           x-show="channel.targetHealth && channel.targetHealth.status !== 'ok'">
+                        <i class="ti me-1" :class="channel.targetHealth?.status === 'error' ? 'ti-alert-triangle' : 'ti-alert-circle'"></i>
+                        <span x-text="channel.targetHealth?.detail"></span>
+                      </div>
                       <div class="d-flex gap-1 mt-2 flex-wrap" x-show="channel.capabilities?.length">
                         <template x-for="capability in (channel.capabilities || [])" :key="capability">
                           <span class="badge bg-secondary-lt" x-text="capability"></span>

package/src/db.ts

@@ -11,6 +11,7 @@ import type {
   ChannelBindingMode,
   ChannelRouteTarget,
   ChannelSummary,
+  ChannelTargetHealth,
   CreatePairInput,
   HealthCheck,
   HealthReport,
@@ -628,6 +629,94 @@ function bindingTargetToLegacyTarget(target: ChannelRouteTarget): string {
   return "";
 }
 
+function channelTargetMatches(target: ChannelRouteTarget): AgentCard[] {
+  const candidates = listAgents().filter((agent) => (
+    agent.id !== "user" &&
+    agent.id !== "system" &&
+    agent.kind !== "channel" &&
+    agent.meta?.kind !== "channel"
+  ));
+  if (target.type === "agent" || target.type === "orchestrator") {
+    const agent = getAgent(target.id);
+    return agent ? [agent] : [];
+  }
+  if (target.type === "label") return candidates.filter((agent) => agent.label === target.id);
+  if (target.type === "tag") return candidates.filter((agent) => agent.tags.includes(target.id));
+  if (target.type === "capability") return candidates.filter((agent) => agent.capabilities.includes(target.id));
+  if (target.type === "broadcast") return candidates;
+  return [];
+}
+
+function channelTargetMatchSnapshot(agent: AgentCard): ChannelTargetHealth["matches"][number] {
+  return {
+    id: agent.id,
+    name: agent.name,
+    status: agent.status,
+    ready: agent.ready,
+    lastSeen: agent.lastSeen,
+    label: agent.label,
+    tags: agent.tags,
+    capabilities: agent.capabilities,
+  };
+}
+
+function isHealthyChannelTarget(agent: AgentCard, now: number): boolean {
+  return isDeliveryAgent(agent) && agent.ready && agent.lastSeen > now - STALE_TTL_MS;
+}
+
+function describeTarget(target: ChannelRouteTarget): string {
+  return bindingTargetToLegacyTarget(target);
+}
+
+function channelTargetHealth(binding: ChannelBinding, now: number = Date.now()): ChannelTargetHealth {
+  const target = binding.target;
+  const targetLabel = describeTarget(target);
+  const matches = channelTargetMatches(target);
+  const snapshots = matches.map(channelTargetMatchSnapshot);
+
+  if (target.type === "agent" || target.type === "orchestrator") {
+    const agent = matches[0];
+    if (!agent) {
+      return { status: "error", detail: `Target ${targetLabel} is not registered`, target, matches: [] };
+    }
+    if (agent.id !== "user" && agent.id !== "system" && (agent.kind === "channel" || agent.meta?.kind === "channel")) {
+      return { status: "error", detail: `Target ${targetLabel} is a channel, not a delivery agent`, target, matches: snapshots };
+    }
+    if (agent.status === "offline") {
+      return { status: "error", detail: `Target ${targetLabel} is offline`, target, matches: snapshots };
+    }
+    if (!agent.ready) {
+      return { status: "warning", detail: `Target ${targetLabel} is online but not ready`, target, matches: snapshots };
+    }
+    if (agent.id !== "user" && agent.id !== "system" && agent.lastSeen <= now - STALE_TTL_MS) {
+      return { status: "warning", detail: `Target ${targetLabel} heartbeat is stale`, target, matches: snapshots };
+    }
+    return { status: "ok", detail: `Target ${targetLabel} is online and ready`, target, matches: snapshots };
+  }
+
+  const healthyMatches = matches.filter((agent) => isHealthyChannelTarget(agent, now));
+  if (matches.length === 0) {
+    return { status: "error", detail: `Target ${targetLabel} has no matching agents`, target, matches: [] };
+  }
+  if (healthyMatches.length === 0) {
+    return { status: "error", detail: `Target ${targetLabel} has no online ready agents`, target, matches: snapshots };
+  }
+  if (binding.mode === "exclusive" && healthyMatches.length > 1) {
+    return {
+      status: "warning",
+      detail: `Target ${targetLabel} matches ${healthyMatches.length} online ready agents for an exclusive binding`,
+      target,
+      matches: snapshots,
+    };
+  }
+  return {
+    status: "ok",
+    detail: `Target ${targetLabel} has ${healthyMatches.length} online ready agent${healthyMatches.length === 1 ? "" : "s"}`,
+    target,
+    matches: snapshots,
+  };
+}
+
 function rowToChannelSummary(row: any): ChannelSummary {
   const binding = row.binding_id ? rowToChannelBinding({
     id: row.binding_id,
@@ -653,6 +742,7 @@ function rowToChannelSummary(row: any): ChannelSummary {
     direction: row.direction,
     target: binding ? bindingTargetToLegacyTarget(binding.target) : undefined,
     binding,
+    targetHealth: binding ? channelTargetHealth(binding) : undefined,
     topicChannels: parseStringArray(row.topic_channels),
     capabilities: parseStringArray(row.channel_capabilities),
     tags: parseStringArray(row.agent_tags),
@@ -965,25 +1055,31 @@ export function upsertChannelBinding(input: {
   const targetId = input.target.type === "broadcast" ? "" : input.target.id;
   const targetKey = input.target.type === "broadcast" ? "broadcast" : `${input.target.type}:${targetId}`;
   const id = `${input.channelId}:${conversationKey || "default"}:${targetKey}`;
+  const mode = input.mode ?? "exclusive";
   const now = Date.now();
-  db.prepare(`
-    INSERT INTO channel_bindings (id, channel_id, conversation_key, conversation_id, target_type, target_id, mode, priority, created_at, updated_at)
-    VALUES ($id, $channelId, $conversationKey, $conversationId, $targetType, $targetId, $mode, $priority, $now, $now)
-    ON CONFLICT(channel_id, conversation_key, target_type, target_id) DO UPDATE SET
-      mode = $mode,
-      priority = $priority,
-      updated_at = $now
-  `).run({
-    $id: id,
-    $channelId: input.channelId,
-    $conversationKey: conversationKey,
-    $conversationId: input.conversationId ?? null,
-    $targetType: input.target.type,
-    $targetId: targetId,
-    $mode: input.mode ?? "exclusive",
-    $priority: input.priority ?? 0,
-    $now: now,
-  });
+  db.transaction(() => {
+    if (mode === "exclusive") {
+      db.prepare("DELETE FROM channel_bindings WHERE channel_id = ? AND conversation_key = ?").run(input.channelId, conversationKey);
+    }
+    db.prepare(`
+      INSERT INTO channel_bindings (id, channel_id, conversation_key, conversation_id, target_type, target_id, mode, priority, created_at, updated_at)
+      VALUES ($id, $channelId, $conversationKey, $conversationId, $targetType, $targetId, $mode, $priority, $now, $now)
+      ON CONFLICT(channel_id, conversation_key, target_type, target_id) DO UPDATE SET
+        mode = $mode,
+        priority = $priority,
+        updated_at = $now
+    `).run({
+      $id: id,
+      $channelId: input.channelId,
+      $conversationKey: conversationKey,
+      $conversationId: input.conversationId ?? null,
+      $targetType: input.target.type,
+      $targetId: targetId,
+      $mode: mode,
+      $priority: input.priority ?? 0,
+      $now: now,
+    });
+  })();
 
   const row = db.prepare("SELECT * FROM channel_bindings WHERE id = ?").get(id) as any;
   return rowToChannelBinding(row);
@@ -1733,6 +1829,21 @@ function isChannelAgentId(agentId: string): boolean {
   ));
 }
 
+function legacyChannelTargets(agent: AgentCard | null | undefined): string[] {
+  if (!agent || !isChannelAgentId(agent.id)) return [];
+  const aliases = new Set<string>();
+  const provider = channelProviderForAgent(agent);
+  if (provider && provider !== "custom") aliases.add(provider);
+  const channelType = stringValue(agent.meta?.channelType);
+  if (channelType) aliases.add(channelType);
+  const transport = stringValue(agent.meta?.transport);
+  if (transport) aliases.add(transport);
+  const providerTag = agent.tags.find((tag) => tag.startsWith("channel:"))?.slice("channel:".length);
+  if (providerTag) aliases.add(providerTag);
+  aliases.delete(agent.id);
+  return [...aliases];
+}
+
 function matchingDeliveryAgents(target: string): AgentCard[] {
   if (!target) return [];
   const candidates = listAgents().filter(isDeliveryAgent);
@@ -1963,11 +2074,15 @@ export function pollMessages(query: PollQuery): Message[] {
   const agentTags = agent?.tags ?? [];
   const agentCaps = agent?.capabilities ?? [];
   const agentLabel = agent?.label;
+  const agentLegacyChannelTargets = legacyChannelTargets(agent);
 
   const conditions: string[] = [];
   const params: any[] = [];
 
-  // Build target matching: direct + broadcast + tag + capability + label
+  // Build target matching: direct + broadcast + tag + capability + label.
+  // Channel agents also accept legacy bare provider targets (for example
+  // "telegram") so older clients keep working after canonical IDs became
+  // provider:account ("telegram:default").
   const targetClauses = ["to_target = ?", "to_target = 'broadcast'"];
   params.push(query.for);
 
@@ -1983,6 +2098,10 @@ export function pollMessages(query: PollQuery): Message[] {
     targetClauses.push("to_target = ?");
     params.push(`label:${agentLabel}`);
   }
+  for (const target of agentLegacyChannelTargets) {
+    targetClauses.push("to_target = ?");
+    params.push(target);
+  }
   conditions.push(`(${targetClauses.join(" OR ")})`);
 
   // Hide active claims held by someone else, but let expired claims surface so
@@ -2267,6 +2386,21 @@ export function getHealth(now: number = Date.now()): HealthReport {
     detail: offlineClaimedTasks > 0 ? `${offlineClaimedTasks} active task(s) are claimed by offline agents` : undefined,
   });
 
+  const unhealthyChannelTargets = listChannels().filter((channel) => channel.targetHealth && channel.targetHealth.status !== "ok");
+  const channelTargetErrors = unhealthyChannelTargets.filter((channel) => channel.targetHealth?.status === "error");
+  const channelTargetDetail = unhealthyChannelTargets
+    .slice(0, 3)
+    .map((channel) => `${channel.name}: ${channel.targetHealth?.detail}`)
+    .join("; ");
+  checks.push({
+    name: "channel-delivery-targets",
+    status: channelTargetErrors.length > 0 ? "error" : unhealthyChannelTargets.length > 0 ? "warn" : "ok",
+    count: unhealthyChannelTargets.length,
+    detail: unhealthyChannelTargets.length > 0
+      ? `${unhealthyChannelTargets.length} channel delivery target issue(s): ${channelTargetDetail}${unhealthyChannelTargets.length > 3 ? "; ..." : ""}`
+      : undefined,
+  });
+
   const status = checks.some((check) => check.status === "error")
     ? "error"
     : checks.some((check) => check.status === "warn")

package/src/types.ts

@@ -290,6 +290,22 @@ export interface ChannelBinding {
   updatedAt: number;
 }
 
+export interface ChannelTargetHealth {
+  status: "ok" | "warning" | "error";
+  detail: string;
+  target: ChannelRouteTarget;
+  matches: Array<{
+    id: string;
+    name: string;
+    status: AgentCard["status"];
+    ready: boolean;
+    lastSeen: number;
+    label?: string;
+    tags: string[];
+    capabilities: string[];
+  }>;
+}
+
 export interface ChannelSummary {
   id: string;
   name: string;
@@ -302,6 +318,7 @@ export interface ChannelSummary {
   direction: ChannelDirection;
   target?: string;
   binding?: ChannelBinding;
+  targetHealth?: ChannelTargetHealth;
   topicChannels: string[];
   capabilities: string[];
   tags: string[];