@vellumai/assistant 0.3.19 → 0.3.20

package/src/memory/ingress-invite-store.ts

@@ -66,7 +66,7 @@ const DEFAULT_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 // Helpers
 // ---------------------------------------------------------------------------
 
-function hashToken(rawToken: string): string {
+export function hashToken(rawToken: string): string {
   return createHash('sha256').update(rawToken).digest('hex');
 }
 
@@ -268,6 +268,12 @@ export function redeemInvite(params: {
     return { error: 'invite_max_uses_reached' };
   }
 
+  // Enforce channel-scoped redemption: when the caller specifies a channel, it
+  // must match the channel the invite was created for.
+  if (params.sourceChannel && params.sourceChannel !== invite.sourceChannel) {
+    return { error: 'invite_channel_mismatch' };
+  }
+
   const newUseCount = invite.useCount + 1;
   const newStatus = newUseCount >= invite.maxUses ? 'redeemed' : 'active';
 
@@ -323,6 +329,94 @@ export function redeemInvite(params: {
   return { invite: updatedInvite, member: rowToMember(memberRow) };
 }
 
+// ---------------------------------------------------------------------------
+// recordInviteUse — consume one use without creating a member row
+// ---------------------------------------------------------------------------
+
+/**
+ * Increment an invite's use count and record redemption metadata without
+ * inserting a new member row. Used when reactivating an existing inactive
+ * member via invite — the member row already exists and just needs an
+ * update, so the transactional INSERT in `redeemInvite` would hit a
+ * unique-key constraint.
+ *
+ * Returns `true` if the use was recorded, or `false` if the invite was
+ * concurrently revoked/expired (the WHERE clause constrains to
+ * `status = 'active'` so a stale write is impossible).
+ */
+export function recordInviteUse(params: {
+  inviteId: string;
+  externalUserId?: string;
+  externalChatId?: string;
+}): boolean {
+  const db = getDb();
+  const now = Date.now();
+
+  const invite = db
+    .select()
+    .from(assistantIngressInvites)
+    .where(eq(assistantIngressInvites.id, params.inviteId))
+    .get();
+
+  if (!invite) return false;
+
+  const newUseCount = invite.useCount + 1;
+  const newStatus = newUseCount >= invite.maxUses ? 'redeemed' : 'active';
+
+  // Constrain the update to active invites so a concurrent revoke/expire
+  // prevents this write rather than silently overwriting the new status.
+  db.update(assistantIngressInvites)
+    .set({
+      useCount: newUseCount,
+      status: newStatus,
+      redeemedByExternalUserId: params.externalUserId ?? null,
+      redeemedByExternalChatId: params.externalChatId ?? null,
+      redeemedAt: now,
+      updatedAt: now,
+    })
+    .where(
+      and(
+        eq(assistantIngressInvites.id, invite.id),
+        eq(assistantIngressInvites.status, 'active'),
+      ),
+    )
+    .run();
+
+  // Re-read to confirm the update took effect (the WHERE clause constrains
+  // to status = 'active', so a concurrent revoke/expire would prevent it).
+  const updated = db
+    .select({ useCount: assistantIngressInvites.useCount })
+    .from(assistantIngressInvites)
+    .where(eq(assistantIngressInvites.id, invite.id))
+    .get();
+
+  return !!updated && updated.useCount === newUseCount;
+}
+
+// ---------------------------------------------------------------------------
+// markInviteExpired
+// ---------------------------------------------------------------------------
+
+/**
+ * Transition an invite's status to 'expired' in storage. This is safe to call
+ * even if the invite is already expired — the WHERE clause scopes the update
+ * to 'active' rows so it becomes a no-op in that case.
+ */
+export function markInviteExpired(inviteId: string): void {
+  const db = getDb();
+  const now = Date.now();
+
+  db.update(assistantIngressInvites)
+    .set({ status: 'expired', updatedAt: now })
+    .where(
+      and(
+        eq(assistantIngressInvites.id, inviteId),
+        eq(assistantIngressInvites.status, 'active'),
+      ),
+    )
+    .run();
+}
+
 // ---------------------------------------------------------------------------
 // findByTokenHash
 // ---------------------------------------------------------------------------

package/src/memory/migrations/035-guardian-action-supersession.ts

@@ -0,0 +1,23 @@
+import type { DrizzleDb } from '../db-connection.js';
+
+/**
+ * Add supersession metadata columns to guardian_action_requests and
+ * create an index for efficient pending-request lookups by call session.
+ *
+ * - superseded_by_request_id: links to the request that replaced this one
+ * - superseded_at: timestamp when supersession occurred
+ * - Index (call_session_id, status, created_at DESC) for fast lookups of
+ *   the most recent pending request per call session
+ *
+ * The existing expired_reason column already supports 'superseded' as a
+ * value — this migration adds the structural metadata to track the
+ * supersession chain.
+ */
+export function migrateGuardianActionSupersession(database: DrizzleDb): void {
+  try { database.run(/*sql*/ `ALTER TABLE guardian_action_requests ADD COLUMN superseded_by_request_id TEXT`); } catch { /* already exists */ }
+  try { database.run(/*sql*/ `ALTER TABLE guardian_action_requests ADD COLUMN superseded_at INTEGER`); } catch { /* already exists */ }
+
+  database.run(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_guardian_action_requests_session_status_created ON guardian_action_requests(call_session_id, status, created_at DESC)`,
+  );
+}

package/src/memory/migrations/index.ts

@@ -33,9 +33,10 @@ export { migrateGuardianActionFollowup } from './030-guardian-action-followup.js
 export { migrateGuardianVerificationPurpose } from './030-guardian-verification-purpose.js';
 export { migrateConversationsThreadTypeIndex } from './031-conversations-thread-type-index.js';
 export { migrateGuardianDeliveryConversationIndex } from './032-guardian-delivery-conversation-index.js';
+export { migrateNotificationDeliveryThreadDecision } from './032-notification-delivery-thread-decision.js';
 export { createScopedApprovalGrantsTable } from './033-scoped-approval-grants.js';
 export { migrateGuardianActionToolMetadata } from './034-guardian-action-tool-metadata.js';
-export { migrateNotificationDeliveryThreadDecision } from './032-notification-delivery-thread-decision.js';
+export { migrateGuardianActionSupersession } from './035-guardian-action-supersession.js';
 export { createCoreTables } from './100-core-tables.js';
 export { createWatchersAndLogsTables } from './101-watchers-and-logs.js';
 export { addCoreColumns } from './102-alter-table-columns.js';

package/src/memory/schema.ts

@@ -845,9 +845,13 @@ export const guardianActionRequests = sqliteTable('guardian_action_requests', {
   followupCompletedAt: integer('followup_completed_at'),
   toolName: text('tool_name'),                                        // tool identity for tool-approval requests
   inputDigest: text('input_digest'),                                  // canonical SHA-256 digest of tool input
+  supersededByRequestId: text('superseded_by_request_id'),            // links to the request that replaced this one
+  supersededAt: integer('superseded_at'),                             // epoch ms when supersession occurred
   createdAt: integer('created_at').notNull(),
   updatedAt: integer('updated_at').notNull(),
-});
+}, (table) => [
+  index('idx_guardian_action_requests_session_status_created').on(table.callSessionId, table.status, table.createdAt),
+]);
 
 // ── Guardian Action Deliveries (per-channel delivery tracking) ───────
 

package/src/memory/scoped-approval-grants.ts

@@ -11,12 +11,12 @@
  *   - Expired and revoked grants cannot be consumed.
  */
 
-import { and, eq, lt, sql } from 'drizzle-orm';
+import { and, eq, sql } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 
+import { getLogger } from '../util/logger.js';
 import { getDb, rawChanges } from './db.js';
 import { scopedApprovalGrants } from './schema.js';
-import { getLogger } from '../util/logger.js';
 
 const log = getLogger('scoped-approval-grants');
 
@@ -104,7 +104,7 @@ export interface CreateScopedApprovalGrantParams {
   expiresAt: string;
 }
 
-export function createScopedApprovalGrant(params: CreateScopedApprovalGrantParams): ScopedApprovalGrant {
+function createScopedApprovalGrant(params: CreateScopedApprovalGrantParams): ScopedApprovalGrant {
   const db = getDb();
   const now = new Date().toISOString();
   const id = uuid();
@@ -167,7 +167,7 @@ export interface ConsumeByRequestIdResult {
  * given `requestId` and `assistantId`.  Uses compare-and-swap on the
  * `status` column so concurrent consumers race safely — at most one wins.
  */
-export function consumeScopedApprovalGrantByRequestId(
+function consumeScopedApprovalGrantByRequestId(
   requestId: string,
   consumingRequestId: string,
   assistantId: string,
@@ -280,7 +280,7 @@ export interface ConsumeByToolSignatureResult {
  * times before giving up. This prevents false denials when multiple matching
  * grants exist but a concurrent consumer steals the first pick.
  */
-export function consumeScopedApprovalGrantByToolSignature(
+function consumeScopedApprovalGrantByToolSignature(
   params: ConsumeByToolSignatureParams,
 ): ConsumeByToolSignatureResult {
   const db = getDb();
@@ -507,3 +507,12 @@ export function revokeScopedApprovalGrantsForContext(params: RevokeContextParams
 
   return count;
 }
+
+// @internal — exposed for tests and the approval-primitive wrapper only.
+// Do not import these from production code outside this package; use the
+// approval-primitive API instead.
+export const _internal = {
+  createScopedApprovalGrant,
+  consumeScopedApprovalGrantByRequestId,
+  consumeScopedApprovalGrantByToolSignature,
+};

package/src/messaging/providers/slack/client.ts

@@ -8,6 +8,7 @@
 import type {
   SlackApiResponse,
   SlackAuthTestResponse,
+  SlackChatDeleteResponse,
   SlackConversationHistoryResponse,
   SlackConversationLeaveResponse,
   SlackConversationMarkResponse,
@@ -188,6 +189,17 @@ export async function addReaction(
   });
 }
 
+export async function deleteMessage(
+  token: string,
+  channel: string,
+  ts: string,
+): Promise<SlackChatDeleteResponse> {
+  return request<SlackChatDeleteResponse>(token, 'chat.delete', undefined, {
+    channel,
+    ts,
+  });
+}
+
 export async function leaveConversation(
   token: string,
   channel: string,

package/src/messaging/providers/slack/types.ts

@@ -116,4 +116,9 @@ export type SlackReactionAddResponse = SlackApiResponse;
 
 export type SlackConversationLeaveResponse = SlackApiResponse;
 
+export interface SlackChatDeleteResponse extends SlackApiResponse {
+  channel: string;
+  ts: string;
+}
+
 export type SlackConversationMarkResponse = SlackApiResponse;

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();
+}