agent-relay-channels-host 0.105.2

package/README.md

@@ -0,0 +1,112 @@
+# agent-relay-channels-host
+
+The **channels host** is a single `agent-relay.connector.v1` connector (`kind:"channel"`)
+that bundles N lightweight egress adapters for the long tail of trivial third-party
+integrations (ntfy, generic webhook, slack/discord-egress, …). It keeps Agent Relay
+**core free of per-service transport code** — core owns only the registry, routing,
+and the `channel.v1` contract; the actual HTTP/push for each service lives in an
+adapter here.
+
+Heavyweight, stateful, two-way integrations (Telegram-class) keep their own repo. This
+host is for one-way / egress-only and other ~30-line adapters.
+
+> Status: the host (#778) installs, registers as a channel connector, and is
+> health-polled by the existing connector subsystem. **ntfy (#774)** is the first
+> bundled adapter; it registers `ntfy:default` (outbound) only when `NTFY_TOPIC` is
+> set, so an unconfigured install still registers zero channels cleanly.
+>
+> Productionized (#794): published as part of the agent-relay lockstep release set and
+> installed into `~/.agent-relay/runtime` as a dependency of `agent-relay-server`. The
+> relay **auto-registers and auto-starts** this connector on boot
+> (`src/connectors.ts` → `ensureChannelsHostConnector`), so it survives deploys/restarts
+> with no manual `register`/`start`. ntfy adapter config is persisted in the connector's
+> `config.json` and migrated once from the legacy core `channel-type/ntfy` setting.
+
+## How it plugs into Agent Relay
+
+The host reuses the existing connector lifecycle machinery (`src/connectors.ts`) — it
+is a *client* of that subsystem, not a reimplementation:
+
+- **Register the connector:** `POST /api/connectors` with the manifest
+  (`src/index.ts register` → `routes/connectors.ts`). The manifest declares the
+  `start/stop/restart/status/doctor` commands the relay drives, and an aggregated
+  `configSchema`.
+- **Lifecycle:** the relay spawns `start` (which detaches the long-running `daemon`),
+  `stop`, `restart`, `status`, `doctor` with a 30s timeout and persists their JSON
+  output as connector state. The 60s status poller keeps the dashboard honest.
+
+## The adapter interface
+
+Adapters implement `ChannelAdapter` (`src/adapter.ts`). The host owns **all** relay
+plumbing, so an adapter never touches SSE, agent registration, or tokens:
+
+| verb | owner | what it does |
+| --- | --- | --- |
+| `registerChannel()` | **host** | `POST /api/agents` with the integration token for each `ChannelSpec`: id `provider:account`, `kind:"channel"`, `meta.direction`. Core derives the channel row + directionality from this. |
+| `onOutboundMessage()` | **host** | subscribe `GET /api/events?for=<channelAgentId>`; the relay fans out only `message.new` frames addressed to that agent. |
+| `push()` | **adapter** | the only transport an adapter writes — deliver one outbound message to the service. |
+
+```ts
+import type { ChannelAdapter } from "agent-relay-channels-host/adapter";
+
+export const myAdapter: ChannelAdapter = {
+  provider: "ntfy",
+  displayName: "ntfy",
+  configSchema: { properties: { NTFY_TOPIC: { type: "string" } }, required: ["NTFY_TOPIC"] },
+  channels(ctx) {
+    const topic = ctx.get("NTFY_TOPIC");
+    return topic ? [{ account: "default", direction: "outbound", config: { topic } }] : [];
+  },
+  async push(message, channel, ctx) {
+    const topic = channel.config?.topic as string;
+    await fetch(`https://ntfy.sh/${topic}`, { method: "POST", body: message.body });
+  },
+};
+```
+
+Register it by appending to `src/adapters/index.ts` — no host or core changes:
+
+```ts
+export const adapters: ChannelAdapter[] = [ntfyAdapter, myAdapter];
+```
+
+See `src/adapters/ntfy.ts` for the reference implementation.
+
+Each adapter's `configSchema` fragment is merged into the connector manifest's
+aggregated `configSchema` (`src/manifest.ts`); dashboard-managed settings flow back to
+the adapter through `ctx.get(name)` (precedence: `process.env` > connector
+`config.json`).
+
+## CLI
+
+```
+agent-relay-channels-host <start|stop|restart|status|doctor|register|manifest|daemon>
+```
+
+- `register` — `POST /api/connectors` with the aggregated manifest.
+- `manifest` — print the aggregated manifest as `{ manifest }` JSON (no relay call). The
+  relay's boot auto-register spawns this from the deployed binary, so the manifest's
+  `binary`/commands resolve to the installed runtime path, never a repo-tree path.
+- `start` — detach the daemon, report `{status, running, endpoint}`.
+- `status` / `doctor` — JSON the relay persists as connector state.
+- `daemon` — internal long-running process (SSE subscriptions + push routing + status server).
+
+## Config
+
+| key | default | purpose |
+| --- | --- | --- |
+| `AGENT_RELAY_URL` | `http://127.0.0.1:4850` | relay base the host registers channels against |
+| `AGENT_RELAY_TOKEN` | — | integration/component token (`agent:write`); empty on a tokenless localhost relay |
+| `CHANNELS_HOST_PORT` | `4863` | daemon status HTTP server port |
+
+Plus every bundled adapter's namespaced keys. ntfy:
+
+| key | default | purpose |
+| --- | --- | --- |
+| `NTFY_TOPIC` | — | topic to publish to; empty disables the ntfy channel |
+| `NTFY_SERVER_URL` | `https://ntfy.sh` | ntfy server base URL |
+| `NTFY_TOKEN` | — | optional access token (sent as `Bearer`) |
+| `NTFY_DEFAULT_PRIORITY` | `default` | priority when the event omits one (`min`…`urgent`) |
+| `NTFY_DEFAULT_TAGS` | — | comma-separated tags merged into every notification |
+| `NTFY_DEFAULT_CLICK` | — | default click-through URL |
+| `NTFY_TIMEOUT_MS` | `15000` | per-request timeout |

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "agent-relay-channels-host",
+  "version": "0.105.2",
+  "description": "Channels host connector for Agent Relay — bundles N lightweight egress adapters (ntfy, webhook, …) behind one agent-relay.connector.v1 channel connector. Core ships zero per-service transport.",
+  "type": "module",
+  "bin": {
+    "agent-relay-channels-host": "src/index.ts"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "bun src/index.ts daemon",
+    "doctor": "bun src/index.ts doctor",
+    "register": "bun src/index.ts register",
+    "test": "bun test"
+  },
+  "license": "AGPL-3.0-or-later",
+  "author": "Edin Mujkanovic <edin@exelerus.com>",
+  "dependencies": {
+    "agent-relay-sdk": "0.2.92"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,117 @@
+import type { ChannelDirection } from "agent-relay-sdk";
+
+/**
+ * The channels-host adapter contract.
+ *
+ * An adapter is a lightweight module (~30 lines) describing the egress for a single
+ * third-party provider — ntfy, a generic webhook, slack/discord-egress, etc. The
+ * host owns ALL relay plumbing so adapters never re-implement it:
+ *
+ *   1. registerChannel()    — the host POSTs /api/agents for each ChannelSpec the
+ *                             adapter declares (`provider:account` id, kind:"channel",
+ *                             meta.direction). See src/relay.ts + src/host.ts.
+ *   2. onOutboundMessage()  — the host subscribes GET /api/events?for=<channelAgentId>
+ *                             on the SSE bus for each registered channel and routes
+ *                             every relay message addressed to it into push().
+ *   3. push()               — the ONLY transport the adapter implements: deliver one
+ *                             outbound message to the third-party service.
+ *
+ * configSchema fragments are aggregated across all bundled adapters into the
+ * connector manifest's `configSchema` (see src/manifest.ts), so dashboard-managed
+ * settings flow back to each adapter via AdapterContext.get().
+ *
+ * This split is the whole point of the epic (#773): core stays thin, the long tail
+ * of trivial egress integrations lives here, and a new adapter ships with zero core
+ * changes.
+ */
+export interface ChannelAdapter {
+  /**
+   * Stable provider id, e.g. "ntfy". Forms the `provider` half of every channel
+   * agent id this adapter registers. Must be lowercase `[a-z0-9_-]`.
+   */
+  readonly provider: string;
+  /** Human-facing name shown in dashboards/logs. */
+  readonly displayName: string;
+  /**
+   * JSON-schema fragment (an object schema with `properties`/`required`) contributed
+   * to the connector's aggregated configSchema. Keys should be namespaced to the
+   * provider (e.g. NTFY_TOPIC) to avoid collisions across adapters.
+   */
+  readonly configSchema?: JsonSchemaObject;
+  /**
+   * Declare the channels this adapter owns, derived from current config. Each becomes
+   * a `provider:account` channel agent. Return [] when the adapter is unconfigured
+   * (e.g. no topic set) — the host skips it cleanly, which is the zero-adapter case
+   * the scaffold ships with. May be async (e.g. to probe the upstream).
+   */
+  channels(ctx: AdapterContext): ChannelSpec[] | Promise<ChannelSpec[]>;
+  /**
+   * Deliver one outbound relay message addressed to `channel`. Called by the host for
+   * every SSE `message.new` frame routed to the channel's agent. Resolve on success;
+   * throw to mark the push failed — the host logs it and surfaces it in connector
+   * status/doctor.
+   */
+  push(message: OutboundMessage, channel: ResolvedChannel, ctx: AdapterContext): Promise<void>;
+}
+
+/** Minimal JSON-schema object shape an adapter contributes for its settings. */
+export interface JsonSchemaObject {
+  type?: "object";
+  properties?: Record<string, unknown>;
+  required?: string[];
+}
+
+/**
+ * One channel an adapter declares. The host turns it into a channel agent registered
+ * as `${provider}:${account}` with kind:"channel" and meta.direction.
+ */
+export interface ChannelSpec {
+  /** Account half of the channel id; combined as `${provider}:${account}` (e.g. "default"). */
+  account: string;
+  /** Directionality, written to meta.direction. Egress adapters use "outbound". */
+  direction: ChannelDirection;
+  /** Optional human-facing channel name; defaults to the adapter displayName. */
+  displayName?: string;
+  /** Extra agent tags merged into the registration (channel/provider tags are added automatically). */
+  tags?: string[];
+  /** Extra agent capabilities merged into the registration. */
+  capabilities?: string[];
+  /** Extra agent meta merged into the registration (kind/provider/accountId/direction are set by the host). */
+  meta?: Record<string, unknown>;
+  /** Opaque per-channel config the adapter needs at push() time (e.g. the resolved topic/url). */
+  config?: Record<string, unknown>;
+}
+
+/** A ChannelSpec resolved with its concrete relay agent id. */
+export type ResolvedChannel = ChannelSpec & {
+  /** `${provider}:${account}` — the relay channel agent id. */
+  readonly agentId: string;
+  /** The owning adapter's provider id. */
+  readonly provider: string;
+};
+
+/** A relay message handed to push() — the outbound channel.v1 envelope on the SSE bus. */
+export interface OutboundMessage {
+  id: number;
+  from: string;
+  to: string;
+  kind: string;
+  body: string;
+  payload?: Record<string, unknown>;
+  createdAt: number;
+}
+
+/** Capabilities the host exposes to adapters. Keeps adapters free of relay plumbing. */
+export interface AdapterContext {
+  /** Relay HTTP base, e.g. http://127.0.0.1:4850. */
+  readonly relayUrl: string;
+  /** Resolve a setting: process.env > connector config.json > undefined. */
+  get(name: string): string | undefined;
+  /** Structured log line, prefixed with the connector id by the host. */
+  log(message: string): void;
+}
+
+/** Build the `${provider}:${account}` relay channel agent id. */
+export function channelAgentId(provider: string, account: string): string {
+  return `${provider}:${account}`;
+}

package/src/adapters/index.ts

@@ -0,0 +1,12 @@
+import type { ChannelAdapter } from "../adapter";
+import { ntfyAdapter } from "./ntfy";
+
+/**
+ * The bundled adapter registry.
+ *
+ * Adding an adapter is a one-line append here plus its module — no host or core
+ * changes. ntfy (#774) is the first; it only registers a `ntfy:default` outbound
+ * channel when NTFY_TOPIC is configured, so an unconfigured install still registers
+ * zero channels cleanly (the scaffold property from #778).
+ */
+export const adapters: ChannelAdapter[] = [ntfyAdapter];

package/src/adapters/ntfy.ts

@@ -0,0 +1,182 @@
+import { isRecord } from "agent-relay-sdk";
+import type { AdapterContext, ChannelAdapter, ChannelSpec, OutboundMessage, ResolvedChannel } from "../adapter";
+
+/**
+ * ntfy egress adapter — the first channels-host adapter (#774).
+ *
+ * Ports the transport from the old in-core `src/ntfy.ts` (sendNtfyNotification /
+ * ntfy headers / config schema) into a `ChannelAdapter`. The host owns channel
+ * registration + the SSE subscription; this module only declares the channel and
+ * implements push().
+ *
+ * The outbound envelope it receives is the pinned `agent-relay.channel.v1` contract
+ * (#776): `{ direction:"outbound", channel:{provider:"ntfy",accountId:"default"},
+ * event:{ title, body, priority?, tags?, click? } }`, addressed to `ntfy:default`.
+ */
+
+export const NTFY_PRIORITIES = ["min", "low", "default", "high", "urgent"] as const;
+export type NtfyPriority = (typeof NTFY_PRIORITIES)[number];
+
+const DEFAULT_SERVER_URL = "https://ntfy.sh";
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MIN_TIMEOUT_MS = 1_000;
+const MAX_TIMEOUT_MS = 60_000;
+
+interface NtfyChannelConfig {
+  serverUrl: string;
+  topic: string;
+  defaultTags: string[];
+  defaultPriority?: number;
+  defaultClick?: string;
+  timeoutMs: number;
+}
+
+/** Settings the adapter contributes to the connector's aggregated configSchema. */
+const configSchema = {
+  type: "object" as const,
+  properties: {
+    NTFY_SERVER_URL: { type: "string", maxLength: 500, default: DEFAULT_SERVER_URL, description: "ntfy server base URL." },
+    NTFY_TOPIC: { type: "string", maxLength: 200, description: "ntfy topic to publish to. Empty disables the ntfy channel." },
+    NTFY_TOKEN: { type: "string", maxLength: 4000, description: "Optional ntfy access token (sent as Bearer auth)." },
+    NTFY_DEFAULT_PRIORITY: {
+      type: "string",
+      enum: [...NTFY_PRIORITIES],
+      default: "default",
+      description: "Priority applied when the outbound event omits one.",
+    },
+    NTFY_DEFAULT_TAGS: { type: "string", maxLength: 500, description: "Comma-separated tags merged into every notification." },
+    NTFY_DEFAULT_CLICK: { type: "string", maxLength: 1000, description: "Default click-through URL when the event omits one." },
+    NTFY_TIMEOUT_MS: { type: "integer", minimum: MIN_TIMEOUT_MS, maximum: MAX_TIMEOUT_MS, default: DEFAULT_TIMEOUT_MS, description: "Per-request timeout." },
+  },
+};
+
+export const ntfyAdapter: ChannelAdapter = {
+  provider: "ntfy",
+  displayName: "ntfy",
+  configSchema,
+
+  channels(ctx: AdapterContext): ChannelSpec[] {
+    const config = resolveConfig(ctx);
+    // Unconfigured (no topic) → no channel, so the host registers nothing for ntfy
+    // and the connector stays clean. Mirrors the old `enabled` gate.
+    if (!config) return [];
+    return [
+      {
+        account: "default",
+        direction: "outbound",
+        displayName: "ntfy",
+        capabilities: ["notify"],
+        meta: { topicChannels: [config.topic] },
+        config: { ...config },
+      },
+    ];
+  },
+
+  async push(message: OutboundMessage, channel: ResolvedChannel, ctx: AdapterContext): Promise<void> {
+    const config = (channel.config as NtfyChannelConfig | undefined) ?? resolveConfig(ctx);
+    if (!config) throw new Error("ntfy channel is not configured (NTFY_TOPIC missing)");
+
+    const event = outboundEvent(message);
+    const body = event.body ?? message.body ?? "";
+    if (!body) throw new Error("ntfy push requires a non-empty event.body");
+
+    const tags = [...new Set([...config.defaultTags, ...event.tags].map((t) => t.trim()).filter(Boolean))];
+    const priority = event.priority ?? config.defaultPriority;
+    const click = event.click ?? config.defaultClick;
+
+    // #796 — publish via ntfy's JSON API (POST JSON to the server base URL) rather than
+    // the header-based API. HTTP header values are ISO-8859-1/ASCII-only, so a non-ASCII
+    // `Title` header (emoji/unicode/em-dash) was rejected upstream ("Header 'Title' has
+    // invalid value"). The JSON body is UTF-8 by construction, so title/message survive.
+    // https://docs.ntfy.sh/publish/#publish-as-json
+    const payload: Record<string, unknown> = { topic: config.topic, message: body };
+    if (event.title) payload.title = event.title;
+    if (priority !== undefined) payload.priority = priority;
+    if (tags.length) payload.tags = tags;
+    if (click) payload.click = click;
+
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    const token = ctx.get("NTFY_TOKEN");
+    if (token) headers.Authorization = `Bearer ${token}`;
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
+    let res: Response;
+    try {
+      res = await fetch(ntfyServerUrl(config), { method: "POST", headers, body: JSON.stringify(payload), signal: controller.signal });
+    } catch (e) {
+      if (controller.signal.aborted) throw new Error(`ntfy notify timed out after ${config.timeoutMs}ms`);
+      throw new Error(`ntfy notify failed: ${(e as Error).message}`);
+    } finally {
+      clearTimeout(timeout);
+    }
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`ntfy notify failed: HTTP ${res.status}${text ? `: ${text.slice(0, 300)}` : ""}`);
+    }
+  },
+};
+
+interface ParsedEvent {
+  title?: string;
+  body?: string;
+  priority?: number;
+  tags: string[];
+  click?: string;
+}
+
+/** Extract the `agent-relay.channel.v1` outbound event from a relay message payload. */
+function outboundEvent(message: OutboundMessage): ParsedEvent {
+  const event = isRecord(message.payload?.event) ? (message.payload!.event as Record<string, unknown>) : {};
+  return {
+    title: typeof event.title === "string" ? event.title : undefined,
+    body: typeof event.body === "string" ? event.body : undefined,
+    priority: ntfyPriority(event.priority),
+    tags: Array.isArray(event.tags) ? event.tags.filter((t): t is string => typeof t === "string") : [],
+    click: typeof event.click === "string" ? event.click : undefined,
+  };
+}
+
+function resolveConfig(ctx: AdapterContext): NtfyChannelConfig | null {
+  const topic = ctx.get("NTFY_TOPIC");
+  if (!topic) return null;
+  if (topic.includes("/") || topic.includes("?") || topic.includes("#")) {
+    throw new Error("NTFY_TOPIC must be a single topic name, not a path or URL");
+  }
+  return {
+    serverUrl: ctx.get("NTFY_SERVER_URL") ?? DEFAULT_SERVER_URL,
+    topic,
+    defaultTags: (ctx.get("NTFY_DEFAULT_TAGS") ?? "").split(",").map((t) => t.trim()).filter(Boolean),
+    defaultPriority: ntfyPriority(ctx.get("NTFY_DEFAULT_PRIORITY")),
+    defaultClick: ctx.get("NTFY_DEFAULT_CLICK"),
+    timeoutMs: clampTimeout(ctx.get("NTFY_TIMEOUT_MS")),
+  };
+}
+
+/** Normalize a priority (numeric ntfy 1-5, or a named level) to the numeric scale. */
+function ntfyPriority(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return Math.min(5, Math.max(1, Math.round(value)));
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (/^[1-5]$/.test(trimmed)) return Number(trimmed);
+    const idx = NTFY_PRIORITIES.indexOf(trimmed as NtfyPriority);
+    if (idx >= 0) return idx + 1;
+  }
+  return undefined;
+}
+
+function clampTimeout(raw: string | undefined): number {
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return DEFAULT_TIMEOUT_MS;
+  return Math.min(MAX_TIMEOUT_MS, Math.max(MIN_TIMEOUT_MS, Math.round(n)));
+}
+
+// The JSON publish API posts to the server base URL (the topic travels in the body),
+// unlike the header API which posts to `${base}/${topic}`.
+function ntfyServerUrl(config: NtfyChannelConfig): string {
+  try {
+    return new URL(config.serverUrl.endsWith("/") ? config.serverUrl : `${config.serverUrl}/`).toString();
+  } catch {
+    throw new Error("NTFY_SERVER_URL must be a valid URL");
+  }
+}

package/src/config.ts

@@ -0,0 +1,78 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+
+/**
+ * Runtime configuration for the channels host, resolved from the environment.
+ *
+ * The relay injects AGENT_RELAY_CONNECTOR_ID / AGENT_RELAY_CONNECTORS_DIR when it
+ * spawns lifecycle actions (see src/connectors.ts:execConnectorCommand). Everything
+ * else has a sane localhost default. Durable per-connector settings live in the
+ * connector's config.json (written by the dashboard / PUT /connectors/:id/config);
+ * the relay spawns commands with only its own process.env, so adapters resolve
+ * their keys through `get()` with precedence: process.env > config.json > default.
+ */
+export interface HostConfig {
+  /** Connector id as registered with the relay (default "channels-host"). */
+  connectorId: string;
+  /** Base dir the relay uses for its connector registry. */
+  connectorsDir: string;
+  /** Per-connector runtime dir (pidfile, logs). */
+  runtimeDir: string;
+  /** Relay HTTP base, e.g. http://127.0.0.1:4850. */
+  relayUrl: string;
+  /** Integration/component token used to register channel agents; localhost relays accept tokenless requests. */
+  relayToken: string | null;
+  /** Port the daemon's status HTTP server listens on. */
+  port: number;
+  /**
+   * Resolve a per-connector setting. Precedence: process.env > config.json > undefined.
+   * Adapters read their own keys (e.g. NTFY_TOPIC) through this so dashboard-managed
+   * settings and ambient env both work without each adapter re-reading config.json.
+   */
+  get(name: string): string | undefined;
+}
+
+export const DEFAULT_CONNECTOR_ID = "channels-host";
+export const DEFAULT_PORT = 4863;
+
+function loadFileConfig(connectorsDir: string, connectorId: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  try {
+    const raw = JSON.parse(readFileSync(join(connectorsDir, connectorId, "config.json"), "utf8"));
+    if (raw && typeof raw === "object") {
+      for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+        if (v != null) out[k] = String(v);
+      }
+    }
+  } catch {
+    /* no config file — env + defaults */
+  }
+  return out;
+}
+
+/** Build a precedence-aware setting resolver: process.env > config.json > undefined. */
+function makeResolver(fileConfig: Record<string, string>): (name: string) => string | undefined {
+  return (name: string): string | undefined => {
+    const v = process.env[name] ?? fileConfig[name];
+    return v && v.trim() ? v.trim() : undefined;
+  };
+}
+
+export function loadConfig(): HostConfig {
+  const connectorId = process.env.AGENT_RELAY_CONNECTOR_ID?.trim() || DEFAULT_CONNECTOR_ID;
+  const connectorsDir = resolve(
+    process.env.AGENT_RELAY_CONNECTORS_DIR?.trim() || join(homedir(), ".agent-relay", "connectors"),
+  );
+  const fileConfig = loadFileConfig(connectorsDir, connectorId);
+  const get = makeResolver(fileConfig);
+  return {
+    connectorId,
+    connectorsDir,
+    runtimeDir: join(connectorsDir, connectorId, "runtime"),
+    relayUrl: (get("AGENT_RELAY_URL") ?? "http://127.0.0.1:4850").replace(/\/$/, ""),
+    relayToken: get("AGENT_RELAY_TOKEN") ?? null,
+    port: Number(get("CHANNELS_HOST_PORT") ?? "") || DEFAULT_PORT,
+    get,
+  };
+}

package/src/daemon.ts

@@ -0,0 +1,39 @@
+import { adapters } from "./adapters";
+import type { HostConfig } from "./config";
+import { ChannelsHost } from "./host";
+
+/**
+ * Long-running daemon: keeps the channels host alive (SSE subscriptions + push routing)
+ * and serves a tiny status HTTP server the `status` lifecycle action and the relay's
+ * connector poller read. Runs under the internal `daemon` action; the relay-spawned
+ * `start` action detaches it and returns within the 30s lifecycle timeout.
+ */
+export class ChannelsHostDaemon {
+  private readonly host: ChannelsHost;
+  private server: ReturnType<typeof Bun.serve> | null = null;
+
+  constructor(private readonly cfg: HostConfig) {
+    this.host = new ChannelsHost(cfg, adapters);
+  }
+
+  async start(): Promise<void> {
+    await this.host.start();
+    this.server = Bun.serve({
+      port: this.cfg.port,
+      idleTimeout: 0,
+      fetch: async (req) => {
+        const url = new URL(req.url);
+        if (url.pathname === "/health") return Response.json({ ok: true });
+        if (url.pathname === "/status") return Response.json(await this.host.status());
+        return new Response("not found", { status: 404 });
+      },
+    });
+    const shutdown = (): void => {
+      this.host.stop();
+      this.server?.stop(true);
+      process.exit(0);
+    };
+    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", shutdown);
+  }
+}

package/src/host.ts

@@ -0,0 +1,182 @@
+import type { AdapterContext, ChannelAdapter, OutboundMessage, ResolvedChannel } from "./adapter";
+import { channelAgentId } from "./adapter";
+import type { HostConfig } from "./config";
+import { RelayClient } from "./relay";
+
+/**
+ * The channels-host runtime. Owns all relay plumbing so adapters stay trivial:
+ * for each bundled adapter it resolves the channels to register, POSTs each as a
+ * `provider:account` channel agent, subscribes the SSE bus for it, and routes every
+ * outbound message into the adapter's push(). With no adapters it registers nothing
+ * and idles — the zero-adapter case the scaffold ships with (#778).
+ */
+
+export interface RegisteredChannel {
+  provider: string;
+  agentId: string;
+  direction: string;
+  connected: boolean;
+  pushOk: number;
+  pushErr: number;
+  lastError?: string;
+}
+
+export interface HostStatus {
+  adapters: number;
+  channels: number;
+  relayConnected: boolean;
+  registered: RegisteredChannel[];
+}
+
+// Cap on remembered delivered message ids per channel (#793). Notifications are low-volume;
+// this bounds memory while comfortably covering any realistic reconnect-replay window.
+const MAX_DELIVERED_IDS = 2_000;
+
+interface ChannelEntry extends RegisteredChannel {
+  adapter: ChannelAdapter;
+  resolved: ResolvedChannel;
+  stop: () => void;
+  // #793 — message ids already pushed for this channel. The relay re-flushes queued
+  // messages on reconnect/re-registration (flush-on-availability), so without a cursor an
+  // already-delivered notification would be pushed again. Insertion-ordered for cheap
+  // oldest-eviction once the cap is hit.
+  delivered: Set<number>;
+}
+
+export class ChannelsHost {
+  private readonly relay: RelayClient;
+  private readonly ctx: AdapterContext;
+  private readonly channels: ChannelEntry[] = [];
+  private started = false;
+
+  constructor(
+    private readonly cfg: HostConfig,
+    private readonly adapters: ChannelAdapter[],
+  ) {
+    this.relay = new RelayClient(cfg.relayUrl, cfg.relayToken);
+    this.ctx = {
+      relayUrl: cfg.relayUrl,
+      get: cfg.get,
+      log: (message: string) => this.log(message),
+    };
+  }
+
+  private log(message: string): void {
+    process.stderr.write(`[${this.cfg.connectorId}] ${message}\n`);
+  }
+
+  /** Register every adapter's channels and start routing outbound traffic. */
+  async start(): Promise<void> {
+    if (this.started) return;
+    this.started = true;
+    for (const adapter of this.adapters) {
+      let specs;
+      try {
+        specs = await adapter.channels(this.ctx);
+      } catch (e) {
+        this.log(`adapter ${adapter.provider} channels() failed: ${(e as Error).message}`);
+        continue;
+      }
+      for (const spec of specs) {
+        const resolved: ResolvedChannel = {
+          ...spec,
+          provider: adapter.provider,
+          agentId: channelAgentId(adapter.provider, spec.account),
+        };
+        await this.registerAndSubscribe(adapter, resolved);
+      }
+    }
+    this.log(`started: ${this.adapters.length} adapter(s), ${this.channels.length} channel(s)`);
+  }
+
+  private async registerAndSubscribe(adapter: ChannelAdapter, resolved: ResolvedChannel): Promise<void> {
+    try {
+      await this.relay.registerChannel(resolved);
+    } catch (e) {
+      this.log(`register ${resolved.agentId} failed: ${(e as Error).message}`);
+      return;
+    }
+    const entry: ChannelEntry = {
+      provider: adapter.provider,
+      agentId: resolved.agentId,
+      direction: resolved.direction,
+      connected: false,
+      pushOk: 0,
+      pushErr: 0,
+      adapter,
+      resolved,
+      stop: () => {},
+      delivered: new Set<number>(),
+    };
+    entry.stop = this.relay.subscribeOutbound(
+      resolved.agentId,
+      (msg) => void this.dispatch(entry, msg),
+      (connected) => {
+        entry.connected = connected;
+      },
+    );
+    this.channels.push(entry);
+    this.log(`registered ${resolved.agentId} (${resolved.direction})`);
+  }
+
+  private async dispatch(entry: ChannelEntry, msg: OutboundMessage): Promise<void> {
+    // #793 — drop messages already delivered for this channel. On reconnect/re-registration
+    // the relay re-flushes queued messages addressed to the channel agent, replaying ones we
+    // already pushed; without this guard each replay would fire a duplicate notification.
+    // Reserve the id BEFORE pushing so a concurrent live+replay of the same id can't both
+    // push; release it on failure so a genuinely failed push is retried (at-least-once).
+    const id = typeof msg.id === "number" ? msg.id : null;
+    if (id !== null) {
+      if (entry.delivered.has(id)) return;
+      entry.delivered.add(id);
+    }
+    try {
+      await entry.adapter.push(msg, entry.resolved, this.ctx);
+      entry.pushOk += 1;
+      entry.lastError = undefined;
+      if (id !== null) {
+        this.capDelivered(entry);
+        // Ack delivered so the relay marks the message delivered and won't re-flush it.
+        void this.relay.ackDelivered(id, entry.agentId).catch(() => {});
+      }
+    } catch (e) {
+      if (id !== null) entry.delivered.delete(id);
+      entry.pushErr += 1;
+      entry.lastError = (e as Error).message;
+      this.log(`push to ${entry.agentId} failed: ${entry.lastError}`);
+    }
+  }
+
+  // Bound the per-channel delivered-id set, evicting oldest-first (insertion order).
+  private capDelivered(entry: ChannelEntry): void {
+    while (entry.delivered.size > MAX_DELIVERED_IDS) {
+      const oldest = entry.delivered.values().next().value;
+      if (oldest === undefined) break;
+      entry.delivered.delete(oldest);
+    }
+  }
+
+  /** Snapshot for the daemon's /status endpoint and the `status` lifecycle action. */
+  async status(): Promise<HostStatus> {
+    return {
+      adapters: this.adapters.length,
+      channels: this.channels.length,
+      relayConnected: await this.relay.reachable(),
+      registered: this.channels.map((c) => ({
+        provider: c.provider,
+        agentId: c.agentId,
+        direction: c.direction,
+        connected: c.connected,
+        pushOk: c.pushOk,
+        pushErr: c.pushErr,
+        lastError: c.lastError,
+      })),
+    };
+  }
+
+  stop(): void {
+    for (const channel of this.channels) channel.stop();
+    this.channels.length = 0;
+    this.started = false;
+  }
+}

package/src/index.ts

@@ -0,0 +1,187 @@
+#!/usr/bin/env bun
+import { existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { adapters } from "./adapters";
+import { loadConfig, type HostConfig } from "./config";
+import { ChannelsHostDaemon } from "./daemon";
+import { buildManifest } from "./manifest";
+import { RelayClient } from "./relay";
+
+/**
+ * CLI entry + connector lifecycle. The relay spawns these actions with a 30s timeout
+ * (src/connectors.ts), so `start` must detach the daemon and return immediately; the
+ * daemon itself runs under the internal `daemon` action.
+ */
+
+const SELF = join(import.meta.dir, "index.ts");
+const VERSION = "0.1.0";
+
+function pidFile(cfg: HostConfig): string {
+  return join(cfg.runtimeDir, "channels-host.pid");
+}
+
+function readPid(cfg: HostConfig): number | null {
+  const f = pidFile(cfg);
+  if (!existsSync(f)) return null;
+  const pid = Number(readFileSync(f, "utf8").trim());
+  return Number.isFinite(pid) && pid > 0 ? pid : null;
+}
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function out(obj: unknown): void {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+
+function statusBase(cfg: HostConfig): string {
+  return `http://127.0.0.1:${cfg.port}`;
+}
+
+async function actionStart(cfg: HostConfig): Promise<void> {
+  mkdirSync(cfg.runtimeDir, { recursive: true });
+  const existing = readPid(cfg);
+  if (existing && isAlive(existing)) {
+    out({ status: "ok", running: true, enabled: true, endpoint: statusBase(cfg), detail: `already running (pid ${existing})` });
+    return;
+  }
+  const logFd = openSync(join(cfg.runtimeDir, "channels-host.log"), "a");
+  const child = Bun.spawn({
+    cmd: ["bun", SELF, "daemon"],
+    env: { ...process.env },
+    stdin: "ignore",
+    stdout: logFd,
+    stderr: logFd,
+  });
+  child.unref();
+  writeFileSync(pidFile(cfg), String(child.pid), { mode: 0o600 });
+
+  // Give the daemon a moment to bind its status port before reporting.
+  let up = false;
+  for (let i = 0; i < 25; i++) {
+    try {
+      const res = await fetch(`${statusBase(cfg)}/health`, { signal: AbortSignal.timeout(500) });
+      if (res.ok) {
+        up = true;
+        break;
+      }
+    } catch {
+      /* not up yet */
+    }
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  out({
+    status: up ? "ok" : "warn",
+    running: up,
+    enabled: true,
+    endpoint: statusBase(cfg),
+    detail: up ? `channels host listening on :${cfg.port}` : "daemon spawned but health check timed out",
+  });
+}
+
+function actionStop(cfg: HostConfig): void {
+  const pid = readPid(cfg);
+  if (pid && isAlive(pid)) {
+    try {
+      process.kill(pid);
+    } catch {
+      /* already gone */
+    }
+  }
+  try {
+    rmSync(pidFile(cfg));
+  } catch {
+    /* none */
+  }
+  out({ status: "ok", running: false, enabled: true, detail: "stopped" });
+}
+
+async function actionStatus(cfg: HostConfig): Promise<void> {
+  const pid = readPid(cfg);
+  const running = Boolean(pid && isAlive(pid));
+  let detail = running ? `running (pid ${pid})` : "not running";
+  if (running) {
+    try {
+      const res = await fetch(`${statusBase(cfg)}/status`, { signal: AbortSignal.timeout(1500) });
+      if (res.ok) {
+        const s = (await res.json()) as { adapters: number; channels: number; relayConnected: boolean };
+        detail = `adapters=${s.adapters} channels=${s.channels} relay=${s.relayConnected ? "up" : "down"}`;
+      }
+    } catch {
+      /* daemon not answering; keep pid detail */
+    }
+  }
+  out({ status: running ? "ok" : "warn", running, enabled: true, endpoint: statusBase(cfg), detail });
+}
+
+async function actionDoctor(cfg: HostConfig): Promise<void> {
+  const checks: Array<{ name: string; status: "ok" | "warn" | "error"; detail: string }> = [];
+
+  const relayUp = await new RelayClient(cfg.relayUrl, cfg.relayToken).reachable();
+  checks.push({ name: "relay", status: relayUp ? "ok" : "warn", detail: relayUp ? cfg.relayUrl : `unreachable at ${cfg.relayUrl}` });
+
+  checks.push({
+    name: "adapters",
+    status: "ok",
+    detail: adapters.length ? adapters.map((a) => a.provider).join(", ") : "no adapters bundled (scaffold)",
+  });
+
+  const pid = readPid(cfg);
+  const running = Boolean(pid && isAlive(pid));
+  checks.push({ name: "daemon", status: running ? "ok" : "warn", detail: running ? `running (pid ${pid})` : "not running" });
+
+  out({ checks, summary: `relay ${relayUp ? "reachable" : "unreachable"}, ${adapters.length} adapter(s)` });
+}
+
+async function actionRegister(cfg: HostConfig): Promise<void> {
+  const manifest = buildManifest({ connectorId: cfg.connectorId, binary: SELF, version: VERSION, adapters });
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (cfg.relayToken) headers.authorization = `Bearer ${cfg.relayToken}`;
+  const res = await fetch(`${cfg.relayUrl}/api/connectors`, { method: "POST", headers, body: JSON.stringify({ manifest }) });
+  if (!res.ok) {
+    out({ status: "error", detail: `register failed: ${res.status} ${await res.text().catch(() => "")}` });
+    process.exit(1);
+  }
+  out({ status: "ok", detail: `registered connector '${cfg.connectorId}' with ${cfg.relayUrl}` });
+}
+
+async function main(): Promise<void> {
+  const action = (process.argv[2] || "").toLowerCase();
+  const cfg = loadConfig();
+  switch (action) {
+    case "daemon":
+      await new ChannelsHostDaemon(cfg).start();
+      return; // long-running, never returns
+    case "start":
+      await actionStart(cfg);
+      return;
+    case "stop":
+      actionStop(cfg);
+      return;
+    case "restart":
+      actionStop(cfg);
+      await new Promise((r) => setTimeout(r, 300));
+      await actionStart(cfg);
+      return;
+    case "status":
+      await actionStatus(cfg);
+      return;
+    case "doctor":
+      await actionDoctor(cfg);
+      return;
+    case "register":
+      await actionRegister(cfg);
+      return;
+    default:
+      process.stderr.write("usage: agent-relay-channels-host <start|stop|restart|status|doctor|register|daemon>\n");
+      process.exit(2);
+  }
+}
+
+void main();

package/src/manifest.ts

@@ -0,0 +1,97 @@
+import type { ConnectorManifest } from "agent-relay-sdk";
+import type { ChannelAdapter } from "./adapter";
+import { DEFAULT_PORT } from "./config";
+
+/**
+ * Build the `agent-relay.connector.v1` manifest for the channels host.
+ *
+ * The configSchema is aggregated: a host-level base (relay URL/token, status port)
+ * merged with every bundled adapter's contributed `properties`/`required`. Adapter
+ * keys are expected to be provider-namespaced (e.g. NTFY_TOPIC); on a duplicate key
+ * the first adapter wins and a warning is collected (surfaced by doctor).
+ */
+
+/** Host-level settings every install needs, independent of which adapters are bundled. */
+function baseConfigSchema(): { properties: Record<string, unknown>; required: string[] } {
+  return {
+    properties: {
+      AGENT_RELAY_URL: {
+        type: "string",
+        description: "Relay HTTP base the host registers channels against.",
+        default: "http://127.0.0.1:4850",
+      },
+      AGENT_RELAY_TOKEN: {
+        type: "string",
+        description: "Integration/component token used to register channel agents (agent:write scope). Empty on a tokenless localhost relay.",
+      },
+      CHANNELS_HOST_PORT: {
+        type: "number",
+        description: "Port the host daemon's status HTTP server listens on.",
+        default: DEFAULT_PORT,
+      },
+    },
+    required: [],
+  };
+}
+
+export interface AggregatedConfigSchema {
+  type: "object";
+  properties: Record<string, unknown>;
+  required: string[];
+  /** Keys an adapter tried to contribute that collided with an existing one (first-wins). */
+  collisions: string[];
+}
+
+export function aggregateConfigSchema(adapters: ChannelAdapter[]): AggregatedConfigSchema {
+  const base = baseConfigSchema();
+  const properties: Record<string, unknown> = { ...base.properties };
+  const required = new Set<string>(base.required);
+  const collisions: string[] = [];
+
+  for (const adapter of adapters) {
+    const schema = adapter.configSchema;
+    if (!schema) continue;
+    for (const [key, value] of Object.entries(schema.properties ?? {})) {
+      if (key in properties) {
+        collisions.push(key);
+        continue;
+      }
+      properties[key] = value;
+    }
+    for (const key of schema.required ?? []) required.add(key);
+  }
+
+  return { type: "object", properties, required: [...required], collisions };
+}
+
+export function buildManifest(opts: {
+  connectorId: string;
+  binary: string;
+  version: string;
+  adapters: ChannelAdapter[];
+}): ConnectorManifest {
+  const { properties, required } = aggregateConfigSchema(opts.adapters);
+  const providers = opts.adapters.map((a) => a.provider).sort();
+  const description =
+    providers.length > 0
+      ? `Channels host bundling lightweight egress adapters: ${providers.join(", ")}.`
+      : "Channels host for lightweight egress adapters (no adapters bundled yet).";
+  return {
+    schema: "agent-relay.connector.v1",
+    id: opts.connectorId,
+    kind: "channel",
+    displayName: "Channels Host",
+    description,
+    version: opts.version,
+    binary: opts.binary,
+    capabilities: ["channel", "channels-host", ...providers],
+    commands: {
+      start: ["bun", opts.binary, "start"],
+      stop: ["bun", opts.binary, "stop"],
+      restart: ["bun", opts.binary, "restart"],
+      status: ["bun", opts.binary, "status"],
+      doctor: ["bun", opts.binary, "doctor"],
+    },
+    configSchema: { type: "object", properties, ...(required.length ? { required } : {}) },
+  };
+}

package/src/relay.ts

@@ -0,0 +1,151 @@
+import { ReconnectionManager, RelayHttpClient } from "agent-relay-sdk";
+import { parseSseFrame } from "agent-relay-sdk/sse";
+import type { OutboundMessage, ResolvedChannel } from "./adapter";
+
+/**
+ * Minimal relay client for the channels host.
+ *
+ * registerChannel():    POST /api/agents with the integration token. The channel is a
+ *                       `provider:account` agent of kind:"channel" carrying meta.direction;
+ *                       core derives the channel row + directionality from it
+ *                       (channelDirectionForAgent, src/db/channels.ts).
+ * subscribeOutbound():  GET /api/events?for=<channelAgentId>. The relay only fans out
+ *                       `message.new` frames addressed to that agent (createSSEStream +
+ *                       messageMatchesAgent), so each subscription receives exactly the
+ *                       outbound traffic for one channel. Auto-reconnects on drop.
+ */
+export class RelayClient {
+  private readonly http: RelayHttpClient;
+
+  constructor(
+    private readonly relayUrl: string,
+    relayToken: string | null,
+  ) {
+    // Auth goes in the relay token header (RELAY_TOKEN_HEADER via RelayHttpClient),
+    // NOT `Authorization: Bearer` — the relay only honours the former.
+    this.http = new RelayHttpClient({ baseUrl: relayUrl, token: relayToken ?? undefined });
+  }
+
+  /** True when the relay answers /api/health. */
+  async reachable(): Promise<boolean> {
+    try {
+      const res = await this.http.requestRaw("GET", "/api/health", undefined, {}, { timeoutMs: 2500 });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Register one channel as a `provider:account` channel agent. Idempotent (upsert). */
+  async registerChannel(channel: ResolvedChannel): Promise<void> {
+    const name = channel.displayName ?? channel.provider;
+    await this.http.registerAgent({
+      id: channel.agentId,
+      name,
+      kind: "channel",
+      status: "online",
+      ready: true,
+      tags: dedupe(["channel", channel.provider, `channel:${channel.provider}`, ...(channel.tags ?? [])]),
+      capabilities: dedupe(["channel", channel.provider, ...(channel.capabilities ?? [])]),
+      meta: {
+        ...(channel.meta ?? {}),
+        kind: "channel",
+        provider: channel.provider,
+        accountId: channel.account,
+        channelType: channel.provider,
+        transport: channel.provider,
+        direction: channel.direction,
+        displayName: name,
+      },
+    });
+  }
+
+  /**
+   * Ack a delivered outbound message (#793). Marks the relay-side message `delivered` so the
+   * flush-on-availability path (resolveQueuedDirectMessages, which only re-emits `queued`
+   * messages) won't re-push it on the next reconnect/re-registration — and so the relay's
+   * delivery health doesn't count a pushed notification as silently lost. The cursor: once
+   * acked, the message is no longer replayable to this channel.
+   */
+  async ackDelivered(messageId: number, channelAgentId: string): Promise<void> {
+    await this.http.recordMessageDeliveryAttempt(messageId, { agentId: channelAgentId, status: "delivered" });
+  }
+
+  /**
+   * Subscribe to outbound messages for one channel agent. Calls `onMessage` for every
+   * `message.new` frame and auto-reconnects on drop. Returns a stop() function.
+   */
+  subscribeOutbound(
+    channelAgentId: string,
+    onMessage: (msg: OutboundMessage) => void,
+    onState?: (connected: boolean) => void,
+  ): () => void {
+    let stopped = false;
+    let controller: AbortController | null = null;
+    const reconnect = new ReconnectionManager();
+    const path = `/api/events?for=${encodeURIComponent(channelAgentId)}`;
+
+    const run = async (): Promise<void> => {
+      while (!stopped) {
+        controller = new AbortController();
+        try {
+          const res = await this.http.requestRaw(
+            "GET",
+            path,
+            undefined,
+            { accept: "text/event-stream" },
+            { signal: controller.signal, timeoutMs: null },
+          );
+          if (!res.ok || !res.body) throw new Error(`GET ${path} -> ${res.status}`);
+          onState?.(true);
+          reconnect.reset();
+          await this.consumeSse(res.body, onMessage);
+        } catch {
+          /* fall through to reconnect */
+        }
+        onState?.(false);
+        if (stopped) break;
+        await reconnect.schedule();
+      }
+    };
+    void run();
+
+    return () => {
+      stopped = true;
+      reconnect.cancel();
+      controller?.abort();
+    };
+  }
+
+  private async consumeSse(body: ReadableStream<Uint8Array>, onMessage: (msg: OutboundMessage) => void): Promise<void> {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let sep: number;
+      // SSE events are separated by a blank line.
+      while ((sep = buffer.indexOf("\n\n")) !== -1) {
+        const chunk = buffer.slice(0, sep);
+        buffer = buffer.slice(sep + 2);
+        this.dispatchSse(chunk, onMessage);
+      }
+    }
+  }
+
+  private dispatchSse(chunk: string, onMessage: (msg: OutboundMessage) => void): void {
+    const { event, data } = parseSseFrame(chunk);
+    if (event !== "message.new" || data.length === 0) return;
+    try {
+      onMessage(JSON.parse(data.join("\n")) as OutboundMessage);
+    } catch {
+      /* ignore malformed frame */
+    }
+  }
+}
+
+function dedupe(values: string[]): string[] {
+  return [...new Set(values.map((v) => v.trim()).filter(Boolean))];
+}