@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/notifications/guardian-question-mode.ts

@@ -75,9 +75,19 @@ const GuardianQuestionPayloadBaseSchema = z.object({
 export const PendingQuestionPayloadSchema =
   GuardianQuestionPayloadBaseSchema.extend({
     requestKind: z.literal("pending_question"),
-    callSessionId: z.string().min(1),
-    activeGuardianRequestCount: z.number(),
+    /** Present only for voice-call questions; absent for ask_question prompts. */
+    callSessionId: z.string().min(1).optional(),
+    activeGuardianRequestCount: z.number().optional(),
     toolName: z.string().optional(),
+    /**
+     * Structured answer options for an ask_question prompt (2–4 entries).
+     * When present, the broadcaster renders them as tappable option actions
+     * (see {@link buildQuestionOptionActionId}); absent payloads render as
+     * plain text with request-code reply instructions.
+     */
+    options: z
+      .array(z.object({ id: z.string().min(1), label: z.string().min(1) }))
+      .optional(),
   });
 
 /**
@@ -221,6 +231,51 @@ export function buildToolApprovalSourceView(
   };
 }
 
+// ── Answer-option action tokens ─────────────────────────────────────────
+
+/**
+ * Action-id scheme for answer-mode option buttons on a `pending_question`
+ * card. The broadcaster builds card actions with these ids (so every channel
+ * adapter renders them without knowing they're question options), the reply
+ * router recognizes a tapped id as an answer selection rather than an
+ * approval action, and the question resolver maps the index back to the
+ * pending interaction's option. Index-based (not the raw option id) so the
+ * channel callback stays small and the LLM-supplied option id never rides
+ * the wire.
+ */
+export const QUESTION_SKIP_ACTION_ID = "answer_skip";
+
+/** Action id for the option at `index` on a question card. */
+export function buildQuestionOptionActionId(index: number): string {
+  return `answer_${index}`;
+}
+
+export type QuestionAnswerSelection =
+  | { kind: "option"; index: number }
+  | { kind: "skip" };
+
+/**
+ * Parse an action token from a question card. Returns `null` for anything
+ * that is not an answer-option token (including ordinary approval actions),
+ * so callers can fall through to approval handling.
+ */
+export function parseQuestionAnswerActionId(
+  token: string,
+): QuestionAnswerSelection | null {
+  if (token === QUESTION_SKIP_ACTION_ID) {
+    return { kind: "skip" };
+  }
+  const match = /^answer_(\d+)$/.exec(token);
+  if (!match) {
+    return null;
+  }
+  const index = Number(match[1]);
+  if (!Number.isInteger(index) || index < 0) {
+    return null;
+  }
+  return { kind: "option", index };
+}
+
 interface GuardianRequestModeInput {
   kind: unknown;
   toolName?: unknown;

package/src/notifications/home-feed-side-effect.ts

@@ -159,6 +159,7 @@ const EVENT_CATEGORY_MAP: Record<string, FeedItemCategory> = {
   "guardian.question": "security",
   "guardian.channel_activation": "security",
   "ingress.access_request": "security",
+  "telegram.webhook_health_alert": "system",
 };
 
 function deriveCategory(signal: NotificationSignal): FeedItemCategory {
@@ -269,6 +270,9 @@ const NOTEWORTHY_EVENT_NAMES: ReadonlySet<string> = new Set([
   "guardian.channel_activation",
   "ingress.access_request",
   "credential.health_alert",
+  // A dark messaging channel is inbox-worthy: the guardian may be waiting on
+  // replies that are silently queueing at Telegram.
+  "telegram.webhook_health_alert",
 ]);
 
 function deriveNoteworthy(signal: NotificationSignal): boolean {

package/src/notifications/signal.ts

@@ -25,6 +25,7 @@ export const NOTIFICATION_SOURCE_CHANNELS = [
   { id: "email", description: "Email channel" },
   { id: "platform", description: "Platform-managed channel" },
   { id: "a2a", description: "Agent-to-agent protocol channel" },
+  { id: "discord", description: "Discord channel" },
   { id: "scheduler", description: "Scheduled task runner (reminders, cron)" },
   { id: "watcher", description: "File/event watcher subsystem" },
 ] as const;
@@ -82,10 +83,6 @@ export const NOTIFICATION_SOURCE_EVENT_NAMES = [
     id: "ingress.trusted_contact.guardian_decision",
     description: "Guardian decided on trusted contact request",
   },
-  {
-    id: "ingress.trusted_contact.denied",
-    description: "Trusted contact request denied",
-  },
   {
     id: "ingress.trusted_contact.verification_sent",
     description: "Verification sent to trusted contact",
@@ -125,6 +122,11 @@ export const NOTIFICATION_SOURCE_EVENT_NAMES = [
     description:
       "OAuth credential health issue detected (expired, revoked, missing scopes)",
   },
+  {
+    id: "telegram.webhook_health_alert",
+    description:
+      "Telegram webhook is not delivering (unregistered, or failing per getWebhookInfo)",
+  },
 ] as const;
 
 export type NotificationSourceEventName =

package/src/notifications/trusted-contact-payloads.ts

@@ -31,10 +31,9 @@ const TrustedContactIdentitySchema = z.object({
 });
 
 /**
- * Payload for `ingress.trusted_contact.guardian_decision` and
- * `ingress.trusted_contact.denied` — the guardian's verdict on an access
- * request. The deny path emits both events from one object; the approve path
- * emits `guardian_decision` with `decision: "approved"` (identical shape).
+ * Payload for `ingress.trusted_contact.guardian_decision` — the guardian's
+ * verdict on an access request. `decision` distinguishes the deny path from
+ * an approve (identical shape).
  */
 export const TrustedContactDecisionPayloadSchema =
   TrustedContactIdentitySchema.extend({

package/src/notifications/vellum-card-affinity.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared vellum-card conversation pin for guardian-request producers.
+ *
+ * Guardian cards (access requests, tool grants, tool approvals, questions)
+ * that know their originating conversation pass this affinity fragment to
+ * `emitNotificationSignal` so the in-app (vellum) card lands inside that
+ * conversation instead of one the decision engine picks. The metadata mirrors
+ * the target's `source` because `pairDeliveryWithConversation` reuses a
+ * conversation only when its source matches the signal's (inbound
+ * conversations default to "user"); a stale/missing target falls back to a
+ * fresh conversation via the same pairing path.
+ */
+
+import { getConversation } from "../persistence/conversation-crud.js";
+
+export interface VellumCardAffinity {
+  conversationAffinityHint: { vellum: string };
+  conversationMetadata: { source: string };
+}
+
+/**
+ * Build the emit-signal affinity fragment pinning the vellum card to
+ * `destinationConversationId`, or `undefined` when the producer has no
+ * originating conversation (callers spread the result:
+ * `...(buildVellumCardAffinity(id) ?? {})`).
+ */
+export function buildVellumCardAffinity(
+  destinationConversationId: string | undefined,
+): VellumCardAffinity | undefined {
+  if (!destinationConversationId) {
+    return undefined;
+  }
+  return {
+    conversationAffinityHint: { vellum: destinationConversationId },
+    conversationMetadata: {
+      source: getConversation(destinationConversationId)?.source ?? "user",
+    },
+  };
+}

package/src/oauth/AGENTS.md

@@ -39,7 +39,7 @@ The `logoUrl` field in `seed-providers.ts` is the source of truth for a provider
 
 For brands Simple Icons doesn't host (e.g. Salesforce, which Simple Icons removed for trademark reasons), use the `glincker/thesvg` source via jsDelivr — `https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/<key>/default.svg`. The recognised `logoUrl` prefixes are enforced by `oauth-provider-seed-logos.test.ts`; if you need a third source, extend that allowlist.
 
-### 5. Secret patterns (if applicable) — `../security/secret-patterns.ts`
+### 5. Secret patterns (if applicable) — `packages/service-contracts/src/secret-detection.ts`
 
 If the provider issues API keys with a recognizable prefix (e.g. `acme_sk_`), add a `PREFIX_PATTERNS` entry. OAuth-only services with opaque access tokens do not need one. See `../security/AGENTS.md` for details.
 

package/src/permissions/channel-permission-query.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  collapseChannelThresholdForContact,
+  effectiveChannelCellThreshold,
+} from "./channel-permission-query.js";
+
+describe("collapseChannelThresholdForContact", () => {
+  test.each([
+    ["none", "none"],
+    ["low", "low"],
+    ["medium", "low"],
+    ["high", "low"],
+  ] as const)("%s collapses to %s", (input, expected) => {
+    expect(collapseChannelThresholdForContact(input)).toBe(expected);
+  });
+});
+
+describe("effectiveChannelCellThreshold", () => {
+  const resolved = (threshold: "none" | "low" | "medium" | "high") => ({
+    ok: true as const,
+    resolved: { threshold },
+  });
+  const noCell = { ok: true as const, resolved: null };
+  const failed = { ok: false as const };
+
+  test("a transport failure authorizes nothing, for every contact type", () => {
+    for (const contactType of [
+      "guardian",
+      "trusted_contact",
+      "unverified_contact",
+      "unknown",
+    ] as const) {
+      expect(
+        effectiveChannelCellThreshold(failed, contactType, "low"),
+      ).toBeUndefined();
+    }
+  });
+
+  test("a contact's resolved cell is collapsed", () => {
+    expect(
+      effectiveChannelCellThreshold(resolved("high"), "trusted_contact", "low"),
+    ).toBe("low");
+    expect(
+      effectiveChannelCellThreshold(resolved("none"), "trusted_contact", "low"),
+    ).toBe("none");
+  });
+
+  test("a contact with no cell gets the caller-derived room default", () => {
+    expect(
+      effectiveChannelCellThreshold(noCell, "trusted_contact", "low"),
+    ).toBe("low");
+    expect(
+      effectiveChannelCellThreshold(noCell, "trusted_contact", "none"),
+    ).toBe("none");
+    expect(
+      effectiveChannelCellThreshold(noCell, "trusted_contact", undefined),
+    ).toBeUndefined();
+  });
+
+  test("guardian queries pass through raw and ignore the room default", () => {
+    expect(
+      effectiveChannelCellThreshold(resolved("high"), "guardian", "low"),
+    ).toBe("high");
+    expect(
+      effectiveChannelCellThreshold(noCell, "guardian", "low"),
+    ).toBeUndefined();
+  });
+});

package/src/permissions/channel-permission-query.ts

@@ -13,10 +13,25 @@ import {
   isChannelConversationType,
   isTrustClass,
   type ResolveChannelPermissionRequest,
+  type ResolvedChannelPermission,
+  type RiskThreshold,
 } from "@vellumai/gateway-client";
 
 import type { PolicyContext } from "./types.js";
 
+/**
+ * The fields a cell query is derived from — a subset of {@link PolicyContext}
+ * so a caller holding only a turn's channel coordinates (the sensitive-tool
+ * gate, which runs before a policy context exists) can build the same query.
+ */
+export type ChannelPermissionCoordinates = Pick<
+  PolicyContext,
+  | "sourceChannel"
+  | "trustClass"
+  | "channelConversationType"
+  | "channelExternalId"
+>;
+
 /**
  * Build the permission-matrix cell query for a permission decision: the
  * channel coordinates of the turn plus the actor's contact-type. Returns
@@ -26,7 +41,7 @@ import type { PolicyContext } from "./types.js";
  * from the conversation override / global defaults as before.
  */
 export function buildChannelPermissionCellQuery(
-  policyContext?: PolicyContext,
+  policyContext?: ChannelPermissionCoordinates,
 ): ResolveChannelPermissionRequest | undefined {
   const adapter = policyContext?.sourceChannel;
   const trustClass = policyContext?.trustClass;
@@ -44,3 +59,60 @@ export function buildChannelPermissionCellQuery(
     contactType: trustClass,
   };
 }
+
+/**
+ * Collapse a threshold to the two levels a channel distinguishes for
+ * non-guardian contact types: `none` is itself, everything else is `low`.
+ * Applied to stored cells and to the global default a cell-less room
+ * inherits alike; the picker applies the same collapse for display (web
+ * `channelTierBehavesAs`), so a room can never behave wider than the level
+ * displayed for it.
+ */
+export function collapseChannelThresholdForContact(
+  threshold: RiskThreshold,
+): RiskThreshold {
+  return threshold === "none" ? "none" : "low";
+}
+
+/**
+ * The threshold a cell resolution actually authorizes for a contact type.
+ * The single rule every cell consumer applies — the sensitive-tool gate,
+ * the threshold cascade, and the pre-prompt refresh — kept in this leaf
+ * module so tests that stub the IPC lookup still exercise it.
+ *
+ * For non-guardian contact types, a resolved cell authorizes its collapsed
+ * threshold ({@link collapseChannelThresholdForContact}), and a successful
+ * walk with no cell at any level authorizes `noCellDefault` — the room
+ * default the caller derives from the owner's global setting, already
+ * collapsed. Callers that cannot derive one pass `undefined`, which keeps
+ * the caller's fail-safe path in charge.
+ *
+ * Guardian queries pass through untouched — a resolved cell keeps its raw
+ * threshold and no-cell returns `undefined` (fall through to the global
+ * thresholds): the channel setting governs other people in the room, never
+ * the guardian's own lane.
+ *
+ * A transport failure (`ok: false`) is `undefined`: an unreachable gateway
+ * must never widen what a channel actor may do.
+ */
+export function effectiveChannelCellThreshold(
+  cell:
+    | {
+        ok: true;
+        resolved: Pick<ResolvedChannelPermission, "threshold"> | null;
+      }
+    | { ok: false },
+  contactType: ResolveChannelPermissionRequest["contactType"],
+  noCellDefault: RiskThreshold | undefined,
+): RiskThreshold | undefined {
+  if (!cell.ok) {
+    return undefined;
+  }
+  if (contactType === "guardian") {
+    return cell.resolved?.threshold;
+  }
+  if (!cell.resolved) {
+    return noCellDefault;
+  }
+  return collapseChannelThresholdForContact(cell.resolved.threshold);
+}