@desplega.ai/agent-swarm 2.5.1 → 2.5.3

package/src/integrations/chat-sdk/reactions.ts

@@ -0,0 +1,107 @@
+import { getKv } from "@/be/db";
+import type { ReactionEvent } from "@/integrations/reaction-events";
+import { scrubSecrets } from "@/utils/secret-scrubber";
+import { errorMessage } from "./logger";
+import { chatChannelKey } from "./router";
+import { getChatInstance } from "./runtime";
+import { assertTrustedChatTarget } from "./teams-origin";
+
+/**
+ * Telegram reactions per lifecycle event. A bot may set only the emoji in the
+ * Bot API `ReactionTypeEmoji` list (https://core.telegram.org/bots/api#reactiontypeemoji),
+ * which has no ✅ or ❌. `✍` is U+270D with no variation selector, as listed.
+ * A bot sets one reaction per message, so each call replaces the previous one.
+ */
+export const TELEGRAM_REACTIONS: Record<ReactionEvent, string> = {
+  accepted: "👀",
+  buffered: "👀",
+  now: "⚡",
+  steered: "✍",
+  completed: "👍",
+  failed: "👎",
+};
+
+/** Adapters that show the task lifecycle as a reaction on the user's message. */
+const CHAT_REACTIONS: Readonly<Record<string, Record<ReactionEvent, string>>> = {
+  telegram: TELEGRAM_REACTIONS,
+};
+
+/** True when `adapter` shows the lifecycle as reactions instead of text acknowledgements. */
+export function chatAdapterReacts(adapter: string): boolean {
+  return adapter in CHAT_REACTIONS;
+}
+
+/**
+ * Set the reaction for `event` on one message. Best effort: an adapter without
+ * a reaction map is a no-op, and a platform error (Telegram answers
+ * `400 REACTION_INVALID` for an emoji a group admin disallowed) is logged and
+ * never thrown, so it cannot block delivery or fail the task.
+ */
+export async function setChatMessageReaction(
+  adapter: string,
+  threadId: string,
+  messageId: string,
+  event: ReactionEvent,
+): Promise<void> {
+  const emoji = CHAT_REACTIONS[adapter]?.[event];
+  if (!emoji) return;
+  try {
+    const target = getChatInstance(adapter)?.getAdapter(adapter);
+    if (!target) return;
+    assertTrustedChatTarget(threadId);
+    await target.addReaction(threadId, messageId, emoji);
+  } catch (error) {
+    console.warn(
+      scrubSecrets(
+        `[chat-sdk] Could not set the ${event} reaction on ${messageId} in ${threadId}: ${errorMessage(error)}`,
+      ),
+    );
+  }
+}
+
+/** Remove the bot's reaction from each message. Best effort, like {@link setChatMessageReaction}. */
+export async function clearChatMessageReactions(
+  adapter: string,
+  threadId: string,
+  messageIds: readonly string[],
+): Promise<void> {
+  if (!chatAdapterReacts(adapter) || messageIds.length === 0) return;
+  const target = getChatInstance(adapter)?.getAdapter(adapter);
+  if (!target) return;
+  for (const messageId of messageIds) {
+    try {
+      // Telegram clears the bot's whole reaction whatever emoji is named.
+      await target.removeReaction(threadId, messageId, TELEGRAM_REACTIONS.accepted);
+    } catch (error) {
+      console.warn(
+        scrubSecrets(
+          `[chat-sdk] Could not clear the reaction on ${messageId} in ${threadId}: ${errorMessage(error)}`,
+        ),
+      );
+    }
+  }
+}
+
+/** KV namespace of per-channel Chat SDK settings, keyed like the channel mappings. */
+export const CHAT_CHANNEL_SETTINGS_NAMESPACE = "integrations:chat:channel-settings";
+
+export interface ChatChannelSettings {
+  /** Also post the text steering acknowledgement on an adapter that reacts. */
+  textAcks?: boolean;
+}
+
+/**
+ * Whether a steering message gets a text acknowledgement. Adapters without
+ * reactions always get one; a reacting adapter only when its channel opts in.
+ */
+export async function wantsChatTextAck(adapter: string, channelId: string): Promise<boolean> {
+  if (!chatAdapterReacts(adapter)) return true;
+  try {
+    const row = await getKv(CHAT_CHANNEL_SETTINGS_NAMESPACE, chatChannelKey(adapter, channelId));
+    const settings = row?.value as ChatChannelSettings | null | undefined;
+    return typeof settings === "object" && settings !== null && settings.textAcks === true;
+  } catch (error) {
+    console.warn(`[chat-sdk] Could not read the channel settings: ${errorMessage(error)}`);
+    return false;
+  }
+}

package/src/integrations/chat-sdk/relay.ts

@@ -1,4 +1,5 @@
 import {
+  getAgentById,
   getPendingChatRelayTasks,
   giveUpStaleChatRelays,
   markChatRelayAttempted,
@@ -6,13 +7,17 @@ import {
   markChatRelayGivenUp,
   recordChatRelayError,
 } from "@/be/db";
+import { terminalReactionEvent } from "@/integrations/reaction-events";
 import { chatThreadOfContextKey } from "@/tasks/context-key";
 import type { AgentTask } from "@/types";
 import { scrubSecrets } from "@/utils/secret-scrubber";
 import { workflowEventBus } from "@/workflows/event-bus";
+import { shortId } from "./commands";
+import { chatMessageLimit, splitChatMessage } from "./limits";
 import { errorMessage } from "./logger";
 import { postChatMessage } from "./outbound";
 import { taskOutputChatFiles } from "./outbound-files";
+import { setChatMessageReaction } from "./reactions";
 import { getChatInstance, getChatSdkHealth } from "./runtime";
 import { sweepExpired } from "./state";
 import { stopTypingKeepalive } from "./typing";
@@ -33,14 +38,64 @@ const SWEEP_EVERY_N_TICKS = 20;
 /** Coalesce bursts of terminal-task events into one early tick. */
 const EARLY_TICK_DEBOUNCE_MS = 250;
 
-/** The text posted for a terminal task. Failed and cancelled tasks get a status line first. */
-export function formatChatRelayText(task: AgentTask): string {
+/**
+ * The first line of every relayed answer: the short task id `/status` shows
+ * and the agent's name, e.g. `#a3f2b1c9 · Coder`. Two answers in one chat stay
+ * apart even when the platform cannot show what they reply to.
+ */
+export function formatChatTaskTag(task: Pick<AgentTask, "id">, agentName?: string): string {
+  return agentName ? `#${shortId(task)} · ${agentName}` : `#${shortId(task)}`;
+}
+
+/** The task tag, an optional status line, and the answer itself. */
+function relayHeadAndBody(task: AgentTask, agentName?: string): { head: string; body: string } {
+  const tag = formatChatTaskTag(task, agentName);
   const body = (task.output || task.failureReason || "").trim();
-  if (task.status === "failed") return body ? `**Task failed.**\n\n${body}` : "**Task failed.**";
-  if (task.status === "cancelled") {
-    return body ? `**Task cancelled.**\n\n${body}` : "**Task cancelled.**";
+  if (task.status === "failed") return { head: `${tag}\n**Task failed.**`, body };
+  if (task.status === "cancelled") return { head: `${tag}\n**Task cancelled.**`, body };
+  return { head: tag, body: body || "Task completed." };
+}
+
+/** The text posted for a terminal task. Failed and cancelled tasks get a status line after the tag. */
+export function formatChatRelayText(task: AgentTask, agentName?: string): string {
+  const { head, body } = relayHeadAndBody(task, agentName);
+  return body ? `${head}\n\n${body}` : head;
+}
+
+/** On Telegram, an answer body longer than this is posted collapsed. */
+export const TELEGRAM_FOLD_CHARS = 1000;
+/** A first paragraph up to this long stays visible above the collapsed rest. */
+const FOLD_LEAD_MAX_CHARS = 280;
+/** Room for the `<details>` markup and separators around one folded piece. */
+const FOLD_MARKUP_CHARS = 80;
+
+/**
+ * The messages posted for a terminal task. On Telegram a long body goes into
+ * collapsed `<details>` blocks: Bot API 10.1 rich messages render them folded
+ * and parse the markdown inside. Each message gets its own block, so the
+ * length split never cuts the markup in two.
+ */
+export function formatChatRelayMessages(
+  task: AgentTask,
+  adapter: string,
+  agentName?: string,
+): string[] {
+  const { head, body } = relayHeadAndBody(task, agentName);
+  if (adapter !== "telegram" || body.length <= TELEGRAM_FOLD_CHARS) {
+    return [formatChatRelayText(task, agentName)];
   }
-  return body || "Task completed.";
+  const breakAt = body.indexOf("\n\n");
+  const lead = breakAt > 0 && breakAt <= FOLD_LEAD_MAX_CHARS ? body.slice(0, breakAt) : "";
+  const rest = lead ? body.slice(breakAt).trim() : body;
+  const top = lead ? `${head}\n\n${lead}` : head;
+  const room = chatMessageLimit(adapter) - top.length - FOLD_MARKUP_CHARS;
+  const pieces = splitChatMessage(rest, room);
+  return pieces.map((piece, index) => {
+    const label = lead ? "Rest of the answer" : "Full answer";
+    const summary = pieces.length > 1 ? `${label} (${index + 1}/${pieces.length})` : label;
+    const block = `<details><summary>${summary}</summary>\n\n${piece}\n\n</details>`;
+    return index === 0 ? `${top}\n\n${block}` : block;
+  });
 }
 
 /**
@@ -96,16 +151,29 @@ export async function processPendingChatRelays(
 
     if (!(await markChatRelayAttempted(task.id, now))) continue;
     try {
+      const agent = task.agentId ? await getAgentById(task.agentId) : null;
       await postChatMessage({
         adapter: target.adapter,
         threadId: target.threadId,
-        text: formatChatRelayText(task),
+        text: formatChatRelayMessages(task, target.adapter, agent?.name),
         taskId: task.id,
         files: await taskOutputChatFiles(task.id),
+        // The inbound message this task answers. A lead follow-up, resume or
+        // defer wake-up inherits it from its parent, so it answers the same ask.
+        replyToMessageId: task.mentionMessageId,
       });
       stopTypingKeepalive(target.threadId);
       await markChatRelayDelivered(task.id, now);
       console.log(`[chat-sdk] Relayed ${task.status} task ${task.id} to ${target.adapter}`);
+      // The ask's reaction ends with the answer. Never throws: delivery already landed.
+      if (task.mentionMessageId) {
+        await setChatMessageReaction(
+          target.adapter,
+          target.threadId,
+          task.mentionMessageId,
+          terminalReactionEvent(task.status),
+        );
+      }
     } catch (error) {
       const message = errorMessage(error);
       await recordChatRelayError(task.id, message, now);

package/src/integrations/chat-sdk/thread-buffer.ts

@@ -17,6 +17,8 @@ export interface ChatBufferedMessage {
   isDirectMessage: boolean;
   /** Why the message was taken; `none` when it is unaddressed. */
   addressed: ChatAddressedReason;
+  /** The message got the `accepted` reaction when it was buffered. */
+  reacted?: boolean;
   facts: ChatMessageFacts;
   attachments: Attachment[];
 }

package/src/integrations/reaction-events.ts

@@ -0,0 +1,20 @@
+import type { AgentTaskStatus } from "@/types";
+
+/**
+ * The task lifecycle a chat channel shows as a reaction on the user's message.
+ * Each channel maps these events to its own emoji: Slack in
+ * `src/slack/reaction-shortcode.ts`, Chat SDK adapters in
+ * `src/integrations/chat-sdk/reactions.ts`.
+ *
+ * - `accepted`: the swarm took the message.
+ * - `buffered`: the message joined a batch that is still waiting.
+ * - `now`: the message skipped the buffer (`!now`).
+ * - `steered`: the message went to a running task, or was queued for it.
+ * - `completed` / `failed`: the task that answers the message ended.
+ */
+export type ReactionEvent = "accepted" | "buffered" | "now" | "steered" | "completed" | "failed";
+
+/** The terminal event for an ended task: anything but `completed` shows as `failed`. */
+export function terminalReactionEvent(status: AgentTaskStatus): "completed" | "failed" {
+  return status === "completed" ? "completed" : "failed";
+}

package/src/providers/amp-adapter.ts

@@ -44,7 +44,7 @@ import type {
  * default; the image installs exactly this version and the per-task settings
  * set `amp.updates.mode: "disabled"`. Bump it deliberately, with a live run.
  */
-export const AMP_PACKAGE = "@ampcode/cli@0.0.1792670445-ge8d5b3";
+export const AMP_PACKAGE = "@ampcode/cli@0.0.1792756861-g6187a2";
 
 /** MCP server name. Amp exposes its tools as `agent_swarm` / `store_progress` (dashes become underscores). */
 const AMP_MCP_SERVER_NAME = "agent-swarm";

package/src/providers/dsh-adapter.ts

@@ -37,7 +37,7 @@ import type {
 } from "./types";
 
 // npm's `latest` is older and lacks the JSON/stdin contract used here.
-export const DSH_PACKAGE = "@deepseek-ai/dsh@0.2.1-rc.2";
+export const DSH_PACKAGE = "@deepseek-ai/dsh@0.2.1-rc.3";
 
 export function checkDshCredentials(env: Record<string, string | undefined>): CredStatus {
   return env.DEEPSEEK_API_KEY?.trim() || env.OPENROUTER_API_KEY?.trim()

package/src/rbac/legacy-policy.ts

@@ -351,6 +351,7 @@ export const LEGACY_POLICY = {
   "script.api.update": leadOnly,
   "script.api.rotate": leadOnly,
   "script.api.delete": leadOnly,
+  "schedule.deferral.update.any": leadOrResourceOwner,
   // Pool writes pick the image that receives a runtime token, so only humans
   // may make them. The lead may only place agents into operator-made pools.
   "runtime_pool.write": operatorOrUser,
@@ -358,6 +359,8 @@ export const LEGACY_POLICY = {
   "runtime_controller.write": operatorOrUser,
   // A worker token stands in for the swarm API key on a worker, so only humans mint it.
   "agent.token.manage": operatorOrUser,
+  // Agents never change human roles.
+  "user.role.manage": operatorOrUser,
   "extension.write": extensionWrite,
   "extension.activate": extensionActivation,
   "extension.install.inline": leadOrOperatorOrUser,

package/src/rbac/permissions.ts

@@ -37,6 +37,10 @@ export const PERMISSIONS = {
     description: "Mint, rotate, or revoke an agent-bound worker token.",
     namespace: "agent",
   },
+  "user.role.manage": {
+    description: "Assign or remove a person's RBAC roles.",
+    namespace: "user",
+  },
   "task.cancel.any": {
     description: "Cancel any task (beyond tasks the caller created).",
     namespace: "task",
@@ -354,6 +358,10 @@ export const PERMISSIONS = {
     description: "Delete an external script API endpoint.",
     namespace: "script",
   },
+  "schedule.deferral.update.any": {
+    description: "Change a defer-task schedule the caller did not create.",
+    namespace: "schedule",
+  },
   "runtime_pool.write": {
     description: "Create, update, or delete runtime pools (image, provider kind, placement).",
     namespace: "runtime_pool",

package/src/scheduler/schedule-task.ts

@@ -1,12 +1,53 @@
-import { createTaskExtended, getDbClient } from "@/be/db";
+import { createTaskExtended, getAgentById, getDbClient, getTaskById } from "@/be/db";
 import { carryUnhandledSteering } from "@/be/steering";
-import { scheduleContextKey } from "@/tasks/context-key";
+import { chatThreadOfContextKey, scheduleContextKey } from "@/tasks/context-key";
 import {
   type PreparedTaskCreate,
   prepareTaskWithSiblingAwareness,
 } from "@/tasks/sibling-awareness";
 import type { AgentTask, ScheduledTask } from "@/types";
 
+/**
+ * Whether the task's own answer is posted to its chat thread. Mirrors the
+ * relay triggers (migration 235): a delegated worker task, or its resume,
+ * reports through the Lead follow-up instead.
+ */
+async function answersInChat(task: AgentTask): Promise<boolean> {
+  if (task.source === "chat") return true;
+  if (task.source === "system" && task.taskType === "follow-up") return true;
+  // Only a wake-up that passed `scheduleTaskContextKey` has a chat key.
+  if (task.source === "schedule" && task.taskType === "deferred") return true;
+  if (task.source === "system" && task.taskType === "resume" && task.agentId) {
+    return (await getAgentById(task.agentId))?.isLead === true;
+  }
+  return false;
+}
+
+/**
+ * A defer-task wake-up of a chat task stays in its chat thread, so the chat
+ * relay posts the real answer there (and `/status` and `/cancel` see it).
+ * Only the deferring agent continuing its own task gets the thread: a schedule
+ * re-targeted or re-owned after the deferral, or the deferral of a task that
+ * never answered in chat, fires like any other schedule. Every other firing
+ * gets the schedule's own key.
+ */
+async function scheduleTaskContextKey(schedule: ScheduledTask): Promise<string> {
+  if (schedule.taskType === "deferred" && schedule.parentTaskId) {
+    const parent = await getTaskById(schedule.parentTaskId);
+    if (
+      parent?.contextKey &&
+      chatThreadOfContextKey(parent.contextKey) &&
+      parent.agentId &&
+      schedule.targetAgentId === parent.agentId &&
+      schedule.createdByAgentId === parent.agentId &&
+      (await answersInChat(parent))
+    ) {
+      return parent.contextKey;
+    }
+  }
+  return scheduleContextKey({ scheduleId: schedule.id });
+}
+
 /**
  * Run the `pre.task.create` extension hooks for a schedule firing. Call this OUTSIDE
  * the transaction that creates the task: the dispatcher skips hooks while a
@@ -35,7 +76,7 @@ export async function prepareStandaloneScheduleTask(
       scheduleId: schedule.id,
       source: "schedule",
       requestedByUserId: schedule.createdBy,
-      contextKey: scheduleContextKey({ scheduleId: schedule.id }),
+      contextKey: await scheduleTaskContextKey(schedule),
       // Set only by `defer-task`. An explicit parent wins over the sibling-awareness
       // auto-wiring (see withSiblingAwareness in src/tasks/sibling-awareness.ts), so
       // the wake-up run continues the deferred task rather than a random sibling.

package/src/scheduler/scheduler.ts

@@ -25,7 +25,7 @@ import {
 } from "@/be/script-connections";
 import { buildScriptCredentialBindingsWithFailures } from "@/be/script-credential-broker";
 import { getScript } from "@/be/scripts/db";
-import { runScript } from "@/scripts-runtime/loader";
+import { runScriptWithRunCredential } from "@/be/scripts/run-credential";
 import { telemetry } from "@/telemetry";
 import type { AgentTask, ScheduledTask } from "@/types";
 import { getExecutorRegistry as getWorkflowExecutorRegistry } from "@/workflows";
@@ -72,7 +72,7 @@ function resolveExecutorRegistry(): ExecutorRegistry | null {
 
 /**
  * Execute a schedule's `targetType='script'` target directly via the
- * scripts-runtime — no agent/LLM in the loop. Reuses the same `runScript()`
+ * scripts-runtime — no agent/LLM in the loop. Reuses the same `runScriptWithRunCredential()`
  * path as the `swarm-script` workflow executor.
  */
 async function executeScheduleScript(schedule: ScheduledTask): Promise<void> {
@@ -98,10 +98,10 @@ async function executeScheduleScript(schedule: ScheduledTask): Promise<void> {
     startedAt: new Date().toISOString(),
   };
 
-  let output: Awaited<ReturnType<typeof runScript>>;
+  let output: Awaited<ReturnType<typeof runScriptWithRunCredential>>;
   try {
     const credentials = await buildScriptCredentialBindingsWithFailures({ agentId });
-    output = await runScript({
+    output = await runScriptWithRunCredential({
       source: script.source,
       args,
       fsMode: "none",

package/src/scripts-runtime/loader.ts

@@ -40,6 +40,13 @@ export type RunScriptInput = {
   args?: unknown;
   fsMode?: ScriptFsMode;
   agentId: string;
+  /**
+   * Bearer for the run's `ctx.swarm` SDK calls. Api-side callers pass a
+   * per-run token bound to the executing agent (`runScriptWithRunCredential`
+   * in `src/be/scripts/run-credential.ts`, which also revokes it). Omitted, the
+   * run presents the swarm API key.
+   */
+  apiKey?: string;
   /** Per-boot runtime identity of the invoking worker; system context, never script input. */
   runtimeInstanceId?: string;
   signal?: AbortSignal;
@@ -74,7 +81,7 @@ export function scriptEgressPolicy(env: NodeJS.ProcessEnv = process.env): Egress
 }
 
 async function buildConfigPayload(input: RunScriptInput): Promise<SwarmConfigPayload> {
-  const apiKey = getApiKey();
+  const apiKey = input.apiKey ?? getApiKey();
   if (!apiKey) throw new Error("Swarm API key is required to run scripts");
 
   return {

package/src/slack/ack.ts

@@ -1,5 +1,6 @@
 import type { WebClient } from "@slack/web-api";
 import { getLogsByTaskIdChronological, getSlackTasksInThread, getTaskById } from "../be/db";
+import { terminalReactionEvent } from "../integrations/reaction-events";
 import { recordSlackReactionInvalidName } from "../otel";
 import { type AgentTask, isTerminalTaskStatus } from "../types";
 import { scrubSecrets } from "../utils/secret-scrubber";
@@ -143,7 +144,7 @@ export type SlackReactionChoice = { name: string; event?: SlackReactionEvent };
 
 /** The reaction choice for a task's terminal outcome, honouring operator config. */
 export function terminalReactionChoice(task: AgentTask): SlackReactionChoice {
-  const event: SlackReactionEvent = task.status === "completed" ? "completed" : "failed";
+  const event = terminalReactionEvent(task.status);
   return { name: reactionName(event), event };
 }
 

package/src/slack/reaction-shortcode.ts

@@ -1,10 +1,7 @@
-export type SlackReactionEvent =
-  | "accepted"
-  | "buffered"
-  | "now"
-  | "steered"
-  | "completed"
-  | "failed";
+import type { ReactionEvent } from "@/integrations/reaction-events";
+
+/** The shared lifecycle events; Slack maps each one to a shortcode below. */
+export type SlackReactionEvent = ReactionEvent;
 
 export const SLACK_REACTION_DEFAULTS: Record<SlackReactionEvent, string> = {
   accepted: "eyes",

package/src/tasks/worker-follow-up.ts

@@ -33,6 +33,7 @@ import {
 } from "../types";
 import { isEnvFlagEnabled } from "../utils/env-flag";
 import { taskAttachmentDisplayUrl } from "../utils/task-attachment-links";
+import { chatThreadOfContextKey } from "./context-key";
 import { taskModelPin } from "./model-pin";
 import { createTaskWithSiblingAwareness } from "./sibling-awareness";
 // Side-effect import: registers task lifecycle templates in the in-memory registry.
@@ -386,6 +387,7 @@ export async function createWorkerTaskFollowUp(args: {
       taskType: "follow-up",
       priority: changes.priority,
       parentTaskId: task.id,
+      contextKey: await deferredWorkChatContextKey(task),
       slackChannelId: task.slackChannelId,
       slackThreadTs: task.slackThreadTs,
       slackUserId: task.slackUserId,
@@ -398,6 +400,34 @@ export async function createWorkerTaskFollowUp(args: {
   );
 }
 
+/** Hop cap for `deferredWorkChatContextKey`; a defer/resume chain is short. */
+const MAX_CONTINUATION_HOPS = 32;
+
+/**
+ * The chat thread a worker's deferred work answers in, for its Lead follow-up.
+ * A worker's defer-task wake-up (and any resume of it) runs on its schedule's
+ * contextKey, so the worker stays out of the chat (`scheduleTaskContextKey`).
+ * The Lead follow-up still answers the original ask: walk back through the
+ * wake-up and resume chain to the deferred task and report on its chat thread.
+ * Undefined when the task already has a chat key or the chain leads to none,
+ * so the follow-up inherits the task's own key as before.
+ */
+async function deferredWorkChatContextKey(task: AgentTask): Promise<string | undefined> {
+  if (chatThreadOfContextKey(task.contextKey)) return undefined;
+  const seen = new Set<string>();
+  let current: AgentTask | null = task;
+  while (current && !seen.has(current.id) && seen.size < MAX_CONTINUATION_HOPS) {
+    if (chatThreadOfContextKey(current.contextKey)) return current.contextKey;
+    const continuation =
+      (current.source === "schedule" && current.taskType === "deferred") ||
+      (current.source === "system" && current.taskType === "resume");
+    if (!continuation || !current.parentTaskId) return undefined;
+    seen.add(current.id);
+    current = await getTaskById(current.parentTaskId);
+  }
+  return undefined;
+}
+
 /** Result of `createResumeFollowUp`. */
 export type CreateResumeFollowUpResult =
   | { kind: "created"; task: AgentTask }