@desplega.ai/agent-swarm 1.172.0 → 2.0.0

package/src/extensions/contract.ts

@@ -181,6 +181,32 @@ export interface SlackRouteModify {
   target: { kind: "agent"; agentId: string } | { kind: "lead" } | { kind: "broadcast" };
 }
 
+/** A Chat SDK message after its thread buffer flushed, before routing. */
+export interface ChatRouteEvent {
+  /** Adapter name, such as `telegram` or `slack`. */
+  adapter: string;
+  channelId: string;
+  /** The Chat SDK thread id, prefixed with the adapter name. */
+  threadId: string;
+  /** The first buffered sender. */
+  userId: string;
+  userName?: string;
+  /** The buffered messages, joined. */
+  text: string;
+  botMentioned: boolean;
+  isDirectMessage: boolean;
+  /** Set when earlier swarm tasks exist in this thread. */
+  threadContext?: { adapter: string; threadId: string };
+}
+
+export interface ChatRouteModify {
+  target:
+    | { kind: "agent"; agentId: string }
+    | { kind: "lead" }
+    | { kind: "broadcast" }
+    | { kind: "workflow"; workflowId: string };
+}
+
 export type HeartbeatClassification = "no-session" | "stale-session" | "fresh-stalled";
 export type HeartbeatAction = "supersede-resume" | "fail" | "record";
 
@@ -236,6 +262,19 @@ export interface SlackMessageEvent {
   taskId?: string;
 }
 
+/** A Chat SDK message the swarm received or sent. */
+export interface ChatMessageEvent {
+  adapter: string;
+  channelId: string;
+  threadId: string;
+  /** The sender, for an inbound message. */
+  userId?: string;
+  text: string;
+  direction: "inbound" | "outbound";
+  taskId?: string;
+  messageId?: string;
+}
+
 /**
  * A person answered an approval request. Fires for workflow and standalone
  * requests. Timeouts and cancellations do not emit it today.
@@ -352,6 +391,11 @@ export interface SwarmEventMap {
     modify: SlackRouteModify;
     result: PreResult<SlackRouteModify>;
   };
+  "pre.chat.route": {
+    event: ChatRouteEvent;
+    modify: ChatRouteModify;
+    result: PreResult<ChatRouteModify>;
+  };
   "pre.heartbeat.remediate": {
     event: HeartbeatRemediateEvent;
     modify: HeartbeatRemediateModify;
@@ -369,6 +413,7 @@ export interface SwarmEventMap {
   "post.task.superseded": { event: TaskSupersededEvent; modify: never; result: void };
   "post.task.progress": { event: TaskProgressEvent; modify: never; result: void };
   "post.slack.message": { event: SlackMessageEvent; modify: never; result: void };
+  "post.chat.message": { event: ChatMessageEvent; modify: never; result: void };
   "post.approval.resolved": { event: ApprovalResolvedEvent; modify: never; result: void };
   "post.task.budgetRefused": { event: TaskBudgetRefusedEvent; modify: never; result: void };
   "post.email.received": { event: EmailReceivedEvent; modify: never; result: void };

package/src/extensions/dispatcher.ts

@@ -171,6 +171,13 @@ export function runContext(event: keyof SwarmEventMap, payload: unknown): RunCon
     case "post.kapso.message":
       subject = `number ${stringField(payload, "phoneNumberId") ?? "?"}: message ${stringField(payload, "messageId") ?? "?"}`;
       break;
+    // Ids only: a chat message text is personal content.
+    case "pre.chat.route":
+    case "post.chat.message": {
+      const taskId = stringField(payload, "taskId");
+      subject = `${stringField(payload, "adapter") ?? "?"} thread ${stringField(payload, "threadId") ?? "?"}${taskId ? `: task ${taskId}` : ""}`;
+      break;
+    }
     case "post.vcs.event": {
       const number = field(payload, "number");
       subject = `${stringField(payload, "provider") ?? "?"} ${stringField(payload, "kind") ?? "?"}.${stringField(payload, "action") ?? "?"}: ${stringField(payload, "repo") ?? "?"}${typeof number === "number" ? `#${number}` : ""}`;

package/src/extensions/post-bridge.ts

@@ -3,6 +3,7 @@ import { scrubSecrets } from "../utils/secret-scrubber";
 import { workflowEventBus } from "../workflows/event-bus";
 import type {
   ApprovalResolvedEvent,
+  ChatMessageEvent,
   KapsoMessageEvent,
   TaskBudgetRefusedEvent,
   VcsEvent,
@@ -258,6 +259,41 @@ const onKapsoMessage = observed("kapso.message.received", async (data) => {
   );
 });
 
+/** `chat.message.received` and `chat.message.sent` carry the same fields; the name sets the direction. */
+function chatMessageBridge(eventName: string, direction: ChatMessageEvent["direction"]) {
+  return observed(eventName, async (data) => {
+    const source = (data ?? {}) as Record<string, unknown>;
+    const adapter = text(source.adapter);
+    const channelId = text(source.channelId);
+    const threadId = text(source.threadId);
+    const messageText = text(source.text);
+    if (
+      adapter === undefined ||
+      channelId === undefined ||
+      threadId === undefined ||
+      messageText === undefined
+    ) {
+      return;
+    }
+    await dispatchPost(
+      "post.chat.message",
+      compact<ChatMessageEvent>({
+        adapter,
+        channelId,
+        threadId,
+        userId: text(source.userId),
+        text: messageText,
+        direction,
+        taskId: text(source.taskId),
+        messageId: text(source.messageId),
+      }),
+    );
+  });
+}
+
+const onChatMessageReceived = chatMessageBridge("chat.message.received", "inbound");
+const onChatMessageSent = chatMessageBridge("chat.message.sent", "outbound");
+
 // The code-host events are named `<provider>.<kind>.<action>` and the last
 // segment is open-ended (`github.pull_request.<action>`, `gitlab.pipeline.<status>`),
 // so one prefix subscription per provider covers them all.
@@ -331,6 +367,8 @@ export function initExtensionPostBridge(): void {
   workflowEventBus.on("task.budget_refused", onTaskBudgetRefused);
   workflowEventBus.on("agentmail.message.received", onEmailReceived);
   workflowEventBus.on("kapso.message.received", onKapsoMessage);
+  workflowEventBus.on("chat.message.received", onChatMessageReceived);
+  workflowEventBus.on("chat.message.sent", onChatMessageSent);
   for (const prefix of VCS_PREFIXES) workflowEventBus.onPrefix(prefix, onVcsEvent);
 }
 
@@ -348,5 +386,7 @@ export function teardownExtensionPostBridge(): void {
   workflowEventBus.off("task.budget_refused", onTaskBudgetRefused);
   workflowEventBus.off("agentmail.message.received", onEmailReceived);
   workflowEventBus.off("kapso.message.received", onKapsoMessage);
+  workflowEventBus.off("chat.message.received", onChatMessageReceived);
+  workflowEventBus.off("chat.message.sent", onChatMessageSent);
   for (const prefix of VCS_PREFIXES) workflowEventBus.offPrefix(prefix, onVcsEvent);
 }

package/src/github/handlers.ts

@@ -877,20 +877,27 @@ export async function handleComment(
     comment.body.slice(0, 100),
   );
 
+  const skip = (reason: string) => {
+    console.log(
+      `[GitHub] Skipped ${eventType}.${action} by ${sender.login} on ${repository.full_name} comment ${comment.id}: ${reason}`,
+    );
+    return { created: false };
+  };
+
   // Only handle created action
   if (action !== "created") {
-    return { created: false };
+    return skip("action is not created");
   }
 
   // Check for @agent-swarm mention in comment
   if (!detectMention(comment.body)) {
-    return { created: false };
+    return skip("no bot mention");
   }
 
   // Deduplicate
   const eventKey = `comment:${repository.full_name}:${comment.id}`;
   if (isDuplicate(eventKey)) {
-    return { created: false };
+    return skip("duplicate delivery");
   }
 
   // Find lead agent (may be null - task will be unassigned)
@@ -932,7 +939,7 @@ export async function handleComment(
   );
 
   if (result.skipped) {
-    return { created: false };
+    return skip("github.comment.mentioned template is skipped");
   }
 
   // Create task (assigned to lead if available, otherwise unassigned)

package/src/heartbeat/templates.ts

@@ -11,15 +11,15 @@ import { registerTemplate } from "../prompts/registry";
 // Heartbeat checklist
 // ============================================================================
 
+// Standing orders and instructions come before the live status: they are
+// usually identical from one tick to the next, so they can form a cacheable
+// prefix of the task text, and the status that changes every tick goes last.
 registerTemplate({
   eventType: "heartbeat.checklist",
   header: "",
   defaultBody: `Task Type: Heartbeat Checklist
 Goal: Review system status and your standing orders, take action if needed.
 
-## Current System Status [auto-generated]
-{{system_status}}
-
 ## Your Standing Orders (snapshot from HEARTBEAT.md)
 {{heartbeat_content}}
 
@@ -29,7 +29,7 @@ Goal: Review system status and your standing orders, take action if needed.
 1. **Read your HEARTBEAT.md** — run \`read /workspace/HEARTBEAT.md\` to get the latest standing orders (the snapshot above may be slightly stale).
 2. **Prune tracked HEARTBEAT items FIRST.** Active Blockers + Watch Items + Open Discussion combined must stay at ≤10 items; 20 is the absolute max only when genuinely super busy. This cap does not apply to evergreen Standing Orders / Governance / Playbook-index reference sections. Before adding anything, re-check every tracked item against its lift trigger and remove anything resolved, stale, or past its trigger date. Lift incident detail to memory; never keep it inline in HEARTBEAT.md. Every new tracked item must include an explicit lift trigger + date; if it has no removal condition, do not add it. If the tracked list is already at/over cap, prune before (or instead of) adding — the cap is binding.
 3. **Run seeded heartbeat data-gathering.** Use \`script-run\` with the global scripts \`schedule-health\` and \`task-failure-audit\`, both with args \`{ "days": 1, "publishPage": false }\`. They report failing schedules and failure clusters. Check any other standing order in HEARTBEAT.md yourself. Scripts can read Slack too (\`ctx.swarm.slack_read\` or the seeded \`slack-thread-flatten\` script), so a recurring Slack check can be scripted.
-4. Review the system status above plus the script results for anything that needs attention (stalled tasks, idle workers with available work, anomalies).
+4. Review the system status below plus the script results for anything that needs attention (stalled tasks, idle workers with available work, anomalies).
 5. **CRITICAL — Reboot failure triage:** Failures with reason "worker session not found" or "worker session heartbeat is stale" indicate tasks that were INTERRUPTED by a server restart. These are NOT "expected auto-cleanup" — they represent work that was lost mid-execution. For each such failure:
    - Check what the task was (via \`get-task-details\` with the task ID from the failure)
    - If a retry task was auto-created (tagged \`reboot-retry\`), verify it is progressing
@@ -39,7 +39,10 @@ Goal: Review system status and your standing orders, take action if needed.
 7. If something needs attention — take action now using your available tools (create tasks, post to Slack, cancel stuck tasks, etc.).
 8. If everything looks healthy and no standing orders are actionable — complete this task with a brief "All clear" summary. You may NOT say "All clear" if reboot-related failures exist that haven't been triaged.
 9. Do NOT create another heartbeat-checklist task — the system handles scheduling.
-10. **Update HEARTBEAT.md only after pruning.** Keep it current, but keep tracked items capped: remove resolved items, add only dated lift-triggered items, and lift detail to memory instead of growing the file.`,
+10. **Update HEARTBEAT.md only after pruning.** Keep it current, but keep tracked items capped: remove resolved items, add only dated lift-triggered items, and lift detail to memory instead of growing the file.
+
+## Current System Status [auto-generated]
+{{system_status}}`,
   variables: [
     {
       name: "system_status",

package/src/hooks/hook.ts

@@ -1336,32 +1336,6 @@ export async function handleHook(): Promise<void> {
       break;
 
     case "Stop":
-      // Clean up any artifact tunnels managed by PM2
-      try {
-        const pm2ListOutput = await Bun.$`pm2 jlist 2>/dev/null || echo "[]"`.text();
-        const pm2Processes = JSON.parse(pm2ListOutput.trim());
-        const artifactProcesses = (pm2Processes as { name?: string }[]).filter((p) =>
-          p.name?.startsWith("artifact-"),
-        );
-
-        for (const proc of artifactProcesses) {
-          try {
-            await Bun.$`pm2 delete ${proc.name!}`.quiet();
-          } catch {
-            // Process might already be stopped
-          }
-        }
-      } catch {
-        // Non-fatal: PM2 might not be available
-      }
-
-      // Save PM2 processes before shutdown (for container restart persistence)
-      try {
-        await Bun.$`pm2 save`.quiet();
-      } catch {
-        // PM2 not available or no processes - silently ignore
-      }
-
       // Sync CLAUDE.md (then restore its backup), identity files, and setup script back to database
       if (agentInfo?.id) {
         try {

package/src/http/all-routes.ts

@@ -21,7 +21,6 @@ import "./config";
 import "./context";
 import "./core";
 import "./db-query";
-import "./ecosystem";
 
 import "./api-keys";
 import "./events";

package/src/http/config.ts

@@ -18,10 +18,12 @@ import { fillOrgLogoFromWebsite } from "../be/org-profile";
 import { getUserGrant } from "../be/rbac-roles";
 import {
   internalConfigKeyError,
+  isApiOnlyConfigKey,
   isInternalConfigKey,
   isReservedConfigKey,
   reservedKeyError,
   validateConfigValue,
+  validateExportToEnv,
 } from "../be/swarm-config-guard";
 import { can, isRbacEnabled, type PermissionVerb } from "../rbac";
 import { SwarmConfigSchema } from "../types";
@@ -35,16 +37,9 @@ const MAX_ENV_PRESENCE_KEYS = 200;
 const SECRETS_FORCE_MASK_NOTE =
   " (secret values masked: this token cannot read secrets in this scope)";
 
-// Config keys the API server owns for its own use and must NEVER hand out over
-// HTTP — workers/entrypoints read config to build their env, and the agent-fs
-// bootstrap admin key would let a compromised worker administer the shared org.
-// The API materializes these into its own process.env at boot via
-// getInjectableGlobalConfigs, so no HTTP consumer legitimately needs them.
-const API_ONLY_CONFIG_KEYS = new Set(["API_AGENT_FS_API_KEY", "SLACK_SIGNING_SECRET"]);
-
 function stripApiOnlyKeys<T extends { key: string }>(configs: T[]): T[] {
   return configs.filter(
-    (config) => !API_ONLY_CONFIG_KEYS.has(config.key) && !isInternalConfigKey(config.key),
+    (config) => !isApiOnlyConfigKey(config.key) && !isInternalConfigKey(config.key),
   );
 }
 
@@ -116,6 +111,28 @@ export async function ensureConfigAdmin(
   req: IncomingMessage,
   res: ServerResponse,
   verb: Extract<PermissionVerb, "config.write.any" | "config.delete.any">,
+): Promise<boolean> {
+  return ensureHttpPermission(
+    req,
+    res,
+    verb,
+    verb === "config.write.any"
+      ? "Writing swarm config requires the lead agent"
+      : "Deleting swarm config requires the lead agent",
+  );
+}
+
+/**
+ * The general form of `ensureConfigAdmin`: operators and users pass, guests
+ * get a plain 403, and an agent principal (session identity first, then the
+ * legacy X-Agent-ID header) must hold `verb`. On denial it writes a 403 with
+ * `forbiddenMessage` and returns false.
+ */
+export async function ensureHttpPermission(
+  req: IncomingMessage,
+  res: ServerResponse,
+  verb: PermissionVerb,
+  forbiddenMessage: string,
 ): Promise<boolean> {
   const auth = getRequestAuth(req);
   if (auth?.kind === "operator" || auth?.kind === "user") return true;
@@ -132,13 +149,7 @@ export async function ensureConfigAdmin(
     source: "http",
   });
   if (!decision.allow) {
-    jsonError(
-      res,
-      verb === "config.write.any"
-        ? "Writing swarm config requires the lead agent"
-        : "Deleting swarm config requires the lead agent",
-      403,
-    );
+    jsonError(res, forbiddenMessage, 403);
     return false;
   }
   return true;
@@ -276,6 +287,12 @@ const upsertConfig = route({
     isSecret: z.boolean().optional(),
     envPath: z.string().nullish(),
     description: z.string().nullish(),
+    exportToEnv: z
+      .boolean()
+      .optional()
+      .describe(
+        "Export this row into agent process env (default true on create, false for a few server-side secrets; omitted on update keeps the stored flag). Rejected as true for keys only the API server reads.",
+      ),
   }),
   responses: {
     200: { description: "Config entry upserted", schema: SwarmConfigSchema },
@@ -442,7 +459,7 @@ export async function handleConfig(
     const parsed = await upsertConfig.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     if (!(await ensureConfigAdmin(req, res, "config.write.any"))) return true;
-    const { scope, scopeId, key, value, isSecret, envPath, description } = parsed.body;
+    const { scope, scopeId, key, value, isSecret, envPath, description, exportToEnv } = parsed.body;
 
     if (scope === "global" && scopeId) {
       jsonError(res, "Global scope must not have scopeId", 400);
@@ -464,7 +481,8 @@ export async function handleConfig(
       return true;
     }
 
-    const validationError = validateConfigValue(key, value);
+    const validationError =
+      validateConfigValue(key, value) ?? validateExportToEnv(key, exportToEnv);
     if (validationError) {
       jsonError(res, validationError, 400);
       return true;
@@ -480,6 +498,7 @@ export async function handleConfig(
         isSecret: isSecret || false,
         envPath: envPath || null,
         description: description || null,
+        exportToEnv,
       });
       // Auto-reload integrations when a global-scoped config changes so callers
       // (CLI, automation, dashboard) don't have to remember to hit /reload.

package/src/http/core.ts

@@ -29,6 +29,7 @@ import { getUserGrant } from "../be/rbac-roles";
 import { syncTelemetryEnabled } from "../be/telemetry-enable";
 import { initGitHub, resetGitHub } from "../github";
 import { initGitLab, isGitLabEnabled, resetGitLab } from "../gitlab";
+import { restartChatSdkIfConfigChanged } from "../integrations/chat-sdk/runtime";
 import { initJira, resetJira } from "../jira";
 import { initLinear, resetLinear } from "../linear";
 import { can, decideAdmission, isRbacEnabled } from "../rbac";
@@ -243,6 +244,9 @@ async function reloadGlobalConfigsAndIntegrationsInner(): Promise<ReloadConfigRe
 
   if (await startSlackApp()) integrations.push("slack");
 
+  // After Slack: the Chat SDK Slack clash check reads SLACK_DISABLE.
+  if (await restartChatSdkIfConfigChanged()) integrations.push("chat-sdk");
+
   return {
     configsLoaded: updated.length,
     keysUpdated: updated,

package/src/http/index.ts

@@ -41,6 +41,7 @@ import {
 import { initGitHub } from "../github";
 import { initGitLab } from "../gitlab";
 import { stopHeartbeat } from "../heartbeat";
+import { startChatSdk, stopChatSdk } from "../integrations/chat-sdk/runtime";
 import { initJira } from "../jira";
 import { initLinear } from "../linear";
 import {
@@ -81,7 +82,6 @@ import { handleConfig } from "./config";
 import { handleContext } from "./context";
 import { handleCore, loadGlobalConfigsIntoEnv } from "./core";
 import { handleDbQuery } from "./db-query";
-import { handleEcosystem } from "./ecosystem";
 import { handleEvents } from "./events";
 import { handleExtensions } from "./extensions";
 import { handleFavorites } from "./favorites";
@@ -345,7 +345,6 @@ const httpServer = createHttpServer(async (req, res) => {
         () => handleAgentRegister(req, res, pathSegments, myAgentId),
         () => handlePoll(req, res, pathSegments, queryParams, myAgentId),
         () => handleSessionData(req, res, pathSegments, queryParams, myAgentId),
-        () => handleEcosystem(req, res, pathSegments, myAgentId),
         () => handleTrackers(req, res, pathSegments),
         () => handleWebhooks(req, res, pathSegments),
         () => handleAgentsRest(req, res, pathSegments, queryParams, myAgentId),
@@ -503,6 +502,9 @@ async function shutdown() {
   // Stop Slack bot
   await stopSlackApp();
 
+  // Stop Chat SDK adapters and drain their background handlers before the DB closes
+  await stopChatSdk();
+
   // Stop OAuth keepalive
   if (process.env.OAUTH_KEEPALIVE_DISABLE !== "true") {
     const { stopOAuthKeepalive } = await import("../oauth/keepalive");
@@ -762,6 +764,16 @@ httpServer
       console.error("[Slack] Failed to start, continuing boot without Slack:", err);
     }
 
+    // Chat SDK channel: never the boot path, so not awaited. Adapter init
+    // makes network calls (Slack's auth.test retries for up to ~30 min), and
+    // the scheduler, heartbeat and supervisor below must start regardless.
+    void startChatSdk().catch((err: unknown) => {
+      console.error(
+        "[chat-sdk] Failed to start, continuing without Chat SDK:",
+        scrubSecrets(err instanceof Error ? err.message : String(err)),
+      );
+    });
+
     // Independent of workers, scheduler targets, and heartbeat agent tasks.
     startQueueStallAlarm();
 

package/src/http/integrations.ts

@@ -1,9 +1,17 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import Anthropic from "@anthropic-ai/sdk";
 import { z } from "zod";
+import {
+  ChatSdkActionError,
+  ChatSdkStatusSchema,
+  getChatSdkStatus,
+  registerTelegramWebhook,
+} from "../integrations/chat-sdk/status";
 import { buildSlackManifest } from "../slack/manifest";
+import { ensureHttpPermission } from "./config";
 import { resolveConfigValue, resolveMcpBaseUrl } from "./config-values";
 import { route } from "./route-def";
+import { jsonError } from "./utils";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -48,6 +56,20 @@ const McpUserConfigSchema = z.object({
 
 const SlackManifestSchema = z.record(z.string(), z.unknown());
 
+const TelegramRegisterWebhookSchema = z.object({
+  webhookUrl: z.string(),
+  webhookInfo: z.looseObject({
+    url: z.string(),
+    has_custom_certificate: z.boolean().optional(),
+    pending_update_count: z.number().optional(),
+    last_error_date: z.number().optional(),
+    last_error_message: z.string().optional(),
+    max_connections: z.number().optional(),
+    ip_address: z.string().optional(),
+    allowed_updates: z.array(z.string()).optional(),
+  }),
+});
+
 // ─── Route Definition ────────────────────────────────────────────────────────
 
 const claudeManagedTestRoute = route({
@@ -94,7 +116,38 @@ const slackManifestRoute = route({
   },
 });
 
-// ─── Helpers ─────────────────────────────────────────────────────────────────
+const chatSdkStatusRoute = route({
+  method: "get",
+  path: "/api/integrations/chat/status",
+  pattern: ["api", "integrations", "chat", "status"],
+  summary:
+    "Chat SDK channel status: enabled flag, Slack clash, per-adapter health and webhook URL.",
+  tags: ["Integrations"],
+  responses: {
+    200: {
+      description:
+        "Per-adapter status. `health` is `disabled` for an adapter that is not running. Never contains secret values.",
+      schema: ChatSdkStatusSchema,
+    },
+  },
+});
+
+const chatSdkTelegramRegisterWebhookRoute = route({
+  method: "post",
+  path: "/api/integrations/chat/telegram/register-webhook",
+  pattern: ["api", "integrations", "chat", "telegram", "register-webhook"],
+  summary:
+    "Register this swarm's public Telegram webhook URL and secret token with the Bot API (setWebhook), then return getWebhookInfo.",
+  tags: ["Integrations"],
+  body: z.object({}).optional(),
+  responses: {
+    200: { description: "Webhook registered", schema: TelegramRegisterWebhookSchema },
+    400: { description: "Telegram is not configured for webhook mode" },
+    403: { description: "Only the lead agent or a dashboard user can register the webhook" },
+    502: { description: "The Telegram Bot API rejected the call" },
+  },
+  rbac: { permission: "integration.chat.manage" },
+});
 
 // ─── Public handler factory ──────────────────────────────────────────────────
 
@@ -122,6 +175,40 @@ export function createIntegrationsHandler(deps: TestConnectionDeps = {}) {
       return true;
     }
 
+    if (chatSdkStatusRoute.match(req.method, pathSegments)) {
+      chatSdkStatusRoute.respond(res, 200, await getChatSdkStatus());
+      return true;
+    }
+
+    if (chatSdkTelegramRegisterWebhookRoute.match(req.method, pathSegments)) {
+      const parsed = await chatSdkTelegramRegisterWebhookRoute.parse(
+        req,
+        res,
+        pathSegments,
+        queryParams,
+      );
+      if (!parsed) return true;
+      // Operators and dashboard users pass; agents need the verb (lead-only
+      // under the legacy policy).
+      if (
+        !(await ensureHttpPermission(
+          req,
+          res,
+          "integration.chat.manage",
+          "Registering the Telegram webhook requires the lead agent",
+        ))
+      ) {
+        return true;
+      }
+      try {
+        chatSdkTelegramRegisterWebhookRoute.respond(res, 200, await registerTelegramWebhook());
+      } catch (error) {
+        if (!(error instanceof ChatSdkActionError)) throw error;
+        jsonError(res, error.message, error.status);
+      }
+      return true;
+    }
+
     if (mcpUserConfigRoute.match(req.method, pathSegments)) {
       const mcpBaseUrl = await resolveMcpBaseUrl();
       mcpUserConfigRoute.respond(res, 200, { mcpBaseUrl, mcpUserUrl: `${mcpBaseUrl}/mcp-user` });

package/src/http/mcp-oauth.ts

@@ -24,6 +24,7 @@ import {
   discoverProtectedResourceMetadata,
   exchangeCodeForTokens,
   isInvalidClientError,
+  mcpOAuthSsrfOptions,
   normalizeTokenEndpointAuthMethod,
   refreshMcpToken,
   registerClient,
@@ -33,19 +34,11 @@ import {
 } from "../oauth/mcp-wrapper";
 import { McpAuthMethodSchema } from "../types";
 import { getAppUrl, getPublicMcpBaseUrl } from "../utils/constants";
-import { isEnvFlagEnabled } from "../utils/env-flag";
 import { route } from "./route-def";
 import { jsonError } from "./utils";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-function ssrfOptions() {
-  return {
-    allowPrivateHosts: isEnvFlagEnabled("MCP_OAUTH_ALLOW_PRIVATE_HOSTS", false),
-    allowInsecure: process.env.NODE_ENV !== "production",
-  };
-}
-
 function callbackRedirectUri(): string {
   // The callback route lives on the API server, so it must use the PUBLIC MCP
   // base (externally reachable), not the dashboard APP_URL.
@@ -165,10 +158,10 @@ function manualClientFromToken(token: McpOAuthToken | null): OAuthClientForAutho
 
   // The manual-client route validates these on write. Re-check before using the
   // stored endpoints because /authorize redirects the browser to authorizeUrl.
-  assertUrlSafe(token.resourceUrl, ssrfOptions());
-  assertUrlSafe(token.authorizeUrl, ssrfOptions());
-  assertUrlSafe(token.tokenUrl, ssrfOptions());
-  if (token.revocationUrl) assertUrlSafe(token.revocationUrl, ssrfOptions());
+  assertUrlSafe(token.resourceUrl, mcpOAuthSsrfOptions());
+  assertUrlSafe(token.authorizeUrl, mcpOAuthSsrfOptions());
+  assertUrlSafe(token.tokenUrl, mcpOAuthSsrfOptions());
+  if (token.revocationUrl) assertUrlSafe(token.revocationUrl, mcpOAuthSsrfOptions());
 
   return {
     clientId: token.dcrClientId,
@@ -184,7 +177,7 @@ function manualClientFromToken(token: McpOAuthToken | null): OAuthClientForAutho
 }
 
 async function discoverForMcp(resourceUrl: string): Promise<DiscoveryResult | null> {
-  assertUrlSafe(resourceUrl, ssrfOptions());
+  assertUrlSafe(resourceUrl, mcpOAuthSsrfOptions());
 
   const prmd = await discoverProtectedResourceMetadata(resourceUrl);
   if (!prmd) return null;