@vellumai/assistant 0.5.6 → 0.5.8

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

@@ -9,7 +9,10 @@ import { fileURLToPath } from "node:url";
 
 import { getBaseDataDir } from "../../config/env-registry.js";
 import { parseIdentityFields } from "../../daemon/handlers/identity.js";
-import { getWorkspacePromptPath, readLockfile } from "../../util/platform.js";
+import { getMaxMigrationVersion } from "../../memory/migrations/registry.js";
+import { getWorkspacePromptPath } from "../../util/platform.js";
+import { WORKSPACE_MIGRATIONS } from "../../workspace/migrations/registry.js";
+import { getLastWorkspaceMigrationId } from "../../workspace/migrations/runner.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
 import { getCachedIntro } from "./identity-intro-cache.js";
@@ -86,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();
@@ -133,6 +136,10 @@ function getPackageVersion(): string | undefined {
 }
 
 export function handleHealth(): Response {
+  return Response.json({ status: "ok" });
+}
+
+export function handleDetailedHealth(): Response {
   return Response.json({
     status: "healthy",
     timestamp: new Date().toISOString(),
@@ -140,9 +147,18 @@ export function handleHealth(): Response {
     disk: getDiskSpaceInfo(),
     memory: getMemoryInfo(),
     cpu: getCpuInfo(),
+    migrations: {
+      dbVersion: getMaxMigrationVersion(),
+      lastWorkspaceMigrationId:
+        getLastWorkspaceMigrationId(WORKSPACE_MIGRATIONS),
+    },
   });
 }
 
+export function handleReadyz(): Response {
+  return Response.json({ status: "ok" });
+}
+
 export function handleGetIdentity(): Response {
   const identityPath = getWorkspacePromptPath("IDENTITY.md");
   if (!existsSync(identityPath)) {
@@ -163,31 +179,6 @@ export function handleGetIdentity(): Response {
     // ignore
   }
 
-  // Read lockfile for assistantId, cloud, and originSystem
-  let assistantId: string | undefined;
-  let cloud: string | undefined;
-  let originSystem: string | undefined;
-  try {
-    const lockData = readLockfile();
-    const assistants = lockData?.assistants as
-      | Array<Record<string, unknown>>
-      | undefined;
-    if (assistants && assistants.length > 0) {
-      // Use the most recently hatched assistant
-      const sorted = [...assistants].sort((a, b) => {
-        const dateA = new Date((a.hatchedAt as string) || 0).getTime();
-        const dateB = new Date((b.hatchedAt as string) || 0).getTime();
-        return dateB - dateA;
-      });
-      const latest = sorted[0];
-      assistantId = latest.assistantId as string | undefined;
-      cloud = latest.cloud as string | undefined;
-      originSystem = cloud === "local" ? "local" : cloud;
-    }
-  } catch {
-    // ignore -- lockfile may not exist
-  }
-
   return Response.json({
     name: fields.name ?? "",
     role: fields.role ?? "",
@@ -195,9 +186,7 @@ export function handleGetIdentity(): Response {
     emoji: fields.emoji ?? "",
     home: fields.home ?? "",
     version,
-    assistantId,
     createdAt,
-    originSystem,
   });
 }
 
@@ -255,7 +244,7 @@ export function identityRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "health",
       method: "GET",
-      handler: () => handleHealth(),
+      handler: () => handleDetailedHealth(),
     },
     {
       endpoint: "identity",

package/src/runtime/routes/inbound-message-handler.ts

@@ -507,6 +507,15 @@ export async function handleChannelInbound(
     !result.duplicate &&
     !guardianReplyResult.skipApprovalInterception
   ) {
+    // Extract the original approval message timestamp for Slack button
+    // cleanup. When a Slack block_actions payload is forwarded, the gateway
+    // sets sourceMetadata.messageId to the ts of the message containing
+    // the button. This lets us edit the message after resolution.
+    const approvalMessageTs =
+      sourceChannel === "slack" && typeof sourceMetadata?.messageId === "string"
+        ? sourceMetadata.messageId
+        : undefined;
+
     const approvalResult = await handleApprovalInterception({
       conversationId: result.conversationId,
       callbackData: body.callbackData,
@@ -520,6 +529,7 @@ export async function handleChannelInbound(
       assistantId: canonicalAssistantId,
       approvalCopyGenerator,
       approvalConversationGenerator,
+      approvalMessageTs,
     });
 
     if (approvalResult.handled) {
@@ -598,6 +608,27 @@ export async function handleChannelInbound(
         }
       }
 
+      // On Slack, edit the original approval message to remove stale buttons
+      // and deliver an ephemeral error so the user gets visible feedback
+      // instead of a silent no-op (JARVIS-299).
+      if (sourceChannel === "slack" && replyCallbackUrl && approvalMessageTs) {
+        deliverChannelReply(
+          replyCallbackUrl,
+          {
+            chatId: conversationExternalId,
+            text: "This approval request has been resolved.",
+            messageTs: approvalMessageTs,
+            assistantId: canonicalAssistantId,
+          },
+          mintBearerToken(),
+        ).catch((err) => {
+          log.error(
+            { err, conversationId: result.conversationId },
+            "Failed to edit stale Slack approval message",
+          );
+        });
+      }
+
       return Response.json({
         accepted: true,
         duplicate: false,
@@ -650,7 +681,6 @@ export async function handleChannelInbound(
       mintBearerToken,
       assistantId: canonicalAssistantId,
       approvalCopyGenerator,
-      externalMessageId: sourceMessageId ?? externalMessageId,
       chatType: sourceChatType,
     });
   }