@vellumai/assistant 0.11.6 → 0.11.7-staging.2

package/src/notifications/__tests__/activity-failed-dedupe.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, test } from "bun:test";
+
+import { activityFailedDedupeKey } from "../activity-failed-dedupe.js";
+
+describe("activityFailedDedupeKey", () => {
+  test("a provider-scoped code collapses across jobs within one scope", () => {
+    const heartbeat = activityFailedDedupeKey({
+      jobName: "heartbeat",
+      errorKind: "model_provider",
+      failureCode: "PROVIDER_BILLING",
+      providerScope: "balanced",
+    });
+    const schedule = activityFailedDedupeKey({
+      jobName: "schedule:job-123",
+      errorKind: "model_provider",
+      failureCode: "PROVIDER_BILLING",
+      providerScope: "balanced",
+    });
+    expect(heartbeat).toBe(schedule);
+    expect(heartbeat).toMatch(
+      /^activity-failed:cause:PROVIDER_BILLING:balanced:\d{4}-\d{2}-\d{2}$/,
+    );
+  });
+
+  test("a provider-scoped code without a scope keys per job", () => {
+    // A caller that cannot name the provider route its failure hit must not
+    // collapse with other routes' failures; per-job is the safe fallback.
+    const key = activityFailedDedupeKey({
+      jobName: "job-a",
+      errorKind: "model_provider",
+      failureCode: "PROVIDER_BILLING",
+    });
+    expect(key).toMatch(/^activity-failed:job-a:\d{4}-\d{2}-\d{2}$/);
+  });
+
+  test("the same code in different provider scopes stays distinct", () => {
+    // Two provider connections can fail for the same class of reason with
+    // different remedies; the first notification must not hide the second.
+    const profileA = activityFailedDedupeKey({
+      jobName: "schedule:job-a",
+      errorKind: "model_provider",
+      failureCode: "PROVIDER_INVALID_KEY",
+      providerScope: "profile-a",
+    });
+    const profileB = activityFailedDedupeKey({
+      jobName: "schedule:job-b",
+      errorKind: "model_provider",
+      failureCode: "PROVIDER_INVALID_KEY",
+      providerScope: "profile-b",
+    });
+    expect(profileA).not.toBe(profileB);
+    expect(profileA).toMatch(
+      /^activity-failed:cause:PROVIDER_INVALID_KEY:profile-a:\d{4}-\d{2}-\d{2}$/,
+    );
+  });
+
+  test("a workspace-wide code collapses regardless of provider scope", () => {
+    const a = activityFailedDedupeKey({
+      jobName: "job-a",
+      errorKind: "model_provider",
+      failureCode: "MANAGED_KEY_INVALID",
+      providerScope: "profile-a",
+    });
+    const b = activityFailedDedupeKey({
+      jobName: "job-b",
+      errorKind: "model_provider",
+      failureCode: "MANAGED_KEY_INVALID",
+      providerScope: "profile-b",
+    });
+    expect(a).toBe(b);
+    expect(a).toMatch(
+      /^activity-failed:cause:MANAGED_KEY_INVALID:\d{4}-\d{2}-\d{2}$/,
+    );
+  });
+
+  test("job-specific failure codes key per job, not on the cause", () => {
+    const a = activityFailedDedupeKey({
+      jobName: "job-a",
+      errorKind: "model_provider",
+      failureCode: "CONTEXT_TOO_LARGE",
+    });
+    const b = activityFailedDedupeKey({
+      jobName: "job-b",
+      errorKind: "model_provider",
+      failureCode: "CONTEXT_TOO_LARGE",
+    });
+    expect(a).toMatch(/^activity-failed:job-a:\d{4}-\d{2}-\d{2}$/);
+    expect(a).not.toBe(b);
+  });
+
+  test("unknown failure codes default to the per-job key", () => {
+    const key = activityFailedDedupeKey({
+      jobName: "job-a",
+      errorKind: "model_provider",
+      failureCode: "SOME_FUTURE_CODE",
+    });
+    expect(key).toMatch(/^activity-failed:job-a:\d{4}-\d{2}-\d{2}$/);
+  });
+
+  test("distinct failure codes stay distinct", () => {
+    const billing = activityFailedDedupeKey({
+      jobName: "job",
+      errorKind: "model_provider",
+      failureCode: "PROVIDER_BILLING",
+      providerScope: "balanced",
+    });
+    const key = activityFailedDedupeKey({
+      jobName: "job",
+      errorKind: "model_provider",
+      failureCode: "MANAGED_KEY_INVALID",
+      providerScope: "balanced",
+    });
+    expect(billing).not.toBe(key);
+  });
+
+  test("code-less provider failures share the cause key within one scope", () => {
+    const a = activityFailedDedupeKey({
+      jobName: "watcher-a",
+      errorKind: "model_provider",
+      providerScope: "balanced",
+    });
+    const b = activityFailedDedupeKey({
+      jobName: "watcher-b",
+      errorKind: "model_provider",
+      providerScope: "balanced",
+    });
+    expect(a).toBe(b);
+    expect(a).toMatch(
+      /^activity-failed:cause:model_provider:balanced:\d{4}-\d{2}-\d{2}$/,
+    );
+    const otherScope = activityFailedDedupeKey({
+      jobName: "watcher-a",
+      errorKind: "model_provider",
+      providerScope: "profile-a",
+    });
+    expect(otherScope).not.toBe(a);
+    const scopeless = activityFailedDedupeKey({
+      jobName: "watcher-a",
+      errorKind: "model_provider",
+    });
+    expect(scopeless).toMatch(/^activity-failed:watcher-a:\d{4}-\d{2}-\d{2}$/);
+  });
+
+  test("job-specific failures key per job", () => {
+    const timeoutA = activityFailedDedupeKey({
+      jobName: "job-a",
+      errorKind: "timeout",
+    });
+    const timeoutB = activityFailedDedupeKey({
+      jobName: "job-b",
+      errorKind: "timeout",
+    });
+    const exceptionA = activityFailedDedupeKey({
+      jobName: "job-a",
+      errorKind: "exception",
+    });
+    expect(timeoutA).toMatch(/^activity-failed:job-a:\d{4}-\d{2}-\d{2}$/);
+    expect(timeoutA).not.toBe(timeoutB);
+    expect(exceptionA).toMatch(/^activity-failed:job-a:\d{4}-\d{2}-\d{2}$/);
+  });
+});

package/src/notifications/__tests__/background-failure-signal.test.ts

@@ -0,0 +1,107 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+const emitCalls: Array<Record<string, unknown>> = [];
+mock.module("../emit-signal.js", () => ({
+  emitNotificationSignal: (params: Record<string, unknown>) => {
+    emitCalls.push(params);
+    return Promise.resolve({
+      signalId: "sig-1",
+      deduplicated: false,
+      dispatched: true,
+      reason: "ok",
+      deliveryResults: [],
+      pipelineFailed: false,
+    });
+  },
+}));
+
+const { emitBackgroundFailureSignal } =
+  await import("../background-failure-signal.js");
+
+describe("emitBackgroundFailureSignal", () => {
+  beforeEach(() => {
+    emitCalls.length = 0;
+  });
+
+  test("carried connection leads the dedupe scope and rides the payload", () => {
+    emitBackgroundFailureSignal({
+      jobName: "schedule:job-1",
+      displayName: "schedule:PR scan",
+      sourceChannel: "scheduler",
+      sourceContextId: "job-1",
+      errorKind: "model_provider",
+      errorMessage: "Agent turn failed (PROVIDER_BILLING)",
+      failureCode: "PROVIDER_BILLING",
+      failureSummary: "You're out of credits.",
+      errorCategory: "credits_exhausted",
+      connectionName: "conn-a",
+      profileName: "balanced",
+      fallbackProviderScope: "cost-optimized",
+    });
+
+    expect(emitCalls).toHaveLength(1);
+    const emitted = emitCalls[0];
+    expect(emitted.sourceEventName).toBe("activity.failed");
+    expect(emitted.dedupeKey as string).toMatch(
+      /^activity-failed:cause:PROVIDER_BILLING:conn-a:\d{4}-\d{2}-\d{2}$/,
+    );
+    expect(emitted.contextPayload).toMatchObject({
+      jobName: "schedule:PR scan",
+      errorKind: "model_provider",
+      failureCode: "PROVIDER_BILLING",
+      failureSummary: "You're out of credits.",
+      errorCategory: "credits_exhausted",
+      connectionName: "conn-a",
+    });
+  });
+
+  test("carried profile scopes when no connection is carried", () => {
+    emitBackgroundFailureSignal({
+      jobName: "heartbeat",
+      sourceChannel: "assistant_tool",
+      sourceContextId: "conv-1",
+      errorKind: "model_provider",
+      errorMessage: "rate limited",
+      failureCode: "PROVIDER_RATE_LIMIT",
+      profileName: "balanced",
+      fallbackProviderScope: "cost-optimized",
+    });
+
+    expect(emitCalls[0].dedupeKey as string).toMatch(
+      /^activity-failed:cause:PROVIDER_RATE_LIMIT:balanced:\d{4}-\d{2}-\d{2}$/,
+    );
+  });
+
+  test("recomputed fallback scopes when nothing is carried", () => {
+    emitBackgroundFailureSignal({
+      jobName: "watcher-a",
+      sourceChannel: "assistant_tool",
+      sourceContextId: "conv-2",
+      errorKind: "model_provider",
+      errorMessage: "provider returned 401",
+      fallbackProviderScope: "cost-optimized",
+    });
+
+    expect(emitCalls[0].dedupeKey as string).toMatch(
+      /^activity-failed:cause:model_provider:cost-optimized:\d{4}-\d{2}-\d{2}$/,
+    );
+  });
+
+  test("no scope at all keys per job", () => {
+    emitBackgroundFailureSignal({
+      jobName: "memory.v2.sweep",
+      sourceChannel: "scheduler",
+      sourceContextId: "job-9",
+      errorKind: "exception",
+      errorMessage: "boom",
+    });
+
+    expect(emitCalls[0].dedupeKey as string).toMatch(
+      /^activity-failed:memory\.v2\.sweep:\d{4}-\d{2}-\d{2}$/,
+    );
+    expect(emitCalls[0].contextPayload).toMatchObject({
+      jobName: "memory.v2.sweep",
+      errorKind: "exception",
+    });
+  });
+});

package/src/notifications/__tests__/connected-channels.test.ts

@@ -78,6 +78,18 @@ describe("getConnectedChannels gateway connectivity", () => {
     expect(await getConnectedChannels()).toContain("slack");
   });
 
+  test("marks discord connected from a verified guardian binding", async () => {
+    deliverableChannels = ["discord"];
+    gatewayGuardians = [gatewayBinding("discord", "999888777666555444")];
+    expect(await getConnectedChannels()).toContain("discord");
+  });
+
+  test("marks discord disconnected when the gateway has no binding", async () => {
+    deliverableChannels = ["discord"];
+    gatewayGuardians = [];
+    expect(await getConnectedChannels()).not.toContain("discord");
+  });
+
   test("always reports vellum and platform connected", async () => {
     deliverableChannels = ["vellum", "platform"];
     gatewayGuardians = null;

package/src/notifications/__tests__/copy-composer.test.ts

@@ -35,6 +35,89 @@ function makeSignal(
 
 const CHANNELS: NotificationChannel[] = ["vellum" as NotificationChannel];
 
+// ── activity.failed rendering ─────────────────────────────────────────
+
+describe("activity.failed copy", () => {
+  function failedSignal(
+    contextPayload: Record<string, unknown>,
+  ): NotificationSignal {
+    return makeSignal({
+      sourceEventName: "activity.failed",
+      contextPayload,
+    });
+  }
+
+  test("renders the carried classification message verbatim", () => {
+    const copy = composeFallbackCopy(
+      failedSignal({
+        jobName: "schedule:PR scan",
+        errorKind: "model_provider",
+        errorMessage: "Agent turn failed (PROVIDER_BILLING)",
+        failureSummary:
+          "You're out of credits. Add credits in Settings to continue.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe("Background job failed: schedule:PR scan");
+    expect(copy.vellum?.body).toBe(
+      "You're out of credits. Add credits in Settings to continue.",
+    );
+  });
+
+  test("an oversized carried summary is bounded", () => {
+    const copy = composeFallbackCopy(
+      failedSignal({
+        jobName: "job",
+        errorKind: "model_provider",
+        errorMessage: "irrelevant",
+        failureSummary: "x".repeat(400),
+      }),
+      CHANNELS,
+    );
+    expect((copy.vellum?.body ?? "").length).toBeLessThanOrEqual(303);
+    expect(copy.vellum?.body).toEndWith("...");
+  });
+
+  test("constant-shaped raw detail never reaches the body", () => {
+    const copy = composeFallbackCopy(
+      failedSignal({
+        jobName: "heartbeat",
+        errorKind: "model_provider",
+        errorMessage: "Agent turn failed (PROVIDER_BILLING)",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.body).toBe("The model provider did not respond.");
+    expect(copy.vellum?.body).not.toContain("PROVIDER_BILLING");
+  });
+
+  test("readable raw detail is appended to the kind prose", () => {
+    const copy = composeFallbackCopy(
+      failedSignal({
+        jobName: "watcher",
+        errorKind: "exception",
+        errorMessage: "The feed endpoint returned an empty document.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.body).toBe(
+      "It stopped with an error. The feed endpoint returned an empty document.",
+    );
+  });
+
+  test("timeout renders its own prose", () => {
+    const copy = composeFallbackCopy(
+      failedSignal({
+        jobName: "filing",
+        errorKind: "timeout",
+        errorMessage: "Background job 'filing' timed out after 1800000ms",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.body).toContain("It ran out of time before finishing.");
+  });
+});
+
 // ── composeFallbackCopy with requestedMessage ─────────────────────────
 
 describe("composeFallbackCopy honors requestedMessage / requestedTitle", () => {

package/src/notifications/__tests__/destination-resolver.test.ts

@@ -79,6 +79,44 @@ describe("resolveDestinations — gateway guardian list", () => {
     expect(result.has("telegram")).toBe(false);
   });
 
+  test("discord addresses the guardian's user snowflake, never a room id", () => {
+    const list = [
+      guardian({
+        channelType: "discord",
+        address: "111222333444555666",
+        externalChatId: "999888777666555444",
+      }),
+    ];
+    const result = resolveDestinations(["discord"], list);
+    expect(result.get("discord")).toEqual({
+      channel: "discord",
+      endpoint: "111222333444555666",
+      metadata: { externalUserId: "111222333444555666" },
+      bindingContext: {
+        sourceChannel: "discord",
+        externalChatId: "999888777666555444",
+        externalUserId: "111222333444555666",
+      },
+    });
+  });
+
+  test("discord without a binding conversation still resolves the person", () => {
+    const list = [
+      guardian({ channelType: "discord", address: "111222333444555666" }),
+    ];
+    const result = resolveDestinations(["discord"], list);
+    expect(result.get("discord")).toEqual({
+      channel: "discord",
+      endpoint: "111222333444555666",
+      metadata: { externalUserId: "111222333444555666" },
+    });
+  });
+
+  test("discord with no guardian binding is omitted", () => {
+    const result = resolveDestinations(["discord"], []);
+    expect(result.has("discord")).toBe(false);
+  });
+
   test("slack resolves DM endpoint and binding context", () => {
     const list = [
       guardian({

package/src/notifications/activity-failed-dedupe.ts

@@ -0,0 +1,95 @@
+import type { ConversationErrorCode } from "../api/events/conversation-error.js";
+import type { BackgroundJobErrorKind } from "../runtime/background-job-runner.js";
+
+/**
+ * Failure codes whose cause is the whole workspace: the managed route and the
+ * local machine exist once, so every job they hit shares one root cause and
+ * one remedy, whatever provider or profile the job used. These collapse into
+ * a single notification per cause per UTC day.
+ *
+ * Typed against {@link ConversationErrorCode} so a renamed code fails the
+ * build here instead of silently un-collapsing.
+ */
+const WORKSPACE_WIDE_FAILURE_CODES = new Set<string>([
+  "MANAGED_KEY_INVALID",
+  "MANAGED_USAGE_LIMIT",
+  "DISK_SPACE_CRITICAL",
+] satisfies ConversationErrorCode[]);
+
+/**
+ * Failure codes whose cause is one provider account or connection: a billing
+ * lapse, a rejected key, a rate limit, an outage. One workspace can hold
+ * several provider connections with independent remedies, so these collapse
+ * only within a provider scope (see {@link activityFailedDedupeKey}), never
+ * across scopes where the first failure would hide a second one that needs a
+ * different fix.
+ *
+ * Codes in NEITHER set key per job on purpose. A code like
+ * `CONTEXT_TOO_LARGE` or `MAX_TOKENS_REACHED` names a defect in one job's own
+ * prompt or output, and collapsing it would hide a second job's unrelated
+ * failure behind the first's notification. Unknown or future codes default to
+ * per-job for the same reason: an extra notification is recoverable, a hidden
+ * one is not.
+ */
+const PROVIDER_SCOPED_FAILURE_CODES = new Set<string>([
+  "PROVIDER_BILLING",
+  "PROVIDER_NOT_CONFIGURED",
+  "PROVIDER_INVALID_KEY",
+  "PROVIDER_RATE_LIMIT",
+  "PROVIDER_OVERLOADED",
+  "PROVIDER_NETWORK",
+  "PROVIDER_API",
+] satisfies ConversationErrorCode[]);
+
+/**
+ * Dedupe key for a background-job failure notification.
+ *
+ * Workspace-wide failures collapse into one notification per cause per UTC
+ * day, however many jobs fail. Provider-scoped failures collapse within one
+ * provider scope per day, so two provider connections failing for the same
+ * class of reason still surface separately (their remedies differ).
+ * Job-specific failures (timeouts, generic exceptions, and unlisted codes)
+ * keep the per-job key so one job's failure cannot swallow the visibility of
+ * another's.
+ *
+ * `providerScope` is the inference-profile key the failing call actually
+ * resolved through, and only when that key names a single provider route
+ * (both producers derive it via `resolveSingleRouteProfileKey`; a mix
+ * winner has no single route). Callers that cannot name a trustworthy scope
+ * omit it, and provider-scoped failures then key per job:
+ * an extra notification is recoverable, while a false collapse across two
+ * provider routes hides a failure whose remedy differs. The profile is a
+ * transitional stand-in for the provider connection the failure actually hit:
+ * one profile resolves to one connection at a time, so scoping by profile can
+ * split one incident across profiles that share a connection but cannot merge
+ * two connections' incidents. Once the turn boundary carries the classified
+ * `connectionName` (today it keeps only the code), this scope should become
+ * the connection itself.
+ *
+ * Shared by every `activity.failed` producer that reports a classified
+ * background failure (the background-job runner, and the scheduler's
+ * retries-exhausted alert), so a schedule exhausting on the same cause as an
+ * already-reported job failure does not produce a second notification.
+ */
+export function activityFailedDedupeKey(args: {
+  jobName: string;
+  errorKind: BackgroundJobErrorKind;
+  failureCode?: string;
+  providerScope?: string;
+}): string {
+  const day = new Date().toISOString().slice(0, 10);
+  const scope = args.providerScope;
+  if (args.failureCode) {
+    if (WORKSPACE_WIDE_FAILURE_CODES.has(args.failureCode)) {
+      return `activity-failed:cause:${args.failureCode}:${day}`;
+    }
+    if (PROVIDER_SCOPED_FAILURE_CODES.has(args.failureCode) && scope) {
+      return `activity-failed:cause:${args.failureCode}:${scope}:${day}`;
+    }
+    return `activity-failed:${args.jobName}:${day}`;
+  }
+  if (args.errorKind === "model_provider" && scope) {
+    return `activity-failed:cause:model_provider:${scope}:${day}`;
+  }
+  return `activity-failed:${args.jobName}:${day}`;
+}

package/src/notifications/adapters/discord.ts

@@ -0,0 +1,132 @@
+/**
+ * Discord channel adapter: delivers notifications to the guardian's DM by
+ * calling the Discord REST API directly.
+ *
+ * The destination endpoint is the guardian's *user* snowflake, never a stored
+ * channel id: user and channel snowflakes are indistinguishable bare numbers,
+ * so the adapter resolves the DM channel from the person at send time
+ * (cached per user) and a room id on the binding can never become a delivery
+ * target. That is Slack's D-prefix DM gate, achieved by construction.
+ *
+ * Approval notifications carry the typed-command instructions instead of
+ * component buttons: nothing ingests INTERACTION_CREATE yet, and a button
+ * whose press goes nowhere is a dead control. When interaction ingest lands,
+ * buttons arrive here as a rendering upgrade, not a new decision path.
+ */
+
+import { openDiscordDmChannel } from "../../messaging/providers/discord/api.js";
+import {
+  editDiscordMessage,
+  sendDiscordReply,
+} from "../../messaging/providers/discord/send.js";
+import { ConfigError } from "../../util/errors.js";
+import { getLogger } from "../../util/logger.js";
+import type {
+  ChannelAdapter,
+  ChannelDeliveryPayload,
+  ChannelDestination,
+  ChannelUpdateContext,
+  ChannelUpdatePayload,
+  DeliveryResult,
+  NotificationChannel,
+} from "../types.js";
+import { appendPlainTextFallback, resolveMessageText } from "./shared.js";
+
+const log = getLogger("notif-adapter-discord");
+
+export class DiscordAdapter implements ChannelAdapter {
+  readonly channel: NotificationChannel = "discord";
+
+  async send(
+    payload: ChannelDeliveryPayload,
+    destination: ChannelDestination,
+  ): Promise<DeliveryResult> {
+    const guardianUserId = destination.endpoint;
+    if (!guardianUserId) {
+      log.warn(
+        { sourceEventName: payload.sourceEventName },
+        "Discord destination has no guardian user id; skipping",
+      );
+      return {
+        success: false,
+        error: "No guardian user id configured for Discord destination",
+      };
+    }
+
+    const text = appendPlainTextFallback(
+      resolveMessageText(payload),
+      payload.approvalContext,
+    );
+
+    try {
+      const channelId = await openDiscordDmChannel(guardianUserId);
+      const sent = await sendDiscordReply({ channelId }, text);
+
+      log.info(
+        { sourceEventName: payload.sourceEventName, guardianUserId },
+        "Discord notification delivered",
+      );
+
+      // The message id lets the delivery row address the card later
+      // (in-place withdrawal when the request resolves elsewhere).
+      return { success: true, messageId: sent.lastMessageId };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      // A missing bot token means the operator simply hasn't configured
+      // Discord; it is not a code fault, so log it at warn to keep it out
+      // of Sentry. Genuine and transient failures stay at error so they
+      // remain visible.
+      const logFn = err instanceof ConfigError ? log.warn : log.error;
+      logFn(
+        { err, sourceEventName: payload.sourceEventName, guardianUserId },
+        "Failed to deliver Discord notification",
+      );
+      return { success: false, error: message };
+    }
+  }
+
+  /**
+   * Replace a delivered notification in place, so a card that has been
+   * answered or withdrawn stops reading as still waiting.
+   */
+  async update(
+    delivery: ChannelUpdateContext,
+    patch: ChannelUpdatePayload,
+  ): Promise<DeliveryResult> {
+    if (!delivery.messageId) {
+      return {
+        success: false,
+        error:
+          "missing_message_id: this delivery has no captured Discord message id",
+      };
+    }
+    const text = patch.body?.trim() || patch.title?.trim();
+    if (!text) {
+      return { success: false, error: "no body or title supplied for update" };
+    }
+    try {
+      // The delivery row's destination is the guardian's user snowflake, so
+      // the edit resolves the same cached DM channel the send used.
+      const channelId = await openDiscordDmChannel(delivery.destination);
+      await editDiscordMessage({ channelId }, delivery.messageId, text);
+      log.info(
+        { guardianUserId: delivery.destination, messageId: delivery.messageId },
+        "Discord notification updated",
+      );
+      // An edit keeps the message it addressed, so the delivery row's id
+      // still identifies the card.
+      return { success: true, messageId: delivery.messageId };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error(
+        {
+          err,
+          guardianUserId: delivery.destination,
+          messageId: delivery.messageId,
+        },
+        "Failed to update Discord notification",
+      );
+      return { success: false, error: message };
+    }
+  }
+}

package/src/notifications/adapters/shared.ts

@@ -33,3 +33,19 @@ export function resolveMessageText(payload: ChannelDeliveryPayload): string {
 
   return payload.sourceEventName.replace(/[._]/g, " ");
 }
+
+/**
+ * Append an approval's typed-command instructions to the message text, when
+ * the copy does not already carry them. Used by adapters delivering an
+ * approval without live buttons (Discord always; Telegram when its rich
+ * delivery fails), so the guardian still knows how to decide.
+ */
+export function appendPlainTextFallback(
+  text: string,
+  approval: ChannelDeliveryPayload["approvalContext"],
+): string {
+  return approval?.plainTextFallback &&
+    !text.includes(approval.plainTextFallback)
+    ? `${text}\n\n${approval.plainTextFallback}`
+    : text;
+}

package/src/notifications/adapters/slack.ts

@@ -355,7 +355,12 @@ function buildToolApprovalCardBlocks(
     type: "card",
     title: {
       type: "mrkdwn",
-      text: details ? "Tool Approval" : "Approval Request",
+      text:
+        approval.intent === "question"
+          ? "Question"
+          : details
+            ? "Tool Approval"
+            : "Approval Request",
     },
     body: { type: "mrkdwn", text: head },
     actions: buildCardActions(approval),