@vellumai/assistant 0.3.19 → 0.3.21

package/src/notifications/decision-engine.ts

@@ -16,6 +16,7 @@ import { getConfig } from '../config/loader.js';
 import { createTimeout, extractToolUse, getConfiguredProvider, userMessage } from '../providers/provider-send-message.js';
 import type { ModelIntent } from '../providers/types.js';
 import { getLogger } from '../util/logger.js';
+import { composeFallbackCopy } from './copy-composer.js';
 import { createDecision } from './decisions-store.js';
 import { getPreferenceSummary } from './preference-summary.js';
 import type { NotificationSignal, RoutingIntent } from './signal.js';
@@ -251,17 +252,7 @@ function buildFallbackDecision(
     };
   }
 
-  const copy: Partial<Record<NotificationChannel, RenderedChannelCopy>> = {};
-  for (const ch of selectedChannels) {
-    const fallbackBody = isHighUrgencyAction
-      ? `Action required: ${signal.sourceEventName}`
-      : signal.sourceEventName;
-    copy[ch] = {
-      title: signal.sourceEventName,
-      body: fallbackBody,
-      ...(ch === 'telegram' ? { deliveryText: fallbackBody } : {}),
-    };
-  }
+  const copy = composeFallbackCopy(signal, selectedChannels);
 
   return {
     shouldNotify: true,
@@ -452,7 +443,8 @@ export async function evaluateSignal(
   const provider = getConfiguredProvider();
   if (!provider) {
     log.warn('Configured provider unavailable for notification decision, using fallback');
-    const decision = buildFallbackDecision(signal, availableChannels);
+    let decision = buildFallbackDecision(signal, availableChannels);
+    decision = enforceConversationAffinity(decision, signal.conversationAffinityHint);
     decision.persistedDecisionId = persistDecision(signal, decision);
     return decision;
   }
@@ -466,6 +458,7 @@ export async function evaluateSignal(
     decision = buildFallbackDecision(signal, availableChannels);
   }
 
+  decision = enforceConversationAffinity(decision, signal.conversationAffinityHint);
   decision.persistedDecisionId = persistDecision(signal, decision);
 
   return decision;
@@ -600,6 +593,50 @@ export function enforceRoutingIntent(
   return decision;
 }
 
+// ── Conversation affinity enforcement ───────────────────────────────────
+
+/**
+ * Enforce conversation affinity on a decision.
+ *
+ * When the signal carries a conversationAffinityHint (per-channel map of
+ * conversationId), override the decision's threadActions for those channels
+ * to `reuse_existing` with the hinted conversationId. This is a
+ * deterministic post-decision guard that prevents the LLM from routing
+ * guardian questions for the same call session to different conversations.
+ */
+export function enforceConversationAffinity(
+  decision: NotificationDecision,
+  affinityHint: Partial<Record<string, string>> | undefined,
+): NotificationDecision {
+  if (!affinityHint) return decision;
+
+  const entries = Object.entries(affinityHint).filter(
+    ([, conversationId]) => typeof conversationId === 'string' && conversationId.length > 0,
+  );
+  if (entries.length === 0) return decision;
+
+  const enforced = { ...decision };
+  const threadActions: Partial<Record<NotificationChannel, ThreadAction>> = {
+    ...(decision.threadActions ?? {}),
+  };
+
+  for (const [channel, conversationId] of entries) {
+    threadActions[channel as NotificationChannel] = {
+      action: 'reuse_existing',
+      conversationId: conversationId!,
+    };
+  }
+
+  enforced.threadActions = threadActions;
+
+  log.info(
+    { affinityHint },
+    'Conversation affinity enforcement: overrode threadActions for hinted channels',
+  );
+
+  return enforced;
+}
+
 // ── Persistence ────────────────────────────────────────────────────────
 
 function persistDecision(signal: NotificationSignal, decision: NotificationDecision): string | undefined {

package/src/notifications/emit-signal.ts

@@ -133,6 +133,12 @@ export interface EmitSignalParams {
   routingIntent?: RoutingIntent;
   /** Free-form hints from the source for the decision engine. */
   routingHints?: Record<string, unknown>;
+  /**
+   * Per-channel conversation affinity hint. Forces the decision engine to
+   * reuse the specified conversation for the given channel(s), bypassing
+   * LLM thread-routing judgment. Keyed by channel name, value is conversationId.
+   */
+  conversationAffinityHint?: Partial<Record<string, string>>;
   /** Optional deduplication key. */
   dedupeKey?: string;
   /**
@@ -177,6 +183,7 @@ export async function emitNotificationSignal(params: EmitSignalParams): Promise<
     attentionHints: params.attentionHints,
     routingIntent: params.routingIntent,
     routingHints: params.routingHints,
+    conversationAffinityHint: params.conversationAffinityHint,
   };
 
   try {

package/src/notifications/signal.ts

@@ -27,4 +27,11 @@ export interface NotificationSignal {
   routingIntent?: RoutingIntent;
   /** Free-form hints from the source for the decision engine (e.g. preferred channels). */
   routingHints?: Record<string, unknown>;
+  /**
+   * Per-channel conversation affinity hint. When set, the decision engine
+   * must force thread reuse to the specified conversation for that channel,
+   * bypassing LLM judgment. Used to enforce deterministic guardian thread
+   * affinity within a call session.
+   */
+  conversationAffinityHint?: Partial<Record<string, string>>;
 }

package/src/notifications/thread-seed-composer.ts

@@ -140,7 +140,8 @@ export function composeThreadSeed(
     const parts: string[] = [];
     if (copy.title && copy.title !== 'Notification') parts.push(copy.title);
     if (copy.body) parts.push(copy.body);
-    if (signal.attentionHints.requiresAction && parts.length > 0) {
+    const alreadyMentionsAction = parts.some((part) => /\baction required\b/i.test(part));
+    if (signal.attentionHints.requiresAction && parts.length > 0 && !alreadyMentionsAction) {
       parts.push('Action required.');
     }
     if (parts.length > 0) {

package/src/runtime/channel-approval-types.ts

@@ -7,6 +7,8 @@
  * same approval flow can be reused across transports.
  */
 
+import type { GuardianDecisionAction } from './guardian-decision-types.js';
+
 // ---------------------------------------------------------------------------
 // Approval actions
 // ---------------------------------------------------------------------------
@@ -20,12 +22,20 @@ export interface ApprovalActionOption {
   label: string;
 }
 
-/** Default action options presented to users across all channels. */
-export const DEFAULT_APPROVAL_ACTIONS: readonly ApprovalActionOption[] = [
-  { id: 'approve_once', label: 'Approve once' },
-  { id: 'approve_always', label: 'Approve always' },
-  { id: 'reject', label: 'Reject' },
-] as const;
+/**
+ * Map `GuardianDecisionAction[]` to `ApprovalActionOption[]` so channel
+ * prompt payloads can be derived from the unified decision action set.
+ * The `action` field from GuardianDecisionAction maps to the `id` field
+ * on ApprovalActionOption (both are canonical action identifiers).
+ */
+export function toApprovalActionOptions(
+  actions: GuardianDecisionAction[],
+): ApprovalActionOption[] {
+  return actions.map(a => ({
+    id: a.action as ApprovalAction,
+    label: a.label,
+  }));
+}
 
 // ---------------------------------------------------------------------------
 // Approval prompt

package/src/runtime/channel-approvals.ts

@@ -17,7 +17,8 @@ import type {
   ApprovalUIMetadata,
   ChannelApprovalPrompt,
 } from './channel-approval-types.js';
-import { DEFAULT_APPROVAL_ACTIONS } from './channel-approval-types.js';
+import { toApprovalActionOptions } from './channel-approval-types.js';
+import { buildDecisionActions, buildPlainTextFallback } from './guardian-decision-types.js';
 import * as pendingInteractions from './pending-interactions.js';
 
 /** Summary of a pending interaction, used by channel approval flows. */
@@ -69,6 +70,11 @@ export function getApprovalInfoByConversation(conversationId: string): PendingAp
 
 /**
  * Internal helper: turn a PendingApprovalInfo into a ChannelApprovalPrompt.
+ *
+ * Derives actions from the shared `buildDecisionActions` builder defined in
+ * guardian-decision-types.ts, then maps them to the channel-facing
+ * `ApprovalActionOption` shape. This ensures channel button sets are always
+ * consistent with the unified `GuardianDecisionPrompt` type.
  */
 function buildPromptFromApprovalInfo(info: PendingApprovalInfo): ChannelApprovalPrompt {
   const promptText = composeApprovalMessage({
@@ -76,15 +82,11 @@ function buildPromptFromApprovalInfo(info: PendingApprovalInfo): ChannelApproval
     toolName: info.toolName,
   });
 
-  // Hide "approve always" when persistent trust rules are disallowed for this invocation.
-  const actions = info.persistentDecisionsAllowed === false
-    ? DEFAULT_APPROVAL_ACTIONS.filter((a) => a.id !== 'approve_always')
-    : [...DEFAULT_APPROVAL_ACTIONS];
-
-  // Plain-text fallback must remain parser-compatible (contains "yes"/"always"/"no" keywords).
-  const plainTextFallback = info.persistentDecisionsAllowed === false
-    ? `${promptText}\n\nReply "yes" to approve or "no" to reject.`
-    : `${promptText}\n\nReply "yes" to approve once, "always" to approve always, or "no" to reject.`;
+  const decisionActions = buildDecisionActions({
+    persistentDecisionsAllowed: info.persistentDecisionsAllowed,
+  });
+  const actions = toApprovalActionOptions(decisionActions);
+  const plainTextFallback = buildPlainTextFallback(promptText, decisionActions);
 
   return { promptText, actions, plainTextFallback };
 }
@@ -199,6 +201,10 @@ export function handleChannelDecision(
  * Build an approval prompt that includes context about which non-guardian
  * user is requesting the action. Sent to the guardian's chat so they
  * can approve or deny on behalf of the requester.
+ *
+ * Uses the shared `buildDecisionActions` builder with `forGuardianOnBehalf`
+ * set to true, which excludes `approve_always` since guardians cannot
+ * permanently allowlist tools on behalf of requesters.
  */
 export function buildGuardianApprovalPrompt(
   info: PendingApprovalInfo,
@@ -210,11 +216,9 @@ export function buildGuardianApprovalPrompt(
     requesterIdentifier,
   });
 
-  // Guardian approvals are always one-time decisions — "approve always"
-  // doesn't make sense when the guardian is approving on behalf of someone else.
-  const actions = DEFAULT_APPROVAL_ACTIONS.filter((a) => a.id !== 'approve_always');
-
-  const plainTextFallback = `${promptText}\n\nReply "yes" to approve or "no" to reject.`;
+  const decisionActions = buildDecisionActions({ forGuardianOnBehalf: true });
+  const actions = toApprovalActionOptions(decisionActions);
+  const plainTextFallback = buildPlainTextFallback(promptText, decisionActions);
 
   return { promptText, actions, plainTextFallback };
 }

package/src/runtime/channel-invite-transport.ts

@@ -0,0 +1,85 @@
+/**
+ * Channel invite transport abstraction.
+ *
+ * Defines a transport interface for building shareable invite links and
+ * extracting inbound invite tokens from channel-specific payloads. Each
+ * channel (Telegram, SMS, Slack, etc.) registers an adapter that knows
+ * how to construct deep links and parse incoming tokens for that channel.
+ *
+ * The transport layer is intentionally thin: it handles URL construction
+ * and token extraction only. Redemption logic lives in
+ * `invite-redemption-service.ts`.
+ */
+
+import type { ChannelId } from '../channels/types.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface InviteSharePayload {
+  /** The full URL the recipient can open to redeem the invite. */
+  url: string;
+  /** Human-readable text suitable for display alongside the link. */
+  displayText: string;
+}
+
+export interface ChannelInviteTransport {
+  /** The channel this transport handles. */
+  channel: ChannelId;
+
+  /**
+   * Build a shareable invite payload (URL + display text) from a raw token.
+   *
+   * The raw token is the base64url-encoded secret returned by
+   * `ingress-invite-store.createInvite`. The transport wraps it in a
+   * channel-specific deep link so the recipient can redeem the invite
+   * by clicking/tapping the link.
+   */
+  buildShareableInvite(params: {
+    rawToken: string;
+    sourceChannel: ChannelId;
+  }): InviteSharePayload;
+
+  /**
+   * Extract an invite token from an inbound channel message.
+   *
+   * Returns the raw token string (without the `iv_` prefix) if the
+   * message contains a valid invite token, or `undefined` otherwise.
+   */
+  extractInboundToken(params: {
+    commandIntent?: Record<string, unknown>;
+    content: string;
+    sourceMetadata?: Record<string, unknown>;
+  }): string | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+const registry = new Map<ChannelId, ChannelInviteTransport>();
+
+/**
+ * Register a channel invite transport. Overwrites any previously registered
+ * transport for the same channel.
+ */
+export function registerTransport(transport: ChannelInviteTransport): void {
+  registry.set(transport.channel, transport);
+}
+
+/**
+ * Look up the registered transport for a channel. Returns `undefined` when
+ * no transport has been registered for the given channel.
+ */
+export function getTransport(channel: ChannelId): ChannelInviteTransport | undefined {
+  return registry.get(channel);
+}
+
+/**
+ * Reset the registry. Intended for tests only.
+ * @internal
+ */
+export function _resetRegistry(): void {
+  registry.clear();
+}

package/src/runtime/channel-invite-transports/telegram.ts

@@ -0,0 +1,105 @@
+/**
+ * Telegram channel invite transport adapter.
+ *
+ * Builds `https://t.me/<botUsername>?start=iv_<token>` deep links and
+ * extracts invite tokens from `/start iv_<token>` command payloads.
+ *
+ * The `iv_` prefix distinguishes invite tokens from `gv_` (guardian
+ * verification) tokens that use the same `/start` deep-link mechanism.
+ */
+
+import type { ChannelId } from '../../channels/types.js';
+import { getCredentialMetadata } from '../../tools/credentials/metadata-store.js';
+import {
+  type ChannelInviteTransport,
+  type InviteSharePayload,
+  registerTransport,
+} from '../channel-invite-transport.js';
+
+// ---------------------------------------------------------------------------
+// Bot username resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the Telegram bot username from credential metadata, falling back
+ * to the TELEGRAM_BOT_USERNAME environment variable. Mirrors the resolution
+ * strategy used in `guardian-outbound-actions.ts`.
+ */
+function getTelegramBotUsername(): string | undefined {
+  const meta = getCredentialMetadata('telegram', 'bot_token');
+  if (meta?.accountInfo && typeof meta.accountInfo === 'string' && meta.accountInfo.trim().length > 0) {
+    return meta.accountInfo.trim();
+  }
+  return process.env.TELEGRAM_BOT_USERNAME || undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Token prefix
+// ---------------------------------------------------------------------------
+
+const INVITE_TOKEN_PREFIX = 'iv_';
+
+// ---------------------------------------------------------------------------
+// Transport implementation
+// ---------------------------------------------------------------------------
+
+export const telegramInviteTransport: ChannelInviteTransport = {
+  channel: 'telegram' as ChannelId,
+
+  buildShareableInvite(params: {
+    rawToken: string;
+    sourceChannel: ChannelId;
+  }): InviteSharePayload {
+    const botUsername = getTelegramBotUsername();
+    if (!botUsername) {
+      throw new Error('Telegram bot username is not configured. Set up the Telegram integration first.');
+    }
+
+    const url = `https://t.me/${botUsername}?start=${INVITE_TOKEN_PREFIX}${params.rawToken}`;
+    return {
+      url,
+      displayText: `Open in Telegram: ${url}`,
+    };
+  },
+
+  extractInboundToken(params: {
+    commandIntent?: Record<string, unknown>;
+    content: string;
+    sourceMetadata?: Record<string, unknown>;
+  }): string | undefined {
+    // Primary path: structured command intent from the gateway.
+    // The gateway normalizes `/start <payload>` into
+    // `{ type: 'start', payload: '<payload>' }`.
+    if (
+      params.commandIntent &&
+      params.commandIntent.type === 'start' &&
+      typeof params.commandIntent.payload === 'string'
+    ) {
+      const payload = params.commandIntent.payload;
+      if (payload.startsWith(INVITE_TOKEN_PREFIX)) {
+        const token = payload.slice(INVITE_TOKEN_PREFIX.length);
+        // Reject empty or whitespace-only tokens
+        if (token.length > 0 && token.trim().length > 0) {
+          return token;
+        }
+      }
+      return undefined;
+    }
+
+    // Fallback: raw content parsing for `/start iv_<token>` messages.
+    // This handles cases where the gateway forwards the raw command text
+    // without a structured commandIntent.
+    const match = params.content.match(/^\/start\s+iv_(\S+)/);
+    if (match && match[1] && match[1].length > 0) {
+      return match[1];
+    }
+
+    return undefined;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Auto-register on import
+// ---------------------------------------------------------------------------
+
+registerTransport(telegramInviteTransport);

package/src/runtime/guardian-action-grant-minter.ts

@@ -7,10 +7,12 @@
  * consistently regardless of which channel the guardian answers on.
  */
 
+import { mintGrantFromDecision } from '../approvals/approval-primitive.js';
 import type { GuardianActionRequest } from '../memory/guardian-action-store.js';
-import { createScopedApprovalGrant } from '../memory/scoped-approval-grants.js';
 import { getLogger } from '../util/logger.js';
+import { runApprovalConversationTurn } from './approval-conversation-turn.js';
 import { parseApprovalDecision } from './channel-approval-parser.js';
+import type { ApprovalConversationGenerator } from './http-types.js';
 
 const log = getLogger('guardian-action-grant-minter');
 
@@ -21,76 +23,131 @@ export const GUARDIAN_ACTION_GRANT_TTL_MS = 5 * 60 * 1000;
  * Mint a `tool_signature` scoped grant when a guardian-action request is
  * resolved and the request carries tool metadata (toolName + inputDigest).
  *
+ * Uses two-tier classification:
+ *   1. Deterministic fast path via parseApprovalDecision (exact keyword match).
+ *   2. LLM fallback via runApprovalConversationTurn when the deterministic
+ *      parser returns null and an approvalConversationGenerator is provided.
+ *
  * Skips silently when:
  *   - The resolved request has no toolName/inputDigest (informational consult).
- *   - The guardian's answer is not an explicit approval (fail-closed).
+ *   - The guardian's answer is not classified as approval by either tier (fail-closed).
  *
  * Fails silently on error -- grant minting is best-effort and must never
  * block the guardian-action answer flow.
  */
-export function tryMintGuardianActionGrant(params: {
-  resolvedRequest: GuardianActionRequest;
+export async function tryMintGuardianActionGrant(params: {
+  request: GuardianActionRequest;
   answerText: string;
   decisionChannel: string;
   guardianExternalUserId?: string;
-}): void {
-  const { resolvedRequest, answerText, decisionChannel, guardianExternalUserId } = params;
+  approvalConversationGenerator?: ApprovalConversationGenerator;
+}): Promise<void> {
+  const { request, answerText, decisionChannel, guardianExternalUserId, approvalConversationGenerator } = params;
 
   // Only mint for requests that carry tool metadata -- informational
   // ASK_GUARDIAN consults without tool context do not produce grants.
-  if (!resolvedRequest.toolName || !resolvedRequest.inputDigest) {
+  if (!request.toolName || !request.inputDigest) {
     return;
   }
 
-  // Gate on explicit affirmative guardian decisions (fail-closed).
-  // Only mint when the deterministic parser recognises an approval keyword
-  // ("yes", "approve", "allow", "go ahead", etc.).  Unrecognised text
-  // (e.g. "nope", "don't do that") is treated as non-approval and skipped,
-  // preventing ambiguous answers from producing grants.
+  // Tier 1: Deterministic fast path -- try exact keyword matching first.
+  // Guardian-action invariant: grants are always one-time `tool_signature`
+  // scoped.  We treat `approve_always` from the deterministic parser the
+  // same as `approve_once` -- the grant is still single-use.  This keeps
+  // the guardian-action path aligned with the primary approval interception
+  // flow where guardians are limited to approve_once / reject.
   const decision = parseApprovalDecision(answerText);
-  if (decision?.action !== 'approve_once' && decision?.action !== 'approve_always') {
+  let isApproval = decision?.action === 'approve_once' || decision?.action === 'approve_always';
+
+  // Tier 2: LLM fallback -- when the deterministic parser found no match
+  // and a generator is available, delegate to the conversational engine.
+  // Only allow approve_once (not approve_always) to keep guardian-action
+  // grants strictly one-time and consistent with guardian policy.
+  if (!isApproval && !decision && approvalConversationGenerator) {
+    try {
+      const llmResult = await runApprovalConversationTurn(
+        {
+          toolName: request.toolName,
+          allowedActions: ['approve_once', 'reject'],
+          role: 'guardian',
+          pendingApprovals: [{ requestId: request.id, toolName: request.toolName }],
+          userMessage: answerText,
+        },
+        approvalConversationGenerator,
+      );
+
+      isApproval = llmResult.disposition === 'approve_once';
+
+      log.info(
+        {
+          event: 'guardian_action_grant_llm_fallback',
+          toolName: request.toolName,
+          requestId: request.id,
+          answerText,
+          llmDisposition: llmResult.disposition,
+          matched: isApproval,
+          decisionChannel,
+        },
+        `LLM fallback classifier returned disposition: ${llmResult.disposition}`,
+      );
+    } catch (err) {
+      // Fail-closed: generator errors must not produce grants.
+      log.warn(
+        {
+          event: 'guardian_action_grant_llm_fallback_error',
+          toolName: request.toolName,
+          requestId: request.id,
+          err,
+          decisionChannel,
+        },
+        'LLM fallback classifier threw an error; treating as non-approval (fail-closed)',
+      );
+    }
+  }
+
+  if (!isApproval) {
     log.info(
       {
         event: 'guardian_action_grant_skipped_no_approval',
-        toolName: resolvedRequest.toolName,
-        requestId: resolvedRequest.id,
+        toolName: request.toolName,
+        requestId: request.id,
         answerText,
         parsedAction: decision?.action ?? null,
         decisionChannel,
       },
-      'Skipped grant minting: guardian answer not classified as explicit approval',
+      'Skipped grant minting: guardian answer not classified as approval',
     );
     return;
   }
 
-  try {
-    createScopedApprovalGrant({
-      assistantId: resolvedRequest.assistantId,
-      scopeMode: 'tool_signature',
-      toolName: resolvedRequest.toolName,
-      inputDigest: resolvedRequest.inputDigest,
-      requestChannel: resolvedRequest.sourceChannel,
-      decisionChannel,
-      executionChannel: null,
-      conversationId: resolvedRequest.sourceConversationId,
-      callSessionId: resolvedRequest.callSessionId,
-      guardianExternalUserId: guardianExternalUserId ?? null,
-      expiresAt: new Date(Date.now() + GUARDIAN_ACTION_GRANT_TTL_MS).toISOString(),
-    });
+  const result = mintGrantFromDecision({
+    assistantId: request.assistantId,
+    scopeMode: 'tool_signature',
+    toolName: request.toolName,
+    inputDigest: request.inputDigest,
+    requestChannel: request.sourceChannel,
+    decisionChannel,
+    executionChannel: null,
+    conversationId: request.sourceConversationId,
+    callSessionId: request.callSessionId,
+    guardianExternalUserId: guardianExternalUserId ?? null,
+    expiresAt: new Date(Date.now() + GUARDIAN_ACTION_GRANT_TTL_MS).toISOString(),
+  });
 
+  if (result.ok) {
     log.info(
       {
         event: 'guardian_action_grant_minted',
-        toolName: resolvedRequest.toolName,
-        requestId: resolvedRequest.id,
-        callSessionId: resolvedRequest.callSessionId,
+        toolName: request.toolName,
+        requestId: request.id,
+        callSessionId: request.callSessionId,
         decisionChannel,
       },
       'Minted scoped approval grant for guardian-action answer resolution',
     );
-  } catch (err) {
+  } else {
     log.error(
-      { err, toolName: resolvedRequest.toolName, requestId: resolvedRequest.id },
+      { reason: result.reason, toolName: request.toolName, requestId: request.id },
       'Failed to mint scoped approval grant for guardian-action (non-fatal)',
     );
   }