@vellumai/assistant 0.11.8-dev.202609012313.7a1acce → 0.11.8-staging.2

package/ARCHITECTURE.md

@@ -120,7 +120,7 @@ Scoped approval grants allow a guardian's approval decision on one channel (e.g.
 
 ### Guardian Decision Primitive
 
-All guardian approval decisions, regardless of how they arrive, route through a single primitive in `src/approvals/guardian-decision-primitive.ts`, which centralizes decision logic for callback button handlers, the conversational approval engine, and channel text replies.
+All guardian approval decisions — regardless of how they arrive — route through a single primitive in `src/approvals/guardian-decision-primitive.ts`, which centralizes decision logic for callback button handlers, the conversational approval engine, and channel reactions/text.
 
 **Core API:**
 

package/docs/guardian-request-flow.md

@@ -28,10 +28,10 @@ anti-pattern was retired in #35642 and again in the ask_question redesign).
   telegram: inline keyboard; slack: blocks;       vellum: conversation card via approval-card-builder)
   card deliveries recorded per channel            (guardian-delivery-recorder.ts → guardian_request_deliveries)
         │
-        ▼ user responds: button tap / "CODE <reply>" / bare text
+        ▼ user responds: button tap / emoji reaction / "CODE <reply>" / bare text
   guardian reply router                          (runtime/guardian-reply-router.ts, invoked from
-  callbacks → request codes → bare answer →       routes/inbound-stages/guardian-reply-intercept.ts,
-  explicit approve/reject → NL                    BEFORE background dispatch: replies to parked
+  reactions → callbacks → request codes →         routes/inbound-stages/guardian-reply-intercept.ts,
+  bare answer → explicit approve/reject → NL      BEFORE background dispatch — replies to parked
         │                                         prompts resolve inline, never deferred)
         ▼ one decision primitive
   applyGuardianDecision                          (approvals/guardian-decision-primitive.ts:
@@ -45,14 +45,14 @@ anti-pattern was retired in #35642 and again in the ask_question redesign).
 
 ## Who owns what
 
-| Concern                                 | Owner                                             | Never                               |
-| --------------------------------------- | ------------------------------------------------- | ----------------------------------- |
-| The "what": card text, actions, options | broadcaster context build (once per broadcast)    | built per-adapter                   |
-| The "how": channel-native rendering     | `notifications/adapters/<channel>`                | domain logic, payload parsing       |
-| Request state                           | gateway `guardian_requests` (+ deliveries)        | daemon-side request tables          |
-| Decisions                               | `applyGuardianDecision` (CAS, atomic ACL outcome) | inline decision logic at call sites |
-| Kind-specific follow-through            | resolver registry (`kind` → resolver)             | switch statements in the router     |
-| Reply understanding                     | guardian reply router (codes, buttons, modes)     | per-feature inbound intercepts      |
+| Concern                                 | Owner                                                    | Never                               |
+| --------------------------------------- | -------------------------------------------------------- | ----------------------------------- |
+| The "what": card text, actions, options | broadcaster context build (once per broadcast)           | built per-adapter                   |
+| The "how": channel-native rendering     | `notifications/adapters/<channel>`                       | domain logic, payload parsing       |
+| Request state                           | gateway `guardian_requests` (+ deliveries)               | daemon-side request tables          |
+| Decisions                               | `applyGuardianDecision` (CAS, atomic ACL outcome)        | inline decision logic at call sites |
+| Kind-specific follow-through            | resolver registry (`kind` → resolver)                    | switch statements in the router     |
+| Reply understanding                     | guardian reply router (codes, buttons, reactions, modes) | per-feature inbound intercepts      |
 
 ## The canonical home-feed projection
 
@@ -186,8 +186,8 @@ chat the turn is running in. On Slack that chat can be a shared room, and the
 card carries the tool, a command preview and live buttons.
 `resolveGuardianPromptDelivery` addresses it to the guardian's bound DM
 instead, by chat id rather than user id because that address is written to the
-delivery row and read back to scope plain-text replies and edit the decided
-card. It returns the address and its route together, since
+delivery row and read back to match reactions, scope plain-text replies and
+edit the decided card. It returns the address and its route together, since
 the turn's own callback carries a `threadTs` naming a thread that does not
 exist in the DM. When no private address resolves it returns nothing and the
 prompt is left to the in-app confirmation, because the room is the disclosure

package/node_modules/@vellumai/gateway-client/src/__tests__/guardian-request-contract.test.ts

@@ -16,6 +16,7 @@ import {
   ExpireGuardianRequestIpcParamsSchema,
   ExpireInteractionBoundIpcResponseSchema,
   GetGuardianRequestByCallSessionIpcParamsSchema,
+  GetGuardianRequestByDestinationMessageIpcParamsSchema,
   GetGuardianRequestByPendingQuestionIpcParamsSchema,
   GUARDIAN_REQUESTS_IPC_METHODS,
   GuardianRequestAclOutcomeSchema,
@@ -481,6 +482,23 @@ describe("delivery + destination IPC schemas", () => {
     );
   });
 
+  test("get_by_destination_message requires all three keys", () => {
+    const params = {
+      channel: "telegram",
+      chatId: "tg-chat-guardian",
+      messageId: "msg-42",
+    };
+    expect(
+      GetGuardianRequestByDestinationMessageIpcParamsSchema.parse(params),
+    ).toEqual(params);
+    expect(() =>
+      GetGuardianRequestByDestinationMessageIpcParamsSchema.parse({
+        channel: "telegram",
+        chatId: "tg-chat-guardian",
+      }),
+    ).toThrow();
+  });
+
   test("list_pending_by_destination accepts either addressing form", () => {
     const byConversation = { conversationId: "conv-1", channel: "telegram" };
     expect(

package/node_modules/@vellumai/gateway-client/src/guardian-request-contract.ts

@@ -15,6 +15,11 @@
  * daemon's client-facing HTTP surface owns the distinct `guardian_actions_*`
  * operationIds (`guardian_actions_pending` / `guardian_actions_decision`),
  * which do not change.
+ *
+ * Destination lookups are deliberately split into a single-message lookup
+ * (`get_by_destination_message`) and a pending-list read
+ * (`list_pending_by_destination`) so each response schema has exactly one
+ * shape instead of a params-dependent polymorphic result.
  */
 
 import { z } from "zod";
@@ -189,6 +194,7 @@ export const GUARDIAN_REQUESTS_IPC_METHODS = {
   updateDelivery: "guardian_requests_update_delivery",
   listDeliveries: "guardian_requests_list_deliveries",
   listDeliveriesByChat: "guardian_requests_list_deliveries_by_chat",
+  getByDestinationMessage: "guardian_requests_get_by_destination_message",
   listPendingByDestination: "guardian_requests_list_pending_by_destination",
   listPendingByScope: "guardian_requests_list_pending_by_scope",
   inScope: "guardian_requests_in_scope",
@@ -621,6 +627,21 @@ export type GuardianRequestDeliveryListIpcResponse = z.infer<
 // Destination + scope lookups
 // ---------------------------------------------------------------------------
 
+/**
+ * Request for `guardian_requests_get_by_destination_message` — reaction
+ * routing: recover the pending request whose delivered card is the reacted-to
+ * message.
+ */
+export const GetGuardianRequestByDestinationMessageIpcParamsSchema = z.object({
+  channel: z.string().min(1),
+  chatId: z.string().min(1),
+  messageId: z.string().min(1),
+});
+
+export type GetGuardianRequestByDestinationMessageIpcParams = z.infer<
+  typeof GetGuardianRequestByDestinationMessageIpcParamsSchema
+>;
+
 /**
  * Request for `guardian_requests_list_pending_by_destination`. Two forms:
  * by destination conversation (`conversationId`, optionally narrowed by

package/node_modules/@vellumai/gateway-client/src/index.ts

@@ -245,6 +245,7 @@ export {
   ExpireInteractionBoundIpcResponseSchema,
   GetGuardianRequestByCallSessionIpcParamsSchema,
   GetGuardianRequestByCodeIpcParamsSchema,
+  GetGuardianRequestByDestinationMessageIpcParamsSchema,
   GetGuardianRequestByPendingQuestionIpcParamsSchema,
   GetGuardianRequestIpcParamsSchema,
   GUARDIAN_REQUESTS_IPC_METHODS,
@@ -285,6 +286,7 @@ export type {
   ExpireInteractionBoundIpcResponse,
   GetGuardianRequestByCallSessionIpcParams,
   GetGuardianRequestByCodeIpcParams,
+  GetGuardianRequestByDestinationMessageIpcParams,
   GetGuardianRequestByPendingQuestionIpcParams,
   GetGuardianRequestIpcParams,
   GuardianRequestAclOutcome,

package/openapi.yaml

@@ -4076,59 +4076,6 @@ paths:
       responses:
         "200":
           description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  success:
-                    type: boolean
-                  bound:
-                    type: boolean
-                  channel:
-                    type: string
-                    enum:
-                      - telegram
-                      - phone
-                      - vellum
-                      - whatsapp
-                      - slack
-                      - email
-                      - platform
-                      - a2a
-                      - discord
-                      - plugin
-                  assistantId:
-                    type: string
-                  hasPendingChallenge:
-                    type: boolean
-                  guardianExternalUserId:
-                    type: string
-                  guardianDeliveryChatId:
-                    type: string
-                  guardianUsername:
-                    type: string
-                  guardianDisplayName:
-                    type: string
-                  verificationSessionId:
-                    type: string
-                  expiresAt:
-                    type: number
-                  nextResendAt:
-                    anyOf:
-                      - type: number
-                      - type: "null"
-                  sendCount:
-                    type: number
-                  pendingBootstrap:
-                    type: boolean
-                required:
-                  - success
-                  - bound
-                  - channel
-                  - assistantId
-                  - hasPendingChallenge
-                additionalProperties: false
   /v1/channels/available:
     get:
       operationId: channels_available_get

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.8-dev.202609012313.7a1acce",
+  "version": "0.11.8-staging.2",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/channel-delivery-store.test.ts

@@ -10,11 +10,10 @@ import { getDb } from "../persistence/db-connection.js";
 import { initializeDb } from "../persistence/db-init.js";
 import {
   clearPayload,
-  findMessageByProviderMessageId,
+  findConversationByProviderMessageId,
   findMessageBySourceId,
   linkMessage,
   recordInbound,
-  recordOutboundPost,
   storePayload,
 } from "../persistence/delivery-crud.js";
 import {
@@ -53,7 +52,6 @@ await initializeDb();
 function resetTables() {
   const db = getDb();
   db.run("DELETE FROM channel_inbound_events");
-  db.run("DELETE FROM channel_outbound_posts");
   db.run("DELETE FROM messages");
   db.run("DELETE FROM conversation_keys");
   db.run("DELETE FROM external_conversation_bindings");
@@ -149,144 +147,35 @@ describe("channel-delivery-store", () => {
       .run();
 
     expect(
-      findMessageByProviderMessageId("discord", chatId, "1234567890123456789"),
-    ).toEqual({
-      messageId: "assistant-post-1",
-      conversationId: minted.conversationId,
-    });
+      findConversationByProviderMessageId(
+        "discord",
+        chatId,
+        "1234567890123456789",
+      ),
+    ).toBe(minted.conversationId);
     // A split reply posts several provider messages from one row; any of
     // their ids resolves it.
     expect(
-      findMessageByProviderMessageId("discord", chatId, "2234567890123456789"),
-    ).toEqual({
-      messageId: "assistant-post-1",
-      conversationId: minted.conversationId,
-    });
+      findConversationByProviderMessageId(
+        "discord",
+        chatId,
+        "2234567890123456789",
+      ),
+    ).toBe(minted.conversationId);
     // The scan is scoped to the reaction's own channel address: the same id
     // is invisible from another channel's or another chat's key space.
     expect(
-      findMessageByProviderMessageId("telegram", chatId, "1234567890123456789"),
-    ).toBeNull();
-    expect(
-      findMessageByProviderMessageId(
-        "discord",
-        "other-chat",
+      findConversationByProviderMessageId(
+        "telegram",
+        chatId,
         "1234567890123456789",
       ),
     ).toBeNull();
-  });
-
-  test("linked inbound rows are excluded from the provider-id scan; crash-window rows resolve", () => {
-    const chatId = "chat-scan-budget";
-    const minted = recordInbound("telegram", chatId, "evt-linked", {
-      sourceMessageId: "tg-linked-1",
-    });
-    const envelope = (messageId: string) =>
-      JSON.stringify({
-        providerMeta: JSON.stringify({
-          source: "telegram",
-          conversationExternalId: chatId,
-          messageId,
-          eventKind: "message",
-        }),
-      });
-
-    // A normally-ingested inbound row: linked to its event, so the
-    // inbound-event index owns its resolution and the fallback scan must
-    // not spend budget on it.
-    insertMessage("linked-user-row", minted.conversationId, {});
-    getDb()
-      .update(messages)
-      .set({ metadata: envelope("tg-linked-1") })
-      .where(eq(messages.id, "linked-user-row"))
-      .run();
-    linkMessage(minted.eventId, "linked-user-row");
-    expect(
-      findMessageByProviderMessageId("telegram", chatId, "tg-linked-1"),
-    ).toBeNull();
-
-    // A crash-window row: persisted with its envelope but its event link
-    // never landed. The fallback is the only path that can resolve it.
-    insertMessage("orphan-user-row", minted.conversationId, {});
-    getDb()
-      .update(messages)
-      .set({ metadata: envelope("tg-orphan-1") })
-      .where(eq(messages.id, "orphan-user-row"))
-      .run();
-    expect(
-      findMessageByProviderMessageId("telegram", chatId, "tg-orphan-1"),
-    ).toEqual({
-      messageId: "orphan-user-row",
-      conversationId: minted.conversationId,
-    });
-
-    // A legacy linked row whose event carries no source_message_id:
-    // findMessageBySourceId matches only that column, so the fallback must
-    // still admit the row or reactions to it become unresolvable.
-    const legacy = recordInbound("telegram", chatId, "evt-legacy");
-    insertMessage("legacy-user-row", legacy.conversationId, {});
-    getDb()
-      .update(messages)
-      .set({ metadata: envelope("tg-legacy-1") })
-      .where(eq(messages.id, "legacy-user-row"))
-      .run();
-    linkMessage(legacy.eventId, "legacy-user-row");
-    expect(
-      findMessageByProviderMessageId("telegram", chatId, "tg-legacy-1"),
-    ).toEqual({
-      messageId: "legacy-user-row",
-      conversationId: legacy.conversationId,
-    });
-  });
-
-  test("the outbound-posts index resolves a post exactly, at any age", () => {
-    const chatId = "999000111222333444";
-    const minted = recordInbound("discord", chatId, "evt-index-seed");
-    const db = getDb();
-    // The row's envelope names nothing: resolution comes from the index
-    // alone, proving the table is the contract rather than a cache in
-    // front of the scan.
-    db.insert(messages)
-      .values({
-        id: "assistant-indexed-post",
-        conversationId: minted.conversationId,
-        role: "assistant",
-        content: "indexed reply",
-        createdAt: Date.now(),
-        metadata: null,
-      })
-      .run();
-    recordOutboundPost({
-      sourceChannel: "discord",
-      externalChatId: chatId,
-      providerMessageId: "555666777888999000",
-      messageId: "assistant-indexed-post",
-      conversationId: minted.conversationId,
-    });
-    // Idempotent on redelivery.
-    recordOutboundPost({
-      sourceChannel: "discord",
-      externalChatId: chatId,
-      providerMessageId: "555666777888999000",
-      messageId: "assistant-indexed-post",
-      conversationId: minted.conversationId,
-    });
-
-    expect(
-      findMessageByProviderMessageId("discord", chatId, "555666777888999000"),
-    ).toEqual({
-      messageId: "assistant-indexed-post",
-      conversationId: minted.conversationId,
-    });
-    // Channel and chat scoping hold on the index path too.
-    expect(
-      findMessageByProviderMessageId("telegram", chatId, "555666777888999000"),
-    ).toBeNull();
     expect(
-      findMessageByProviderMessageId(
+      findConversationByProviderMessageId(
         "discord",
         "other-chat",
-        "555666777888999000",
+        "1234567890123456789",
       ),
     ).toBeNull();
   });

package/src/__tests__/channel-reply-delivery.test.ts

@@ -32,13 +32,6 @@ type UpdateMessageMetadataCall = {
 };
 const updateMessageMetadataCalls: UpdateMessageMetadataCall[] = [];
 
-/**
- * Number of leading `updateMessageMetadata` calls that throw a transient
- * SQLite error before the mock starts writing. Lets a test assert that a lost
- * reconciliation write is recovered rather than forfeited.
- */
-let metadataWriteFailuresRemaining = 0;
-
 /** Per-test override for the synthetic Slack `ts` returned by deliverChannelReply. */
 let nextDeliveryTs: string | null = null;
 
@@ -152,14 +145,6 @@ mock.module("../persistence/conversation-crud.js", () => ({
     messageId: string,
     updates: Record<string, unknown>,
   ) => {
-    if (metadataWriteFailuresRemaining > 0) {
-      metadataWriteFailuresRemaining -= 1;
-      // Shaped like bun:sqlite's error so `withSqliteRetry` classifies it as
-      // transient contention rather than a fatal write.
-      throw Object.assign(new Error("database is locked"), {
-        code: "SQLITE_BUSY",
-      });
-    }
     updateMessageMetadataCalls.push({ messageId, updates });
     const row = conversationMessages.find((m) => m.id === messageId);
     if (!row) {
@@ -174,15 +159,6 @@ mock.module("../persistence/conversation-crud.js", () => ({
   reserveMessage: mock(async () => ({ id: "msg-reserve" })),
 }));
 
-// The reconciler writes the outbound-posts index through delivery-crud;
-// stub it so this suite stays DB-free while capturing the writes.
-const recordedOutboundPosts: Array<Record<string, string>> = [];
-mock.module("../persistence/delivery-crud.js", () => ({
-  recordOutboundPost: (post: Record<string, string>) => {
-    recordedOutboundPosts.push(post);
-  },
-}));
-
 mock.module("../persistence/attachments-store.js", () => ({
   getAttachmentMetadataForMessage: (messageId: string) =>
     attachmentsByMessageId.get(messageId) ?? [],
@@ -207,7 +183,6 @@ describe("channel-reply-delivery", () => {
     conversationMessages.length = 0;
     attachmentsByMessageId.clear();
     updateMessageMetadataCalls.length = 0;
-    metadataWriteFailuresRemaining = 0;
     nextDeliveryTs = null;
     renderedHistoryContentQueue.length = 0;
     renderedHistoryContent = {
@@ -812,9 +787,7 @@ describe("channel-reply-delivery", () => {
       attachments,
       startFromSegment: 1,
       messageTs: "1700000000.000055",
-      onMessageTs: (ts) => {
-        seenTs.push(ts);
-      },
+      onMessageTs: (ts) => seenTs.push(ts),
     });
 
     expect(deliveryCalls).toHaveLength(1);
@@ -1281,9 +1254,7 @@ describe("channel-reply-delivery", () => {
         "http://gateway/deliver/slack",
         "assistant-compose",
         {
-          onMessageTs: (ts) => {
-            callerTsSeen.push(ts);
-          },
+          onMessageTs: (ts) => callerTsSeen.push(ts),
         },
       );
 
@@ -1323,100 +1294,5 @@ describe("channel-reply-delivery", () => {
       expect(parsed?.source).toBe("slack");
       expect(parsed?.eventKind).toBe("message");
     });
-
-    it("retries a reconciliation write that hits transient SQLite contention", async () => {
-      // The stamp is the only durable record of the post's ts: no later sweep
-      // heals a miss once the event is marked delivered, so a SQLITE_BUSY on
-      // the first attempt must not lose it.
-      pushPartialAssistantRow("conv-busy", "msg-busy", "C333");
-      nextDeliveryTs = "1700000800.000444";
-      metadataWriteFailuresRemaining = 1;
-
-      await deliverReplyViaCallback(
-        "conv-busy",
-        "C333",
-        "http://gateway/deliver/slack",
-        "assistant-busy",
-      );
-
-      expect(updateMessageMetadataCalls.length).toBe(1);
-      const merged = updateMessageMetadataCalls[0].updates.slackMeta as string;
-      const parsed = JSON.parse(merged) as Record<string, unknown>;
-      expect(parsed.channelTs).toBe("1700000800.000444");
-    });
-
-    it("stamps from a later segment when the first segment's write is lost", async () => {
-      // The row records the first ts that reaches a DURABLE write, not the
-      // first ts observed. A first-invocation latch would forfeit channelTs
-      // forever when that write fails, which is the reconciliation gap this
-      // reproduces: the reply posts successfully and the row never gains its
-      // own id, so history projects no `slackMessage` for it.
-      pushPartialAssistantRow("conv-lost", "msg-lost", "C444");
-      renderedHistoryContent = {
-        text: "AlphaBeta",
-        textSegments: ["Alpha", "Beta"],
-        toolCalls: [],
-        toolCallsBeforeText: false,
-        contentOrder: ["text:0", "tool:0", "text:1"],
-        surfaces: [],
-        thinkingSegments: [],
-      };
-      nextDeliveryTs = "1700000900.000555";
-      // Exhaust the initial attempt plus every `withSqliteRetry` retry, so the
-      // first segment's reconciliation is genuinely swallowed.
-      metadataWriteFailuresRemaining = 4;
-
-      await deliverReplyViaCallback(
-        "conv-lost",
-        "C444",
-        "http://gateway/deliver/slack",
-        "assistant-lost",
-      );
-
-      // Both segments posted; the surviving write carries the second post's ts
-      // rather than leaving the row without any id of its own.
-      expect(deliveryCalls.length).toBe(2);
-      expect(updateMessageMetadataCalls.length).toBe(1);
-      const merged = updateMessageMetadataCalls[0].updates.slackMeta as string;
-      const { readSlackMetadata } =
-        await import("../messaging/providers/slack/message-metadata.js");
-      expect(readSlackMetadata(merged)).not.toBeNull();
-    });
-
-    it("commits the reconciliation write before posting the next segment", async () => {
-      // `onMessageTs` is awaited, so the row is durable at each segment
-      // boundary. Otherwise a crash between two posts of a split reply loses
-      // the stamp for a message the reader can already see.
-      pushPartialAssistantRow("conv-order", "msg-order", "C555");
-      renderedHistoryContent = {
-        text: "AlphaBeta",
-        textSegments: ["Alpha", "Beta"],
-        toolCalls: [],
-        toolCallsBeforeText: false,
-        contentOrder: ["text:0", "tool:0", "text:1"],
-        surfaces: [],
-        thinkingSegments: [],
-      };
-      nextDeliveryTs = "1700001000.000666";
-
-      await deliverReplyViaCallback(
-        "conv-order",
-        "C555",
-        "http://gateway/deliver/slack",
-        "assistant-order",
-      );
-
-      // The row already parses through the strict reader by the time the
-      // second POST goes out, which is what makes the second segment a no-op.
-      const row = conversationMessages.find((m) => m.id === "msg-order");
-      const envelope = JSON.parse(row?.metadata ?? "{}") as Record<
-        string,
-        unknown
-      >;
-      const { readSlackMetadata } =
-        await import("../messaging/providers/slack/message-metadata.js");
-      expect(readSlackMetadata(envelope.slackMeta as string)).not.toBeNull();
-      expect(updateMessageMetadataCalls.length).toBe(1);
-    });
   });
 });