@desplega.ai/agent-swarm 2.5.1 → 2.5.3

package/src/http/sessions.ts

@@ -26,7 +26,7 @@ import {
   moveSessionChains,
   type SessionKeyMove,
 } from "../be/db/session-moves";
-import { getSessionReadState, getSessionTree } from "../be/db/session-tree";
+import { getSessionReadState, getSessionTree, triageSessionList } from "../be/db/session-tree";
 import { getUserGrant } from "../be/rbac-roles";
 import {
   getSessionRoot,
@@ -157,6 +157,9 @@ const SessionTreeResponseSchema = z.object({
   later: SessionSectionCountsSchema,
   done: SessionSectionCountsSchema,
   noGroup: SessionSectionCountsSchema,
+  sources: z
+    .array(z.object({ source: z.string(), total: z.number().int() }))
+    .describe("Each root source in this view with its session count, hidden sources included."),
 });
 
 const SessionApprovalSchema = z.object({
@@ -480,6 +483,43 @@ async function handleAgentTokens(
   return true;
 }
 
+const SessionShowSchema = z
+  .enum(["mine", "all"])
+  .optional()
+  .describe(
+    "Sessions v2 view, for a user viewer with tree scope. mine (default): roots the user started from a human channel (not workflow, schedule, or system) plus sessions shared with the user. all: every tree session. Lists only: access is unchanged.",
+  );
+
+const SessionHideSourceSchema = z
+  .string()
+  // The same cap as the `hideSource` body field of `POST /api/session-triage`.
+  .refine((value) => value.split(",").length <= 32, "hideSource takes at most 32 sources.")
+  .optional()
+  .transform((value) =>
+    value
+      ?.split(",")
+      .map((source) => source.trim())
+      .filter(Boolean),
+  )
+  .describe(
+    "Comma-separated root sources to leave out, e.g. `slack,chat`. Older sessions v2 clients send this; `showSource` replaces it.",
+  );
+
+const SessionShowSourceSchema = z
+  .string()
+  // The same cap as the `showSource` body field of `POST /api/session-triage`.
+  .refine((value) => value.split(",").length <= 32, "showSource takes at most 32 sources.")
+  .optional()
+  .transform((value) =>
+    value
+      ?.split(",")
+      .map((source) => source.trim())
+      .filter(Boolean),
+  )
+  .describe(
+    "Comma-separated root sources to keep (the sessions v2 source filter), e.g. `ui,slack`. Present and empty keeps none; omit to keep every source.",
+  );
+
 const listSessions = route({
   method: "get",
   path: "/api/sessions",
@@ -539,6 +579,12 @@ const listSessions = route({
       .describe(
         "mine: owned sessions. shared: sessions shared with me. tree: Sessions that GET /api/session-tree counts: mine plus shared with me, no ownerless roots. A bypass actor sees every root with tree scope.",
       ),
+    /** With `scope=tree`: `mine` (default) or `all`. Must match the tree's `show`. */
+    show: SessionShowSchema,
+    /** Root sources to leave out. Must match the tree's `hideSource`. */
+    hideSource: SessionHideSourceSchema,
+    /** Root sources to keep. Must match the tree's `showSource`. */
+    showSource: SessionShowSourceSchema,
   }),
   responses: {
     200: {
@@ -561,6 +607,11 @@ const sessionTree = route({
   pattern: ["api", "session-tree"],
   summary: "Get session groups and triage counts",
   tags: ["Sessions"],
+  query: z.object({
+    show: SessionShowSchema,
+    hideSource: SessionHideSourceSchema,
+    showSource: SessionShowSourceSchema,
+  }),
   responses: {
     200: { description: "Visible groups and section counts", schema: SessionTreeResponseSchema },
     401: { description: "Unauthorized" },
@@ -568,6 +619,41 @@ const sessionTree = route({
   auth: { apiKey: true },
 });
 
+const triageSessionListRoute = route({
+  method: "post",
+  path: "/api/session-triage",
+  pattern: ["api", "session-triage"],
+  summary: "Triage every session of one sidebar list",
+  description:
+    "The bulk bar's 'Select all N': Done, back to the Inbox, read, or unread for every session that one sessions v2 list shows the caller (the `GET /api/sessions?scope=tree` filters). Needs a picked user.",
+  tags: ["Sessions"],
+  body: z
+    .object({
+      action: z.enum(["done", "inbox", "read", "unread"]),
+      /** The list: one of Inbox, Later, Done, No group, or a group. */
+      triage: z.enum(["inbox", "later", "done"]).optional(),
+      noGroup: z.boolean().optional(),
+      groupKey: SessionKeyFilterSchema.optional(),
+      show: SessionShowSchema,
+      hideSource: z.array(z.string().min(1)).max(32).optional(),
+      /** Root sources to keep; an empty array keeps none. */
+      showSource: z.array(z.string().min(1)).max(32).optional(),
+    })
+    .refine((body) => [body.triage, body.noGroup, body.groupKey].filter(Boolean).length === 1, {
+      message: "Name exactly one list: triage, noGroup, or groupKey",
+    }),
+  responses: {
+    200: {
+      description: "The number of sessions written",
+      schema: z.object({ updated: z.number().int() }),
+    },
+    400: { description: "Validation error, or no picked user" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+  rbac: { ungated: "per-user inbox UI state, same posture as PATCH /api/inbox-state" },
+});
+
 const SESSION_MOVE_LIMIT = 200;
 const SESSION_MOVE_OWNER_ONLY = "Only the session owner can move this group";
 const SESSION_MOVE_UNAVAILABLE = "Session not found or not accessible";
@@ -877,6 +963,8 @@ export async function handleSessions(
     }
     const filterOpts = {
       source: sources,
+      hideSource: parsed.query.hideSource,
+      showSource: parsed.query.showSource,
       q: parsed.query.q,
       requestedByUserId: parsed.query.requestedByUserId,
       contextKeyPrefix: parsed.query.contextKeyPrefix,
@@ -888,6 +976,7 @@ export async function handleSessions(
       withUserId: parsed.query.withUserId,
       now: new Date().toISOString(),
       tree: parsed.query.scope === "tree",
+      mine: parsed.query.scope === "tree" && parsed.query.show !== "all",
       ...(actor.kind === "user"
         ? {
             viewer: {
@@ -922,7 +1011,34 @@ export async function handleSessions(
   if (sessionTree.match(req.method, pathSegments)) {
     const parsed = await sessionTree.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
-    sessionTree.respond(res, 200, await getSessionTree(await resolveSessionActor(req, myAgentId)));
+    const actor = await resolveSessionActor(req, myAgentId);
+    sessionTree.respond(
+      res,
+      200,
+      await getSessionTree(actor, undefined, {
+        mine: parsed.query.show !== "all",
+        hideSource: parsed.query.hideSource,
+        showSource: parsed.query.showSource,
+      }),
+    );
+    return true;
+  }
+
+  if (triageSessionListRoute.match(req.method, pathSegments)) {
+    const parsed = await triageSessionListRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const actor = await resolveSessionActor(req, myAgentId);
+    if (actor.kind !== "user" || !actor.userId) {
+      jsonError(res, "Pick a user to triage sessions", 400);
+      return true;
+    }
+    const { action, show, ...list } = parsed.body;
+    const updated = await triageSessionList(
+      actor.userId,
+      { ...list, mine: show !== "all" },
+      action,
+    );
+    triageSessionListRoute.respond(res, 200, { updated });
     return true;
   }
 

package/src/http/user-roles.ts

@@ -0,0 +1,173 @@
+/**
+ * RBAC role assignment for people.
+ *
+ *   GET /api/rbac/roles
+ *   GET /api/users/:id/roles
+ *   PUT /api/users/:id/roles
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { getUserById } from "../be/db";
+import {
+  getUserGrant,
+  InvalidRoleSetError,
+  LastAdminError,
+  listRbacRoles,
+  listUserRoles,
+  PRIMARY_ROLE_NAMES,
+  setUserRoles,
+} from "../be/rbac-roles";
+import { recordIdentityEvent } from "../be/users";
+import { can, isRbacEnabled } from "../rbac";
+import { RbacRoleSchema, UserRbacRolesSchema } from "../types";
+import { getRequestAuth } from "../utils/request-auth-context";
+import { getOperatorActor } from "./operator-actor";
+import { agentFirstPrincipal, rejectGuest } from "./request-principal";
+import { route } from "./route-def";
+import { jsonError } from "./utils";
+
+const listRolesRoute = route({
+  method: "get",
+  path: "/api/rbac/roles",
+  pattern: ["api", "rbac", "roles"],
+  operationId: "rbac_listRoles",
+  summary: "List RBAC roles with their verbs",
+  tags: ["Users"],
+  responses: {
+    200: { description: "Role catalog", schema: z.object({ roles: z.array(RbacRoleSchema) }) },
+  },
+});
+
+const getUserRolesRoute = route({
+  method: "get",
+  path: "/api/users/{id}/roles",
+  pattern: ["api", "users", null, "roles"],
+  operationId: "users_getRbacRoles",
+  summary: "Get a user's RBAC roles",
+  tags: ["Users"],
+  params: z.object({ id: z.string().min(1) }),
+  responses: {
+    200: { description: "The user's roles", schema: UserRbacRolesSchema },
+    404: { description: "User not found" },
+  },
+});
+
+const setUserRolesRoute = route({
+  method: "put",
+  path: "/api/users/{id}/roles",
+  pattern: ["api", "users", null, "roles"],
+  operationId: "users_setRbacRoles",
+  summary: "Set a user's RBAC roles",
+  description: `Replaces the user's roles. The set holds exactly one of ${PRIMARY_ROLE_NAMES.join(", ")} plus any extra roles. Demoting a user below admin removes the ability to answer approval requests, even when the user is listed as an approver. Fails with 409 when it would leave no active admin.`,
+  tags: ["Users"],
+  params: z.object({ id: z.string().min(1) }),
+  body: z.object({ roles: z.array(z.string().min(1)).min(1) }).strict(),
+  responses: {
+    200: { description: "The user's roles after the change", schema: UserRbacRolesSchema },
+    400: { description: "Invalid role set" },
+    403: { description: "Not allowed to change roles" },
+    404: { description: "User not found" },
+    409: { description: "Would leave no active admin" },
+  },
+  rbac: { permission: "user.role.manage" },
+});
+
+async function composeRoles(userId: string) {
+  const [catalog, held] = await Promise.all([listRbacRoles(), listUserRoles(userId)]);
+  const names = new Set(held.map((role) => role.name));
+  return { userId, roles: catalog.filter((role) => names.has(role.name)) };
+}
+
+/** Operator or user only; agents never change human roles, even with the shared key. */
+async function ensureRoleManager(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  if (rejectGuest(req, res)) return false;
+  const auth = getRequestAuth(req);
+  if (auth?.kind !== "operator" && auth?.kind !== "user") {
+    jsonError(res, "Role changes require operator or user credentials", 403);
+    return false;
+  }
+  const header = req.headers["x-agent-id"];
+  const decision = can({
+    principal: await agentFirstPrincipal(req, Array.isArray(header) ? header[0] : header),
+    verb: "user.role.manage",
+    resource: { kind: "none" },
+    source: "http",
+  });
+  if (!decision.allow) {
+    jsonError(res, decision.reason, 403);
+    return false;
+  }
+  // A custom role holding user.role.manage must not be able to grant admin.
+  if (auth.kind === "user" && isRbacEnabled() && !(await getUserGrant(auth.userId)).grantsAll) {
+    jsonError(res, "Role changes require a grant-all role", 403);
+    return false;
+  }
+  return true;
+}
+
+export async function handleUserRoles(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  if (listRolesRoute.match(req.method, pathSegments)) {
+    if (rejectGuest(req, res)) return true;
+    listRolesRoute.respond(res, 200, { roles: await listRbacRoles() });
+    return true;
+  }
+
+  if (getUserRolesRoute.match(req.method, pathSegments)) {
+    if (rejectGuest(req, res)) return true;
+    const parsed = await getUserRolesRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await getUserById(parsed.params.id))) {
+      jsonError(res, "User not found", 404);
+      return true;
+    }
+    getUserRolesRoute.respond(res, 200, await composeRoles(parsed.params.id));
+    return true;
+  }
+
+  if (setUserRolesRoute.match(req.method, pathSegments)) {
+    const parsed = await setUserRolesRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await ensureRoleManager(req, res))) return true;
+    const actor = getOperatorActor(req, res);
+    if (!actor) return true;
+    const userId = parsed.params.id;
+    if (!(await getUserById(userId))) {
+      jsonError(res, "User not found", 404);
+      return true;
+    }
+    try {
+      const { before, after } = await setUserRoles(
+        userId,
+        parsed.body.roles,
+        actor.kind === "user" ? actor.id : null,
+      );
+      await recordIdentityEvent(
+        userId,
+        "profile_changed",
+        actor,
+        { rbacRoles: before },
+        { rbacRoles: after },
+      );
+    } catch (err) {
+      if (err instanceof LastAdminError) {
+        jsonError(res, "last_admin", 409);
+        return true;
+      }
+      if (err instanceof InvalidRoleSetError) {
+        jsonError(res, err.message, 400);
+        return true;
+      }
+      throw err;
+    }
+    setUserRolesRoute.respond(res, 200, await composeRoles(userId));
+    return true;
+  }
+
+  return false;
+}

package/src/http/users.ts

@@ -45,6 +45,7 @@ import {
   updateUser,
   upsertBudget,
 } from "../be/db";
+import { assertNotLastAdmin, LastAdminError } from "../be/rbac-roles";
 import {
   getUserIdentities,
   type IdentityEvent,
@@ -484,6 +485,7 @@ const mergeUsersRoute = route({
     400: { description: "Validation error (e.g. target == source)" },
     401: { description: "Unauthorized" },
     404: { description: "Target or source user not found" },
+    409: { description: "Source is the last active admin (last_admin)" },
   },
   auth: { apiKey: true },
 });
@@ -1071,6 +1073,9 @@ export async function handleUsers(
           }
         }
 
+        // The source's roles go with it; never leave the swarm without an admin.
+        await assertNotLastAdmin(sourceId);
+
         // Delete source — CASCADE cleans up any leftover external_ids row that
         // we may have missed. Retained user references move to the target.
         await deleteUser(sourceId, targetId);
@@ -1095,6 +1100,10 @@ export async function handleUsers(
       });
       mergeUsersRoute.respond(res, 200, { user: mergedUser });
     } catch (err) {
+      if (err instanceof LastAdminError) {
+        jsonError(res, "last_admin", 409);
+        return true;
+      }
       jsonError(res, err instanceof Error ? err.message : "Failed to merge users", 500);
     }
     return true;

package/src/http/x.ts

@@ -15,12 +15,12 @@ import {
   restoreScratchScriptLastUsedIfUnchanged,
   touchScratchScriptLastUsed,
 } from "../be/scripts/db";
+import { runScriptWithRunCredential } from "../be/scripts/run-credential";
 import {
   MAX_SCRIPT_WALL_CLOCK_MS,
   MIN_SCRIPT_WALL_CLOCK_MS,
 } from "../scripts-runtime/executors/types";
 import type { RunScriptOutput } from "../scripts-runtime/loader";
-import { runScript } from "../scripts-runtime/loader";
 import { scrubObject, scrubSecrets } from "../utils/secret-scrubber";
 import { validateJsonSchema } from "../workflows/json-schema-validator";
 import { route } from "./route-def";
@@ -242,7 +242,7 @@ export async function handleX(
   const credentials = await buildScriptCredentialBindingsWithFailures({
     agentId: endpoint.agentId,
   });
-  const output = await runScript({
+  const output = await runScriptWithRunCredential({
     source: script.source,
     args: args ?? null,
     fsMode: "none",

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

@@ -63,7 +63,19 @@ function helpText(): string {
   return ["Commands:", ...CHAT_COMMANDS.map((c) => `/${c.command}: ${c.description}`)].join("\n");
 }
 
-function shortId(task: AgentTask): string {
+/**
+ * Telegram sends `/start` when a user opens a bot DM. It stays out of
+ * `CHAT_COMMANDS`, so the `/` menu does not list it.
+ */
+function welcomeText(): string {
+  return [
+    "Hi! Send a message here (in a group, mention me) and the swarm picks it up. Each answer arrives as a reply to your message.",
+    "",
+    helpText(),
+  ].join("\n");
+}
+
+export function shortId(task: Pick<AgentTask, "id">): string {
   return task.id.slice(0, 8);
 }
 
@@ -115,6 +127,7 @@ export async function runChatCommand(
 ): Promise<string> {
   const name = command.replace(/^\//, "").toLowerCase();
   if (name === "help") return helpText();
+  if (name === "start") return welcomeText();
   if (!CHAT_COMMANDS.some((c) => c.command === name)) {
     return `Unknown command /${name}.\n${helpText()}`;
   }

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

@@ -32,6 +32,12 @@ import { getChatThreadResetAt } from "./commands";
 import { type ChatAddressedReason, formatChatHeaderFacts, readChatMessageFacts } from "./facts";
 import { errorMessage } from "./logger";
 import { emitChatMessageSent, postChatMessage } from "./outbound";
+import {
+  chatAdapterReacts,
+  clearChatMessageReactions,
+  setChatMessageReaction,
+  wantsChatTextAck,
+} from "./reactions";
 import {
   type ChatAgentMatch,
   type ChatRouteTarget,
@@ -154,9 +160,14 @@ export async function handleChatInbound(
       console.log(
         `[chat-sdk] ${adapter} message steered task ${steering.task.id} (${steering.result.outcome})`,
       );
+      await setChatMessageReaction(adapter, thread.id, message.id, "steered");
+      if (!(await wantsChatTextAck(adapter, thread.channelId))) return;
       try {
         const ack = formatChatSteeringAck(steering.result);
-        const sent = await thread.post({ markdown: ack });
+        // Telegram threads the ack under the steering message; other adapters post it.
+        const sent = thread.adapter.reply
+          ? await thread.reply(message, { markdown: ack })
+          : await thread.post({ markdown: ack });
         emitChatMessageSent({
           adapter,
           channelId: thread.channelId,
@@ -177,6 +188,10 @@ export async function handleChatInbound(
   }
 
   if (text || attachments.length > 0) {
+    // An unaddressed subscribed-thread message may be dropped by the router at
+    // flush time; it gets typing and a reaction once a task exists (see
+    // flushChatThread). A mention, reply to the bot, or DM is acknowledged now.
+    const acknowledge = kind !== "subscribed" || isDirectMessage || mentioned || facts.replyToBot;
     bufferChatMessage(thread.id, {
       messageId: message.id,
       channelId: thread.channelId,
@@ -186,12 +201,14 @@ export async function handleChatInbound(
       botMentioned: mentioned || facts.replyToBot,
       isDirectMessage,
       addressed,
+      reacted: acknowledge && chatAdapterReacts(adapter),
       facts,
       attachments,
     });
-    // Subscribed-thread messages may be dropped by the router at flush time;
-    // they get typing once a task exists (see flushChatThread).
-    if (kind !== "subscribed") startTypingKeepalive(adapter, thread.id);
+    if (acknowledge) {
+      startTypingKeepalive(adapter, thread.id);
+      await setChatMessageReaction(adapter, thread.id, message.id, immediate ? "now" : "accepted");
+    }
   }
   if (immediate) await instantFlushChat(thread.id);
 }
@@ -377,6 +394,9 @@ export async function flushChatThread(
   // One task carries every sender's text, so a batch from several people
   // gets no requester: one sender's identity must not vouch for another's words.
   const otherSenders = new Set(items.map((item) => item.userId)).size - 1;
+  // The task answers the newest message; it alone carries the reaction lifecycle.
+  const answered = items.at(-1) ?? first;
+  const reacted = items.filter((item) => item.reacted).map((item) => item.messageId);
 
   // After `/reset` the thread's earlier tasks are not context: the new task gets
   // no parent and no thread history older than the reset.
@@ -418,6 +438,7 @@ export async function flushChatThread(
       scrubSecrets(routeResult.reason),
     );
     stopTypingKeepalive(threadId);
+    await clearChatMessageReactions(adapter, threadId, reacted);
     return;
   }
 
@@ -433,12 +454,14 @@ export async function flushChatThread(
   if (!target) {
     console.log(`[chat-sdk] ${threadId}: message not addressed to the swarm, ignored`);
     stopTypingKeepalive(threadId);
+    await clearChatMessageReactions(adapter, threadId, reacted);
     return;
   }
 
   if (target.kind === "workflow") {
-    // A workflow run has no relay that would stop the indicator.
+    // A workflow run has no relay that would stop the indicator or end the reaction.
     stopTypingKeepalive(threadId);
+    await clearChatMessageReactions(adapter, threadId, reacted);
     try {
       // The adapter verified the platform signature, and the workflow id comes
       // from an operator mapping or an extension, never from the message.
@@ -533,6 +556,11 @@ export async function flushChatThread(
       // A human message in the thread: never answer it in the previous task's
       // structured-output contract.
       inheritParentOutputSchema: false,
+      // The relay answers as a reply to the newest buffered message. Always set
+      // explicitly: `createTask` copies the parent's anchor into a child that
+      // has none, and that would point at an older ask.
+      mentionMessageId: answered.messageId,
+      mentionChannelId: first.channelId,
     };
     try {
       const { task, unattached } = await createChatTaskWithFiles(description, options, inbound);
@@ -553,10 +581,18 @@ export async function flushChatThread(
   if (created > 0) {
     await rememberChatThreadRequester(threadId, requester.userId);
     await subscribe(thread);
-    // Subscribed-thread messages start typing only here, once a task exists.
+    // Unaddressed subscribed-thread messages start typing only here, once a task exists.
     startTypingKeepalive(adapter, threadId);
+    await clearChatMessageReactions(
+      adapter,
+      threadId,
+      reacted.filter((id) => id !== answered.messageId),
+    );
+    if (!answered.reacted)
+      await setChatMessageReaction(adapter, threadId, answered.messageId, "accepted");
   } else {
     stopTypingKeepalive(threadId);
+    await clearChatMessageReactions(adapter, threadId, reacted);
   }
 }
 

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

@@ -76,12 +76,14 @@ export class ChatFileTooLargeError extends Error {
   }
 }
 
+type SentChunk = { id: string; threadId?: string };
+
 interface PostTarget {
   post(message: {
     markdown: string;
     files?: FileUpload[];
     attachments?: Attachment[];
-  }): Promise<{ id: string; threadId?: string }>;
+  }): Promise<SentChunk>;
 }
 
 /** A fence opener or closer: up to 3 spaces, then 3+ backticks or tildes. */
@@ -120,16 +122,22 @@ export function escapeTelegramHashLines(markdown: string): string {
     .join("\n");
 }
 
+/** `replyFirst` sends the first chunk as a native reply; later chunks are plain posts. */
 async function postChunks(
   adapter: string,
   target: PostTarget,
-  text: string,
+  parts: readonly string[],
+  replyFirst?: (message: { markdown: string }) => Promise<SentChunk>,
 ): Promise<{ messageIds: string[]; threadId?: string }> {
   const messageIds: string[] = [];
   let threadId: string | undefined;
-  for (const chunk of splitChatMessage(text, chatMessageLimit(adapter))) {
-    const markdown = adapter === "telegram" ? escapeTelegramHashLines(chunk) : chunk;
-    const sent = await target.post({ markdown });
+  const limit = chatMessageLimit(adapter);
+  for (const chunk of parts.flatMap((part) => splitChatMessage(part, limit))) {
+    const message = { markdown: adapter === "telegram" ? escapeTelegramHashLines(chunk) : chunk };
+    const sent =
+      replyFirst && messageIds.length === 0
+        ? await replyFirst(message)
+        : await target.post(message);
     messageIds.push(sent.id);
     threadId ??= sent.threadId;
   }
@@ -323,28 +331,45 @@ export function formatUnsentFilesNote(unsent: UnsentChatFile[]): string {
  * Delivery is at-least-once: a chunk failure re-posts earlier chunks on retry,
  * and a crash between the send and `markChatRelayDelivered` re-sends the
  * message.
+ *
+ * An array `text` is posted as one message per element, each still split at
+ * the limit; the caller uses it when its own markup must not be cut in two.
+ *
+ * `replyToMessageId` anchors the first chunk to that message on a thread
+ * target. Telegram sends it with `allow_sending_without_reply`, so a deleted
+ * target still gets the message, unthreaded.
  */
 export async function postChatMessage(args: {
   adapter: string;
   threadId?: string;
   channelId?: string;
-  text: string;
+  text: string | readonly string[];
   taskId?: string;
   files?: OutboundChatFile[];
+  replyToMessageId?: string;
 }): Promise<ChatPostResult> {
   // Ids come from tools and stored context keys. Check the Teams origin
   // before the adapter sends its token.
   assertTrustedChatTarget(args.threadId ?? args.channelId ?? "");
   const chat = getChatInstance(args.adapter);
   if (!chat) throw new ChatAdapterUnavailableError(args.adapter);
-  const text = scrubSecrets(args.text);
+  const parts = (typeof args.text === "string" ? [args.text] : args.text).map(scrubSecrets);
+  const text = parts.join("\n\n");
 
   let result: ChatPostResult;
   let target: PostTarget;
   if (args.threadId) {
     const thread = chat.thread(args.threadId);
     target = thread;
-    const sent = await postChunks(args.adapter, thread, text);
+    // Only adapters with a native reply (Telegram in this SDK version) anchor;
+    // the others post unanchored, as before.
+    const replyTo = args.replyToMessageId;
+    const sent = await postChunks(
+      args.adapter,
+      thread,
+      parts,
+      replyTo && thread.adapter.reply ? (message) => thread.reply(replyTo, message) : undefined,
+    );
     result = {
       adapter: args.adapter,
       threadId: thread.id,
@@ -355,7 +380,7 @@ export async function postChatMessage(args: {
   } else if (args.channelId) {
     const channel = chat.channel(args.channelId);
     target = channel;
-    const sent = await postChunks(args.adapter, channel, text);
+    const sent = await postChunks(args.adapter, channel, parts);
     result = {
       adapter: args.adapter,
       threadId: sent.threadId ?? channel.id,
@@ -373,7 +398,7 @@ export async function postChatMessage(args: {
     result.unsentFiles = sent.unsent;
     if (sent.unsent.length > 0) {
       const note = formatUnsentFilesNote(sent.unsent);
-      const noted = await postChunks(args.adapter, target, scrubSecrets(note));
+      const noted = await postChunks(args.adapter, target, [scrubSecrets(note)]);
       result.messageIds.push(...noted.messageIds);
     }
   }