@vellumai/assistant 0.12.4-dev.202609232047.847daa9 → 0.12.4-dev.202609232215.634e2d2

package/docs/architecture/scheduling.md

@@ -94,11 +94,13 @@ sequenceDiagram
 
 The `enforceRoutingIntent()` step runs after the LLM produces a channel selection but before deterministic checks. It acts as a post-decision guard:
 
-| Intent           | Enforcement Rule                                                                                  |
-| ---------------- | ------------------------------------------------------------------------------------------------- |
-| `single_channel` | No override. The LLM's channel selection stands.                                                  |
-| `multi_channel`  | If the LLM selected < 2 channels and 2+ are connected, expand to at least two connected channels. |
-| `all_channels`   | Replace the LLM's selection with all connected channels.                                          |
+| Intent           | Enforcement Rule                                                                                                             |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `single_channel` | Cap delivery to one channel: the signal's source channel when it is connected, otherwise the first channel the LLM selected. |
+| `multi_channel`  | If the LLM selected < 2 channels and 2+ are connected, expand to at least two connected channels.                            |
+| `all_channels`   | Replace the LLM's selection with all connected channels.                                                                     |
+
+A decision the LLM suppressed (`shouldNotify: false`) is left alone under every intent. A signal with no routing intent keeps the LLM's selection.
 
 When enforcement changes the decision, the updated `selectedChannels` and annotated `reasoningSummary` are re-persisted to `notification_decisions` so the audit trail reflects what was actually dispatched.
 

package/docs/guardian-request-flow.md

@@ -24,7 +24,7 @@ anti-pattern was retired in #35642 and again in the ask_question redesign).
   (generic actions[] + plainTextFallback)         resolveQuestionContext)
         │
         ▼ per-channel rendering ONLY
-  channel adapters                               (notifications/adapters/{telegram,slack,macos,platform},
+  channel adapters                               (notifications/adapters/{telegram,slack,discord,macos,platform},
   telegram: inline keyboard; slack: blocks;       vellum: conversation card via approval-card-builder)
   card deliveries recorded per channel            (guardian-delivery-recorder.ts → guardian_request_deliveries)
         │

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.4-dev.202609232047.847daa9",
+  "version": "0.12.4-dev.202609232215.634e2d2",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/emit-signal-routing-intent.test.ts

@@ -359,6 +359,68 @@ describe("access-request vellum floor", () => {
     );
   });
 
+  test("an all_channels access request the decision engine suppressed still fans out", async () => {
+    evaluateSignalMock.mockResolvedValue({
+      shouldNotify: false,
+      selectedChannels: [],
+      reasoningSummary: "LLM suppressed",
+      renderedCopy: {},
+      dedupeKey: "dedupe-ar-email",
+      confidence: 0.9,
+      fallbackUsed: false,
+      persistedDecisionId: "dec-ar-email",
+    });
+    // The real enforcement leaves a suppressed decision alone and replaces
+    // the selection with every connected channel otherwise.
+    enforceRoutingIntentMock.mockImplementation(
+      (
+        decision: { shouldNotify: boolean; selectedChannels: string[] },
+        intent: string | undefined,
+        connected: string[],
+      ) =>
+        intent === "all_channels" && decision.shouldNotify
+          ? { ...decision, selectedChannels: [...connected] }
+          : decision,
+    );
+
+    await emitNotificationSignal({
+      sourceEventName: "ingress.access_request",
+      sourceChannel: "email",
+      sourceContextId: "access-req-email-stranger",
+      requiresConversation: true,
+      routingIntent: "all_channels",
+      attentionHints: {
+        requiresAction: true,
+        urgency: "high",
+        isAsyncBackground: false,
+        visibleInSourceNow: false,
+      },
+      contextPayload: {
+        requestId: "req-email",
+        requestCode: "EM12CD",
+        sourceChannel: "email",
+        conversationExternalId: "<thread-1@example.com>",
+        actorExternalId: "stranger@example.com",
+        actorDisplayName: null,
+        actorUsername: null,
+        senderIdentifier: "stranger@example.com",
+        guardianBindingChannel: null,
+        guardianResolutionSource: "vellum-anchor",
+        previousMemberStatus: null,
+        messagePreview: null,
+      },
+    });
+
+    const enforced = enforceRoutingIntentMock.mock.calls[0][0] as {
+      shouldNotify: boolean;
+    };
+    expect(enforced.shouldNotify).toBe(true);
+    const dispatched = dispatchDecisionMock.mock.calls[0][1] as {
+      selectedChannels: string[];
+    };
+    expect(dispatched.selectedChannels).toContain("vellum");
+  });
+
   test("re-adds vellum when single_channel routing enforcement strips it", async () => {
     evaluateSignalMock.mockResolvedValue({
       shouldNotify: true,

package/src/__tests__/introduction-card-resolver.test.ts

@@ -218,6 +218,29 @@ describe("introduction card decisions", () => {
     }
   });
 
+  test("handshake approval on an email sender is coerced to direct trust", async () => {
+    for (const action of ["approve_once", "verify_code"] as const) {
+      resetState();
+      const req = makeAccessRequest({ sourceChannel: "email" });
+
+      const result = await applyGuardianDecision({
+        requestId: req.id,
+        action,
+        actorContext: desktopGuardian(),
+      });
+
+      expect(result.applied).toBe(true);
+      // No code is minted: email has no route to deliver one to the sender.
+      expect(outcomesOfType("mint_outbound_session")).toHaveLength(0);
+      const activations = outcomesOfType("activate_member");
+      expect(activations).toHaveLength(1);
+      expect(activations[0].sourceChannel).toBe("email");
+      expect(activations[0].verifiedVia).toBe("manual_channel_claim");
+      // The reported and projected outcome is the trust that was applied.
+      expect(result.applied && result.decidedAction).toBe("trust");
+    }
+  });
+
   test("leave_unverified persists the sender as unverified and is silent (legacy reject path)", async () => {
     for (const action of ["leave_unverified", "reject"] as const) {
       resetState();
@@ -392,18 +415,40 @@ describe("introduction card decisions", () => {
 });
 
 describe("introductionOutcomeForAction", () => {
+  const slackStranger = {
+    sourceChannel: "slack",
+    requesterSignals: serializeRequesterSignals({ isStranger: true }) ?? null,
+  };
+
   test("folds the generic decision pair onto the introduction outcomes", () => {
     // `reject` and `leave_unverified` both park the contact at `unverified`;
     // `approve_once` starts the handshake. Introduction actions map to
     // themselves. Callers that must present the resolved outcome (the card
     // projection) rely on this so a `reject` park never reads as "Denied".
-    expect(introductionOutcomeForAction("reject")).toBe("leave_unverified");
-    expect(introductionOutcomeForAction("leave_unverified")).toBe(
-      "leave_unverified",
-    );
-    expect(introductionOutcomeForAction("approve_once")).toBe("verify_code");
-    expect(introductionOutcomeForAction("verify_code")).toBe("verify_code");
-    expect(introductionOutcomeForAction("trust")).toBe("trust");
-    expect(introductionOutcomeForAction("block")).toBe("block");
+    const outcome = (
+      action: Parameters<typeof introductionOutcomeForAction>[1],
+    ) => introductionOutcomeForAction(slackStranger, action);
+    expect(outcome("reject")).toBe("leave_unverified");
+    expect(outcome("leave_unverified")).toBe("leave_unverified");
+    expect(outcome("approve_once")).toBe("verify_code");
+    expect(outcome("verify_code")).toBe("verify_code");
+    expect(outcome("trust")).toBe("trust");
+    expect(outcome("block")).toBe("block");
+  });
+
+  test("a handshake approval resolves to trust where the handshake cannot complete", () => {
+    const email = { sourceChannel: "email", requesterSignals: null };
+    const bot = {
+      sourceChannel: "slack",
+      requesterSignals: serializeRequesterSignals({ isBot: true }) ?? null,
+    };
+    for (const request of [email, bot]) {
+      expect(introductionOutcomeForAction(request, "approve_once")).toBe(
+        "trust",
+      );
+      expect(introductionOutcomeForAction(request, "verify_code")).toBe(
+        "trust",
+      );
+    }
   });
 });

package/src/__tests__/non-member-access-request.test.ts

@@ -598,6 +598,54 @@ describe("access-request-helper unit tests", () => {
     expect(payload.guardianBindingChannel).toBe("vellum");
   });
 
+  test("an email access request routes to every channel the guardian is connected on", async () => {
+    const result = await notifyGuardianOfAccessRequest({
+      sourceChannel: "email",
+      conversationExternalId: "<thread-1@example.com>",
+      actorExternalId: "stranger@example.com",
+    });
+
+    expect(result.notified).toBe(true);
+    expect(emitSignalCalls.length).toBe(1);
+    expect(emitSignalCalls[0].routingIntent).toBe("all_channels");
+  });
+
+  test("an admitted email sender's nudge keeps the default routing", async () => {
+    await maybeNotifyGuardianOfAdmittedContact({
+      sourceChannel: "email",
+      conversationExternalId: "<thread-2@example.com>",
+      actorExternalId: "admitted@example.com",
+    });
+
+    expect(emitSignalCalls.length).toBe(1);
+    expect(emitSignalCalls[0].routingIntent).toBeUndefined();
+  });
+
+  test("a telegram access request with a telegram guardian stays on telegram", async () => {
+    seedGatewayGuardian({
+      channelType: "telegram",
+      address: "guardian-tg",
+      externalChatId: "tg-chat",
+      principalId: anchorPrincipalId,
+    });
+    createGuardianBinding({
+      channel: "telegram",
+      guardianExternalUserId: "guardian-tg",
+      guardianDeliveryChatId: "tg-chat",
+      guardianPrincipalId: anchorPrincipalId,
+      verifiedVia: "test",
+    });
+
+    await notifyGuardianOfAccessRequest({
+      sourceChannel: "telegram",
+      conversationExternalId: "chat-123",
+      actorExternalId: "unknown-user",
+    });
+
+    expect(emitSignalCalls.length).toBe(1);
+    expect(emitSignalCalls[0].routingIntent).toBe("single_channel");
+  });
+
   test("notifyGuardianOfAccessRequest prefers source-channel binding over vellum anchor", async () => {
     // Both Telegram and voice bindings exist with the anchor principal
     seedGatewayGuardian({

package/src/__tests__/trusted-contact-inline-approval-integration.test.ts

@@ -1308,15 +1308,15 @@ describe("(g) access_request resolver: requester code delivery", () => {
     expect(verificationSent.length).toBe(1);
   });
 
-  test("off-channel approval on a channel with no deliverable callback (e.g. email) still records verification_sent", async () => {
-    // `email` has no deliver URL (resolveDeliverCallbackUrlForChannel returns
+  test("off-channel approval on a channel with no deliverable callback (e.g. a plugin channel) still records verification_sent", async () => {
+    // `plugin` has no deliver URL (resolveDeliverCallbackUrlForChannel returns
     // null), so the requester cannot be auto-notified here. The guardian still
     // receives the code inline, so the lifecycle transition must be recorded —
     // the emit must not be gated on requester deliverability.
     const req = createAccessRequest({
-      sourceChannel: "email",
-      requesterChatId: "requester@example.com",
-      sourceConversationId: "conv-access-email",
+      sourceChannel: "plugin",
+      requesterChatId: "plugin-requester-1",
+      sourceConversationId: "conv-access-plugin",
     });
 
     const result = await applyGuardianDecision({
@@ -1335,7 +1335,7 @@ describe("(g) access_request resolver: requester code delivery", () => {
     const replyText = result.applied ? result.resolverReplyText : undefined;
     expect(replyText).toContain("123456");
     const requesterDelivery = deliveredReplies.find(
-      (r) => r.payload.chatId === "requester@example.com",
+      (r) => r.payload.chatId === "plugin-requester-1",
     );
     expect(requesterDelivery).toBeUndefined();
 

package/src/approvals/guardian-decision-primitive.ts

@@ -529,12 +529,13 @@ export async function applyGuardianDecision(
   // never throws; the `.catch` is a defensive backstop.
   // For access requests the resolver folds the generic decision pair onto the
   // introduction outcomes (`reject` → `leave_unverified`, `approve_once` →
-  // `verify_code`), so the resolved card must reflect the OUTCOME, not the raw
+  // `verify_code`, or `trust` for a requester who cannot complete a code
+  // handshake), so the resolved card must reflect the OUTCOME, not the raw
   // button — otherwise a `reject` that actually parked the contact at
   // `unverified` would still render "Denied". Other kinds have no such mapping.
   const cardAction =
     request.kind === "access_request"
-      ? introductionOutcomeForAction(effectiveAction)
+      ? introductionOutcomeForAction(resolved, effectiveAction)
       : effectiveAction;
   void withdrawGuardianRequestCards({
     request: resolved,

package/src/approvals/guardian-request-resolvers.ts

@@ -46,6 +46,7 @@ import { deliverChannelReply } from "../runtime/gateway-client.js";
 import {
   introductionMode,
   parseRequesterSignals,
+  requesterCanCompleteHandshake,
   type RequesterIdentitySignals,
   resolveTrustBinding,
 } from "../runtime/introduction-policy.js";
@@ -619,20 +620,33 @@ const OUTCOME_BY_ACTION = {
 } as const satisfies Record<ApprovalAction, IntroductionOutcome>;
 
 /**
- * The introduction outcome a decision action resolves to for an access request.
- * The generic decision pair folds onto the card outcomes (`reject` →
- * `leave_unverified`, `approve_once` → `verify_code`); the introduction actions
- * map to themselves. Every outcome is itself an `ApprovalAction`, so a caller
- * that must reflect the resolved *outcome* rather than the raw button — the
- * resolved-card projection, so a `reject` that parked the contact at
- * `unverified` reads as the neutral "Left unverified" and not "Denied" — can
- * normalize through this. It does not apply the bot handshake→trust coercion,
- * which does not affect the park/deny distinction the card cares about.
+ * The introduction outcome a decision action resolves to for an access
+ * request. The generic decision pair folds onto the card outcomes (`reject` →
+ * `leave_unverified`, `approve_once` → `verify_code`) and the introduction
+ * actions map to themselves, except that a handshake approval on a requester
+ * who can never complete the handshake (a bot, an email sender) resolves to
+ * direct trust: the guardian's intent ("let them in") is unambiguous.
+ *
+ * The one derivation of the outcome: the resolver plans and follows through on
+ * it, and the decision primitive reports it (`decidedAction`) and projects it
+ * onto the resolved cards, so a `reject` that parked the contact reads as the
+ * neutral "Left unverified" and a coerced approval reads as the trust it was.
  */
 export function introductionOutcomeForAction(
+  request: Pick<GuardianRequestWire, "sourceChannel" | "requesterSignals">,
   action: ApprovalAction,
-): ApprovalAction {
-  return OUTCOME_BY_ACTION[action];
+): IntroductionOutcome {
+  const outcome = OUTCOME_BY_ACTION[action];
+  if (
+    outcome === "verify_code" &&
+    !requesterCanCompleteHandshake(
+      request.sourceChannel ?? undefined,
+      parseRequesterSignals(request.requesterSignals),
+    )
+  ) {
+    return "trust";
+  }
+  return outcome;
 }
 
 /** Derived access-request decision facts shared by `prepare` and `resolve`. */
@@ -675,15 +689,7 @@ function deriveAccessRequestDecision(
     requesterContactResult?.contact.displayName ?? null;
 
   const signals = parseRequesterSignals(request.requesterSignals);
-  let outcome: IntroductionOutcome = OUTCOME_BY_ACTION[action];
-
-  // A bot cannot return a verification code, so a handshake approval on a
-  // bot requester can never complete. Coerce it to direct trust — the
-  // guardian's intent ("let it in") is unambiguous. Logged once, in
-  // `prepare` (this derivation runs again in `resolve`).
-  if (outcome === "verify_code" && signals.isBot === true) {
-    outcome = "trust";
-  }
+  const outcome = introductionOutcomeForAction(request, action);
 
   return {
     channel,
@@ -885,8 +891,8 @@ async function notifyRequesterOfDenial(params: {
  * follow-through (requester/guardian notices, verification-code delivery
  * from the decide's `mintedSession`, lifecycle signals).
  *
- * A bot requester can never return a code, so handshake approvals are
- * coerced to direct trust.
+ * A requester who can never complete the handshake (a bot, an email
+ * sender) has handshake approvals coerced to direct trust.
  */
 const accessRequestResolver: GuardianRequestResolver = {
   kind: "access_request",
@@ -905,11 +911,12 @@ const accessRequestResolver: GuardianRequestResolver = {
     if (outcome !== OUTCOME_BY_ACTION[decision.action]) {
       log.info(
         {
-          event: "resolver_access_request_bot_coercion",
+          event: "resolver_access_request_trust_coercion",
           requestId: request.id,
           action: decision.action,
+          channel,
         },
-        "Access request resolver: handshake approval on a bot coerced to direct trust",
+        "Access request resolver: handshake approval coerced to direct trust (requester cannot complete a handshake)",
       );
     }
 

package/src/daemon/activity-trail.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Tests for the daemon activity trail. A block report asks "what overlapped
+ * the last N ms", so the trail must include work still running, include work
+ * that ended inside the window, exclude work that ended before it, and group
+ * identical labels so the report stays small.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import type { InterfaceId } from "../channels/types.js";
+import {
+  getActivityOverlapping,
+  resetActivityTrailForTests,
+  trackDaemonActivity,
+  turnActivityLabel,
+  turnConversationType,
+} from "./activity-trail.js";
+
+/** Resolves after `ms` of wall time. */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+beforeEach(() => {
+  resetActivityTrailForTests();
+});
+
+describe("getActivityOverlapping", () => {
+  test("reports running work and work that ended inside the window", async () => {
+    // GIVEN a background turn that has ended and a user turn still running
+    await trackDaemonActivity({ kind: "schedule_tick" }, async () => {});
+    let release!: () => void;
+    const userTurn = trackDaemonActivity(
+      {
+        kind: "turn",
+        conversationType: "standard",
+        callSite: "mainAgent",
+        turnInterface: "web",
+        interactive: true,
+      },
+      () => new Promise<void>((resolve) => (release = resolve)),
+    );
+
+    // WHEN the last minute is queried
+    const groups = getActivityOverlapping(60_000);
+
+    // THEN both appear, the user turn marked as running
+    expect(groups).toHaveLength(2);
+    expect(groups).toContainEqual(
+      expect.objectContaining({ kind: "schedule_tick", count: 1, running: 0 }),
+    );
+    expect(groups).toContainEqual(
+      expect.objectContaining({
+        kind: "turn",
+        turnInterface: "web",
+        interactive: true,
+        running: 1,
+      }),
+    );
+    release();
+    await userTurn;
+  });
+
+  test("excludes work that ended before the window began", async () => {
+    // GIVEN work that ended ~50ms ago
+    await trackDaemonActivity({ kind: "git_compaction" }, async () => {});
+    await sleep(50);
+
+    // WHEN only the last 10ms are queried
+    const groups = getActivityOverlapping(10);
+
+    // THEN it is not attributed to the window
+    expect(groups).toEqual([]);
+  });
+
+  test("groups identical labels and keeps the longest duration", async () => {
+    // GIVEN three heartbeat turns, one noticeably longer
+    const heartbeat = {
+      kind: "turn" as const,
+      conversationType: "background" as const,
+      callSite: "heartbeatAgent" as const,
+      interactive: false,
+    };
+    await trackDaemonActivity(heartbeat, async () => {});
+    await trackDaemonActivity(heartbeat, () => sleep(30));
+    await trackDaemonActivity(heartbeat, async () => {});
+
+    // WHEN the window covers all three
+    const groups = getActivityOverlapping(60_000);
+
+    // THEN they collapse into one group
+    expect(groups).toHaveLength(1);
+    expect(groups[0]).toMatchObject({ ...heartbeat, count: 3, running: 0 });
+    expect(groups[0]!.longestMs).toBeGreaterThanOrEqual(25);
+  });
+
+  test("a failing job still closes its mark", async () => {
+    // GIVEN tracked work that throws
+    await expect(
+      trackDaemonActivity({ kind: "vbundle_export" }, async () => {
+        throw new Error("boom");
+      }),
+    ).rejects.toThrow("boom");
+
+    // WHEN the trail is queried
+    const groups = getActivityOverlapping(60_000);
+
+    // THEN the work is recorded as ended, not left running forever
+    expect(groups).toEqual([
+      expect.objectContaining({ kind: "vbundle_export", running: 0 }),
+    ]);
+  });
+});
+
+describe("burst retention", () => {
+  test("a burst of finished work does not evict what overlapped a block", async () => {
+    // GIVEN a user turn that ends, then a burst of 500 short jobs
+    await trackDaemonActivity(
+      { kind: "turn", conversationType: "standard", callSite: "mainAgent" },
+      async () => {},
+    );
+    for (let i = 0; i < 500; i++) {
+      await trackDaemonActivity({ kind: "schedule_tick" }, async () => {});
+    }
+
+    // WHEN the last minute is queried
+    const groups = getActivityOverlapping(60_000);
+
+    // THEN the earlier turn is still attributed
+    expect(groups).toContainEqual(
+      expect.objectContaining({ kind: "turn", count: 1 }),
+    );
+    expect(groups).toContainEqual(
+      expect.objectContaining({ kind: "schedule_tick", count: 500 }),
+    );
+  });
+});
+
+describe("turnActivityLabel", () => {
+  function conversation(opts: {
+    isSubagent?: boolean;
+    originInterface?: InterfaceId;
+    liveInterface?: InterfaceId;
+  }) {
+    return {
+      conversationType: "standard",
+      isSubagent: opts.isSubagent ?? false,
+      originInterface: opts.originInterface,
+      getTurnInterfaceContext: () =>
+        opts.liveInterface
+          ? { userMessageInterface: opts.liveInterface }
+          : null,
+    };
+  }
+
+  test("a subagent turn without an explicit call site is a subagent turn", () => {
+    // GIVEN a subagent conversation and a queue-drained turn with no call site
+    // WHEN its label is built
+    const label = turnActivityLabel(
+      conversation({ isSubagent: true }),
+      undefined,
+      false,
+    );
+    // THEN it matches the call site the loop resolves, not mainAgent
+    expect(label.callSite).toBe("subagentSpawn");
+  });
+
+  test("an explicit call site wins", () => {
+    const label = turnActivityLabel(conversation({}), "heartbeatAgent", false);
+    expect(label.callSite).toBe("heartbeatAgent");
+  });
+
+  test("the turn's own interface wins over the conversation's origin", () => {
+    // GIVEN a conversation started on web, now continued from Slack
+    // WHEN the Slack turn's label is built
+    const label = turnActivityLabel(
+      conversation({ originInterface: "web", liveInterface: "slack" }),
+      undefined,
+      true,
+    );
+    // THEN it is attributed to Slack
+    expect(label.turnInterface).toBe("slack");
+    expect(label.interactive).toBe(true);
+  });
+
+  test("falls back to the origin interface, and omits it when unknown", () => {
+    expect(
+      turnActivityLabel(
+        conversation({ originInterface: "macos" }),
+        undefined,
+        false,
+      ).turnInterface,
+    ).toBe("macos");
+    expect(
+      turnActivityLabel(conversation({}), undefined, false),
+    ).not.toHaveProperty("turnInterface");
+  });
+});
+
+describe("turnConversationType", () => {
+  test("keeps known types, defaults a missing one, and buckets the rest", () => {
+    expect(turnConversationType("background")).toBe("background");
+    expect(turnConversationType("scheduled")).toBe("scheduled");
+    expect(turnConversationType(undefined)).toBe("standard");
+    expect(turnConversationType("something-new")).toBe("other");
+  });
+});