@vellumai/assistant 0.10.5 → 0.10.6-dev.202607062043.72bc40b

package/src/runtime/routes/inbound-stages/background-dispatch.test.ts

@@ -438,7 +438,12 @@ describe("processChannelMessageInBackground — slack thread mapping", () => {
     await flush();
 
     expect(slackStreamOps()).toEqual([
-      { action: "start", threadTs, markdownText: "Streamed DM reply." },
+      {
+        action: "start",
+        threadTs,
+        markdownText: "Streamed DM reply.",
+        taskDisplayMode: "plan",
+      },
       { action: "stop", streamTs },
     ]);
     expect(

package/src/runtime/routes/inbound-stages/background-dispatch.ts

@@ -46,7 +46,7 @@ import type {
   MessageProcessor,
   SlackInboundMessageMetadata,
 } from "../../http-types.js";
-import { hasDeliverableAssistantText } from "../../slack-no-response.js";
+import { hasDeliverableAssistantText } from "../../no-response.js";
 import { createSlackReplySession } from "../../slack-reply-session.js";
 import type { TaskProgressData } from "../../slack-task-progress.js";
 import {

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

@@ -0,0 +1,266 @@
+/**
+ * Unit tests for the bootstrap deep-link intercept stage against the
+ * gateway-backed session client.
+ *
+ * Covers: the happy-path /start gv_<token> handoff (resolve → bind →
+ * fresh identity-bound session → delivery tracking; the mint revokes the
+ * bootstrap session gateway-side), fall-through for unresolvable tokens,
+ * ACL-threaded session reuse (no second gateway lookup), the
+ * gateway-unreachable posture (handled "unavailable" response — never
+ * fall-through to normal processing), retryability (any failure before the
+ * mint leaves the original session pending_bootstrap), and the atomic claim:
+ * a concurrent handoff that already consumed the token conflicts instead of
+ * minting a second code.
+ */
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { createGatewayVerificationSessionsStub } from "../../../__tests__/helpers/gateway-verification-sessions-stub.js";
+
+mock.module("../../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, { get: () => () => {} }),
+}));
+
+// Gateway-backed session client (async IPC); throw toggles simulate an
+// unreachable gateway per lifecycle call.
+const gatewaySessions = createGatewayVerificationSessionsStub({
+  mintResult: () => ({
+    sessionId: "new-session-1",
+    secret: "654321",
+    challengeHash: "hash-1",
+    expiresAt: Date.now() + 600_000,
+    ttlSeconds: 600,
+  }),
+});
+mock.module(
+  "../../../channels/gateway-verification-sessions.js",
+  () => gatewaySessions.module,
+);
+
+const telegramReplies: Array<{ chatId: string; text: string }> = [];
+mock.module("../../../messaging/providers/telegram-bot/send.js", () => ({
+  sendTelegramReply: async (chatId: string, text: string) => {
+    telegramReplies.push({ chatId, text });
+  },
+}));
+
+mock.module("../../verification-outbound-actions.js", () => ({
+  RESEND_COOLDOWN_MS: 60_000,
+}));
+
+import type { VerificationSessionWire } from "../../../channels/gateway-verification-sessions.js";
+import type { BootstrapInterceptParams } from "./bootstrap-intercept.js";
+import { handleBootstrapIntercept } from "./bootstrap-intercept.js";
+
+function makeParams(
+  overrides: Partial<BootstrapInterceptParams> = {},
+): BootstrapInterceptParams {
+  return {
+    isDuplicate: false,
+    commandIntent: { type: "start", payload: "gv_token123" },
+    rawSenderId: "user-42",
+    canonicalAssistantId: "self",
+    sourceChannel: "telegram",
+    conversationExternalId: "chat-123",
+    eventId: "event-1",
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  gatewaySessions.reset();
+  gatewaySessions.state.bootstrapSession = {
+    id: "bootstrap-session-1",
+    channel: "telegram",
+    status: "pending_bootstrap",
+  };
+  telegramReplies.length = 0;
+});
+
+describe("handleBootstrapIntercept", () => {
+  test("valid token binds identity, rotates the session, and returns bootstrap_bound", async () => {
+    const result = await handleBootstrapIntercept(makeParams());
+
+    expect(result).toEqual({
+      accepted: true,
+      duplicate: false,
+      eventId: "event-1",
+      verificationOutcome: "bootstrap_bound",
+    });
+
+    // Raw token (gv_ prefix stripped); hashing is gateway-side.
+    expect(gatewaySessions.calls.resolveBootstrapToken).toEqual([
+      ["telegram", "token123"],
+    ]);
+    expect(gatewaySessions.calls.bindSessionIdentity).toEqual([
+      ["bootstrap-session-1", "user-42", "chat-123"],
+    ]);
+    // The mint revokes the bootstrap session gateway-side; no separate
+    // status transition — that would make a mint failure unretryable.
+    expect(gatewaySessions.calls.updateSessionStatus).toHaveLength(0);
+    expect(gatewaySessions.calls.create).toEqual([
+      {
+        channel: "telegram",
+        expectedExternalUserId: "user-42",
+        expectedChatId: "chat-123",
+        identityBindingStatus: "bound",
+        destinationAddress: "chat-123",
+        // Atomic gateway-side claim of the bootstrap session.
+        requireSourceSessionPending: "bootstrap-session-1",
+      },
+    ]);
+    expect(gatewaySessions.calls.updateSessionDelivery).toHaveLength(1);
+    expect(gatewaySessions.calls.updateSessionDelivery[0][0]).toBe(
+      "new-session-1",
+    );
+  });
+
+  test("unresolvable token falls through to normal /start handling", async () => {
+    gatewaySessions.state.bootstrapSession = null;
+
+    const result = await handleBootstrapIntercept(makeParams());
+
+    expect(result).toBeNull();
+    expect(gatewaySessions.calls.bindSessionIdentity).toHaveLength(0);
+    expect(gatewaySessions.calls.create).toHaveLength(0);
+  });
+
+  test("non-pending_bootstrap session falls through", async () => {
+    gatewaySessions.state.bootstrapSession = {
+      id: "bootstrap-session-1",
+      channel: "telegram",
+      status: "consumed",
+    };
+
+    const result = await handleBootstrapIntercept(makeParams());
+
+    expect(result).toBeNull();
+    expect(gatewaySessions.calls.bindSessionIdentity).toHaveLength(0);
+  });
+
+  test("non-bootstrap commands fall through untouched", async () => {
+    expect(
+      await handleBootstrapIntercept(
+        makeParams({ commandIntent: { type: "start", payload: "iv_other" } }),
+      ),
+    ).toBeNull();
+    expect(
+      await handleBootstrapIntercept(makeParams({ isDuplicate: true })),
+    ).toBeNull();
+    expect(
+      await handleBootstrapIntercept(makeParams({ rawSenderId: undefined })),
+    ).toBeNull();
+    expect(gatewaySessions.calls.resolveBootstrapToken).toHaveLength(0);
+  });
+
+  test("gateway unreachable on token resolution returns a handled unavailable response — no fall-through", async () => {
+    gatewaySessions.unreachable.resolveBootstrapToken = true;
+
+    const result = await handleBootstrapIntercept(makeParams());
+
+    expect(result).toEqual({
+      accepted: true,
+      duplicate: false,
+      eventId: "event-1",
+      verificationOutcome: "bootstrap_unavailable",
+    });
+    expect(gatewaySessions.calls.bindSessionIdentity).toHaveLength(0);
+    expect(gatewaySessions.calls.create).toHaveLength(0);
+    expect(telegramReplies).toHaveLength(1);
+    expect(telegramReplies[0].text).toContain("tap the link again");
+  });
+
+  test("gateway unreachable on identity bind leaves the session pending_bootstrap and responds unavailable", async () => {
+    gatewaySessions.unreachable.bindSessionIdentity = true;
+
+    const result = await handleBootstrapIntercept(makeParams());
+
+    expect(result).toMatchObject({
+      verificationOutcome: "bootstrap_unavailable",
+    });
+    // Nothing moved the session out of pending_bootstrap — re-tap retries.
+    expect(gatewaySessions.calls.updateSessionStatus).toHaveLength(0);
+    expect(gatewaySessions.calls.create).toHaveLength(0);
+    expect(telegramReplies).toHaveLength(1);
+  });
+
+  test("gateway unreachable on session creation leaves the session pending_bootstrap and responds unavailable", async () => {
+    gatewaySessions.unreachable.createOutboundSessionConditional = true;
+
+    const result = await handleBootstrapIntercept(makeParams());
+
+    expect(result).toMatchObject({
+      verificationOutcome: "bootstrap_unavailable",
+    });
+    // Bind ran but binding never changes status, so the token is still
+    // resolvable and the deep link remains retryable.
+    expect(gatewaySessions.calls.bindSessionIdentity).toHaveLength(1);
+    expect(gatewaySessions.calls.updateSessionStatus).toHaveLength(0);
+    expect(gatewaySessions.calls.updateSessionDelivery).toHaveLength(0);
+    expect(telegramReplies).toHaveLength(1);
+  });
+
+  test("ACL-threaded session skips the second gateway lookup and completes the handoff", async () => {
+    const result = await handleBootstrapIntercept(
+      makeParams({
+        validatedBootstrapSession: {
+          id: "bootstrap-session-1",
+          channel: "telegram",
+          status: "pending_bootstrap",
+        } as unknown as VerificationSessionWire,
+      }),
+    );
+
+    expect(result).toMatchObject({ verificationOutcome: "bootstrap_bound" });
+    expect(gatewaySessions.calls.resolveBootstrapToken).toHaveLength(0);
+    expect(gatewaySessions.calls.bindSessionIdentity).toEqual([
+      ["bootstrap-session-1", "user-42", "chat-123"],
+    ]);
+  });
+
+  test("ACL-threaded session with a failing handoff still returns the handled unavailable response", async () => {
+    gatewaySessions.unreachable.bindSessionIdentity = true;
+
+    const result = await handleBootstrapIntercept(
+      makeParams({
+        validatedBootstrapSession: {
+          id: "bootstrap-session-1",
+          channel: "telegram",
+          status: "pending_bootstrap",
+        } as unknown as VerificationSessionWire,
+      }),
+    );
+
+    expect(result).toMatchObject({
+      verificationOutcome: "bootstrap_unavailable",
+    });
+    expect(gatewaySessions.calls.resolveBootstrapToken).toHaveLength(0);
+    expect(telegramReplies).toHaveLength(1);
+  });
+
+  test("losing the concurrent claim race returns a handled response without a second code", async () => {
+    gatewaySessions.state.conflictReason = "source_session_not_pending";
+
+    const result = await handleBootstrapIntercept(makeParams());
+
+    // The winner already sent its code; the loser must not mint, reply, or
+    // touch delivery tracking — and must not fall through.
+    expect(result).toEqual({
+      accepted: true,
+      duplicate: false,
+      eventId: "event-1",
+      verificationOutcome: "bootstrap_already_claimed",
+    });
+    expect(gatewaySessions.calls.create).toHaveLength(1);
+    expect(gatewaySessions.calls.updateSessionDelivery).toHaveLength(0);
+    expect(telegramReplies).toHaveLength(0);
+  });
+
+  test("delivery-tracking failure after the code is sent does not unwind the bootstrap", async () => {
+    gatewaySessions.unreachable.updateSessionDelivery = true;
+
+    const result = await handleBootstrapIntercept(makeParams());
+
+    expect(result).toMatchObject({ verificationOutcome: "bootstrap_bound" });
+  });
+});

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

@@ -11,16 +11,19 @@
  * Extracted from inbound-message-handler.ts to keep the top-level handler
  * focused on orchestration.
  */
-import type { ChannelId } from "../../../channels/types.js";
-import { sendTelegramReply } from "../../../messaging/providers/telegram-bot/send.js";
-import { getLogger } from "../../../util/logger.js";
+import type {
+  CreateOutboundSessionResult,
+  VerificationSessionWire,
+} from "../../../channels/gateway-verification-sessions.js";
 import {
   bindSessionIdentity,
-  createOutboundSession,
+  createOutboundSessionConditional,
   resolveBootstrapToken,
   updateSessionDelivery,
-  updateSessionStatus,
-} from "../../channel-verification-service.js";
+} from "../../../channels/gateway-verification-sessions.js";
+import type { ChannelId } from "../../../channels/types.js";
+import { sendTelegramReply } from "../../../messaging/providers/telegram-bot/send.js";
+import { getLogger } from "../../../util/logger.js";
 import { RESEND_COOLDOWN_MS } from "../../verification-outbound-actions.js";
 import {
   composeVerificationTelegram,
@@ -41,6 +44,40 @@ export interface BootstrapInterceptParams {
   sourceChannel: ChannelId;
   conversationExternalId: string;
   eventId: string;
+  /**
+   * Session already resolved by ACL enforcement for this token. When set,
+   * the admission floor was skipped on its strength; this stage reuses it
+   * instead of re-resolving via the gateway.
+   */
+  validatedBootstrapSession?: VerificationSessionWire;
+}
+
+const BOOTSTRAP_UNAVAILABLE_REPLY =
+  "I couldn't process your verification link just now. Please tap the link again in a moment.";
+
+/**
+ * Deterministic handled response for gateway failures mid-bootstrap. ACL may
+ * have skipped the admission floor for this token, so a gv_ command must
+ * never fall through to normal processing on a transient gateway failure.
+ */
+async function respondBootstrapUnavailable(
+  conversationExternalId: string,
+  eventId: string,
+): Promise<Record<string, unknown>> {
+  try {
+    await sendTelegramReply(conversationExternalId, BOOTSTRAP_UNAVAILABLE_REPLY);
+  } catch (err) {
+    log.error(
+      { err, chatId: conversationExternalId },
+      "Failed to deliver bootstrap unavailable reply",
+    );
+  }
+  return {
+    accepted: true,
+    duplicate: false,
+    eventId,
+    verificationOutcome: "bootstrap_unavailable",
+  };
 }
 
 /**
@@ -60,6 +97,7 @@ export async function handleBootstrapIntercept(
     sourceChannel,
     conversationExternalId,
     eventId,
+    validatedBootstrapSession,
   } = params;
 
   if (
@@ -72,29 +110,85 @@ export async function handleBootstrapIntercept(
     return null;
   }
 
+  // Sessions live in the gateway. When ACL already validated this token it
+  // threads the session through — no second lookup. Otherwise resolve here;
+  // a gateway failure must never fall through to normal processing (the
+  // floor may have been skipped), so degrade to a handled "try again" reply.
   const bootstrapToken = (commandIntent.payload as string).slice(3);
-  const bootstrapSession = resolveBootstrapToken(sourceChannel, bootstrapToken);
+  let bootstrapSession: VerificationSessionWire | null;
+  if (validatedBootstrapSession) {
+    bootstrapSession = validatedBootstrapSession;
+  } else {
+    try {
+      bootstrapSession = await resolveBootstrapToken(
+        sourceChannel,
+        bootstrapToken,
+      );
+    } catch (err) {
+      log.warn(
+        { err, sourceChannel },
+        "Bootstrap intercept: token resolution failed (gateway unreachable)",
+      );
+      return respondBootstrapUnavailable(conversationExternalId, eventId);
+    }
+  }
 
   if (!bootstrapSession || bootstrapSession.status !== "pending_bootstrap") {
-    // Not found or expired — fall through to normal /start handling
+    // Not found or expired — fall through to normal /start handling. Only
+    // reachable when ACL did not validate the token (a threaded session is
+    // always pending_bootstrap), so the admission floor already ran.
     return null;
   }
 
-  // Bind the pending_bootstrap session to the sender's identity
-  bindSessionIdentity(bootstrapSession.id, rawSenderId, conversationExternalId);
+  let minted: Awaited<ReturnType<typeof createOutboundSessionConditional>>;
+  try {
+    // Bind the pending_bootstrap session to the sender's identity. Binding
+    // leaves status untouched, so a failure anywhere before the mint keeps
+    // the token resolvable and the deep link retryable.
+    await bindSessionIdentity(
+      bootstrapSession.id,
+      rawSenderId,
+      conversationExternalId,
+    );
 
-  // Transition bootstrap session to awaiting_response
-  updateSessionStatus(bootstrapSession.id, "awaiting_response");
+    // Mint the identity-bound replacement with a fresh secret. The gateway
+    // revokes the bootstrap session in the same call, so a successful mint
+    // is what consumes the token — no separate status transition needed.
+    // requireSourceSessionPending makes the claim atomic gateway-side: if a
+    // concurrent /start for the same deep link already minted (revoking the
+    // bootstrap session), this call conflicts instead of revoking the
+    // winner's freshly sent code.
+    minted = await createOutboundSessionConditional({
+      channel: sourceChannel,
+      expectedExternalUserId: rawSenderId,
+      expectedChatId: conversationExternalId,
+      identityBindingStatus: "bound",
+      destinationAddress: conversationExternalId,
+      requireSourceSessionPending: bootstrapSession.id,
+    });
+  } catch (err) {
+    log.warn(
+      { err, sourceChannel, sessionId: bootstrapSession.id },
+      "Bootstrap intercept: session handoff failed (gateway unreachable)",
+    );
+    return respondBootstrapUnavailable(conversationExternalId, eventId);
+  }
 
-  // Create a new identity-bound outbound session with a fresh secret.
-  // The old bootstrap session is auto-revoked by createOutboundSession.
-  const newSession = createOutboundSession({
-    channel: sourceChannel,
-    expectedExternalUserId: rawSenderId,
-    expectedChatId: conversationExternalId,
-    identityBindingStatus: "bound",
-    destinationAddress: conversationExternalId,
-  });
+  if ("conflict" in minted) {
+    // A concurrent /start already claimed this token and sent its code —
+    // handled response, no new mint, no reply (the winner's code stands).
+    log.info(
+      { sourceChannel, sessionId: bootstrapSession.id, reason: minted.reason },
+      "Bootstrap intercept: token already claimed by a concurrent handoff",
+    );
+    return {
+      accepted: true,
+      duplicate: false,
+      eventId,
+      verificationOutcome: "bootstrap_already_claimed",
+    };
+  }
+  const newSession: CreateOutboundSessionResult = minted;
 
   // Compose and send the verification prompt via Telegram
   const telegramBody = composeVerificationTelegram(
@@ -114,9 +208,21 @@ export async function handleBootstrapIntercept(
     canonicalAssistantId,
   );
 
-  // Update delivery tracking
+  // Update delivery tracking (best-effort — the code is already on its way)
   const now = Date.now();
-  updateSessionDelivery(newSession.sessionId, now, 1, now + RESEND_COOLDOWN_MS);
+  try {
+    await updateSessionDelivery(
+      newSession.sessionId,
+      now,
+      1,
+      now + RESEND_COOLDOWN_MS,
+    );
+  } catch (err) {
+    log.error(
+      { err, sessionId: newSession.sessionId },
+      "Bootstrap intercept: failed to update session delivery tracking",
+    );
+  }
 
   return ({
     accepted: true,