agent-relay-server 0.4.39 → 0.6.0

package/README.md

@@ -40,20 +40,20 @@ Agent Relay has two parts:
 
 Pick your provider: install the Claude Code plugin, the Codex connector, or both. The shared config is the same four env vars either way. See the [full mental model](docs/mental-model.md) for routing, identity, and task lifecycle details, or the [provider spec](docs/provider-spec.md) if you want to build your own integration.
 
-## Extension Model
+## Connector Model
 
-Agent Relay is built around four extension points:
+Agent Relay extensions run as external **Connectors**. The relay discovers them from `~/.agent-relay/connectors/<id>/manifest.json`, then can show status and run lifecycle actions without loading connector code in-process.
 
 > **Agents do work. Providers host agents. Integrations create work. Channels carry conversations.**
 
-That split keeps the system small without making everything a one-off plugin:
+Connector kinds:
 
-- **Agents** are running AI sessions or workers that can receive messages, claim tasks, and produce results.
-- **Providers** connect an AI runtime to the relay. The Claude plugin and Codex connector are providers.
-- **Integrations** connect external systems that create or update work. CI, monitoring, support desks, and deployment tools fit here.
-- **Channels** connect communication surfaces where humans and systems already talk. Telegram is the first channel; Slack, email, SMS, Matrix, Discord, and web chat are natural next ones.
+- **Provider connectors** host AI runtimes. The Claude plugin and Codex connector register coding-agent sessions as Relay agents.
+- **Event connectors** connect external systems that create or update work. CI, monitoring, support desks, and deployment tools fit here.
+- **Channel connectors** connect communication surfaces where humans and systems already talk. Telegram is the first channel; Slack, email, SMS, Matrix, Discord, and web chat are natural next ones.
+- **Orchestrator connectors** supervise hosts and can spawn or control provider sessions.
 
-If you want to contribute, pick the shape that matches your system. Building a new AI runtime adapter? Build a provider. Sending alerts or tickets into Agent Relay? Build an integration. Opening Agent Relay to another messaging app? Build a channel.
+If you want to contribute, pick the shape that matches your system. Building a new AI runtime adapter? Build a provider connector. Sending alerts or tickets into Agent Relay? Build an event connector. Opening Agent Relay to another messaging app? Build a channel connector.
 
 ## Quick Start
 

package/package.json

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

package/public/dashboard.js

@@ -54,11 +54,13 @@
 
       agents: [],
       agentsById: {},
+      orchestrators: [],
       pairs: [],
       messages: [],
       tasks: [],
       integrations: [],
       channels: [],
+      connectors: [],
       taskEvents: [],
       taskEventCache: {},
       stats: {},
@@ -85,6 +87,14 @@
       replyTo: null,
       composeOpen: false,
       agentSpawnOpen: false,
+      orchestratorSpawnOpen: false,
+      spawnOrchId: "",
+      spawnProvider: "claude",
+      spawnCwd: "",
+      spawnLabel: "",
+      spawnApproval: "guarded",
+      spawnPrompt: "",
+      spawnDirListing: null,
       agentDirectoryBrowser: { open: false, loading: false, path: "", parent: "", home: "", cwd: "", entries: [], error: "" },
       pairInviteOpen: false,
       pairMessageOpen: false,
@@ -231,6 +241,7 @@
         if (view === "work") await Promise.all([this.fetchMessages(), this.fetchTasks()]);
         if (view === "pairs") this.fetchPairs();
         if (view === "channels") await this.fetchChannels();
+        if (view === "connectors") await this.fetchConnectors();
         if (view === "integrations") await this.fetchIntegrations();
         if (view === "tasks") this.fetchTasks();
       },
@@ -281,6 +292,8 @@
     es.addEventListener("message.claimed", (event) => handleMessageClaimed(this, parseEventData(event)));
     es.addEventListener("message.claim_released", (event) => handleMessageClaimReleased(this, parseEventData(event)));
     es.addEventListener("message.deleted", (event) => handleMessageDeleted(this, parseEventData(event)));
+    es.addEventListener("orchestrator.status", (event) => handleOrchestratorStatus(this, parseEventData(event)));
+    es.addEventListener("orchestrator.removed", (event) => handleOrchestratorRemoved(this, parseEventData(event)));
     registerTaskEvents(this, es);
   }
 
@@ -320,6 +333,14 @@
     refreshChartsIfVisible(vm);
   }
 
+  function handleOrchestratorStatus(vm, orch) {
+    upsertById(vm.orchestrators, orch);
+  }
+
+  function handleOrchestratorRemoved(vm, data) {
+    vm.orchestrators = vm.orchestrators.filter((o) => o.id !== data.id);
+  }
+
   function handleMessageClaimed(vm, data) {
     const msg = vm.messages.find((item) => item.id === data.messageId);
     if (!msg) return;
@@ -374,7 +395,7 @@
       },
 
       async refresh() {
-        await Promise.all([this.fetchStats(), this.fetchHealth(), this.fetchAgents(), this.fetchPairs(), this.fetchMessages(), this.fetchTasks(), this.fetchChannels(), this.fetchIntegrations(), this.fetchInboxState(), this.fetchActivityEvents()]);
+        await Promise.all([this.fetchStats(), this.fetchHealth(), this.fetchAgents(), this.fetchOrchestrators(), this.fetchPairs(), this.fetchMessages(), this.fetchTasks(), this.fetchChannels(), this.fetchConnectors(), this.fetchIntegrations(), this.fetchInboxState(), this.fetchActivityEvents()]);
       },
 
       async refreshLiveData() {
@@ -407,6 +428,12 @@
         } catch {}
       },
 
+      async fetchOrchestrators() {
+        try {
+          this.orchestrators = await this.api("GET", "/orchestrators");
+        } catch {}
+      },
+
       async fetchPairs() {
         try {
           let pairs;
@@ -451,6 +478,12 @@
         } catch {}
       },
 
+      async fetchConnectors() {
+        try {
+          this.connectors = await this.api("GET", "/connectors");
+        } catch {}
+      },
+
       async fetchChannels() {
         try {
           this.channels = await this.api("GET", "/channels");
@@ -523,6 +556,7 @@
       activityItems: { get: getActivityItems },
       workQueueItems: { get: getWorkQueueItems },
       channelCards: { get: getChannelCards },
+      connectorCards: { get: getConnectorCards },
       integrationCards: { get: getIntegrationCards },
       openPairCount: { get: getOpenPairCount },
       filteredMessages: { get: getFilteredMessages },
@@ -535,9 +569,15 @@
       healthIssues: { get: getHealthIssues },
       healthDiagnostics: { get: getHealthDiagnostics },
       commandPaletteItems: { get: getCommandPaletteItems },
+      spawnAvailableProviders: { get: getSpawnAvailableProviders },
     };
   }
 
+  function getSpawnAvailableProviders() {
+    const orch = this.orchestrators.find((o) => o.id === this.spawnOrchId);
+    return orch ? orch.providers : ["claude", "codex"];
+  }
+
   function getOnlineCount() {
     return visibleAgents(this).filter((agent) => agent.status !== "offline").length;
   }
@@ -613,6 +653,11 @@
     if (!message || !channel) return false;
     const channelKeys = [channel.id, channel.type, ...(channel.topicChannels || [])].filter(Boolean);
     if (message.channel && channelKeys.includes(message.channel)) return true;
+    const payloadChannel = message.payload?.channel;
+    if (payloadChannel && typeof payloadChannel === "object") {
+      const payloadKeys = [payloadChannel.agentId, payloadChannel.provider, payloadChannel.accountId].filter(Boolean);
+      if (payloadKeys.includes(channel.id) || payloadKeys.includes(channel.type) || payloadKeys.includes(channel.accountId)) return true;
+    }
     if (channel.agentId && (message.from === channel.agentId || message.to === channel.agentId)) return true;
     return false;
   }
@@ -679,7 +724,7 @@
     const haystack = [
       vm.displayTarget(thread.peer),
       thread.peer,
-      ...thread.messages.flatMap((msg) => [msg.subject || "", msg.body || "", msg.channel || "", vm.displayTarget(msg.from), vm.displayTarget(msg.to)]),
+      ...thread.messages.flatMap((msg) => [msg.subject || "", messageBody.call(vm, msg) || "", msg.channel || "", vm.displayTarget(msg.from), vm.displayTarget(msg.to)]),
     ].join("\n").toLowerCase();
     return haystack.includes(search);
   }
@@ -768,12 +813,12 @@
       }));
 
     const messageItems = (this.messages || [])
-      .filter((msg) => msg.claimable)
+      .filter(isClaimableMessageWaiting)
       .map((msg) => ({
         id: "message-" + msg.id,
         sourceType: "message",
         title: msg.subject || "Claimable message #" + msg.id,
-        body: msg.body,
+        body: messageBody(msg),
         severity: "warning",
         status: msg.claimedBy ? "claimed" : "open",
         owner: msg.claimedBy || "",
@@ -821,7 +866,7 @@
     return (vm.messages || []).flatMap((msg) => {
       const ts = toTimestamp(msg.createdAt);
       const items = [];
-      const pairEvent = msg.meta?.pairEvent;
+      const pairEvent = msg.payload?.pairEvent;
       if (pairEvent) {
         items.push(activityItem({
           id: "pair-message-" + msg.id,
@@ -837,10 +882,10 @@
       } else if (msg.from === HUMAN_AGENT_ID) {
         items.push(activityItem({
           id: "human-send-" + msg.id,
-          kind: msg.claimable ? "task" : "message",
+          kind: msg.kind === "task" ? "task" : "message",
           ts,
-          icon: msg.claimable ? "ti-hand-grab" : "ti-send",
-          title: msg.claimable ? "Claimable task sent" : "Message sent",
+          icon: msg.kind === "task" ? "ti-hand-grab" : "ti-send",
+          title: msg.kind === "task" ? "Claimable task sent" : "Message sent",
           body: vm.messagePreview(msg),
           meta: "to " + vm.displayTarget(msg.to),
           view: inboxPeer(msg) ? "inbox" : "messages",
@@ -1018,7 +1063,7 @@
   }
 
   function messageLooksLikeQuestion(msg) {
-    return /\?/.test(`${msg.subject || ""}\n${msg.body || ""}`);
+    return /\?/.test(`${msg.subject || ""}\n${messageBody(msg)}`);
   }
 
   function countClaimableWaiting(vm) {
@@ -1038,7 +1083,7 @@
   }
 
   function isClaimableMessageWaiting(msg) {
-    return Boolean(msg.claimable && !msg.claimedBy);
+    return Boolean(msg.claimable && !msg.claimedBy && !(msg.kind === "task" && Number.isSafeInteger(msg.payload?.taskId)));
   }
 
   function targetMatchesAgent(target, agent) {
@@ -1110,6 +1155,17 @@
     });
   }
 
+  function getConnectorCards() {
+    return [...(this.connectors || [])].sort((a, b) => {
+      const statusRank = { error: 0, warn: 1, unknown: 2, ok: 3 };
+      const aStatus = a.runtime?.status || "unknown";
+      const bStatus = b.runtime?.status || "unknown";
+      const statusDiff = (statusRank[aStatus] ?? 2) - (statusRank[bStatus] ?? 2);
+      if (statusDiff !== 0) return statusDiff;
+      return String(a.displayName || a.id || "").localeCompare(String(b.displayName || b.id || ""));
+    });
+  }
+
   function getOpenPairCount() {
     return (this.pairs || []).filter(isOpenPair).length;
   }
@@ -1173,7 +1229,7 @@
   }
 
   function isChannelAgent(agent) {
-    return agent?.meta?.kind === "channel" || agent?.tags?.includes("channel");
+    return agent?.kind === "channel" || agent?.meta?.kind === "channel" || agent?.tags?.includes("channel");
   }
 
   function agentSupportsControlActions(agent) {
@@ -1312,6 +1368,7 @@
       displayName,
       displayTarget,
       conversationTitle,
+      messageBody,
       messagePreview,
       agentPair,
       pairPeerId,
@@ -1332,6 +1389,7 @@
       isBuiltInAgent,
       agentChannels,
       channelPresence,
+      connectorPresence,
       integrationPresence,
       composeTargetAllowsClaimable,
       inboxComposeTargetAllowsClaimable,
@@ -1365,10 +1423,43 @@
   }
 
   function messagePreview(msg) {
-    const text = msg?.subject || msg?.body || "";
+    const text = msg?.subject || messageBody(msg) || "";
     return text.length > 90 ? text.slice(0, 90) + "..." : text;
   }
 
+  function messageBody(msg) {
+    if (!msg) return "";
+    const payload = msg.payload || {};
+    const channelMessage = payload.message;
+    if (channelMessage && typeof channelMessage === "object" && typeof channelMessage.text === "string" && channelMessage.text.trim()) {
+      return channelMessage.text;
+    }
+    const interaction = payload.interaction;
+    if (interaction && typeof interaction === "object") {
+      const title = typeof interaction.title === "string" ? interaction.title.trim() : "";
+      const description = typeof interaction.description === "string" ? interaction.description.trim() : "";
+      if (title && description) return title + "\n" + description;
+      if (title) return title;
+      if (description) return description;
+    }
+    const reaction = payload.reaction;
+    if (reaction && typeof reaction === "object") {
+      const name = typeof reaction.name === "string" ? reaction.name : "";
+      const emoji = typeof reaction.emoji === "string" ? reaction.emoji : "";
+      const value = typeof reaction.value === "string" ? reaction.value : "";
+      return ["Reaction", emoji || name || value].filter(Boolean).join(": ");
+    }
+    const activity = payload.activity;
+    if (activity && typeof activity === "object") {
+      const kind = typeof activity.kind === "string" ? activity.kind : "activity";
+      const state = typeof activity.state === "string" ? activity.state : "";
+      return [kind, state].filter(Boolean).join(" ");
+    }
+    if (typeof payload.text === "string" && payload.text.trim()) return payload.text;
+    if (typeof payload.message === "string" && payload.message.trim()) return payload.message;
+    return msg.body || "";
+  }
+
   function agentPair(agent) {
     return agent ? this.pairsByAgentId[agent.id] : null;
   }
@@ -1552,6 +1643,16 @@
     return { label: "configured", tone: "primary", icon: "ti-plug-connected" };
   }
 
+  function connectorPresence(connector) {
+    const runtime = connector?.runtime || {};
+    if (runtime.status === "error") return { label: "error", tone: "danger", icon: "ti-alert-triangle" };
+    if (runtime.status === "warn") return { label: "warning", tone: "warning", icon: "ti-alert-circle" };
+    if (runtime.running) return { label: "running", tone: "success", icon: "ti-circle-check" };
+    if (runtime.enabled === false) return { label: "disabled", tone: "secondary", icon: "ti-player-pause" };
+    if (runtime.status === "ok") return { label: "ok", tone: "success", icon: "ti-circle-check" };
+    return { label: "unknown", tone: "secondary", icon: "ti-help-circle" };
+  }
+
   function agentChannels(agent) {
     if (!agent) return [];
     return (this.channels || []).filter((ch) => ch.agentId === agent.id);
@@ -1644,6 +1745,7 @@
       recordOperatorActivity,
       openActivityItem,
       runHealthAction,
+      runConnectorAction,
       openCommandPalette,
       closeCommandPalette,
       runCommand,
@@ -1667,6 +1769,12 @@
       openAgentDirectoryBrowser,
       browseAgentDirectory,
       selectAgentDirectory,
+      openOrchestratorSpawn,
+      openOrchestratorSpawnFor,
+      browseOrchestratorDirs,
+      submitOrchestratorSpawn,
+      orchestratorAction,
+      deleteOrchestrator,
       doSendPairMessage,
       doAcceptPair,
       doRejectPair,
@@ -1903,7 +2011,11 @@
       };
       if (this.inboxCompose.channel) payload.channel = this.inboxCompose.channel;
       if (this.inboxCompose.subject) payload.subject = this.inboxCompose.subject;
-      if (this.inboxCompose.claimable && inboxComposeTargetAllowsClaimable.call(this)) payload.claimable = true;
+      if (this.inboxCompose.claimable && inboxComposeTargetAllowsClaimable.call(this)) {
+        payload.claimable = true;
+        payload.kind = "task";
+        payload.payload = { title: this.inboxCompose.subject || "Claimable task" };
+      }
       await this.api("POST", "/messages", payload);
       this.recordOperatorActivity({
         title: payload.claimable ? "Claimable task sent" : "Message sent",
@@ -1946,7 +2058,11 @@
     if (vm.compose.channel) payload.channel = vm.compose.channel;
     if (vm.compose.subject) payload.subject = vm.compose.subject;
     if (vm.replyTo) payload.replyTo = vm.replyTo.id;
-    if (vm.compose.claimable && composeTargetAllowsClaimable.call(vm)) payload.claimable = true;
+    if (vm.compose.claimable && composeTargetAllowsClaimable.call(vm)) {
+      payload.claimable = true;
+      payload.kind = "task";
+      payload.payload = { title: vm.compose.subject || "Claimable task" };
+    }
     return payload;
   }
 
@@ -2163,6 +2279,16 @@
     if (action.copy) await copyText(action.copy);
   }
 
+  async function runConnectorAction(connector, action) {
+    if (!connector || !action) return;
+    try {
+      await this.api("POST", "/connectors/" + encodeURIComponent(connector.id) + "/actions", { action });
+      await this.fetchConnectors();
+    } catch (e) {
+      alert("Connector action failed: " + e.message);
+    }
+  }
+
   async function copyText(value) {
     if (typeof navigator === "undefined") return;
     try {
@@ -2252,8 +2378,8 @@
 
   function pairMessages(vm, pair) {
     return (vm.messages || []).filter((msg) =>
-      msg.meta?.pairId === pair.id ||
-      (msg.meta?.pairEvent && [pair.requesterId, pair.targetId].includes(msg.from) && [pair.requesterId, pair.targetId].includes(msg.to))
+      msg.payload?.pairId === pair.id ||
+      (msg.payload?.pairEvent && [pair.requesterId, pair.targetId].includes(msg.from) && [pair.requesterId, pair.targetId].includes(msg.to))
     );
   }
 
@@ -2306,7 +2432,7 @@
       if (msg.channel) lines.push("- Channel: " + msg.channel);
       if (msg.subject) lines.push("- Subject: " + msg.subject);
       if (msg.claimedBy) lines.push("- Claimed by: " + vm.displayTarget(msg.claimedBy));
-      lines.push("", msg.body || "", "");
+      lines.push("", messageBody.call(vm, msg) || "", "");
     }
   }
 
@@ -2478,6 +2604,96 @@
     }
   }
 
+  // --- Orchestrator methods ---
+
+  function openOrchestratorSpawn() {
+    const online = this.orchestrators.filter((o) => o.status === "online");
+    if (online.length === 0) return alert("No orchestrators online");
+    this.spawnOrchId = online[0].id;
+    this.spawnProvider = "claude";
+    this.spawnCwd = "";
+    this.spawnLabel = "";
+    this.spawnApproval = "guarded";
+    this.spawnPrompt = "";
+    this.spawnDirListing = null;
+    this.orchestratorSpawnOpen = true;
+  }
+
+  function openOrchestratorSpawnFor(orchId) {
+    this.spawnOrchId = orchId;
+    this.spawnProvider = "claude";
+    this.spawnCwd = "";
+    this.spawnLabel = "";
+    this.spawnApproval = "guarded";
+    this.spawnPrompt = "";
+    this.spawnDirListing = null;
+    this.orchestratorSpawnOpen = true;
+  }
+
+  async function browseOrchestratorDirs() {
+    try {
+      const query = this.spawnCwd ? "?path=" + encodeURIComponent(this.spawnCwd) : "";
+      this.spawnDirListing = await this.api("GET", "/agents/spawn/directories" + query);
+    } catch (e) {
+      alert("Directory browse failed: " + e.message);
+    }
+  }
+
+  async function submitOrchestratorSpawn() {
+    if (!this.spawnOrchId) return alert("Select an orchestrator");
+    try {
+      const payload = {
+        provider: this.spawnProvider,
+        approvalMode: this.spawnApproval,
+      };
+      if (this.spawnCwd) payload.cwd = this.spawnCwd;
+      if (this.spawnLabel) payload.label = this.spawnLabel;
+      if (this.spawnPrompt) payload.prompt = this.spawnPrompt;
+      await this.api("POST", "/orchestrators/" + encodeURIComponent(this.spawnOrchId) + "/spawn", payload);
+      this.orchestratorSpawnOpen = false;
+      this.recordOperatorActivity({
+        title: `${this.spawnProvider} agent spawn requested`,
+        body: this.spawnCwd || "",
+        meta: this.spawnOrchId,
+        icon: "ti-plus",
+        kind: "state",
+        view: "orchestrators",
+      });
+      await Promise.all([this.fetchOrchestrators(), this.fetchActivityEvents()]);
+    } catch (e) {
+      alert("Spawn failed: " + e.message);
+    }
+  }
+
+  async function orchestratorAction(orchId, action, agentId) {
+    const label = action === "restart" ? "Restart" : "Shutdown";
+    if (!confirm(`${label} agent "${agentId || "all"}" on orchestrator "${orchId}"?`)) return;
+    try {
+      await this.api("POST", "/orchestrators/" + encodeURIComponent(orchId) + "/actions", { action, agentId });
+      this.recordOperatorActivity({
+        title: `Agent ${action} requested`,
+        body: agentId || "all agents",
+        meta: orchId,
+        icon: action === "restart" ? "ti-refresh" : "ti-power",
+        kind: "state",
+        view: "orchestrators",
+      });
+      await Promise.all([this.fetchOrchestrators(), this.fetchActivityEvents()]);
+    } catch (e) {
+      alert(`${label} failed: ` + e.message);
+    }
+  }
+
+  async function deleteOrchestrator(orchId) {
+    if (!confirm(`Remove orchestrator "${orchId}"? This will NOT stop its managed agents.`)) return;
+    try {
+      await this.api("DELETE", "/orchestrators/" + encodeURIComponent(orchId));
+      await this.fetchOrchestrators();
+    } catch (e) {
+      alert("Delete failed: " + e.message);
+    }
+  }
+
   function closePairMessage() {
     this.pairMessageOpen = false;
     this.pairMessage = { ...DEFAULT_PAIR_MESSAGE };

package/public/icons/agent-relay.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <rect width="512" height="512" rx="96" fill="#0d1117"/>
+  <g stroke="#30363d" stroke-width="22" stroke-linecap="round">
+    <line x1="137" y1="151" x2="221" y2="229"/>
+    <line x1="375" y1="151" x2="291" y2="229"/>
+    <line x1="137" y1="361" x2="221" y2="283"/>
+    <line x1="375" y1="361" x2="291" y2="283"/>
+  </g>
+  <circle cx="256" cy="256" r="72" fill="#58a6ff"/>
+  <circle cx="96" cy="116" r="42" fill="#3fb950"/>
+  <circle cx="416" cy="116" r="42" fill="#3fb950"/>
+  <circle cx="96" cy="396" r="42" fill="#3fb950"/>
+  <circle cx="416" cy="396" r="42" fill="#3fb950"/>
+</svg>