@vellumai/assistant 0.5.16 → 0.6.1

package/src/runtime/routes/inbound-stages/guardian-activation-intercept.test.ts

@@ -0,0 +1,292 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Mocks — must be set up before importing the module under test
+// ---------------------------------------------------------------------------
+
+let mockGuardian: { contact: unknown; channel: unknown } | null = null;
+let mockActiveSession: Record<string, unknown> | null = null;
+let mockSessionResult = {
+  sessionId: "sess-1",
+  secret: "123456",
+  challengeHash: "hash-1",
+  expiresAt: Date.now() + 600_000,
+  ttlSeconds: 600,
+};
+
+// Track calls manually to avoid TypeScript issues with mock() generics
+let createOutboundSessionCalls: unknown[] = [];
+let deliverChannelReplyCalls: unknown[][] = [];
+let emitNotificationSignalCalls: unknown[] = [];
+let messageIdCounter = 0;
+
+mock.module("../../../contacts/contact-store.js", () => ({
+  findGuardianForChannel: () => mockGuardian,
+}));
+
+mock.module("../../channel-verification-service.js", () => ({
+  createOutboundSession: (params: unknown) => {
+    createOutboundSessionCalls.push(params);
+    return mockSessionResult;
+  },
+  findActiveSession: () => mockActiveSession,
+}));
+
+mock.module("../../gateway-client.js", () => ({
+  deliverChannelReply: (url: unknown, payload: unknown, token: unknown) => {
+    deliverChannelReplyCalls.push([url, payload, token]);
+    return Promise.resolve({ ok: true });
+  },
+}));
+
+mock.module("../../../notifications/emit-signal.js", () => ({
+  emitNotificationSignal: (params: unknown) => {
+    emitNotificationSignalCalls.push(params);
+    return Promise.resolve({
+      signalId: "sig-1",
+      deduplicated: false,
+      dispatched: true,
+      reason: "ok",
+      deliveryResults: [],
+    });
+  },
+}));
+
+mock.module("../../../util/logger.js", () => ({
+  getLogger: () => ({
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+  }),
+}));
+
+// Import after mocks are installed
+const { handleGuardianActivationIntercept } =
+  await import("./guardian-activation-intercept.js");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeParams(
+  overrides: Partial<
+    Parameters<typeof handleGuardianActivationIntercept>[0]
+  > = {},
+) {
+  messageIdCounter++;
+  return {
+    sourceChannel: "telegram" as const,
+    conversationExternalId: "chat-123",
+    rawSenderId: "user-42",
+    canonicalSenderId: "user-42",
+    actorDisplayName: "Alice",
+    actorUsername: "alice",
+    sourceMetadata: { commandIntent: { type: "start" } },
+    replyCallbackUrl: "https://gateway/reply",
+    mintBearerToken: () => "token-123",
+    assistantId: "self",
+    externalMessageId: `msg-${messageIdCounter}`,
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("handleGuardianActivationIntercept", () => {
+  beforeEach(() => {
+    mockGuardian = null;
+    mockActiveSession = null;
+    mockSessionResult = {
+      sessionId: "sess-1",
+      secret: "123456",
+      challengeHash: "hash-1",
+      expiresAt: Date.now() + 600_000,
+      ttlSeconds: 600,
+    };
+    createOutboundSessionCalls = [];
+    deliverChannelReplyCalls = [];
+    emitNotificationSignalCalls = [];
+  });
+
+  afterEach(() => {
+    createOutboundSessionCalls = [];
+    deliverChannelReplyCalls = [];
+    emitNotificationSignalCalls = [];
+  });
+
+  test("bare /start with no guardian creates session and returns early", async () => {
+    const result = await handleGuardianActivationIntercept(makeParams());
+
+    expect(result).not.toBeNull();
+    const body = await result!.json();
+    expect(body).toEqual({ accepted: true, guardianActivation: true });
+
+    // Verify createOutboundSession was called with correct params
+    expect(createOutboundSessionCalls).toHaveLength(1);
+    expect(createOutboundSessionCalls[0]).toEqual({
+      channel: "telegram",
+      expectedExternalUserId: "user-42",
+      expectedChatId: "chat-123",
+      identityBindingStatus: "bound",
+      destinationAddress: "chat-123",
+      verificationPurpose: "guardian",
+    });
+
+    // Verify deliverChannelReply was called with the welcome/verify message
+    expect(deliverChannelReplyCalls).toHaveLength(1);
+    expect(deliverChannelReplyCalls[0][0]).toBe("https://gateway/reply");
+    expect(deliverChannelReplyCalls[0][1]).toEqual({
+      chatId: "chat-123",
+      text: "Welcome! To verify your identity as guardian, check your assistant app for a verification code and enter it here.",
+      assistantId: "self",
+    });
+
+    // Verify emitNotificationSignal was called with guardian.channel_activation
+    expect(emitNotificationSignalCalls).toHaveLength(1);
+    const signalArgs = emitNotificationSignalCalls[0] as Record<string, any>;
+    expect(signalArgs.sourceEventName).toBe("guardian.channel_activation");
+    expect(signalArgs.contextPayload.verificationCode).toBe("123456");
+    expect(signalArgs.contextPayload.sourceChannel).toBe("telegram");
+    expect(signalArgs.contextPayload.actorExternalId).toBe("user-42");
+    expect(signalArgs.contextPayload.sessionId).toBe("sess-1");
+    expect(signalArgs.dedupeKey).toBe("guardian-activation:sess-1");
+  });
+
+  test("bare /start with existing guardian returns null", async () => {
+    mockGuardian = {
+      contact: { id: "contact-1", role: "guardian" },
+      channel: { id: "ch-1", type: "telegram" },
+    };
+
+    const result = await handleGuardianActivationIntercept(makeParams());
+    expect(result).toBeNull();
+    expect(createOutboundSessionCalls).toHaveLength(0);
+  });
+
+  test("/start with payload returns null", async () => {
+    const result = await handleGuardianActivationIntercept(
+      makeParams({
+        sourceMetadata: {
+          commandIntent: { type: "start", payload: "gv_token" },
+        },
+      }),
+    );
+    expect(result).toBeNull();
+    expect(createOutboundSessionCalls).toHaveLength(0);
+  });
+
+  test("non-/start message returns null", async () => {
+    const result = await handleGuardianActivationIntercept(
+      makeParams({
+        sourceMetadata: { commandIntent: { type: "other" } },
+      }),
+    );
+    expect(result).toBeNull();
+    expect(createOutboundSessionCalls).toHaveLength(0);
+  });
+
+  test("no commandIntent returns null", async () => {
+    const result = await handleGuardianActivationIntercept(
+      makeParams({ sourceMetadata: {} }),
+    );
+    expect(result).toBeNull();
+
+    const result2 = await handleGuardianActivationIntercept(
+      makeParams({ sourceMetadata: undefined }),
+    );
+    expect(result2).toBeNull();
+    expect(createOutboundSessionCalls).toHaveLength(0);
+  });
+
+  test("non-telegram channel returns null", async () => {
+    const result = await handleGuardianActivationIntercept(
+      makeParams({ sourceChannel: "slack" as any }),
+    );
+    expect(result).toBeNull();
+    expect(createOutboundSessionCalls).toHaveLength(0);
+  });
+
+  test("missing sender ID returns null", async () => {
+    const result = await handleGuardianActivationIntercept(
+      makeParams({ rawSenderId: undefined }),
+    );
+    expect(result).toBeNull();
+    expect(createOutboundSessionCalls).toHaveLength(0);
+  });
+
+  test("existing active session from same sender sends 'already in progress' reply", async () => {
+    mockActiveSession = {
+      id: "existing-sess",
+      channel: "telegram",
+      status: "awaiting_response",
+      expectedExternalUserId: "user-42",
+      expectedChatId: "chat-123",
+    };
+
+    const result = await handleGuardianActivationIntercept(makeParams());
+
+    expect(result).not.toBeNull();
+    const body = await result!.json();
+    expect(body).toEqual({ accepted: true, guardianActivationPending: true });
+
+    // createOutboundSession should NOT be called
+    expect(createOutboundSessionCalls).toHaveLength(0);
+
+    // deliverChannelReply should be called with the "already in progress" message
+    expect(deliverChannelReplyCalls).toHaveLength(1);
+    expect(deliverChannelReplyCalls[0][1]).toEqual({
+      chatId: "chat-123",
+      text: "A verification is already in progress. Check your assistant app for the code and enter it here.",
+      assistantId: "self",
+    });
+
+    // emitNotificationSignal should NOT be called
+    expect(emitNotificationSignalCalls).toHaveLength(0);
+  });
+
+  test("existing active session from different sender allows superseding", async () => {
+    mockActiveSession = {
+      id: "existing-sess",
+      channel: "telegram",
+      status: "awaiting_response",
+      expectedExternalUserId: "user-OTHER",
+      expectedChatId: "chat-OTHER",
+    };
+
+    const result = await handleGuardianActivationIntercept(makeParams());
+
+    // Should proceed and create a new session (superseding the stale one)
+    expect(result).not.toBeNull();
+    const body = await result!.json();
+    expect(body).toEqual({ accepted: true, guardianActivation: true });
+    expect(createOutboundSessionCalls).toHaveLength(1);
+    expect(emitNotificationSignalCalls).toHaveLength(1);
+  });
+
+  test("duplicate webhook retry is silently deduped", async () => {
+    const params = makeParams({ externalMessageId: "dedup-test-msg" });
+
+    // First call should process normally
+    const result1 = await handleGuardianActivationIntercept(params);
+    expect(result1).not.toBeNull();
+    const body1 = await result1!.json();
+    expect(body1).toEqual({ accepted: true, guardianActivation: true });
+    expect(createOutboundSessionCalls).toHaveLength(1);
+    expect(deliverChannelReplyCalls).toHaveLength(1);
+    expect(emitNotificationSignalCalls).toHaveLength(1);
+
+    // Second call with same externalMessageId should be deduped
+    const result2 = await handleGuardianActivationIntercept(params);
+    expect(result2).not.toBeNull();
+    const body2 = await result2!.json();
+    expect(body2).toEqual({ accepted: true, guardianActivation: true });
+
+    // No additional session/reply/signal calls
+    expect(createOutboundSessionCalls).toHaveLength(1);
+    expect(deliverChannelReplyCalls).toHaveLength(1);
+    expect(emitNotificationSignalCalls).toHaveLength(1);
+  });
+});

package/src/runtime/routes/inbound-stages/guardian-activation-intercept.ts

@@ -0,0 +1,207 @@
+/**
+ * Guardian activation intercept stage: when a bare /start arrives on a
+ * Telegram channel with no existing guardian, auto-initiate a verification
+ * session so the first user can claim the channel as guardian.
+ *
+ * This runs BEFORE ACL enforcement — a bare /start from an unknown user
+ * would otherwise be rejected. When the user subsequently enters the
+ * 6-digit code, the existing verification intercept validates it, creates
+ * the guardian binding, and sends a success reply.
+ */
+import type { ChannelId } from "../../../channels/types.js";
+import { findGuardianForChannel } from "../../../contacts/contact-store.js";
+import { emitNotificationSignal } from "../../../notifications/emit-signal.js";
+import type { NotificationSourceChannel } from "../../../notifications/signal.js";
+import { getLogger } from "../../../util/logger.js";
+import {
+  createOutboundSession,
+  findActiveSession,
+} from "../../channel-verification-service.js";
+import { deliverChannelReply } from "../../gateway-client.js";
+
+const log = getLogger("runtime-http");
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface GuardianActivationInterceptParams {
+  sourceChannel: ChannelId;
+  conversationExternalId: string;
+  rawSenderId: string | undefined;
+  canonicalSenderId: string | null;
+  actorDisplayName: string | undefined;
+  actorUsername: string | undefined;
+  sourceMetadata: Record<string, unknown> | undefined;
+  replyCallbackUrl: string | undefined;
+  mintBearerToken: () => string;
+  assistantId: string;
+  externalMessageId: string;
+}
+
+/**
+ * Lightweight dedup set for guardian activation intercepts.
+ * Prevents duplicate replies when Telegram retries the same webhook.
+ * Entries are evicted after DEDUP_TTL_MS to avoid unbounded growth.
+ */
+const DEDUP_TTL_MS = 60_000;
+const processedMessageIds = new Map<string, number>();
+
+function isAlreadyProcessed(messageId: string): boolean {
+  const now = Date.now();
+  // Evict stale entries
+  for (const [key, ts] of processedMessageIds) {
+    if (now - ts > DEDUP_TTL_MS) processedMessageIds.delete(key);
+  }
+  return processedMessageIds.has(messageId);
+}
+
+function markProcessed(messageId: string): void {
+  processedMessageIds.set(messageId, Date.now());
+}
+
+export async function handleGuardianActivationIntercept(
+  params: GuardianActivationInterceptParams,
+): Promise<Response | null> {
+  const {
+    sourceChannel,
+    conversationExternalId,
+    rawSenderId,
+    actorDisplayName,
+    actorUsername,
+    sourceMetadata,
+    replyCallbackUrl,
+    mintBearerToken,
+    assistantId,
+    externalMessageId,
+  } = params;
+
+  // ── Extract commandIntent ──
+  const rawCommandIntent = sourceMetadata?.commandIntent;
+  const commandIntent =
+    rawCommandIntent &&
+    typeof rawCommandIntent === "object" &&
+    !Array.isArray(rawCommandIntent)
+      ? (rawCommandIntent as Record<string, unknown>)
+      : undefined;
+
+  // Only proceed for /start commands
+  if (!commandIntent || commandIntent.type !== "start") return null;
+
+  // If /start has a payload (e.g. gv_token, iv_token), let the existing
+  // bootstrap/invite handlers deal with it.
+  if (
+    typeof commandIntent.payload === "string" &&
+    commandIntent.payload.length > 0
+  ) {
+    return null;
+  }
+
+  // Only proceed for Telegram (can be extended later)
+  if (sourceChannel !== "telegram") return null;
+
+  // If a guardian already exists for this channel, continue to normal flow
+  if (findGuardianForChannel(sourceChannel)) return null;
+
+  // Can't bind a session without sender identity
+  if (!rawSenderId) return null;
+
+  // ── Webhook retry dedup ──
+  // The intercept runs before recordInbound, so use a lightweight in-memory
+  // dedup to prevent duplicate replies when Telegram retries the webhook.
+  // Only checked here; marked as processed after successful session creation
+  // so transient failures remain retryable.
+  if (isAlreadyProcessed(externalMessageId)) {
+    return Response.json({ accepted: true, guardianActivation: true });
+  }
+
+  // ── Idempotency: check for an existing active session from this sender ──
+  const existingSession = findActiveSession(sourceChannel);
+  if (existingSession) {
+    // Only block if the session belongs to the same sender. If a different
+    // user triggered the session, let this sender proceed (they'll supersede
+    // the stale session via createOutboundSession's revocation logic).
+    const sessionOwner =
+      existingSession.expectedExternalUserId ?? existingSession.expectedChatId;
+    if (
+      sessionOwner === rawSenderId ||
+      sessionOwner === conversationExternalId
+    ) {
+      if (replyCallbackUrl) {
+        deliverChannelReply(
+          replyCallbackUrl,
+          {
+            chatId: conversationExternalId,
+            text: "A verification is already in progress. Check your assistant app for the code and enter it here.",
+            assistantId,
+          },
+          mintBearerToken(),
+        ).catch((err) => {
+          log.error(
+            { err, sourceChannel, conversationExternalId },
+            "Failed to deliver guardian activation idempotency reply",
+          );
+        });
+      }
+      markProcessed(externalMessageId);
+      return Response.json({ accepted: true, guardianActivationPending: true });
+    }
+  }
+
+  // ── Create verification session ──
+  const sessionResult = createOutboundSession({
+    channel: sourceChannel,
+    expectedExternalUserId: rawSenderId,
+    expectedChatId: conversationExternalId,
+    identityBindingStatus: "bound",
+    destinationAddress: conversationExternalId,
+    verificationPurpose: "guardian",
+  });
+
+  // Mark as processed only after session creation succeeds so transient
+  // failures (e.g. temporary DB issues) remain retryable on the next webhook.
+  markProcessed(externalMessageId);
+
+  // ── Send deterministic Telegram reply ──
+  if (replyCallbackUrl) {
+    deliverChannelReply(
+      replyCallbackUrl,
+      {
+        chatId: conversationExternalId,
+        text: "Welcome! To verify your identity as guardian, check your assistant app for a verification code and enter it here.",
+        assistantId,
+      },
+      mintBearerToken(),
+    ).catch((err) => {
+      log.error(
+        { err, sourceChannel, conversationExternalId },
+        "Failed to deliver guardian activation welcome reply",
+      );
+    });
+  }
+
+  // ── Emit notification signal to deliver code to macOS app ──
+  void emitNotificationSignal({
+    sourceEventName: "guardian.channel_activation",
+    sourceChannel: sourceChannel as NotificationSourceChannel,
+    sourceContextId: `guardian-activation-${sourceChannel}-${rawSenderId}`,
+    attentionHints: {
+      requiresAction: true,
+      urgency: "high",
+      isAsyncBackground: false,
+      visibleInSourceNow: false,
+    },
+    contextPayload: {
+      verificationCode: sessionResult.secret,
+      sourceChannel,
+      actorExternalId: rawSenderId,
+      actorDisplayName: actorDisplayName ?? null,
+      actorUsername: actorUsername ?? null,
+      sessionId: sessionResult.sessionId,
+      expiresAt: sessionResult.expiresAt,
+    },
+    dedupeKey: `guardian-activation:${sessionResult.sessionId}`,
+  });
+
+  return Response.json({ accepted: true, guardianActivation: true });
+}

package/src/runtime/routes/llm-context-normalization.ts

@@ -570,16 +570,8 @@ function anthropicMessageSections(
   const role = asString(message.role) ?? "unknown";
   const content = message.content;
   const sections: LlmContextSection[] = [];
-  const text = collectAnthropicMessageText(content);
-  if (text) {
-    sections.push({
-      kind: "message",
-      label,
-      role,
-      text,
-    });
-  }
 
+  // Collect reasoning sections first so they appear before the message text.
   for (const block of asRecordArray(content) ?? []) {
     const type = asString(block.type);
     if (type === "thinking" || type === "redacted_thinking") {
@@ -589,9 +581,21 @@ function anthropicMessageSections(
         role,
         text: collectAnthropicReasoningText(block),
       });
-      continue;
     }
+  }
 
+  const text = collectAnthropicMessageText(content);
+  if (text) {
+    sections.push({
+      kind: "message",
+      label,
+      role,
+      text,
+    });
+  }
+
+  for (const block of asRecordArray(content) ?? []) {
+    const type = asString(block.type);
     if (isAnthropicToolUseType(type)) {
       sections.push({
         kind: "tool_use",