@vellumai/assistant 0.5.7 → 0.5.8

package/src/runtime/auth/__tests__/guard-tests.test.ts

@@ -16,6 +16,10 @@ import { readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { describe, expect, test } from "bun:test";
 
+// Cross-package import: gateway duplicates the epoch constant and both must
+// stay in sync. Importing directly is more reliable than regex-extracting.
+import { CURRENT_POLICY_EPOCH as GATEWAY_POLICY_EPOCH } from "../../../../../gateway/src/auth/policy.js";
+import { CURRENT_POLICY_EPOCH } from "../policy.js";
 import { resolveScopeProfile } from "../scopes.js";
 import type { Scope, ScopeProfile } from "../types.js";
 
@@ -337,56 +341,11 @@ describe("scope profile contract", () => {
 // ---------------------------------------------------------------------------
 
 describe("CURRENT_POLICY_EPOCH sync", () => {
-  /**
-   * The policy epoch constant is duplicated in assistant, gateway, and cli
-   * packages. This test reads the exported value from each source file and
-   * asserts they are all equal.
-   */
-
-  const EPOCH_FILES = [
-    {
-      label: "assistant",
-      path: resolve(PROJECT_ROOT, "assistant/src/runtime/auth/policy.ts"),
-    },
-    {
-      label: "gateway",
-      path: resolve(PROJECT_ROOT, "gateway/src/auth/policy.ts"),
-    },
-  ];
-
-  function extractEpoch(filePath: string): number {
-    const src = readFileSync(filePath, "utf-8");
-    const match = src.match(
-      /export\s+const\s+CURRENT_POLICY_EPOCH\s*=\s*(\d+)/,
-    );
-    if (!match) {
-      throw new Error(`Could not find CURRENT_POLICY_EPOCH in ${filePath}`);
-    }
-    return parseInt(match[1], 10);
-  }
-
-  test("all non-skill packages export the same CURRENT_POLICY_EPOCH value", () => {
-    const values = EPOCH_FILES.map((f) => ({
-      label: f.label,
-      epoch: extractEpoch(f.path),
-    }));
-
-    const canonical = values[0];
-    const mismatches = values.filter((v) => v.epoch !== canonical.epoch);
-
-    if (mismatches.length > 0) {
-      const summary = values
-        .map((v) => `  - ${v.label}: ${v.epoch}`)
-        .join("\n");
-      const message = [
-        "CURRENT_POLICY_EPOCH is out of sync across packages:",
-        "",
-        summary,
-        "",
-        "All locations must have the same value.",
+  test("assistant and gateway export the same CURRENT_POLICY_EPOCH value", () => {
+    expect(
+      CURRENT_POLICY_EPOCH,
+      `CURRENT_POLICY_EPOCH mismatch: assistant=${CURRENT_POLICY_EPOCH}, gateway=${GATEWAY_POLICY_EPOCH}. ` +
         "The canonical source is assistant/src/runtime/auth/policy.ts.",
-      ].join("\n");
-      expect(mismatches, message).toEqual([]);
-    }
+    ).toBe(GATEWAY_POLICY_EPOCH);
   });
 });

package/src/runtime/auth/route-policy.ts

@@ -259,6 +259,8 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
 
   // Secrets
   { endpoint: "secrets", scopes: ["settings.write"] },
+  { endpoint: "secrets:GET", scopes: ["settings.read"] },
+  { endpoint: "secrets/read", scopes: ["settings.write"] },
 
   // Pairing (authenticated)
   { endpoint: "pairing/register", scopes: ["settings.write"] },

package/src/runtime/gateway-client.ts

@@ -6,6 +6,24 @@ import type { RuntimeAttachmentMetadata } from "./http-types.js";
 
 const log = getLogger("gateway-client");
 
+/**
+ * Error thrown when the gateway returns a non-OK response for channel delivery.
+ * Carries the optional `userMessage` field from the gateway so callers can
+ * surface actionable error text to end-users.
+ */
+export class ChannelDeliveryError extends Error {
+  readonly statusCode: number;
+  /** A user-facing error message from the gateway, if available. */
+  readonly userMessage?: string;
+
+  constructor(statusCode: number, body: string, userMessage?: string) {
+    super(`Channel reply delivery failed (${statusCode}): ${body}`);
+    this.name = "ChannelDeliveryError";
+    this.statusCode = statusCode;
+    this.userMessage = userMessage;
+  }
+}
+
 const DELIVERY_TIMEOUT_MS = 30_000;
 const MANAGED_OUTBOUND_SEND_PATH =
   "/v1/internal/managed-gateway/outbound-send/";
@@ -37,6 +55,8 @@ export interface ChannelReplyPayload {
   useBlocks?: boolean;
   /** When provided, add or remove an emoji reaction on a message. */
   reaction?: { action: "add" | "remove"; name: string; messageTs: string };
+  /** When provided, set or clear the Slack Assistants API thread status. */
+  assistantThreadStatus?: { channel: string; threadTs: string; status: string };
 }
 
 export interface ChannelDeliveryResult {
@@ -81,13 +101,36 @@ export async function deliverChannelReply(
 
   if (!response.ok) {
     const body = await response.text().catch(() => "<unreadable>");
+
+    // Try to extract userMessage from JSON error responses (e.g. from the
+    // Slack delivery endpoint) so callers can surface actionable errors.
+    let userMessage: string | undefined;
+    try {
+      const parsed = JSON.parse(body) as { userMessage?: string };
+      if (typeof parsed.userMessage === "string") {
+        userMessage = parsed.userMessage;
+      }
+    } catch {
+      // Body wasn't JSON — that's fine, userMessage stays undefined.
+    }
+
     log.error(
-      { status: response.status, body, callbackUrl, chatId: payload.chatId },
+      {
+        status: response.status,
+        body,
+        callbackUrl,
+        chatId: payload.chatId,
+        ...(userMessage && { userMessage }),
+      },
       "Channel reply delivery failed",
     );
-    throw new Error(
-      `Channel reply delivery failed (${response.status}): ${body}`,
-    );
+    if (userMessage) {
+      log.warn(
+        { chatId: payload.chatId, userMessage },
+        "Gateway returned actionable error for user",
+      );
+    }
+    throw new ChannelDeliveryError(response.status, body, userMessage);
   }
 
   const result: ChannelDeliveryResult = { ok: true };

package/src/runtime/guardian-decision-types.ts

@@ -38,6 +38,8 @@ export interface GuardianDecisionAction {
   action: string;
   /** Human-readable label for the action. */
   label: string;
+  /** Short explanation shown in rich-UI legends (Telegram, Slack). */
+  description?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -46,14 +48,27 @@ export interface GuardianDecisionAction {
 
 /** Canonical set of all guardian decision actions with their labels. */
 export const GUARDIAN_DECISION_ACTIONS = {
-  approve_once: { action: "approve_once", label: "Approve once" },
-  approve_10m: { action: "approve_10m", label: "Allow 10 min" },
+  approve_once: {
+    action: "approve_once",
+    label: "Approve once",
+    description: "This tool, this call only",
+  },
+  approve_10m: {
+    action: "approve_10m",
+    label: "Allow 10 min",
+    description: "All tools for 10 minutes",
+  },
   approve_conversation: {
     action: "approve_conversation",
     label: "Allow conversation",
+    description: "All tools for this conversation",
+  },
+  approve_always: {
+    action: "approve_always",
+    label: "Approve always",
+    description: "This tool, permanently",
   },
-  approve_always: { action: "approve_always", label: "Approve always" },
-  reject: { action: "reject", label: "Reject" },
+  reject: { action: "reject", label: "Reject", description: "Deny this call" },
 } as const satisfies Record<string, GuardianDecisionAction>;
 
 /**
@@ -89,6 +104,32 @@ export function buildDecisionActions(opts?: {
   ];
 }
 
+/**
+ * Build a compact legend string explaining each action, for rich-UI channels
+ * (Telegram, Slack) where buttons are shown but their scope isn't obvious.
+ *
+ * Accepts either `GuardianDecisionAction[]` or action ID strings and looks up
+ * descriptions from the canonical constants.
+ */
+export function buildActionLegend(
+  actionIds: readonly (string | { action?: string; id?: string })[],
+): string {
+  const lookup = GUARDIAN_DECISION_ACTIONS as Record<
+    string,
+    GuardianDecisionAction | undefined
+  >;
+  const lines = actionIds
+    .map((a) => {
+      const id = typeof a === "string" ? a : (a.action ?? a.id ?? "");
+      const canonical = lookup[id];
+      return canonical?.description
+        ? `• *${canonical.label}* — ${canonical.description}`
+        : null;
+    })
+    .filter(Boolean);
+  return lines.length > 0 ? lines.join("\n") : "";
+}
+
 /**
  * Build the plain-text fallback instruction string that matches the given
  * set of decision actions. Ensures the text always includes parser-compatible

package/src/runtime/http-server.ts

@@ -145,8 +145,11 @@ import { handleGuardianRefresh } from "./routes/guardian-refresh-routes.js";
 import { hostBashRouteDefinitions } from "./routes/host-bash-routes.js";
 import { hostCuRouteDefinitions } from "./routes/host-cu-routes.js";
 import { hostFileRouteDefinitions } from "./routes/host-file-routes.js";
-import { handleHealth, handleReadyz } from "./routes/identity-routes.js";
-import { identityRouteDefinitions } from "./routes/identity-routes.js";
+import {
+  handleHealth,
+  handleReadyz,
+  identityRouteDefinitions,
+} from "./routes/identity-routes.js";
 import { slackChannelRouteDefinitions } from "./routes/integrations/slack/channel.js";
 import { slackShareRouteDefinitions } from "./routes/integrations/slack/share.js";
 import { telegramRouteDefinitions } from "./routes/integrations/telegram.js";

package/src/runtime/routes/access-request-decision.ts

@@ -116,7 +116,7 @@ export async function deliverVerificationCodeToGuardian(params: {
 }): Promise<DeliveryResult> {
   const text =
     `You approved access for ${params.requesterIdentifier}. ` +
-    `Give them this verification code: ${params.verificationCode}. ` +
+    `Give them this verification code: \`${params.verificationCode}\`. ` +
     `The code expires in 10 minutes.`;
 
   try {
@@ -189,7 +189,7 @@ export async function deliverVerificationCodeToRequester(params: {
 }): Promise<DeliveryResult> {
   const text =
     `Great news — your access request was approved! ` +
-    `Your verification code is: ${params.verificationCode}. ` +
+    `Your verification code is: \`${params.verificationCode}\`. ` +
     `Reply with it here to complete verification. The code expires in 10 minutes.`;
 
   const target = resolveRequesterTarget(params);

package/src/runtime/routes/app-management-routes.ts

@@ -36,6 +36,7 @@ import {
   getApp,
   getAppDirPath,
   getAppPreview,
+  inlineDistAssets,
   isMultifileApp,
   listApps,
   queryAppRecords,
@@ -684,7 +685,7 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
               }
             }
             if (existsSync(distIndex)) {
-              html = readFileSync(distIndex, "utf-8");
+              html = inlineDistAssets(appDir, readFileSync(distIndex, "utf-8"));
             } else {
               html = `<p>App compilation failed. Edit a source file to trigger a rebuild.</p>`;
             }

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

@@ -7,6 +7,7 @@ import { applyGuardianDecision } from "../../../approvals/guardian-decision-prim
 import type { ChannelId } from "../../../channels/types.js";
 import {
   getAllPendingApprovalsByGuardianChat,
+  getApprovalRequestById,
   getPendingApprovalByRequestAndGuardianChat,
   type GuardianApprovalRequest,
 } from "../../../memory/guardian-approvals.js";
@@ -42,6 +43,17 @@ import {
 
 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 GuardianCallbackDecisionParams {
   content: string;
   callbackData?: string;
@@ -53,6 +65,8 @@ export interface GuardianCallbackDecisionParams {
   assistantId: string;
   approvalCopyGenerator?: ApprovalCopyGenerator;
   approvalConversationGenerator?: ApprovalConversationGenerator;
+  /** Original approval message timestamp (Slack ts) for editing after resolution. */
+  approvalMessageTs?: string;
 }
 
 export interface ApprovalInterceptionResult {
@@ -84,6 +98,7 @@ export async function handleGuardianCallbackDecision(
     assistantId,
     approvalCopyGenerator,
     approvalConversationGenerator,
+    approvalMessageTs,
   } = params;
 
   // Callback/button path: deterministic and takes priority.
@@ -129,6 +144,7 @@ export async function handleGuardianCallbackDecision(
           "Failed to deliver stale callback disambiguation notice",
         extraContext: { pendingCount: allPending.length },
         errorLogContext: { conversationExternalId },
+        ephemeralUserId: slackEphemeralUserId(sourceChannel, actorExternalId),
       });
       return { handled: true, type: "stale_ignored" };
     }
@@ -181,6 +197,7 @@ export async function handleGuardianCallbackDecision(
       logger: log,
       errorLogMessage: "Failed to deliver guardian identity rejection notice",
       errorLogContext: { conversationExternalId },
+      ephemeralUserId: slackEphemeralUserId(sourceChannel, actorExternalId),
     });
     return { handled: true, type: "guardian_decision_applied" };
   }
@@ -195,6 +212,7 @@ export async function handleGuardianCallbackDecision(
       assistantId,
       bearerToken,
       approvalCopyGenerator,
+      approvalMessageTs,
     });
   }
 
@@ -247,15 +265,20 @@ export async function handleGuardianCallbackDecision(
         {},
         approvalCopyGenerator,
       );
-      await deliverChannelReply(
-        replyCallbackUrl,
-        {
-          chatId: conversationExternalId,
-          text,
-          assistantId,
-        },
-        bearerToken,
+      const fallbackPayload: Parameters<typeof deliverChannelReply>[1] = {
+        chatId: conversationExternalId,
+        text,
+        assistantId,
+      };
+      const guardianFallbackEphemeral = slackEphemeralUserId(
+        sourceChannel,
+        actorExternalId,
       );
+      if (guardianFallbackEphemeral) {
+        fallbackPayload.ephemeral = true;
+        fallbackPayload.user = guardianFallbackEphemeral;
+      }
+      await deliverChannelReply(replyCallbackUrl, fallbackPayload, bearerToken);
     } catch (err) {
       log.error(
         { err, conversationExternalId },
@@ -282,6 +305,7 @@ async function handleCallbackDecision(params: {
   assistantId: string;
   bearerToken?: string;
   approvalCopyGenerator?: ApprovalCopyGenerator;
+  approvalMessageTs?: string;
 }): Promise<ApprovalInterceptionResult> {
   const {
     guardianApproval,
@@ -292,6 +316,7 @@ async function handleCallbackDecision(params: {
     assistantId,
     bearerToken,
     approvalCopyGenerator,
+    approvalMessageTs,
   } = params;
 
   // Access request approvals don't have a pending interaction in the
@@ -326,10 +351,12 @@ async function handleCallbackDecision(params: {
       callbackDecision.action === "approve_always"
         ? "approve_once"
         : callbackDecision.action;
+    const decisionOutcome: "approved" | "denied" =
+      effectiveAction === "reject" ? "denied" : "approved";
     const outcomeText = await composeApprovalMessageGenerative(
       {
         scenario: "guardian_decision_outcome",
-        decision: effectiveAction === "reject" ? "denied" : "approved",
+        decision: decisionOutcome,
         toolName: guardianApproval.toolName,
         channel: sourceChannel,
       },
@@ -337,15 +364,20 @@ async function handleCallbackDecision(params: {
       approvalCopyGenerator,
     );
     try {
-      await deliverChannelReply(
-        replyCallbackUrl,
-        {
-          chatId: guardianApproval.requesterChatId,
-          text: outcomeText,
-          assistantId,
-        },
-        bearerToken,
+      const outcomePayload: Parameters<typeof deliverChannelReply>[1] = {
+        chatId: guardianApproval.requesterChatId,
+        text: outcomeText,
+        assistantId,
+      };
+      const requesterEphemeral = slackEphemeralUserId(
+        sourceChannel,
+        guardianApproval.requesterExternalUserId,
       );
+      if (requesterEphemeral) {
+        outcomePayload.ephemeral = true;
+        outcomePayload.user = requesterEphemeral;
+      }
+      await deliverChannelReply(replyCallbackUrl, outcomePayload, bearerToken);
     } catch (err) {
       log.error(
         { err, conversationId: guardianApproval.conversationId },
@@ -353,12 +385,71 @@ async function handleCallbackDecision(params: {
       );
     }
 
+    // Edit the original Slack approval message to show the decision and
+    // remove stale action buttons. This prevents users from clicking
+    // buttons that have already been resolved.
+    if (sourceChannel === "slack" && approvalMessageTs) {
+      editSlackApprovalMessage({
+        replyCallbackUrl,
+        chatId: guardianApproval.guardianChatId,
+        messageTs: approvalMessageTs,
+        decision: decisionOutcome,
+        assistantId,
+        bearerToken,
+        conversationId: guardianApproval.conversationId,
+      });
+    }
+
     // Post-decision delivery is handled by the onEvent callback
     // in the session that registered the pending interaction.
     return { handled: true, type: "guardian_decision_applied" };
   }
 
   // Race condition: callback arrived after request was already resolved.
+  // On Slack, edit the original message to show it's resolved and remove
+  // stale buttons so the guardian isn't left with actionable UI that does
+  // nothing. Also send an ephemeral error message for visibility.
+  if (sourceChannel === "slack" && approvalMessageTs) {
+    // Re-read the approval from DB to get the actual resolved status.
+    // The in-memory `guardianApproval` was loaded via a pending-status
+    // filter and is still "pending" even though it was resolved by
+    // another process.
+    const refreshed = getApprovalRequestById(guardianApproval.id);
+    const resolvedStatus =
+      refreshed?.status === "approved" ? "approved" : "denied";
+    editSlackApprovalMessage({
+      replyCallbackUrl,
+      chatId: guardianApproval.guardianChatId,
+      messageTs: approvalMessageTs,
+      decision: resolvedStatus,
+      assistantId,
+      bearerToken,
+      conversationId: guardianApproval.conversationId,
+    });
+  }
+
+  // Deliver a visible ephemeral error so the user sees feedback (JARVIS-299).
+  if (sourceChannel === "slack") {
+    try {
+      await deliverChannelReply(
+        replyCallbackUrl,
+        {
+          chatId: guardianApproval.guardianChatId,
+          text: "This approval request has already been resolved.",
+          assistantId,
+          ephemeral: true,
+          user: actorExternalId,
+        },
+        bearerToken,
+      );
+    } catch (err) {
+      log.error(
+        { err, conversationId: guardianApproval.conversationId },
+        "Failed to deliver stale approval ephemeral notice",
+      );
+    }
+  }
+
   return { handled: true, type: "stale_ignored" };
 }
 
@@ -415,13 +506,22 @@ async function handleConversationalDecision(params: {
   if (engineResult.disposition === "keep_pending") {
     // Non-decision follow-up (clarification, disambiguation, etc.)
     try {
+      const keepPendingPayload: Parameters<typeof deliverChannelReply>[1] = {
+        chatId: conversationExternalId,
+        text: engineResult.replyText,
+        assistantId,
+      };
+      const guardianEphemeral = slackEphemeralUserId(
+        sourceChannel,
+        actorExternalId,
+      );
+      if (guardianEphemeral) {
+        keepPendingPayload.ephemeral = true;
+        keepPendingPayload.user = guardianEphemeral;
+      }
       await deliverChannelReply(
         replyCallbackUrl,
-        {
-          chatId: conversationExternalId,
-          text: engineResult.replyText,
-          assistantId,
-        },
+        keepPendingPayload,
         bearerToken,
       );
     } catch (err) {
@@ -481,6 +581,7 @@ async function handleConversationalDecision(params: {
       errorLogMessage:
         "Failed to deliver guardian identity mismatch notice for engine target",
       errorLogContext: { conversationExternalId },
+      ephemeralUserId: slackEphemeralUserId(sourceChannel, actorExternalId),
     });
     return { handled: true, type: "guardian_decision_applied" };
   }
@@ -528,13 +629,23 @@ async function handleConversationalDecision(params: {
       approvalCopyGenerator,
     );
     try {
-      await deliverChannelReply(
-        replyCallbackUrl,
+      const requesterOutcomePayload: Parameters<typeof deliverChannelReply>[1] =
         {
           chatId: targetApproval.requesterChatId,
           text: outcomeText,
           assistantId,
-        },
+        };
+      const requesterEphemeral = slackEphemeralUserId(
+        sourceChannel,
+        targetApproval.requesterExternalUserId,
+      );
+      if (requesterEphemeral) {
+        requesterOutcomePayload.ephemeral = true;
+        requesterOutcomePayload.user = requesterEphemeral;
+      }
+      await deliverChannelReply(
+        replyCallbackUrl,
+        requesterOutcomePayload,
         bearerToken,
       );
     } catch (err) {
@@ -546,13 +657,22 @@ async function handleConversationalDecision(params: {
 
     // Deliver the engine's reply to the guardian
     try {
+      const guardianReplyPayload: Parameters<typeof deliverChannelReply>[1] = {
+        chatId: conversationExternalId,
+        text: engineResult.replyText,
+        assistantId,
+      };
+      const guardianEphemeral = slackEphemeralUserId(
+        sourceChannel,
+        actorExternalId,
+      );
+      if (guardianEphemeral) {
+        guardianReplyPayload.ephemeral = true;
+        guardianReplyPayload.user = guardianEphemeral;
+      }
       await deliverChannelReply(
         replyCallbackUrl,
-        {
-          chatId: conversationExternalId,
-          text: engineResult.replyText,
-          assistantId,
-        },
+        guardianReplyPayload,
         bearerToken,
       );
     } catch (err) {
@@ -578,11 +698,80 @@ async function handleConversationalDecision(params: {
     logger: log,
     errorLogMessage: "Failed to deliver stale guardian approval notice",
     errorLogContext: { conversationId: targetApproval.conversationId },
+    ephemeralUserId: slackEphemeralUserId(sourceChannel, actorExternalId),
   });
 
   return { handled: true, type: "stale_ignored" };
 }
 
+// ---------------------------------------------------------------------------
+// Slack approval message edit helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Fire-and-forget: edit the original Slack approval message to show the
+ * decision outcome and remove stale action buttons. Uses `chat.update` via
+ * the gateway deliver endpoint with `messageTs`.
+ *
+ * The status line replaces the inline buttons so users see the result
+ * inline without any actionable UI remaining.
+ */
+function editSlackApprovalMessage(params: {
+  replyCallbackUrl: string;
+  chatId: string;
+  messageTs: string;
+  decision: "approved" | "denied";
+  assistantId: string;
+  bearerToken?: string;
+  conversationId: string;
+}): void {
+  const {
+    replyCallbackUrl,
+    chatId,
+    messageTs,
+    decision,
+    assistantId,
+    bearerToken,
+    conversationId,
+  } = params;
+
+  const statusEmoji = decision === "approved" ? "\u2713" : "\u2717";
+  const statusLabel = decision === "approved" ? "Approved" : "Denied";
+  const statusText = `${statusEmoji} ${statusLabel}`;
+
+  // Build Block Kit blocks matching the resolved approval layout:
+  // a section with the status text and a context line with the decision.
+  // This replaces the original approval prompt's action buttons with a
+  // read-only status display.
+  const blocks = [
+    {
+      type: "section",
+      text: { type: "mrkdwn", text: statusText },
+    },
+    {
+      type: "context",
+      elements: [{ type: "mrkdwn", text: `${statusEmoji} ${statusLabel}` }],
+    },
+  ];
+
+  deliverChannelReply(
+    replyCallbackUrl,
+    {
+      chatId,
+      text: statusText,
+      blocks,
+      messageTs,
+      assistantId,
+    },
+    bearerToken,
+  ).catch((err) => {
+    log.error(
+      { err, conversationId, messageTs },
+      "Failed to edit Slack approval message after resolution",
+    );
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Access request decision helper
 // ---------------------------------------------------------------------------