@vellumai/assistant 0.11.8 → 0.11.9-staging.2

package/src/runtime/routes/inbound-stages/reaction-intercept.ts

@@ -1,9 +1,9 @@
 /**
- * Slack reaction intercept stage.
+ * Reaction intercept stage, on any channel.
  *
- * Reactions are passive channel signals — not messages, and not access
- * attempts. They are dispatched here *before* the message pipeline (ACL,
- * admission floor, disk-pressure block, conversation binding) so that:
+ * Reactions are not messages and not access attempts. They are dispatched
+ * here *before* the message pipeline (ACL, admission floor, disk-pressure
+ * block, conversation binding) so that:
  *
  *   - a 👍 never triggers an ingress access challenge / verification handshake
  *     or an access-request notification (LUM-2489),
@@ -11,50 +11,64 @@
  *     row — it is dropped as channel noise,
  *   - a known contact's reaction is recorded as an inline transcript signal in
  *     the conversation of the message it was attached to, whether that message
- *     arrived from the channel or the assistant posted it,
- *   - a guardian's reaction on an approval card is routed through the guardian
- *     decision pipeline (the same path as buttons and text replies).
+ *     arrived from the channel or the assistant posted it.
  *
  * The reactor's trust is read solely from the gateway-stamped verdict on
  * `sourceMetadata`; a missing/failed/contradictory verdict fails closed to
- * `unknown` (drop). Reactions never drive an agent turn.
+ * `unknown` (drop).
+ *
+ * One reaction shape addresses the assistant rather than annotating the
+ * room: an admitted actor ADDING a reaction to a message the assistant
+ * itself authored. That one wakes a discretion turn through the ordinary
+ * channel-turn machinery (`buildReactionWakeTurn`); every other reaction
+ * stays a passive transcript row and never drives a turn.
  */
 import type { SourceMetadata } from "@vellumai/gateway-client";
 import {
   type InboundReactionPayload,
   resolveInboundEventKind,
 } from "@vellumai/gateway-client";
+import { pickReactionEmojiFields } from "@vellumai/service-contracts/reactions";
 
 import type { ChannelId, InterfaceId } from "../../../channels/types.js";
+import { createApprovalCopyGenerator } from "../../../daemon/approval-generators.js";
 import { findConversation } from "../../../daemon/conversation-registry.js";
 import { getDiskPressureStatus } from "../../../daemon/disk-pressure-guard.js";
 import { classifyDiskPressureTurnPolicy } from "../../../daemon/disk-pressure-policy.js";
+import { processMessage } from "../../../daemon/process-message.js";
+import { renderReactionHistoryText } from "../../../daemon/reaction-history-render.js";
 import type { TrustContext } from "../../../daemon/trust-context-types.js";
 import { writeSlackMetadata } from "../../../messaging/providers/slack/message-metadata.js";
 import {
   buildNeutralReactionMeta,
+  buildReactionRowEnvelope,
   buildSlackReactionMeta,
 } from "../../../messaging/reaction-envelopes.js";
+import { readProviderMetadata } from "../../../messaging/read-provider-metadata.js";
+import { isGuardianCardRow } from "../../../notifications/approval-card-data.js";
 import {
   addMessage,
+  getMessageById,
   provenanceFromTrustContext,
 } from "../../../persistence/conversation-crud.js";
 import {
-  findConversationByProviderMessageId,
   findInboundEvent,
+  findMessageByProviderMessageId,
   findMessageBySourceId,
   linkMessage,
   recordInbound,
+  storePayload,
 } from "../../../persistence/delivery-crud.js";
 import { markProcessed } from "../../../persistence/delivery-status.js";
+import { extractTextFromStoredMessageContent } from "../../../persistence/message-content.js";
 import { getLogger } from "../../../util/logger.js";
 import { toTrustContext } from "../../actor-trust-resolver.js";
-import type { ApprovalConversationGenerator } from "../../http-types.js";
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "../../assistant-scope.js";
 import {
   actorTrustContextFromVerdict,
   verdictUsability,
 } from "../../trust-verdict-consumer.js";
-import { handleGuardianReplyIntercept } from "./guardian-reply-intercept.js";
+import { processChannelMessageInBackground } from "./background-dispatch.js";
 
 const log = getLogger("runtime-http");
 
@@ -87,7 +101,6 @@ export interface ReactionInterceptParams {
   actorUsername: string | undefined;
   replyCallbackUrl: string | undefined;
   sourceMetadata: SourceMetadata | undefined;
-  approvalConversationGenerator: ApprovalConversationGenerator | undefined;
 }
 
 /**
@@ -110,7 +123,6 @@ export async function handleReactionIntercept(
     actorUsername,
     replyCallbackUrl,
     sourceMetadata,
-    approvalConversationGenerator,
   } = params;
 
   // Classify the reactor from the gateway-stamped verdict — the same source
@@ -142,10 +154,9 @@ export async function handleReactionIntercept(
 
   const reactedMessageTs = reaction.targetMessageId;
   // Respect disk-pressure cleanup so reactions don't bypass storage
-  // protection. Guardians resolve to `allow-cleanup-mode` (not `block`), so a
-  // guardian's approval-by-reaction still flows. Blocked silently and before
-  // any write: a reaction is a passive signal, so the message pipeline's
-  // "storage is low, try again" notice is meaningless for an emoji.
+  // protection. Blocked silently and before any write: a reaction is a
+  // passive signal, so the message pipeline's "storage is low, try again"
+  // notice is meaningless for an emoji.
   const diskPressure = classifyDiskPressureTurnPolicy(getDiskPressureStatus(), {
     sourceChannel,
     sourceInterface,
@@ -163,9 +174,9 @@ export async function handleReactionIntercept(
     };
   }
 
-  // A redelivery is answered before anything acts on it. Recording the event
-  // is what dedups a reaction, and that happens after the guardian rail, so
-  // without this probe the same emoji could drive a decision twice.
+  // A redelivery is answered before the reacted message is resolved, so a
+  // repeat delivery costs no lookup. `recordInbound` below is the durable
+  // dedup; this is the early out in front of it.
   const alreadyRecorded = findInboundEvent(
     sourceChannel,
     conversationExternalId,
@@ -179,34 +190,6 @@ export async function handleReactionIntercept(
     };
   }
 
-  // Guardian approval-by-reaction runs before the reacted message is resolved:
-  // an approval card is addressed by its own message id and is not always a
-  // stored message. Only `reaction:` (added) expresses intent;
-  // `reaction_removed:` never does. `handleGuardianReplyIntercept` self-gates
-  // on `trustClass === "guardian"`, so a contact's reaction returns no
-  // response and falls through to persistence.
-  if (reaction.op === "added" && replyCallbackUrl) {
-    const reactionIntercept = await handleGuardianReplyIntercept({
-      isDuplicate: false,
-      trimmedContent: "",
-      hasCallbackData: true,
-      callbackData: undefined,
-      reaction,
-      reactedMessageTs,
-      rawSenderId,
-      canonicalSenderId,
-      sourceChannel,
-      conversationExternalId,
-      replyCallbackUrl,
-      trustClass: trustCtx.trustClass,
-      guardianPrincipalId: trustCtx.guardianPrincipalId,
-      approvalConversationGenerator,
-    });
-    if (reactionIntercept.response) {
-      return reactionIntercept.response;
-    }
-  }
-
   // The reaction belongs to the conversation of the message it was attached
   // to. Slack sends no `thread_ts` on a reaction, so resolving a conversation
   // from the reaction's own address keys one on the reacted message instead of
@@ -217,19 +200,19 @@ export async function handleReactionIntercept(
   // them. The assistant's own posts open no inbound event, so a reaction on
   // one is resolved through the envelope those rows carry (`slackMeta` on
   // Slack, the neutral `providerMeta` everywhere else).
-  const targetConversationId = reactedMessageTs
+  const target = reactedMessageTs
     ? (findMessageBySourceId(
         sourceChannel,
         conversationExternalId,
         reactedMessageTs,
-      )?.conversationId ??
-      findConversationByProviderMessageId(
+      ) ??
+      findMessageByProviderMessageId(
         sourceChannel,
         conversationExternalId,
         reactedMessageTs,
       ))
     : null;
-  if (!targetConversationId || !reactedMessageTs) {
+  if (!target || !reactedMessageTs) {
     log.debug(
       { sourceChannel, conversationExternalId, reactedMessageTs },
       "Dropping reaction: reacted message is not stored",
@@ -237,6 +220,23 @@ export async function handleReactionIntercept(
     return { accepted: true, reaction: "dropped_unknown_target" };
   }
 
+  // A guardian card is a delivery projection, not conversation content.
+  // `isGuardianCardRow` is the predicate both history assemblers already use
+  // to keep these rows out of a turn's history; the wake path is the third
+  // reader of the same question. A reaction on a card has nothing to
+  // annotate, and the card is assistant-authored, so without this it would
+  // read as a signal addressed to the assistant and wake a turn. Channel
+  // deliveries persist no row today, but ones paired before the
+  // projection-only policy are still stored.
+  const targetRow = getMessageById(target.messageId, target.conversationId);
+  if (isGuardianCardRow(targetRow?.content)) {
+    log.debug(
+      { sourceChannel, conversationExternalId, reactedMessageTs },
+      "Dropping reaction: reacted message is a guardian card",
+    );
+    return { accepted: true, reaction: "dropped_guardian_card" };
+  }
+
   const result = recordInbound(
     sourceChannel,
     conversationExternalId,
@@ -245,11 +245,20 @@ export async function handleReactionIntercept(
     // own message, and a reaction is not one. Claiming the reacted message's
     // id here would put two linked rows on that id, leaving a later edit or
     // delete of it free to resolve to the reaction instead.
-    { conversationId: targetConversationId },
+    { conversationId: target.conversationId },
   );
+  if (result.duplicate) {
+    return {
+      accepted: result.accepted,
+      duplicate: true,
+      eventId: result.eventId,
+    };
+  }
 
-  // Record the reaction as an inline transcript signal.
-  try {
+  const rowTrustContext = toTrustContext(trustCtx, conversationExternalId);
+  const actorExternalId = canonicalSenderId ?? rawSenderId ?? undefined;
+
+  const persistPassively = async (): Promise<void> => {
     await persistReactionAsMessage({
       conversationId: result.conversationId,
       conversationExternalId,
@@ -257,21 +266,70 @@ export async function handleReactionIntercept(
       sourceChannel,
       reaction,
       actorDisplayName,
-      actorExternalId: canonicalSenderId ?? rawSenderId ?? undefined,
+      actorExternalId,
       reactedMessageTs,
-      duplicate: result.duplicate,
-      trustCtx: toTrustContext(trustCtx, conversationExternalId),
+      duplicate: false,
+      trustCtx: rowTrustContext,
     });
-    if (!result.duplicate) {
-      // Reactions never drive a turn, so a resident conversation would
-      // otherwise carry the new row only after eviction. Marking it stale
-      // makes the next turn's history reload pick the reaction up.
-      findConversation(result.conversationId)?.markHistoryStale();
+    // A passive row lands in the store only, so a resident conversation
+    // would otherwise carry it only after eviction. Marking it stale makes
+    // the next turn's history reload pick the reaction up.
+    findConversation(result.conversationId)?.markHistoryStale();
+  };
+
+  // An admitted actor ADDING a reaction to the assistant's own message is a
+  // signal addressed to the assistant, like a thumbs-up sent to a person: it
+  // wakes a discretion turn. Everything else stays a passive transcript
+  // row: removals retract rather than address, and a reaction on another
+  // participant's message is between-humans signaling. Mechanics on
+  // `buildReactionWakeTurn`.
+  const wakeTurn =
+    reaction.op === "added" && replyCallbackUrl && sourceInterface
+      ? buildReactionWakeTurn({
+          target,
+          targetRow,
+          result,
+          reaction,
+          sourceChannel,
+          sourceInterface,
+          conversationExternalId,
+          replyCallbackUrl,
+          actorDisplayName,
+          actorExternalId,
+          reactedMessageTs,
+          trustCtx: rowTrustContext,
+          chatType: sourceMetadata?.chatType?.trim() || undefined,
+          persistPassively,
+        })
+      : null;
+  if (wakeTurn) {
+    try {
+      wakeTurn();
+      return {
+        accepted: result.accepted,
+        duplicate: false,
+        eventId: result.eventId,
+        reaction: "wake_dispatched",
+      };
+    } catch (err) {
+      // Dispatch startup failed before the background turn owns the event
+      // (its own failures degrade through `onTurnLostToBusy`). The dedup
+      // record already exists, so a gateway retry would short-circuit and
+      // leave the reaction unrecorded entirely; fall through to the passive
+      // row, which is what this reaction would have been without the wake.
+      log.error(
+        { err, conversationId: result.conversationId, eventId: result.eventId },
+        "Reaction wake dispatch failed to start; recording the passive row",
+      );
     }
+  }
+
+  try {
+    await persistPassively();
   } catch (err) {
     log.error(
       { err, conversationId: result.conversationId, eventId: result.eventId },
-      "Failed to persist Slack reaction event",
+      "Failed to persist reaction event",
     );
   }
 
@@ -282,11 +340,163 @@ export async function handleReactionIntercept(
   };
 }
 
+/**
+ * Build the dispatch thunk for a reaction-driven discretion turn, or null
+ * when the reaction does not qualify: only a reaction on a message the
+ * assistant itself authored addresses the assistant.
+ *
+ * The turn rides `processChannelMessageInBackground` unchanged, so it defers
+ * behind an in-flight turn, streams and delivers its reply through the
+ * channel rail, and a `<no_response/>` outcome is suppressed everywhere. Its
+ * persisted user row carries the same reaction envelope the passive path
+ * writes, so the row reads as a reaction to every envelope consumer, and its
+ * live content is the same line `renderReactionHistoryText` produces at
+ * reload, so the model sees one wording on both paths.
+ *
+ * Wake turns are at-most-once. The retry sweep's processing lane rebuilds a
+ * turn from its stored payload as a plain message, which would corrupt a
+ * reaction into a fabricated user message, so the event is marked processed
+ * up front and the payload it stores is delivery-only: it names where a
+ * generated reply goes and carries no content to rebuild a turn from. A
+ * crash mid-turn therefore loses the discretionary turn, never a row the
+ * store already held. The one recoverable loss, a non-channel turn stealing
+ * the lock after admission, degrades through `persistPassively` to exactly
+ * the row the passive path would have written.
+ */
+function buildReactionWakeTurn(params: {
+  target: { messageId: string; conversationId: string };
+  targetRow: ReturnType<typeof getMessageById>;
+  result: { eventId: string; conversationId: string };
+  reaction: InboundReactionPayload;
+  sourceChannel: ChannelId;
+  sourceInterface: InterfaceId;
+  conversationExternalId: string;
+  replyCallbackUrl: string;
+  actorDisplayName: string | undefined;
+  actorExternalId: string | undefined;
+  reactedMessageTs: string;
+  trustCtx: TrustContext;
+  chatType: string | undefined;
+  persistPassively: () => Promise<void>;
+}): (() => void) | null {
+  const targetRow = params.targetRow;
+  if (!targetRow || targetRow.role !== "assistant") {
+    return null;
+  }
+
+  const facts = reactionFacts(params);
+  const neutralMeta = buildNeutralReactionMeta(facts);
+  const targetText = extractTextFromStoredMessageContent(targetRow.content);
+  const content = renderReactionHistoryText(
+    neutralMeta,
+    () => targetText || undefined,
+    { selfAuthored: false },
+  );
+  if (!content) {
+    return null;
+  }
+  // The reaction envelope rides the same carrier lanes ordinary ingress
+  // uses: the neutral `channelInbound` for every non-Slack channel (its
+  // lane validates through the canonical schema and passes reaction-kind
+  // envelopes verbatim), and the transitional Slack-only field while Slack
+  // still writes its own envelope. The passive path keeps
+  // `buildReactionRowEnvelope`; the lanes here materialize the same
+  // builders' facts, so the two writers still cannot drift.
+  const envelopeCarrier =
+    params.sourceChannel === "slack"
+      ? {
+          slackReactionRowMeta: writeSlackMetadata(
+            buildSlackReactionMeta(facts),
+          ),
+        }
+      : { channelInbound: neutralMeta };
+
+  const replyCallbackUrl = resolveWakeReplyCallbackUrl(
+    params.sourceChannel,
+    params.replyCallbackUrl,
+    targetRow.metadata,
+  );
+
+  return () => {
+    // A delivery-only payload: the fields `channel-retry-sweep`'s delivery
+    // lane needs to re-post a generated reply whose first delivery failed
+    // transiently. It deliberately carries no `content` or `sourceChannel`,
+    // so it can never be replayed as a message turn even if this event
+    // somehow reached the processing lane; that replay is what the
+    // at-most-once design exists to prevent.
+    storePayload(params.result.eventId, {
+      replyCallbackUrl,
+      externalChatId: params.conversationExternalId,
+      assistantId: DAEMON_INTERNAL_ASSISTANT_ID,
+    });
+    markProcessed(params.result.eventId);
+    processChannelMessageInBackground({
+      processMessage,
+      conversationId: params.result.conversationId,
+      eventId: params.result.eventId,
+      content,
+      sourceChannel: params.sourceChannel,
+      sourceInterface: params.sourceInterface,
+      externalChatId: params.conversationExternalId,
+      trustCtx: params.trustCtx,
+      metadataHints: [],
+      replyCallbackUrl,
+      assistantId: DAEMON_INTERNAL_ASSISTANT_ID,
+      approvalCopyGenerator: createApprovalCopyGenerator(),
+      ...(params.chatType ? { chatType: params.chatType } : {}),
+      ...envelopeCarrier,
+      clientMessageId: `reaction:${params.result.eventId}`,
+      skipUserMessageIndexing: true,
+      onTurnLostToBusy: params.persistPassively,
+    });
+  };
+}
+
+/**
+ * Where a wake turn's reply goes, which is the conversation the reacted
+ * message lives in rather than the reaction's own address.
+ *
+ * A reaction event names no thread of its own, so Slack's normalizer fills
+ * the callback's `threadTs` with the REACTED MESSAGE's ts. Delivering
+ * through it would root the reply at that message: a thread of its own off
+ * a channel post, or an invalid parent when the target is itself a threaded
+ * reply. Slack rows record the thread they live in, so the target row's
+ * stored `threadId` is the authoritative destination, and its absence means
+ * the target sits at the channel root, where the reply belongs too.
+ *
+ * Every other channel is already correct: a Discord thread IS a channel, so
+ * a reaction inside one carries that thread as its address.
+ */
+function resolveWakeReplyCallbackUrl(
+  sourceChannel: ChannelId,
+  reactionCallbackUrl: string,
+  targetMetadata: string | null,
+): string {
+  if (sourceChannel !== "slack") {
+    return reactionCallbackUrl;
+  }
+  let url: URL;
+  try {
+    url = new URL(reactionCallbackUrl);
+  } catch {
+    return reactionCallbackUrl;
+  }
+  const targetThreadTs = readProviderMetadata(targetMetadata, {
+    allowFlatLegacy: true,
+  })?.threadId;
+  if (targetThreadTs) {
+    url.searchParams.set("threadTs", targetThreadTs);
+  } else {
+    url.searchParams.delete("threadTs");
+  }
+  return url.toString();
+}
+
 /**
  * Persist a Slack reaction event as a `messages` row with a `slackMeta`
  * envelope so the renderer can surface it inline in the chronological
- * transcript. Reactions do not trigger an agent response — the row is written
- * and the inbound event is linked, but the agent loop is not dispatched.
+ * transcript. The row is written and the inbound event is linked; the wake
+ * decision is the caller's (`buildReactionWakeTurn`).
  *
  * The caller is expected to have run `recordInbound` already so that
  * deduplication and conversation resolution have happened. Duplicate inbound
@@ -319,42 +529,10 @@ async function persistReactionAsMessage(params: {
   if (params.duplicate) {
     return;
   }
-  const facts = {
-    channel: params.sourceChannel,
-    chatId: params.conversationExternalId,
-    targetMessageId: params.reactedMessageTs,
-    emoji: params.reaction.emoji,
-    op: params.reaction.op,
-    ...(params.actorExternalId
-      ? { actorExternalId: params.actorExternalId }
-      : {}),
-    ...(params.actorDisplayName
-      ? { actorDisplayName: params.actorDisplayName }
-      : {}),
-  };
+  const facts = reactionFacts(params);
 
-  if (params.sourceChannel !== "slack") {
-    const persisted = await addMessage(
-      params.conversationId,
-      "user",
-      "[reaction]",
-      {
-        metadata: {
-          ...provenanceFromTrustContext(params.trustCtx),
-          providerMeta: JSON.stringify(buildNeutralReactionMeta(facts)),
-        },
-        skipIndexing: true,
-      },
-    );
-    linkMessage(params.eventId, persisted.id);
-    markProcessed(params.eventId);
-    return;
-  }
-
-  const slackMeta = buildSlackReactionMeta(facts);
-
-  // Sentinel content — Slack transcript renderers read `slackMeta` to format
-  // the reaction line; the literal text is never displayed to the model.
+  // Sentinel content: transcript renderers read the envelope to format the
+  // reaction line; the literal text is never displayed to the model.
   const persisted = await addMessage(
     params.conversationId,
     "user",
@@ -362,7 +540,7 @@ async function persistReactionAsMessage(params: {
     {
       metadata: {
         ...provenanceFromTrustContext(params.trustCtx),
-        slackMeta: writeSlackMetadata(slackMeta),
+        ...buildReactionRowEnvelope(facts),
       },
       skipIndexing: true,
     },
@@ -370,3 +548,32 @@ async function persistReactionAsMessage(params: {
   linkMessage(params.eventId, persisted.id);
   markProcessed(params.eventId);
 }
+
+/**
+ * The envelope facts of one inbound reaction, from the intercept's own
+ * vocabulary. Shared by the passive row and the wake turn's row so the two
+ * writers describe the same reaction identically.
+ */
+function reactionFacts(params: {
+  sourceChannel: ChannelId;
+  conversationExternalId: string;
+  reactedMessageTs: string;
+  reaction: InboundReactionPayload;
+  actorExternalId?: string;
+  actorDisplayName?: string;
+}) {
+  return {
+    channel: params.sourceChannel,
+    chatId: params.conversationExternalId,
+    targetMessageId: params.reactedMessageTs,
+    emoji: params.reaction.emoji,
+    ...pickReactionEmojiFields(params.reaction),
+    op: params.reaction.op,
+    ...(params.actorExternalId
+      ? { actorExternalId: params.actorExternalId }
+      : {}),
+    ...(params.actorDisplayName
+      ? { actorDisplayName: params.actorDisplayName }
+      : {}),
+  };
+}

package/src/runtime/routes/index.ts

@@ -139,6 +139,7 @@ import { ROUTES as SCHEDULE_WORKER_ROUTES } from "./schedule-worker-routes.js";
 import { ROUTES as SECRET_ROUTES } from "./secret-routes.js";
 import { ROUTES as SEQUENCE_ROUTES } from "./sequence-routes.js";
 import { ROUTES as SETTINGS_ROUTES } from "./settings-routes.js";
+import { ROUTES as SIGHT_FRAME_ROUTES } from "./sight-frame-routes.js";
 import { ROUTES as SKILL_ROUTES } from "./skills-routes.js";
 import { ROUTES as SLACK_CHANNEL_RESOLVE_ROUTES } from "./slack-channel-routes.js";
 import { ROUTES as SOUNDS_CONFIG_ROUTES } from "./sounds-config-routes.js";
@@ -287,6 +288,7 @@ export const ROUTES: RouteDefinition[] = [
   ...SANITY_ROUTES,
   ...SECRET_ROUTES,
   ...SETTINGS_ROUTES,
+  ...SIGHT_FRAME_ROUTES,
   ...SOUNDS_CONFIG_ROUTES,
   ...SKILL_ROUTES,
   ...A2A_ROUTES,