@vellumai/assistant 0.5.7 → 0.5.8

package/src/runtime/routes/approval-strategies/guardian-text-engine-strategy.ts

@@ -22,6 +22,17 @@ import { deliverStaleApprovalReply } from "../guardian-approval-reply-helpers.js
 
 const log = getLogger("runtime-http");
 
+/**
+ * Resolve the Slack ephemeral user ID when the source channel is Slack.
+ * Returns `undefined` for non-Slack channels.
+ */
+function slackEphemeralUserId(
+  sourceChannel: ChannelId,
+  userId: string | undefined,
+): string | undefined {
+  return sourceChannel === "slack" && userId ? userId : undefined;
+}
+
 export interface TextEngineDecisionParams {
   conversationId: string;
   conversationExternalId: string;
@@ -36,6 +47,8 @@ export interface TextEngineDecisionParams {
   pending: Array<{ requestId: string; toolName: string }>;
   /** Allowed actions from the pending prompt. */
   allowedActions: string[];
+  /** External user ID of the actor (for Slack ephemeral routing). */
+  actorExternalId?: string;
 }
 
 /**
@@ -58,6 +71,7 @@ export async function handleGuardianTextEngineDecision(
     approvalConversationGenerator,
     pending,
     allowedActions,
+    actorExternalId,
   } = params;
 
   const engineContext: ApprovalConversationContext = {
@@ -79,13 +93,19 @@ export async function handleGuardianTextEngineDecision(
   if (engineResult.disposition === "keep_pending") {
     // Non-decision follow-up — deliver the engine's reply and keep the request pending
     try {
+      const keepPendingPayload: Parameters<typeof deliverChannelReply>[1] = {
+        chatId: conversationExternalId,
+        text: engineResult.replyText,
+        assistantId,
+      };
+      const ephemeral = slackEphemeralUserId(sourceChannel, actorExternalId);
+      if (ephemeral) {
+        keepPendingPayload.ephemeral = true;
+        keepPendingPayload.user = ephemeral;
+      }
       await deliverChannelReply(
         replyCallbackUrl,
-        {
-          chatId: conversationExternalId,
-          text: engineResult.replyText,
-          assistantId,
-        },
+        keepPendingPayload,
         bearerToken,
       );
     } catch (err) {
@@ -112,15 +132,17 @@ export async function handleGuardianTextEngineDecision(
   if (result.applied) {
     // Deliver the engine's reply text to the user
     try {
-      await deliverChannelReply(
-        replyCallbackUrl,
-        {
-          chatId: conversationExternalId,
-          text: engineResult.replyText,
-          assistantId,
-        },
-        bearerToken,
-      );
+      const decisionPayload: Parameters<typeof deliverChannelReply>[1] = {
+        chatId: conversationExternalId,
+        text: engineResult.replyText,
+        assistantId,
+      };
+      const ephemeral = slackEphemeralUserId(sourceChannel, actorExternalId);
+      if (ephemeral) {
+        decisionPayload.ephemeral = true;
+        decisionPayload.user = ephemeral;
+      }
+      await deliverChannelReply(replyCallbackUrl, decisionPayload, bearerToken);
     } catch (err) {
       log.error(
         { err, conversationId },
@@ -145,6 +167,7 @@ export async function handleGuardianTextEngineDecision(
     logger: log,
     errorLogMessage: "Failed to deliver stale approval notice",
     errorLogContext: { conversationId },
+    ephemeralUserId: slackEphemeralUserId(sourceChannel, actorExternalId),
   });
 
   return { handled: true, type: "stale_ignored" };

package/src/runtime/routes/channel-readiness-routes.ts

@@ -63,10 +63,15 @@ export async function handleGetChannelReadiness(url: URL): Promise<Response> {
 export async function handleRefreshChannelReadiness(
   req: Request,
 ): Promise<Response> {
-  const body = (await req.json().catch(() => ({}))) as {
-    channel?: ChannelId;
-    includeRemote?: boolean;
-  };
+  let body: { channel?: ChannelId; includeRemote?: boolean };
+  try {
+    body = (await req.json()) as typeof body;
+  } catch {
+    return Response.json(
+      { success: false, error: "Invalid JSON in request body" },
+      { status: 400 },
+    );
+  }
 
   const service = getReadinessService();
 

package/src/runtime/routes/debug-routes.ts

@@ -8,7 +8,10 @@ import { getConfig } from "../../config/loader.js";
 import { countConversations } from "../../memory/conversation-queries.js";
 import { rawAll } from "../../memory/db.js";
 import { getMemoryJobCounts } from "../../memory/jobs-store.js";
-import { getProviderDebugStatus } from "../../providers/registry.js";
+import {
+  getProviderRoutingSource,
+  listProviders,
+} from "../../providers/registry.js";
 import { countSchedules } from "../../schedule/schedule-store.js";
 import { getDbPath } from "../../util/platform.js";
 import type { RouteDefinition } from "../http-router.js";
@@ -48,13 +51,11 @@ function handleDebug(): Response {
   const scheduleCounts = countSchedules();
 
   const config = getConfig();
-  const providerOrder = Array.isArray(config.providerOrder)
-    ? config.providerOrder
-    : [];
-  const providerStatus = getProviderDebugStatus(
-    config.services.inference.provider,
-    providerOrder,
-  );
+  const registeredProviders = listProviders();
+  const routingSources: Record<string, string | undefined> = {};
+  for (const name of registeredProviders) {
+    routingSources[name] = getProviderRoutingSource(name);
+  }
 
   return Response.json({
     session: {
@@ -62,7 +63,9 @@ function handleDebug(): Response {
       startedAt: new Date(startedAt).toISOString(),
     },
     provider: {
-      ...providerStatus,
+      configuredProvider: config.services.inference.provider,
+      registeredProviders,
+      routingSources,
       inferenceMode: config.services.inference.mode,
     },
     memory: {

package/src/runtime/routes/guardian-approval-interception.ts

@@ -42,6 +42,18 @@ import { deliverStaleApprovalReply } from "./guardian-approval-reply-helpers.js"
 
 const log = getLogger("runtime-http");
 
+/**
+ * Resolve the Slack ephemeral user ID when the source channel is Slack.
+ * Returns `undefined` for non-Slack channels so callers can pass the
+ * result directly to `ephemeralUserId` without branching.
+ */
+function slackEphemeralUserId(
+  sourceChannel: ChannelId,
+  userId: string | undefined,
+): string | undefined {
+  return sourceChannel === "slack" && userId ? userId : undefined;
+}
+
 export interface ApprovalInterceptionParams {
   conversationId: string;
   callbackData?: string;
@@ -55,6 +67,8 @@ export interface ApprovalInterceptionParams {
   assistantId: string;
   approvalCopyGenerator?: ApprovalCopyGenerator;
   approvalConversationGenerator?: ApprovalConversationGenerator;
+  /** Original approval message timestamp (Slack ts) for editing after resolution. */
+  approvalMessageTs?: string;
 }
 
 export interface ApprovalInterceptionResult {
@@ -92,6 +106,7 @@ export async function handleApprovalInterception(
     assistantId,
     approvalCopyGenerator,
     approvalConversationGenerator,
+    approvalMessageTs,
   } = params;
 
   // ── Guardian approval decision path ──
@@ -110,6 +125,7 @@ export async function handleApprovalInterception(
       assistantId,
       approvalCopyGenerator,
       approvalConversationGenerator,
+      approvalMessageTs,
     });
     if (guardianResult) {
       return guardianResult;
@@ -262,13 +278,23 @@ export async function handleApprovalInterception(
                   approvalCopyGenerator,
                 ));
               try {
-                await deliverChannelReply(
-                  replyCallbackUrl,
+                const cancelPayload: Parameters<typeof deliverChannelReply>[1] =
                   {
                     chatId: conversationExternalId,
                     text: replyText,
                     assistantId,
-                  },
+                  };
+                const requesterEphemeral = slackEphemeralUserId(
+                  sourceChannel,
+                  actorExternalId,
+                );
+                if (requesterEphemeral) {
+                  cancelPayload.ephemeral = true;
+                  cancelPayload.user = requesterEphemeral;
+                }
+                await deliverChannelReply(
+                  replyCallbackUrl,
+                  cancelPayload,
                   bearerToken,
                 );
               } catch (err) {
@@ -290,13 +316,24 @@ export async function handleApprovalInterception(
                   {},
                   approvalCopyGenerator,
                 );
+                const guardianCancelPayload: Parameters<
+                  typeof deliverChannelReply
+                >[1] = {
+                  chatId: guardianApprovalForRequest.guardianChatId,
+                  text: guardianNotice,
+                  assistantId,
+                };
+                const guardianEphemeral = slackEphemeralUserId(
+                  sourceChannel,
+                  guardianApprovalForRequest.guardianExternalUserId,
+                );
+                if (guardianEphemeral) {
+                  guardianCancelPayload.ephemeral = true;
+                  guardianCancelPayload.user = guardianEphemeral;
+                }
                 await deliverChannelReply(
                   replyCallbackUrl,
-                  {
-                    chatId: guardianApprovalForRequest.guardianChatId,
-                    text: guardianNotice,
-                    assistantId,
-                  },
+                  guardianCancelPayload,
                   bearerToken,
                 );
               } catch (err) {
@@ -322,19 +359,33 @@ export async function handleApprovalInterception(
               errorLogMessage:
                 "Failed to deliver stale requester-cancel notice",
               errorLogContext: { conversationId },
+              ephemeralUserId: slackEphemeralUserId(
+                sourceChannel,
+                actorExternalId,
+              ),
             });
             return { handled: true, type: "stale_ignored" };
           }
 
           if (requesterFollowupReplyText) {
             try {
-              await deliverChannelReply(
-                replyCallbackUrl,
+              const followupPayload: Parameters<typeof deliverChannelReply>[1] =
                 {
                   chatId: conversationExternalId,
                   text: requesterFollowupReplyText,
                   assistantId,
-                },
+                };
+              const followupEphemeral = slackEphemeralUserId(
+                sourceChannel,
+                actorExternalId,
+              );
+              if (followupEphemeral) {
+                followupPayload.ephemeral = true;
+                followupPayload.user = followupEphemeral;
+              }
+              await deliverChannelReply(
+                replyCallbackUrl,
+                followupPayload,
                 bearerToken,
               );
             } catch (err) {
@@ -360,6 +411,7 @@ export async function handleApprovalInterception(
           errorLogMessage:
             "Failed to deliver guardian-pending notice to requester",
           errorLogContext: { conversationId },
+          ephemeralUserId: slackEphemeralUserId(sourceChannel, actorExternalId),
         });
         return { handled: true, type: "assistant_turn" };
       }
@@ -394,6 +446,7 @@ export async function handleApprovalInterception(
             "Failed to deliver guardian-expiry notice to requester",
           extraContext: { toolName: pending[0].toolName },
           errorLogContext: { conversationId },
+          ephemeralUserId: slackEphemeralUserId(sourceChannel, actorExternalId),
         });
         return { handled: true, type: "decision_applied" };
       }
@@ -430,6 +483,7 @@ export async function handleApprovalInterception(
           errorLogMessage:
             "Failed to deliver guardian-pending notice to non-guardian actor (pre-row guard)",
           errorLogContext: { conversationId },
+          ephemeralUserId: slackEphemeralUserId(sourceChannel, actorExternalId),
         });
         return { handled: true, type: "assistant_turn" };
       }
@@ -478,6 +532,19 @@ export async function handleApprovalInterception(
             { conversationId, callbackRequestId: cbDecision.requestId },
             "Callback request ID does not match any pending interaction, ignoring stale button press",
           );
+
+          // Edit the original Slack approval message to remove stale buttons
+          if (sourceChannel === "slack" && approvalMessageTs) {
+            editStaleSlackApprovalMessage({
+              replyCallbackUrl,
+              chatId: conversationExternalId,
+              messageTs: approvalMessageTs,
+              assistantId,
+              bearerToken,
+              conversationId,
+            });
+          }
+
           return { handled: true, type: "stale_ignored" };
         }
       }
@@ -485,6 +552,32 @@ export async function handleApprovalInterception(
       const result = handleChannelDecision(conversationId, cbDecision);
 
       if (result.applied) {
+        // Edit the original Slack approval message to show the decision
+        // and remove stale action buttons.
+        if (sourceChannel === "slack" && approvalMessageTs) {
+          const decisionOutcome: "approved" | "denied" =
+            cbDecision.action === "reject" ? "denied" : "approved";
+          const statusEmoji =
+            decisionOutcome === "approved" ? "\u2713" : "\u2717";
+          const statusLabel =
+            decisionOutcome === "approved" ? "Approved" : "Denied";
+          deliverChannelReply(
+            replyCallbackUrl,
+            {
+              chatId: conversationExternalId,
+              text: `${statusEmoji} ${statusLabel}`,
+              messageTs: approvalMessageTs,
+              assistantId,
+            },
+            bearerToken,
+          ).catch((err) => {
+            log.error(
+              { err, conversationId, messageTs: approvalMessageTs },
+              "Failed to edit Slack approval message after decision",
+            );
+          });
+        }
+
         // Post-decision delivery is handled by the onEvent callback
         // in the session that registered the pending interaction.
         return { handled: true, type: "decision_applied" };
@@ -492,6 +585,18 @@ export async function handleApprovalInterception(
 
       // Race condition: request was already resolved between the stale check
       // above and the decision attempt.
+      // Edit the original Slack approval message to remove stale buttons
+      if (sourceChannel === "slack" && approvalMessageTs) {
+        editStaleSlackApprovalMessage({
+          replyCallbackUrl,
+          chatId: conversationExternalId,
+          messageTs: approvalMessageTs,
+          assistantId,
+          bearerToken,
+          conversationId,
+        });
+      }
+
       return { handled: true, type: "stale_ignored" };
     }
   }
@@ -514,6 +619,7 @@ export async function handleApprovalInterception(
       approvalConversationGenerator,
       pending,
       allowedActions,
+      actorExternalId,
     });
   }
 
@@ -556,7 +662,58 @@ export async function handleApprovalInterception(
       toolName: pending.length > 0 ? pending[0].toolName : undefined,
     },
     errorLogContext: { conversationId },
+    ephemeralUserId: slackEphemeralUserId(sourceChannel, actorExternalId),
   });
 
   return { handled: true, type: "assistant_turn" };
 }
+
+// ---------------------------------------------------------------------------
+// Slack approval message edit helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Fire-and-forget: edit a stale Slack approval message to indicate it has
+ * been resolved and remove the action buttons. Used when a button click
+ * arrives for an already-resolved approval.
+ */
+function editStaleSlackApprovalMessage(params: {
+  replyCallbackUrl: string;
+  chatId: string;
+  messageTs: string;
+  assistantId: string;
+  bearerToken?: string;
+  conversationId: string;
+}): void {
+  const statusText = "This approval request has been resolved.";
+  const blocks = [
+    {
+      type: "section",
+      text: { type: "mrkdwn", text: statusText },
+    },
+    {
+      type: "context",
+      elements: [{ type: "mrkdwn", text: statusText }],
+    },
+  ];
+  deliverChannelReply(
+    params.replyCallbackUrl,
+    {
+      chatId: params.chatId,
+      text: statusText,
+      blocks,
+      messageTs: params.messageTs,
+      assistantId: params.assistantId,
+    },
+    params.bearerToken,
+  ).catch((err) => {
+    log.error(
+      {
+        err,
+        conversationId: params.conversationId,
+        messageTs: params.messageTs,
+      },
+      "Failed to edit stale Slack approval message",
+    );
+  });
+}

package/src/runtime/routes/guardian-approval-prompt.ts

@@ -14,6 +14,7 @@ import {
   deliverApprovalPrompt,
   deliverChannelReply,
 } from "../gateway-client.js";
+import { buildActionLegend } from "../guardian-decision-types.js";
 import type { ApprovalCopyGenerator } from "../http-types.js";
 import { requiredDecisionKeywords } from "./channel-route-shared.js";
 
@@ -60,11 +61,15 @@ export async function deliverGeneratedApprovalPrompt(
       approvalCopyGenerator,
     );
 
+    // Append a legend explaining what each button does
+    const legend = buildActionLegend(uiMetadata.actions);
+    const richTextWithLegend = legend ? `${richText}\n\n${legend}` : richText;
+
     try {
       await deliverApprovalPrompt(
         replyCallbackUrl,
         chatId,
-        richText,
+        richTextWithLegend,
         uiMetadata,
         assistantId,
         bearerToken,

package/src/runtime/routes/guardian-approval-reply-helpers.ts

@@ -11,6 +11,25 @@ import { composeApprovalMessageGenerative } from "../approval-message-composer.j
 import { deliverChannelReply } from "../gateway-client.js";
 import type { ApprovalCopyGenerator } from "../http-types.js";
 
+// ---------------------------------------------------------------------------
+// Deduplication for "already resolved" ephemeral messages
+// ---------------------------------------------------------------------------
+
+/**
+ * Tracks recently sent stale approval notifications to prevent flooding the
+ * user when they rapidly click stale approval buttons. Keyed by
+ * `${chatId}:${scenario}` with a 30-second TTL per entry.
+ */
+const recentStaleNotifications = new Set<string>();
+
+/** TTL in milliseconds for dedup entries. Exported for testing. */
+export const STALE_DEDUP_TTL_MS = 30_000;
+
+/** Clear the dedup cache. Exported for testing only. */
+export function clearStaleNotificationCache(): void {
+  recentStaleNotifications.clear();
+}
+
 interface DeliverApprovalReplyParams {
   context: ApprovalMessageContext;
   replyCallbackUrl: string;
@@ -22,14 +41,19 @@ interface DeliverApprovalReplyParams {
   errorLogMessage: string;
   /** Extra fields merged into the pino error context. */
   errorLogContext?: Record<string, unknown>;
+  /**
+   * When set, deliver via `chat.postEphemeral` so only this Slack user
+   * sees the message. Used to keep approval-related noise out of shared
+   * channels.
+   */
+  ephemeralUserId?: string;
 }
 
 /**
  * Compose a generative approval message and deliver it as a channel reply.
- * Swallows delivery errors and logs them — callers don't need their own
- * try/catch blocks.
+ * Throws on failure — callers decide whether to swallow or propagate.
  */
-async function deliverApprovalReply(
+async function composeAndDeliver(
   params: DeliverApprovalReplyParams,
 ): Promise<void> {
   const {
@@ -39,24 +63,41 @@ async function deliverApprovalReply(
     assistantId,
     bearerToken,
     approvalCopyGenerator,
-    logger,
-    errorLogMessage,
-    errorLogContext,
+    ephemeralUserId,
   } = params;
 
+  const text = await composeApprovalMessageGenerative(
+    context,
+    {},
+    approvalCopyGenerator,
+  );
+  const payload: Parameters<typeof deliverChannelReply>[1] = {
+    chatId,
+    text,
+    assistantId,
+  };
+  if (ephemeralUserId) {
+    payload.ephemeral = true;
+    payload.user = ephemeralUserId;
+  }
+  await deliverChannelReply(replyCallbackUrl, payload, bearerToken);
+}
+
+/**
+ * Compose a generative approval message and deliver it as a channel reply.
+ * Swallows delivery errors and logs them — callers don't need their own
+ * try/catch blocks.
+ */
+async function deliverApprovalReply(
+  params: DeliverApprovalReplyParams,
+): Promise<void> {
   try {
-    const text = await composeApprovalMessageGenerative(
-      context,
-      {},
-      approvalCopyGenerator,
-    );
-    await deliverChannelReply(
-      replyCallbackUrl,
-      { chatId, text, assistantId },
-      bearerToken,
-    );
+    await composeAndDeliver(params);
   } catch (err) {
-    logger.error({ err, ...errorLogContext }, errorLogMessage);
+    params.logger.error(
+      { err, ...params.errorLogContext },
+      params.errorLogMessage,
+    );
   }
 }
 
@@ -78,25 +119,60 @@ export interface DeliverStaleApprovalReplyParams {
   extraContext?: Partial<ApprovalMessageContext>;
   /** Extra fields merged into the pino error context. */
   errorLogContext?: Record<string, unknown>;
+  /**
+   * When set, deliver via `chat.postEphemeral` so only this Slack user
+   * sees the message. Keeps approval noise out of shared channels.
+   */
+  ephemeralUserId?: string;
 }
 
 /**
  * Deliver a stale/already-resolved approval notice to a channel chat.
  * Consolidates the repeated compose + deliver + try/catch pattern.
+ *
+ * For `approval_already_resolved` scenarios, deduplicates notifications
+ * per chat so rapid stale button clicks don't flood the user with
+ * repeated ephemeral warnings.
  */
 export async function deliverStaleApprovalReply(
   params: DeliverStaleApprovalReplyParams,
 ): Promise<void> {
-  const { scenario, sourceChannel, extraContext, ...rest } = params;
+  const { scenario, sourceChannel, extraContext, ephemeralUserId, ...rest } =
+    params;
 
-  await deliverApprovalReply({
+  const replyParams: DeliverApprovalReplyParams = {
     ...rest,
+    ephemeralUserId,
     context: {
       scenario,
       channel: sourceChannel,
       ...extraContext,
     },
-  });
+  };
+
+  // Deduplicate "already resolved" ephemeral messages per chat.
+  // If the same (chatId, scenario) pair was notified within the TTL, skip.
+  if (scenario === "approval_already_resolved") {
+    const dedupeKey = `${rest.chatId}:${scenario}`;
+    if (recentStaleNotifications.has(dedupeKey)) {
+      return;
+    }
+
+    // Cache the dedup key only after successful delivery so that failures
+    // don't silently suppress retries for the TTL window.
+    try {
+      await composeAndDeliver(replyParams);
+      recentStaleNotifications.add(dedupeKey);
+      setTimeout(() => {
+        recentStaleNotifications.delete(dedupeKey);
+      }, STALE_DEDUP_TTL_MS);
+    } catch (err) {
+      rest.logger.error({ err, ...rest.errorLogContext }, rest.errorLogMessage);
+    }
+    return;
+  }
+
+  await deliverApprovalReply(replyParams);
 }
 
 // ---------------------------------------------------------------------------
@@ -114,6 +190,11 @@ export interface DeliverIdentityMismatchReplyParams {
   errorLogMessage: string;
   /** Extra fields merged into the pino error context. */
   errorLogContext?: Record<string, unknown>;
+  /**
+   * When set, deliver via `chat.postEphemeral` so only this Slack user
+   * sees the message.
+   */
+  ephemeralUserId?: string;
 }
 
 /**
@@ -123,10 +204,11 @@ export interface DeliverIdentityMismatchReplyParams {
 export async function deliverIdentityMismatchReply(
   params: DeliverIdentityMismatchReplyParams,
 ): Promise<void> {
-  const { sourceChannel, ...rest } = params;
+  const { sourceChannel, ephemeralUserId, ...rest } = params;
 
   await deliverApprovalReply({
     ...rest,
+    ephemeralUserId,
     context: {
       scenario: "guardian_identity_mismatch",
       channel: sourceChannel,

package/src/runtime/routes/identity-routes.ts

@@ -89,7 +89,7 @@ interface CpuInfo {
   maxCores: number;
 }
 
-// Track CPU usage over a rolling window so /healthz reports near-real-time
+// Track CPU usage over a rolling window so /v1/health reports near-real-time
 // utilization instead of a lifetime average (total CPU time / total uptime).
 const CPU_SAMPLE_INTERVAL_MS = 5_000;
 let _lastCpuUsage: NodeJS.CpuUsage = process.cpuUsage();