agent-relay-server 0.4.27 → 0.4.28

package/README.md

@@ -40,6 +40,21 @@ 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
+
+Agent Relay is built around four extension points:
+
+> **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:
+
+- **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.
+
+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.
+
 ## Quick Start
 
 ### 1. Start the relay server
@@ -193,7 +208,7 @@ When an integration has `callbackUrl`, Agent Relay posts task lifecycle events
 
 Integration tokens can also be used as scoped API tokens when the full admin
 `AGENT_RELAY_TOKEN` would be too broad. Supported scopes include `stats:read`,
-`health:read`, `events:read`, `agents:read`, `agents:write`, `messages:read`,
+`health:read`, `events:read`, `channels:read`, `agents:read`, `agents:write`, `messages:read`,
 `messages:write`, `tasks:read`, `tasks:write`, `pairs:read`, `pairs:write`,
 `system:write`, and `*`.
 The event ingress endpoint also accepts the legacy `tasks:create` and
@@ -370,6 +385,8 @@ relay asks for a more specific target such as `id:...`, `label:...`, `tag:...`,
 
 | Method | Path | Purpose |
 |--------|------|---------|
+| `GET` | `/channels` | List registered communication channels such as Telegram |
+| `GET` | `/integrations` | List configured and observed task/system integrations |
 | `POST` | `/integrations/events` | Integration event ingress |
 | `GET` | `/tasks` | List tasks |
 | `GET` | `/tasks/:id` | Get one task |

package/package.json

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

package/public/dashboard.js

@@ -50,6 +50,8 @@
       pairs: [],
       messages: [],
       tasks: [],
+      integrations: [],
+      channels: [],
       taskEvents: [],
       taskEventCache: {},
       stats: {},
@@ -211,6 +213,8 @@
         if (view === "activity") await Promise.all([this.fetchMessages(), this.fetchPairs(), this.fetchTasks(), this.fetchActivityEvents()]);
         if (view === "work") await Promise.all([this.fetchMessages(), this.fetchTasks()]);
         if (view === "pairs") this.fetchPairs();
+        if (view === "channels") await this.fetchChannels();
+        if (view === "integrations") await this.fetchIntegrations();
         if (view === "tasks") this.fetchTasks();
       },
 
@@ -353,7 +357,7 @@
       },
 
       async refresh() {
-        await Promise.all([this.fetchStats(), this.fetchHealth(), this.fetchAgents(), this.fetchPairs(), this.fetchMessages(), this.fetchTasks(), this.fetchInboxState(), this.fetchActivityEvents()]);
+        await Promise.all([this.fetchStats(), this.fetchHealth(), this.fetchAgents(), this.fetchPairs(), this.fetchMessages(), this.fetchTasks(), this.fetchChannels(), this.fetchIntegrations(), this.fetchInboxState(), this.fetchActivityEvents()]);
       },
 
       async refreshLiveData() {
@@ -424,6 +428,18 @@
         } catch {}
       },
 
+      async fetchIntegrations() {
+        try {
+          this.integrations = await this.api("GET", "/integrations");
+        } catch {}
+      },
+
+      async fetchChannels() {
+        try {
+          this.channels = await this.api("GET", "/channels");
+        } catch {}
+      },
+
       async fetchInboxState() {
         try {
           const state = await this.api("GET", "/inbox/state?operatorId=" + encodeURIComponent(INBOX_OPERATOR_ID));
@@ -486,6 +502,8 @@
       attentionAgentCount: { get: getAttentionAgentCount },
       activityItems: { get: getActivityItems },
       workQueueItems: { get: getWorkQueueItems },
+      channelCards: { get: getChannelCards },
+      integrationCards: { get: getIntegrationCards },
       filteredMessages: { get: getFilteredMessages },
       groupedMessages: { get: getGroupedMessages },
       filteredTasks: { get: getFilteredTasks },
@@ -1004,6 +1022,28 @@
     return this.tasks.filter((task) => !CLOSED_TASK_STATUSES.has(task.status));
   }
 
+  function getIntegrationCards() {
+    return [...(this.integrations || [])].sort((a, b) => {
+      const aStats = a.taskStats || {};
+      const bStats = b.taskStats || {};
+      const openDiff = (bStats.openTasks || 0) - (aStats.openTasks || 0);
+      if (openDiff !== 0) return openDiff;
+      const waitingDiff = (bStats.waitingTasks || 0) - (aStats.waitingTasks || 0);
+      if (waitingDiff !== 0) return waitingDiff;
+      return String(a.name || "").localeCompare(String(b.name || ""));
+    });
+  }
+
+  function getChannelCards() {
+    return [...(this.channels || [])].sort((a, b) => {
+      const readyDiff = Number(Boolean(b.ready)) - Number(Boolean(a.ready));
+      if (readyDiff !== 0) return readyDiff;
+      const statusDiff = String(a.status || "").localeCompare(String(b.status || ""));
+      if (statusDiff !== 0) return statusDiff;
+      return String(a.name || "").localeCompare(String(b.name || ""));
+    });
+  }
+
   function getComposeAgents() {
     const list = visibleAgents(this);
     return this.showOffline ? list : list.filter((agent) => agent.status !== "offline");
@@ -1177,6 +1217,8 @@
       agentStatusClass,
       severityClass,
       agentStatusTitle,
+      channelPresence,
+      integrationPresence,
       timeAgo,
       fmtTime,
       healthAlertClass,
@@ -1389,6 +1431,23 @@
     return "bg-info-lt";
   }
 
+  function integrationPresence(integration) {
+    const stats = integration?.taskStats || {};
+    if ((stats.waitingTasks || 0) > 0) return { label: "waiting", tone: "warning", icon: "ti-alert-circle" };
+    if ((stats.openTasks || 0) > 0) return { label: "active", tone: "info", icon: "ti-activity" };
+    if (!integration?.configured) return { label: "observed only", tone: "secondary", icon: "ti-eye" };
+    if (integration.observed) return { label: "quiet", tone: "success", icon: "ti-circle-check" };
+    return { label: "configured", tone: "primary", icon: "ti-plug-connected" };
+  }
+
+  function channelPresence(channel) {
+    if (!channel) return { label: "unknown", tone: "secondary", icon: "ti-plug-off" };
+    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" };
+    return { label: "ready", tone: "success", icon: "ti-circle-check" };
+  }
+
   function agentStatusTitle(agent) {
     if (!agent) return "";
     if (agent.status === "offline") return "offline";

package/public/index.html

@@ -190,6 +190,16 @@
         <span class="badge bg-warning text-white ms-auto" x-show="attentionAgentCount > 0" x-text="attentionAgentCount"></span>
         <span class="badge bg-success text-white ms-1" x-text="onlineCount"></span>
       </a>
+      <a href="#" class="nav-link" :class="{ active: view === 'channels' }" @click.prevent="switchView('channels')">
+        <i class="ti ti-messages"></i>Channels
+        <span class="badge bg-success text-white ms-auto" x-show="channelCards.filter((item) => item.ready).length > 0" x-text="channelCards.filter((item) => item.ready).length"></span>
+        <span class="badge bg-secondary text-white ms-1" x-text="channelCards.length"></span>
+      </a>
+      <a href="#" class="nav-link" :class="{ active: view === 'integrations' }" @click.prevent="switchView('integrations')">
+        <i class="ti ti-plug-connected"></i>Integrations
+        <span class="badge bg-warning text-white ms-auto" x-show="integrationCards.some((item) => (item.taskStats?.waitingTasks || 0) > 0)" x-text="integrationCards.reduce((total, item) => total + (item.taskStats?.waitingTasks || 0), 0)"></span>
+        <span class="badge bg-secondary text-white ms-1" x-text="integrationCards.length"></span>
+      </a>
       <a href="#" class="nav-link" :class="{ active: view === 'inbox' }" @click.prevent="switchView('inbox')">
         <i class="ti ti-inbox"></i>Inbox
         <span class="badge bg-danger text-white ms-auto" x-show="attentionSummary.unreadInbox > 0" x-text="attentionSummary.unreadInbox"></span>
@@ -251,7 +261,7 @@
 
   <!-- Mobile nav -->
   <div class="mobile-nav d-none border-bottom p-2 gap-1 position-fixed top-0 w-100 bg-dark" style="z-index:50">
-    <template x-for="v in ['overview','agents','inbox','activity','pairs','messages','work','tasks','analytics']">
+    <template x-for="v in ['overview','agents','channels','integrations','inbox','activity','pairs','messages','work','tasks','analytics']">
       <button class="btn btn-sm" :class="view === v ? 'btn-primary' : 'btn-ghost-secondary'" @click="switchView(v)" x-text="v.charAt(0).toUpperCase() + v.slice(1)"></button>
     </template>
   </div>
@@ -660,6 +670,164 @@
         </template>
       </div>
 
+      <!-- ==================== CHANNELS ==================== -->
+      <div x-show="view === 'channels'" x-cloak class="fade-in">
+        <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>
+          <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>
+            </button>
+          </div>
+        </div>
+
+        <div class="row g-3">
+          <template x-for="channel in channelCards" :key="channel.id">
+            <div class="col-md-6 col-xl-4">
+              <div class="card">
+                <div class="card-body">
+                  <div class="d-flex align-items-start gap-2">
+                    <span class="agent-type-icon agent mt-0">
+                      <i class="ti" :class="channelPresence(channel).icon"></i>
+                    </span>
+                    <div class="flex-grow-1 min-width-0">
+                      <div class="d-flex align-items-center gap-2">
+                        <span class="fw-bold text-truncate" x-text="channel.name"></span>
+                        <span class="badge" :class="'bg-' + channelPresence(channel).tone + '-lt'">
+                          <i class="ti me-1" :class="channelPresence(channel).icon"></i><span x-text="channelPresence(channel).label"></span>
+                        </span>
+                      </div>
+                      <div class="d-flex gap-1 mt-2 flex-wrap">
+                        <span class="badge bg-info-lt" x-text="channel.type"></span>
+                        <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="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>
+                        </template>
+                      </div>
+                      <div class="d-flex gap-1 mt-2 flex-wrap" x-show="channel.topicChannels?.length">
+                        <template x-for="topic in (channel.topicChannels || [])" :key="topic">
+                          <span class="badge bg-warning-lt" x-text="'#' + topic"></span>
+                        </template>
+                      </div>
+                      <div class="text-secondary small mt-2 d-flex gap-2 flex-wrap">
+                        <span x-text="'Agent: ' + channel.agentId"></span>
+                        <span x-text="'Last seen: ' + timeAgo(channel.lastSeen)"></span>
+                      </div>
+                    </div>
+                    <button class="btn btn-sm btn-ghost-secondary p-1" title="Show agent" @click="openAgentDetail(agentsById[channel.agentId])">
+                      <i class="ti ti-robot"></i>
+                    </button>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </template>
+        </div>
+
+        <template x-if="channelCards.length === 0">
+          <div class="card">
+            <div class="card-body text-center text-secondary py-5">
+              <i class="ti ti-message-off" style="font-size:48px; opacity:0.3"></i>
+              <p class="mt-2">No channels registered</p>
+            </div>
+          </div>
+        </template>
+      </div>
+
+      <!-- ==================== INTEGRATIONS ==================== -->
+      <div x-show="view === 'integrations'" x-cloak class="fade-in">
+        <div class="d-flex align-items-center mb-3 gap-2 flex-wrap">
+          <h2 class="page-title mb-0">Integrations</h2>
+          <span class="badge bg-warning-lt" x-show="integrationCards.some((item) => (item.taskStats?.waitingTasks || 0) > 0)" x-text="integrationCards.reduce((total, item) => total + (item.taskStats?.waitingTasks || 0), 0) + ' waiting'"></span>
+          <div class="ms-auto d-flex gap-2 align-items-center">
+            <button class="btn btn-sm btn-ghost-secondary" @click="fetchIntegrations()">
+              <i class="ti ti-refresh"></i>
+            </button>
+          </div>
+        </div>
+
+        <div class="row g-3">
+          <template x-for="integration in integrationCards" :key="integration.name">
+            <div class="col-md-6 col-xl-4">
+              <div class="card">
+                <div class="card-body">
+                  <div class="d-flex align-items-start gap-2">
+                    <span class="agent-type-icon agent mt-0">
+                      <i class="ti" :class="integrationPresence(integration).icon"></i>
+                    </span>
+                    <div class="flex-grow-1 min-width-0">
+                      <div class="d-flex align-items-center gap-2">
+                        <span class="fw-bold text-truncate" x-text="integration.name"></span>
+                        <span class="badge" :class="'bg-' + integrationPresence(integration).tone + '-lt'">
+                          <i class="ti me-1" :class="integrationPresence(integration).icon"></i><span x-text="integrationPresence(integration).label"></span>
+                        </span>
+                      </div>
+                      <div class="d-flex gap-1 mt-2 flex-wrap">
+                        <span class="badge" :class="integration.configured ? 'bg-success-lt' : 'bg-secondary-lt'" x-text="integration.configured ? 'configured' : 'not configured'"></span>
+                        <span class="badge" :class="integration.observed ? 'bg-info-lt' : 'bg-secondary-lt'" x-text="integration.observed ? 'observed' : 'no tasks'"></span>
+                        <span class="badge" :class="integration.callbackConfigured ? 'bg-purple-lt' : 'bg-secondary-lt'" x-text="integration.callbackConfigured ? 'callback' : 'no callback'"></span>
+                      </div>
+                      <div class="row g-2 mt-2 text-center">
+                        <div class="col-3">
+                          <div class="text-secondary small">Tasks</div>
+                          <div class="h3 mb-0" x-text="integration.taskStats?.tasks || 0"></div>
+                        </div>
+                        <div class="col-3">
+                          <div class="text-secondary small">Open</div>
+                          <div class="h3 mb-0" x-text="integration.taskStats?.openTasks || 0"></div>
+                        </div>
+                        <div class="col-3">
+                          <div class="text-secondary small">Waiting</div>
+                          <div class="h3 mb-0" :class="(integration.taskStats?.waitingTasks || 0) ? 'text-warning' : ''" x-text="integration.taskStats?.waitingTasks || 0"></div>
+                        </div>
+                        <div class="col-3">
+                          <div class="text-secondary small">Failed</div>
+                          <div class="h3 mb-0" :class="(integration.taskStats?.failedTasks || 0) ? 'text-danger' : ''" x-text="integration.taskStats?.failedTasks || 0"></div>
+                        </div>
+                      </div>
+                      <div class="d-flex gap-1 mt-2 flex-wrap" x-show="integration.scopes?.length">
+                        <template x-for="scope in (integration.scopes || [])" :key="scope">
+                          <span class="badge bg-secondary-lt" x-text="scope"></span>
+                        </template>
+                      </div>
+                      <div class="d-flex gap-1 mt-2 flex-wrap" x-show="integration.targets?.length || integration.channels?.length">
+                        <template x-for="target in (integration.targets || [])" :key="target">
+                          <span class="badge bg-cyan-lt" x-text="displayTarget(target)"></span>
+                        </template>
+                        <template x-for="channel in (integration.channels || [])" :key="channel">
+                          <span class="badge bg-warning-lt" x-text="'#' + channel"></span>
+                        </template>
+                      </div>
+                      <div class="text-secondary small mt-2 d-flex gap-2 flex-wrap">
+                        <span x-show="integration.taskStats?.lastSeenAt" x-text="'Last task: ' + timeAgo(integration.taskStats?.lastSeenAt)"></span>
+                        <span x-show="integration.callbackHost" x-text="integration.callbackHost"></span>
+                        <span x-text="'Rate: ' + (integration.rateLimit?.currentWindowCount || 0) + '/' + (integration.rateLimit?.limitPerMinute || 0) + ' min'"></span>
+                      </div>
+                    </div>
+                    <button class="btn btn-sm btn-ghost-secondary p-1" title="Show tasks" @click="taskSourceFilter = integration.name; taskStatusFilter = ''; switchView('tasks')">
+                      <i class="ti ti-list-details"></i>
+                    </button>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </template>
+        </div>
+
+        <template x-if="integrationCards.length === 0">
+          <div class="card">
+            <div class="card-body text-center text-secondary py-5">
+              <i class="ti ti-plug-off" style="font-size:48px; opacity:0.3"></i>
+              <p class="mt-2">No integrations configured or observed</p>
+            </div>
+          </div>
+        </template>
+      </div>
+
       <!-- ==================== INBOX ==================== -->
       <div x-show="view === 'inbox'" x-cloak class="fade-in">
         <div class="d-flex align-items-center mb-3 gap-2 flex-wrap">

package/src/db.ts

@@ -23,6 +23,7 @@ import type {
   TaskSeverity,
   TaskStatus,
   IntegrationEventInput,
+  IntegrationTaskStats,
   InboxDraft,
   InboxState,
   InboxThreadState,
@@ -856,6 +857,32 @@ export function listTasks(filter?: { status?: string; source?: string; target?:
   return (db.prepare(`${TASK_SELECT} ${where} ORDER BY updated_at DESC LIMIT ?`).all(...params) as any[]).map(rowToTask);
 }
 
+export function listIntegrationTaskStats(): IntegrationTaskStats[] {
+  const rows = db.prepare(`
+    SELECT
+      source,
+      COUNT(*) AS tasks,
+      SUM(CASE WHEN status NOT IN ('done', 'failed', 'canceled') THEN 1 ELSE 0 END) AS open_tasks,
+      SUM(CASE WHEN status IN ('open', 'blocked') AND claimed_by IS NULL THEN 1 ELSE 0 END) AS waiting_tasks,
+      SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS failed_tasks,
+      MAX(last_seen_at) AS last_seen_at,
+      MAX(updated_at) AS last_updated_at
+    FROM tasks
+    GROUP BY source
+    ORDER BY last_seen_at DESC, source ASC
+  `).all() as any[];
+
+  return rows.map((row) => ({
+    source: row.source,
+    tasks: Number(row.tasks ?? 0),
+    openTasks: Number(row.open_tasks ?? 0),
+    waitingTasks: Number(row.waiting_tasks ?? 0),
+    failedTasks: Number(row.failed_tasks ?? 0),
+    lastSeenAt: row.last_seen_at ?? undefined,
+    lastUpdatedAt: row.last_updated_at ?? undefined,
+  }));
+}
+
 export function listTaskEvents(taskId: number): TaskEvent[] {
   return (db.prepare("SELECT * FROM task_events WHERE task_id = ? ORDER BY id ASC").all(taskId) as any[]).map(rowToTaskEvent);
 }

package/src/routes.ts

@@ -24,6 +24,7 @@ import {
   ingestIntegrationEvent,
   listTasks,
   getTask,
+  listIntegrationTaskStats,
   listTaskEvents,
   claimTask,
   renewTaskClaim,
@@ -49,7 +50,7 @@ import {
   validateAgentSession,
   ValidationError,
 } from "./db";
-import type { ActivityEventInput, ActivityKind, AgentSessionGuard, CreatePairInput, IntegrationEventInput, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, SendMessageInput, TaskStatus, TaskStatusInput } from "./types";
+import type { ActivityEventInput, ActivityKind, AgentCard, AgentSessionGuard, ChannelDirection, ChannelSummary, CreatePairInput, IntegrationEventInput, IntegrationSummary, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, SendMessageInput, TaskStatus, TaskStatusInput } from "./types";
 import { getIntegrationTokens, INTEGRATION_RATE_LIMIT_PER_MINUTE, MAX_BODY_BYTES } from "./config";
 import {
   getIntegrationAuth,
@@ -481,6 +482,61 @@ function checkIntegrationRateLimit(name: string): boolean {
   return bucket.count <= INTEGRATION_RATE_LIMIT_PER_MINUTE;
 }
 
+function safeCallbackHost(url: string | undefined): string | undefined {
+  if (!url) return undefined;
+  try {
+    return new URL(url).host;
+  } catch {
+    return undefined;
+  }
+}
+
+function metaString(meta: Record<string, unknown> | undefined, key: string): string | undefined {
+  const value = meta?.[key];
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function metaStringArray(meta: Record<string, unknown> | undefined, key: string): string[] {
+  const value = meta?.[key];
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.trim().length > 0) : [];
+}
+
+function metaDirection(meta: Record<string, unknown> | undefined): ChannelDirection {
+  const value = metaString(meta, "direction");
+  return value === "inbound" || value === "outbound" || value === "bidirectional" ? value : "bidirectional";
+}
+
+function isChannelAgent(agent: AgentCard): boolean {
+  const kind = metaString(agent.meta, "kind");
+  return kind === "channel" ||
+    kind === "communication-channel" ||
+    agent.tags.includes("channel") ||
+    agent.capabilities.includes("channel");
+}
+
+function agentToChannel(agent: AgentCard): ChannelSummary {
+  const type = metaString(agent.meta, "channelType") ?? metaString(agent.meta, "type") ?? agent.tags.find((tag) => tag.startsWith("channel:"))?.slice("channel:".length) ?? "custom";
+  const transport = metaString(agent.meta, "transport") ?? type;
+  const topicChannels = metaStringArray(agent.meta, "topicChannels");
+
+  return {
+    id: metaString(agent.meta, "channelId") ?? agent.id,
+    name: metaString(agent.meta, "displayName") ?? agent.name,
+    type,
+    transport,
+    agentId: agent.id,
+    status: agent.status,
+    ready: agent.ready,
+    direction: metaDirection(agent.meta),
+    target: metaString(agent.meta, "target"),
+    topicChannels,
+    capabilities: agent.capabilities,
+    tags: agent.tags,
+    lastSeen: agent.lastSeen,
+    meta: agent.meta,
+  };
+}
+
 async function dispatchTaskCallbacks(taskId: number, eventType: string): Promise<void> {
   const task = getTask(taskId);
   if (!task) return;
@@ -956,6 +1012,58 @@ const postActivityEvent: Handler = async (req) => {
 
 // --- Tasks and integrations ---
 
+const getIntegrations: Handler = () => {
+  const configured = new Map(getIntegrationTokens().map((integration) => [integration.name, integration]));
+  const observedStats = new Map(listIntegrationTaskStats().map((stats) => [stats.source, stats]));
+  const names = [...new Set([...configured.keys(), ...observedStats.keys()])].sort((a, b) => a.localeCompare(b));
+  const now = Date.now();
+
+  const integrations: IntegrationSummary[] = names.map((name) => {
+    const config = configured.get(name);
+    const taskStats = observedStats.get(name) ?? {
+      source: name,
+      tasks: 0,
+      openTasks: 0,
+      waitingTasks: 0,
+      failedTasks: 0,
+    };
+    const bucket = integrationRateBuckets.get(name);
+    const bucketCurrent = Boolean(bucket && now - bucket.windowStart < 60_000);
+
+    return {
+      name,
+      configured: Boolean(config),
+      observed: observedStats.has(name),
+      scopes: config?.scopes ?? [],
+      targets: config?.targets ?? [],
+      channels: config?.channels ?? [],
+      callbackHost: safeCallbackHost(config?.callbackUrl),
+      callbackConfigured: Boolean(config?.callbackUrl),
+      rateLimit: {
+        limitPerMinute: INTEGRATION_RATE_LIMIT_PER_MINUTE,
+        currentWindowCount: bucketCurrent ? bucket!.count : 0,
+        windowStartedAt: bucketCurrent ? bucket!.windowStart : undefined,
+      },
+      taskStats,
+    };
+  });
+
+  return json(integrations);
+};
+
+const getChannels: Handler = () => {
+  const channels = listAgents()
+    .filter(isChannelAgent)
+    .map(agentToChannel)
+    .sort((a, b) => {
+      const readyDiff = Number(b.ready) - Number(a.ready);
+      if (readyDiff !== 0) return readyDiff;
+      return a.name.localeCompare(b.name);
+    });
+
+  return json(channels);
+};
+
 const postIntegrationEvent: Handler = async (req) => {
   const auth = getIntegrationAuth(req);
   if (!auth) return error("integration token required", 401);
@@ -1333,6 +1441,8 @@ const routes: Route[] = [
   route("GET", "/api/activity", getActivityEvents),
   route("POST", "/api/activity", postActivityEvent),
 
+  route("GET", "/api/channels", getChannels),
+  route("GET", "/api/integrations", getIntegrations),
   route("POST", "/api/integrations/events", postIntegrationEvent),
   route("GET", "/api/tasks", getTasks),
   route("GET", "/api/tasks/:id", getTaskById),

package/src/security.ts

@@ -95,7 +95,8 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname === "/api/stats") return "stats:read";
   if (pathname === "/api/health") return "health:read";
   if (pathname === "/api/events") return "events:read";
-  if (pathname.startsWith("/api/integrations/")) return method === "GET" ? "integrations:read" : "integrations:write";
+  if (pathname === "/api/channels") return "channels:read";
+  if (pathname === "/api/integrations" || pathname.startsWith("/api/integrations/")) return method === "GET" ? "integrations:read" : "integrations:write";
   if (pathname.startsWith("/api/agents")) return method === "GET" ? "agents:read" : "agents:write";
   if (pathname.startsWith("/api/activity")) return method === "GET" ? "activity:read" : "activity:write";
   if (pathname.startsWith("/api/inbox")) return method === "GET" ? "messages:read" : "messages:write";
@@ -110,7 +111,7 @@ export function isScopedRequestAuthorized(req: Request): boolean {
   const auth = getIntegrationAuth(req);
   if (!auth) return false;
   const pathname = new URL(req.url).pathname;
-  if (pathname.startsWith("/api/integrations/") && req.method !== "GET") {
+  if ((pathname === "/api/integrations" || pathname.startsWith("/api/integrations/")) && req.method !== "GET") {
     return hasIntegrationScope(auth, "integrations:write") ||
       hasIntegrationScope(auth, "tasks:create") ||
       hasIntegrationScope(auth, "events:create");

package/src/types.ts

@@ -174,6 +174,52 @@ export interface IntegrationEventInput {
   metadata?: Record<string, unknown>;
 }
 
+export interface IntegrationTaskStats {
+  source: string;
+  tasks: number;
+  openTasks: number;
+  waitingTasks: number;
+  failedTasks: number;
+  lastSeenAt?: number;
+  lastUpdatedAt?: number;
+}
+
+export interface IntegrationSummary {
+  name: string;
+  configured: boolean;
+  observed: boolean;
+  scopes: string[];
+  targets: string[];
+  channels: string[];
+  callbackHost?: string;
+  callbackConfigured: boolean;
+  rateLimit: {
+    limitPerMinute: number;
+    currentWindowCount: number;
+    windowStartedAt?: number;
+  };
+  taskStats: IntegrationTaskStats;
+}
+
+export type ChannelDirection = "inbound" | "outbound" | "bidirectional";
+
+export interface ChannelSummary {
+  id: string;
+  name: string;
+  type: string;
+  transport: string;
+  agentId: string;
+  status: AgentCard["status"];
+  ready: boolean;
+  direction: ChannelDirection;
+  target?: string;
+  topicChannels: string[];
+  capabilities: string[];
+  tags: string[];
+  lastSeen: number;
+  meta?: Record<string, unknown>;
+}
+
 export interface TaskStatusInput {
   status: TaskStatus;
   agentId?: string;