agent-relay-server 0.105.2 → 0.106.0

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.105.2",
+    "version": "0.106.0",
     "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.105.2",
+  "version": "0.106.0",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -36,6 +36,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
+    "agent-relay-channels-host": "0.106.0",
     "agent-relay-providers": "0.104.0",
     "agent-relay-sdk": "0.2.92",
     "ajv": "^8.20.0"

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.105.2",
+  "version": "0.106.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/runner/plugins/claude/monitors/relay-monitor.provisioned.mjs

@@ -1035,6 +1035,17 @@ var NOTIFICATION_NUDGE = "\u21AA Notification \u2014 no reply needed.";
 function isNotificationMessage(message) {
   return isPersistedRelayMessage(message) && message.replyExpected === false;
 }
+function dedupePersistedMessages(messages2) {
+  const seen = new Set;
+  return messages2.filter((message) => {
+    if (!isPersistedRelayMessage(message))
+      return true;
+    if (seen.has(message.id))
+      return false;
+    seen.add(message.id);
+    return true;
+  });
+}
 function providerAttachmentText(message) {
   const refs = attachmentRefs(message);
   if (!refs.length)
@@ -1165,11 +1176,12 @@ function replyReminder(message, readOnly) {
 }
 function claudeProviderMessageText(messages2, options) {
   const relaySurface = options.relaySurface !== false;
-  const sections = messages2.map((message) => formatMessage(message, relaySurface));
-  const replyable = latestReplyableMessage(messages2);
+  const uniqueMessages = dedupePersistedMessages(messages2);
+  const sections = uniqueMessages.map((message) => formatMessage(message, relaySurface));
+  const replyable = latestReplyableMessage(uniqueMessages);
   if (relaySurface && replyable && shouldShowReplyReminder(options.deliveryCount)) {
     sections.push(replyReminder(replyable, options.readOnly === true));
-  } else if (relaySurface && !replyable && messages2.some(isNotificationMessage)) {
+  } else if (relaySurface && !replyable && uniqueMessages.some(isNotificationMessage)) {
     sections.push(NOTIFICATION_NUDGE);
   }
   return sections.join(`

package/runner/src/adapter.ts

@@ -304,6 +304,16 @@ function latestReplyableMessage(messages: Message[]): Message | undefined {
     .at(-1);
 }
 
+export function dedupePersistedMessages(messages: Message[]): Message[] {
+  const seen = new Set<number>();
+  return messages.filter((message) => {
+    if (!isPersistedRelayMessage(message)) return true;
+    if (seen.has(message.id)) return false;
+    seen.add(message.id);
+    return true;
+  });
+}
+
 function providerSenderLabel(message: Message): string {
   if (message.from === "user") return "human user";
   const source = isRecord(message.payload?.source) ? message.payload.source : undefined;
@@ -356,9 +366,10 @@ export function providerAttachmentText(message: Message): string | undefined {
 }
 
 export function providerMessageText(messages: Message[]): string {
-  const replyable = latestReplyableMessage(messages);
+  const uniqueMessages = dedupePersistedMessages(messages);
+  const replyable = latestReplyableMessage(uniqueMessages);
   const maxChars = providerMessageBodyMaxChars();
-  const sections = messages
+  const sections = uniqueMessages
     .map((message) => {
       const subject = message.subject ? `Subject: ${message.subject}\n` : "";
       const isMemoryContext = isMemoryInjection(message);
@@ -404,7 +415,7 @@ export function providerMessageText(messages: Message[]): string {
       "If you already delivered the useful response through Relay, do not send a separate status-only confirmation.",
       "If multiple messages arrived together, cover them in one reply instead of answering each line separately.",
     ].join("\n"));
-  } else if (messages.some(isNotificationMessage)) {
+  } else if (uniqueMessages.some(isNotificationMessage)) {
     // #283 — pure notification batch: no scaffold, just the one-line no-reply nudge.
     sections.push(NOTIFICATION_NUDGE);
   }

package/src/connectors.ts

@@ -6,6 +6,7 @@ import { ValidationError } from "./db";
 import { isRecord } from "agent-relay-sdk";
 import { registerConnectorConfigSetting, validateConnectorConfig } from "./settings/modules";
 import { connectorActionTimeoutMs as configuredConnectorActionTimeoutMs, connectorsDirFromEnv } from "./config";
+import { getConfig } from "./config-store";
 
 const CONNECTOR_SCHEMA = "agent-relay.connector.v1";
 const VALID_KINDS = new Set(["channel", "event", "provider", "orchestrator"]);
@@ -248,13 +249,124 @@ async function refreshConnectorStatus(id: string): Promise<void> {
 }
 
 export function startConnectorStatusPoller(): void {
-  // Relaunch connectors that were running before this process restarted (e.g. a
-  // deploy that took down the relay/orchestrator tree) BEFORE the first status
-  // poll overwrites their persisted "running" flag with the now-dead reality.
-  void reconcileConnectorsOnBoot().finally(() => void refreshAllConnectorStatuses());
+  // 1. Auto-register + auto-start the bundled channels host so ntfy/webhook egress
+  //    survives a deploy/restart with NO manual `register`/`start` (issue #794). Core
+  //    removed its in-core ntfy transport (v0.102.0), so this connector IS the egress
+  //    path now. Runs BEFORE reconcile so a fresh install is registered before the
+  //    boot relaunch + first status poll observe it.
+  // 2. Relaunch connectors that were running before this process restarted (e.g. a
+  //    deploy that took down the relay/orchestrator tree) BEFORE the first status
+  //    poll overwrites their persisted "running" flag with the now-dead reality.
+  void ensureChannelsHostConnector()
+    .catch(() => {})
+    .finally(() => void reconcileConnectorsOnBoot().finally(() => void refreshAllConnectorStatuses()));
   setInterval(() => void refreshAllConnectorStatuses(), STATUS_POLL_INTERVAL_MS);
 }
 
+const CHANNELS_HOST_ID = "channels-host";
+const CHANNELS_HOST_PACKAGE = "agent-relay-channels-host";
+// The legacy in-core ntfy channel persisted its settings here (src/ntfy.ts, removed in
+// v0.102.0). We migrate that value into the channels-host connector config on first
+// registration so an operator's existing ntfy setup keeps working after the cutover.
+const LEGACY_NTFY_NAMESPACE = "channel-type";
+const LEGACY_NTFY_KEY = "ntfy";
+
+/**
+ * Resolve the DEPLOYED channels-host CLI entry. In the published runtime it lives at
+ * `~/.agent-relay/runtime/node_modules/agent-relay-channels-host` (a dependency of
+ * agent-relay-server); in the dev tree it resolves to the workspace symlink. Returns
+ * null when the package isn't installed (e.g. a server checkout without the workspace
+ * dep) so boot stays a no-op rather than throwing.
+ */
+function resolveChannelsHostEntry(): string | null {
+  try {
+    const pkgJsonPath = Bun.resolveSync(`${CHANNELS_HOST_PACKAGE}/package.json`, import.meta.dir);
+    const pkgDir = dirname(pkgJsonPath);
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as { bin?: Record<string, string> | string };
+    const binRel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.[CHANNELS_HOST_PACKAGE] ?? "src/index.ts";
+    return join(pkgDir, binRel);
+  } catch {
+    return null;
+  }
+}
+
+/** Ask the deployed binary for its aggregated connector manifest (single source of truth). */
+async function loadChannelsHostManifest(entry: string): Promise<ConnectorManifest | null> {
+  try {
+    const proc = Bun.spawn({
+      cmd: ["bun", entry, "manifest"],
+      stdout: "pipe",
+      stderr: "ignore",
+      env: { ...process.env, AGENT_RELAY_CONNECTOR_ID: CHANNELS_HOST_ID, AGENT_RELAY_CONNECTORS_DIR: connectorRegistryDir() },
+    });
+    const timeout = setTimeout(() => proc.kill(), connectorActionTimeoutMs());
+    const [exitCode, stdout] = await Promise.all([proc.exited, new Response(proc.stdout).text()]);
+    clearTimeout(timeout);
+    if (exitCode !== 0) return null;
+    const parsed = parseJsonMaybe(stdout.trim());
+    const manifest = isRecord(parsed) && isRecord(parsed.manifest) ? parsed.manifest : parsed;
+    return normalizeConnectorManifest(manifest);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Migrate the legacy core ntfy settings (`channel-type/ntfy`) into channels-host
+ * connector config keys. Only an ENABLED legacy channel is migrated — a disabled one
+ * stays disabled (channels-host treats a missing NTFY_TOPIC as "off"), preserving
+ * operator intent. Returns undefined when there's nothing (active) to carry over.
+ */
+export function migrateLegacyNtfyConfig(): Record<string, unknown> | undefined {
+  const legacy = getConfig<Record<string, unknown>>(LEGACY_NTFY_NAMESPACE, LEGACY_NTFY_KEY)?.value;
+  if (!isRecord(legacy) || legacy.enabled !== true) return undefined;
+  const config: Record<string, string> = {};
+  const topic = typeof legacy.topic === "string" ? legacy.topic.trim() : "";
+  if (!topic) return undefined; // no topic → nothing the adapter can act on
+  config.NTFY_TOPIC = topic;
+  if (typeof legacy.serverUrl === "string" && legacy.serverUrl.trim()) config.NTFY_SERVER_URL = legacy.serverUrl.trim();
+  if (Array.isArray(legacy.defaultTags) && legacy.defaultTags.length) {
+    config.NTFY_DEFAULT_TAGS = legacy.defaultTags.filter((t): t is string => typeof t === "string").join(",");
+  }
+  if (typeof legacy.defaultClick === "string" && legacy.defaultClick.trim()) config.NTFY_DEFAULT_CLICK = legacy.defaultClick.trim();
+  if (typeof legacy.timeoutMs === "number" && Number.isFinite(legacy.timeoutMs)) config.NTFY_TIMEOUT_MS = String(legacy.timeoutMs);
+  // The legacy config stored the *name* of an env var holding the token, not the token
+  // itself; resolve it if that env var is present so the credential carries over.
+  if (typeof legacy.tokenEnv === "string" && legacy.tokenEnv.trim()) {
+    const token = process.env[legacy.tokenEnv.trim()];
+    if (token && token.trim()) config.NTFY_TOKEN = token.trim();
+  }
+  return config;
+}
+
+/**
+ * Auto-register and auto-start the channels host on boot (issue #794). Idempotent:
+ * - registers/refreshes the manifest from the deployed binary every boot (keeps the
+ *   binary path + version current across upgrades) without clobbering existing config;
+ * - seeds config from the legacy core ntfy setting only on first registration;
+ * - starts the daemon unless an operator deliberately stopped it (state.running === false).
+ */
+export async function ensureChannelsHostConnector(): Promise<void> {
+  const entry = resolveChannelsHostEntry();
+  if (!entry) return; // package not installed in this runtime — nothing to bring up
+  const existing = getConnector(CHANNELS_HOST_ID);
+  const manifest = await loadChannelsHostManifest(entry);
+  if (!manifest) return;
+
+  const hasConfig = isRecord(existing?.config) && Object.keys(existing.config).length > 0;
+  const seedConfig = hasConfig ? undefined : migrateLegacyNtfyConfig();
+  registerConnectorManifest(manifest, seedConfig ? { config: seedConfig } : {});
+
+  // Bring it up by default; respect a deliberate stop (persisted running:false).
+  const deliberatelyStopped = existing?.state?.running === false;
+  if (deliberatelyStopped) return;
+  try {
+    await runConnectorAction(CHANNELS_HOST_ID, "start");
+  } catch {
+    /* best-effort; the status poll surfaces failures */
+  }
+}
+
 // On boot, bring back any connector whose last persisted state says it was
 // running. `start` is idempotent — a daemon that survived the restart reports
 // "already running"; one that died with the process tree is relaunched. A

package/src/mcp-egress-tools.ts

@@ -8,7 +8,8 @@
 // the ntfy event payload { title, body, priority?, tags?, click? }. Same tool name
 // and args as before; async ("accepted for delivery"). Zero ntfy HTTP transport in core.
 //
-// Both tools use notifications:write scope (aliased; DECISION LOCKED — #773).
+// relay_send_to_channel uses channel:egress (least-privilege split — #792).
+// relay_notify_ntfy stays on notifications:write (operator-notification shim — #773).
 
 import { MAX_BODY_BYTES } from "./config";
 import { getChannel, sendMessage, ValidationError } from "./db";
@@ -27,7 +28,7 @@ export const EGRESS_TOOLS: ToolDefinition[] = [
   {
     name: "relay_send_to_channel",
     description: "Send an outbound message to a registered channel agent (e.g. ntfy, webhook). channelId is the channel agent ID; event is an opaque payload the adapter interprets.",
-    requiredScopes: ["notifications:write"],
+    requiredScopes: ["channel:egress"],
     inputSchema: {
       type: "object",
       properties: {

package/src/notification-router.ts

@@ -100,7 +100,7 @@ export function routeNotification(input: RouteNotificationInput): Message[] {
       subject: input.message.subject,
       body: input.message.body,
       payload: { ...(input.message.payload ?? {}), routing: compactRoutingExplanation(routing) },
-      idempotencyKey: input.message.idempotencyKey,
+      idempotencyKey: recipientScopedIdempotencyKey(input.message.idempotencyKey, routing.recipient),
       kind: input.message.kind,
       from: input.message.from,
       replyExpected: input.message.replyExpected,
@@ -111,6 +111,11 @@ export function routeNotification(input: RouteNotificationInput): Message[] {
   });
 }
 
+function recipientScopedIdempotencyKey(key: string | undefined, recipient: string): string | undefined {
+  if (!key) return undefined;
+  return `${key}:recipient:${recipient}`;
+}
+
 export function previewNotificationRouting(input: Pick<RouteNotificationInput, "type" | "scope" | "recipients">): NotificationRoutingPreview {
   const candidates = normalizeRoutingRecipients(input);
   const recipients: NotificationRoutingExplanation[] = [];

package/src/notify.ts

@@ -1,4 +1,4 @@
-import { sendMessage } from "./db";
+import { sendMessageWithResult } from "./db";
 import { emitNewMessage } from "./sse";
 import type { Message, MessageKind } from "./types";
 
@@ -34,7 +34,7 @@ interface SystemNotifyOptions {
  * recipient is offline (#234). Used by the GC sweep (maintenance) and lifecycle events (#239).
  */
 export function notifySystemMessage(to: string, opts: SystemNotifyOptions): Message {
-  const msg = sendMessage({
+  const result = sendMessageWithResult({
     from: opts.from ?? "system",
     to,
     kind: opts.kind ?? "system",
@@ -45,6 +45,6 @@ export function notifySystemMessage(to: string, opts: SystemNotifyOptions): Mess
     replyExpected: opts.replyExpected,
     maxAgeSeconds: opts.maxAgeSeconds,
   });
-  emitNewMessage(msg);
-  return msg;
+  if (result.created || result.updated) emitNewMessage(result.message);
+  return result.message;
 }

package/src/quota-band-transition.ts

@@ -247,6 +247,7 @@ function emitBandTransition(input: {
 
   const recipients = getSpawnCapableAgentIds();
   if (recipients.length === 0) return;
+  if (!shouldPushBandTransition(window.band, direction)) return;
 
   routeNotification({
     type: "routing.quota.band_transition",
@@ -256,12 +257,17 @@ function emitBandTransition(input: {
       subject: `${providerLabel(provider)} ${window.role} quota band → ${window.band}`,
       body: buildBody(input),
       payload,
+      idempotencyKey: `routing.quota.band_transition:${provider}:${window.role}:${window.band}`,
       replyExpected: false,
     },
     emittedAt: now,
   });
 }
 
+function shouldPushBandTransition(newBand: QuotaBand, direction: "degraded" | "recovered"): boolean {
+  return direction === "degraded" && bandRank(newBand) >= bandRank("caution");
+}
+
 function buildBody(input: {
   provider: string;
   window: ProviderBandWindow;

package/src/token-db.ts

@@ -78,7 +78,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Agent",
     description: "Coding-agent runtime access for messages, commands, tasks, and scoped memory reads.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "schedule:write", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "plans:read", "plans:write", "teams:read", "teams:write", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write", "quota:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "schedule:write", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "plans:read", "plans:write", "teams:read", "teams:write", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "channel:egress", "insights:write", "quota:write"],
     ttlSeconds: 24 * 60 * 60,
     builtIn: true,
     createdBy: "system",
@@ -88,7 +88,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Child Agent",
     description: "Delegated child-agent runtime access, constrained to its parent and spawn request.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "schedule:write", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write", "quota:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "schedule:write", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "channel:egress", "insights:write", "quota:write"],
     constraints: { canDelegate: false },
     ttlSeconds: 2 * 60 * 60,
     builtIn: true,
@@ -99,7 +99,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Interactive Agent",
     description: "User-launched provider runtime access constrained to its own agent and cwd for long interactive sessions.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "schedule:write", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write", "quota:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "schedule:write", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "channel:egress", "insights:write", "quota:write"],
     constraints: { terminalAttach: false, logsRead: false, canDelegate: false },
     ttlSeconds: 30 * 24 * 60 * 60,
     builtIn: true,