@vellumai/assistant 0.3.19 → 0.3.21

package/src/approvals/approval-primitive.ts

@@ -0,0 +1,381 @@
+/**
+ * Unified approval primitive for scoped approval grants.
+ *
+ * All producers (voice guardian-action minter, channel guardian approval
+ * interception) and consumers (tool executor grant checks) must go through
+ * this module instead of calling the storage layer directly.  This enforces
+ * all scope constraints in one place and provides structured logging for
+ * mint/consume hit/miss diagnostics.
+ *
+ * Storage remains in `scoped_approval_grants` via the existing CRUD module;
+ * this primitive wraps that layer with a unified API surface.
+ */
+
+import {
+  _internal,
+  type ConsumeByRequestIdResult,
+  type ConsumeByToolSignatureResult,
+  type ScopedApprovalGrant,
+} from '../memory/scoped-approval-grants.js';
+
+const { createScopedApprovalGrant, consumeScopedApprovalGrantByRequestId, consumeScopedApprovalGrantByToolSignature } = _internal;
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('approval-primitive');
+
+// ---------------------------------------------------------------------------
+// Mint
+// ---------------------------------------------------------------------------
+
+export interface MintGrantParams {
+  assistantId: string;
+  scopeMode: 'request_id' | 'tool_signature';
+  requestId?: string | null;
+  toolName?: string | null;
+  inputDigest?: string | null;
+  requestChannel: string;
+  decisionChannel: string;
+  executionChannel?: string | null;
+  conversationId?: string | null;
+  callSessionId?: string | null;
+  requesterExternalUserId?: string | null;
+  guardianExternalUserId?: string | null;
+  expiresAt: string;
+}
+
+export type MintGrantResult =
+  | { ok: true; grant: ScopedApprovalGrant }
+  | { ok: false; reason: 'missing_request_id' | 'missing_tool_fields' | 'storage_error'; error?: unknown };
+
+/**
+ * Mint a scoped approval grant from a guardian decision.
+ *
+ * Validates scope-mode-specific field requirements before delegating to the
+ * storage layer:
+ *   - `request_id` scope requires a non-null `requestId`.
+ *   - `tool_signature` scope requires both `toolName` and `inputDigest`.
+ *
+ * Returns a discriminated result so callers can inspect failure reasons
+ * without catching exceptions.
+ */
+export function mintGrantFromDecision(params: MintGrantParams): MintGrantResult {
+  // Scope-mode field validation
+  if (params.scopeMode === 'request_id' && !params.requestId) {
+    log.warn(
+      {
+        event: 'approval_primitive_mint_rejected',
+        reason: 'missing_request_id',
+        scopeMode: params.scopeMode,
+        assistantId: params.assistantId,
+        requestChannel: params.requestChannel,
+        decisionChannel: params.decisionChannel,
+      },
+      'Mint rejected: request_id scope requires a non-null requestId',
+    );
+    return { ok: false, reason: 'missing_request_id' };
+  }
+
+  if (params.scopeMode === 'tool_signature' && (!params.toolName || !params.inputDigest)) {
+    log.warn(
+      {
+        event: 'approval_primitive_mint_rejected',
+        reason: 'missing_tool_fields',
+        scopeMode: params.scopeMode,
+        toolName: params.toolName ?? null,
+        inputDigest: params.inputDigest ?? null,
+        assistantId: params.assistantId,
+        requestChannel: params.requestChannel,
+        decisionChannel: params.decisionChannel,
+      },
+      'Mint rejected: tool_signature scope requires both toolName and inputDigest',
+    );
+    return { ok: false, reason: 'missing_tool_fields' };
+  }
+
+  try {
+    const grant = createScopedApprovalGrant({
+      assistantId: params.assistantId,
+      scopeMode: params.scopeMode,
+      requestId: params.requestId ?? null,
+      toolName: params.toolName ?? null,
+      inputDigest: params.inputDigest ?? null,
+      requestChannel: params.requestChannel,
+      decisionChannel: params.decisionChannel,
+      executionChannel: params.executionChannel ?? null,
+      conversationId: params.conversationId ?? null,
+      callSessionId: params.callSessionId ?? null,
+      requesterExternalUserId: params.requesterExternalUserId ?? null,
+      guardianExternalUserId: params.guardianExternalUserId ?? null,
+      expiresAt: params.expiresAt,
+    });
+
+    log.info(
+      {
+        event: 'approval_primitive_mint_success',
+        grantId: grant.id,
+        scopeMode: params.scopeMode,
+        toolName: params.toolName ?? null,
+        requestId: params.requestId ?? null,
+        assistantId: params.assistantId,
+        requestChannel: params.requestChannel,
+        decisionChannel: params.decisionChannel,
+        conversationId: params.conversationId ?? null,
+        callSessionId: params.callSessionId ?? null,
+        expiresAt: params.expiresAt,
+      },
+      'Approval grant minted',
+    );
+
+    return { ok: true, grant };
+  } catch (error) {
+    log.error(
+      {
+        event: 'approval_primitive_mint_error',
+        scopeMode: params.scopeMode,
+        toolName: params.toolName ?? null,
+        assistantId: params.assistantId,
+        err: error,
+      },
+      'Failed to mint approval grant (storage error)',
+    );
+    return { ok: false, reason: 'storage_error', error };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Consume
+// ---------------------------------------------------------------------------
+
+export interface ConsumeByRequestIdParams {
+  requestId: string;
+  consumingRequestId: string;
+  assistantId: string;
+  now?: string;
+}
+
+export interface ConsumeByToolSignatureParams {
+  toolName: string;
+  inputDigest: string;
+  consumingRequestId: string;
+  assistantId?: string;
+  executionChannel?: string;
+  conversationId?: string;
+  callSessionId?: string;
+  requesterExternalUserId?: string;
+  now?: string;
+}
+
+export type ConsumeGrantResult =
+  | { ok: true; grant: ScopedApprovalGrant }
+  | { ok: false; reason: 'no_match' | 'scope_mismatch' | 'expired' | 'already_consumed' | 'aborted' };
+
+export interface ConsumeGrantParams {
+  requestId?: string;
+  toolName: string;
+  inputDigest: string;
+  consumingRequestId: string;
+  assistantId: string;
+  executionChannel?: string;
+  conversationId?: string;
+  callSessionId?: string;
+  requesterExternalUserId?: string;
+  now?: string;
+}
+
+/**
+ * Single synchronous attempt to consume a scoped approval grant.
+ *
+ * Tries `request_id` mode first when a requestId is provided, then falls
+ * back to `tool_signature` mode.  This mirrors the priority ordering at
+ * the consume site: an exact request-bound grant takes precedence over a
+ * tool-signature grant.
+ *
+ * This is an internal helper — callers should use {@link consumeGrantForInvocation}
+ * which adds retry polling to handle the voice pipeline race condition.
+ */
+function consumeGrantSync(params: ConsumeGrantParams): ConsumeGrantResult {
+  // Try request_id mode first when a requestId is provided
+  if (params.requestId) {
+    const reqResult: ConsumeByRequestIdResult = consumeScopedApprovalGrantByRequestId(
+      params.requestId,
+      params.consumingRequestId,
+      params.assistantId,
+      params.now,
+    );
+
+    if (reqResult.ok && reqResult.grant) {
+      log.info(
+        {
+          event: 'approval_primitive_consume_hit',
+          mode: 'request_id',
+          grantId: reqResult.grant.id,
+          requestId: params.requestId,
+          consumingRequestId: params.consumingRequestId,
+          assistantId: params.assistantId,
+          toolName: params.toolName,
+        },
+        'Approval grant consumed via request_id',
+      );
+      return { ok: true, grant: reqResult.grant };
+    }
+
+    log.info(
+      {
+        event: 'approval_primitive_consume_miss',
+        mode: 'request_id',
+        reason: 'no_match',
+        requestId: params.requestId,
+        consumingRequestId: params.consumingRequestId,
+        assistantId: params.assistantId,
+        toolName: params.toolName,
+      },
+      'No request_id grant match, falling through to tool_signature',
+    );
+  }
+
+  // Fall back to tool_signature mode
+  const sigResult: ConsumeByToolSignatureResult = consumeScopedApprovalGrantByToolSignature({
+    toolName: params.toolName,
+    inputDigest: params.inputDigest,
+    consumingRequestId: params.consumingRequestId,
+    assistantId: params.assistantId,
+    executionChannel: params.executionChannel,
+    conversationId: params.conversationId,
+    callSessionId: params.callSessionId,
+    requesterExternalUserId: params.requesterExternalUserId,
+    now: params.now,
+  });
+
+  if (sigResult.ok && sigResult.grant) {
+    log.info(
+      {
+        event: 'approval_primitive_consume_hit',
+        mode: 'tool_signature',
+        grantId: sigResult.grant.id,
+        toolName: params.toolName,
+        consumingRequestId: params.consumingRequestId,
+        assistantId: params.assistantId,
+        conversationId: params.conversationId ?? null,
+        callSessionId: params.callSessionId ?? null,
+      },
+      'Approval grant consumed via tool_signature',
+    );
+    return { ok: true, grant: sigResult.grant };
+  }
+
+  log.info(
+    {
+      event: 'approval_primitive_consume_miss',
+      mode: 'tool_signature',
+      reason: 'no_match',
+      toolName: params.toolName,
+      consumingRequestId: params.consumingRequestId,
+      assistantId: params.assistantId,
+      conversationId: params.conversationId ?? null,
+      callSessionId: params.callSessionId ?? null,
+      executionChannel: params.executionChannel ?? null,
+    },
+    'No tool_signature grant match found',
+  );
+
+  return { ok: false, reason: 'no_match' };
+}
+
+// ---------------------------------------------------------------------------
+// Public consume API (with retry for voice pipeline race condition)
+// ---------------------------------------------------------------------------
+
+/** Default polling interval for grant retry (ms). */
+const GRANT_RETRY_INTERVAL_MS = 250;
+/** Default maximum wait time for grant retry (ms). */
+const GRANT_RETRY_MAX_WAIT_MS = 10_000;
+
+/**
+ * Consume a scoped approval grant for a tool invocation.
+ *
+ * Performs a synchronous lookup first and returns immediately when a
+ * matching grant exists.  When the first attempt misses, retries with
+ * polling to handle the voice pipeline race condition where the grant
+ * may still be in-flight: `answerCall()` triggers the voice turn as
+ * fire-and-forget, and the voice LLM can attempt tool execution before
+ * `tryMintGuardianActionGrant`'s LLM fallback finishes minting the
+ * grant.  Polling bridges this timing gap without changing the
+ * fire-and-forget architecture.
+ */
+export async function consumeGrantForInvocation(
+  params: ConsumeGrantParams,
+  options?: { maxWaitMs?: number; intervalMs?: number; signal?: AbortSignal },
+): Promise<ConsumeGrantResult> {
+  // Fast path: try once synchronously — covers the common case where the
+  // grant already exists (deterministic classifier, or prior turns).
+  const first = consumeGrantSync(params);
+  if (first.ok) {
+    return first;
+  }
+
+  // When maxWaitMs is 0, skip retry entirely — used by non-voice channels
+  // where grant-minting race conditions don't apply.
+  const maxWait = options?.maxWaitMs ?? GRANT_RETRY_MAX_WAIT_MS;
+  if (maxWait <= 0) {
+    return first;
+  }
+
+  const interval = options?.intervalMs ?? GRANT_RETRY_INTERVAL_MS;
+  const deadline = Date.now() + maxWait;
+
+  log.info(
+    {
+      event: 'approval_primitive_consume_retry_start',
+      toolName: params.toolName,
+      consumingRequestId: params.consumingRequestId,
+      maxWaitMs: maxWait,
+      intervalMs: interval,
+    },
+    'Grant not found on first attempt; starting retry polling',
+  );
+
+  const signal = options?.signal;
+
+  while (Date.now() < deadline) {
+    // Exit promptly on cancellation (e.g. voice barge-in) so the session
+    // can tear down the current turn without waiting for the full timeout.
+    // Returns 'aborted' (not 'no_match') so callers can distinguish
+    // cancellation from a genuine grant miss.
+    if (signal?.aborted) {
+      return { ok: false, reason: 'aborted' };
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, interval));
+
+    if (signal?.aborted) {
+      return { ok: false, reason: 'aborted' };
+    }
+
+    const result = consumeGrantSync(params);
+    if (result.ok) {
+      log.info(
+        {
+          event: 'approval_primitive_consume_retry_hit',
+          toolName: params.toolName,
+          consumingRequestId: params.consumingRequestId,
+          grantId: result.grant.id,
+          elapsedMs: maxWait - (deadline - Date.now()),
+        },
+        'Grant found after retry polling',
+      );
+      return result;
+    }
+  }
+
+  log.info(
+    {
+      event: 'approval_primitive_consume_retry_timeout',
+      toolName: params.toolName,
+      consumingRequestId: params.consumingRequestId,
+      maxWaitMs: maxWait,
+    },
+    'Grant retry polling timed out — no matching grant found',
+  );
+
+  return { ok: false, reason: 'no_match' };
+}

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

@@ -0,0 +1,191 @@
+/**
+ * Unified guardian decision primitive.
+ *
+ * All guardian decision entrypoints (callback buttons, conversational engine,
+ * legacy parser, requester self-cancel) call through this module instead of
+ * inlining the decision-application logic.  This centralizes:
+ *
+ *   1. `approve_always` downgrade for guardian-on-behalf requests
+ *   2. Identity validation (actor must match assigned guardian)
+ *   3. Approval-info capture before the pending interaction is consumed
+ *   4. Atomic decision application via `handleChannelDecision`
+ *   5. Guardian approval record update
+ *   6. Scoped grant minting on approve
+ *
+ * Security invariants enforced here:
+ *   - Decision application is identity-bound to expected guardian identity
+ *   - Decisions are first-response-wins (CAS-like stale protection)
+ *   - `approve_always` is rejected/downgraded for guardian-on-behalf requests
+ *   - Scoped grant minting only on explicit approve for requests with tool metadata
+ */
+
+import type { ChannelId } from '../channels/types.js';
+import {
+  type GuardianApprovalRequest,
+  updateApprovalDecision,
+} from '../memory/channel-guardian-store.js';
+import type {
+  ApprovalDecisionResult,
+} from '../runtime/channel-approval-types.js';
+import {
+  getApprovalInfoByConversation,
+  handleChannelDecision,
+  type PendingApprovalInfo,
+} from '../runtime/channel-approvals.js';
+import type { ApplyGuardianDecisionResult } from '../runtime/guardian-decision-types.js';
+import { computeToolApprovalDigest } from '../security/tool-approval-digest.js';
+import { getLogger } from '../util/logger.js';
+import { mintGrantFromDecision } from './approval-primitive.js';
+
+const log = getLogger('guardian-decision-primitive');
+
+/** TTL for scoped approval grants minted on guardian approve_once decisions. */
+export const GRANT_TTL_MS = 5 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Scoped grant minting
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint a `tool_signature` scoped grant when a guardian approves a tool-approval
+ * request.  Only mints when the approval info contains a tool invocation with
+ * input (so we can compute the input digest).  Informational ASK_GUARDIAN
+ * requests that lack tool input are skipped.
+ *
+ * Fails silently on error -- grant minting is best-effort and must never block
+ * the approval flow.
+ */
+export function tryMintToolApprovalGrant(params: {
+  approvalInfo: PendingApprovalInfo;
+  approval: GuardianApprovalRequest;
+  decisionChannel: ChannelId;
+  guardianExternalUserId: string;
+}): void {
+  const { approvalInfo, approval, decisionChannel, guardianExternalUserId } = params;
+
+  if (!approvalInfo.toolName) {
+    return;
+  }
+
+  let inputDigest: string;
+  try {
+    inputDigest = computeToolApprovalDigest(approvalInfo.toolName, approvalInfo.input);
+  } catch (err) {
+    log.error(
+      { err, toolName: approvalInfo.toolName, conversationId: approval.conversationId },
+      'Failed to compute tool approval digest for grant minting (non-fatal)',
+    );
+    return;
+  }
+
+  const result = mintGrantFromDecision({
+    assistantId: approval.assistantId,
+    scopeMode: 'tool_signature',
+    toolName: approvalInfo.toolName,
+    inputDigest,
+    requestChannel: approval.channel,
+    decisionChannel,
+    executionChannel: null,
+    conversationId: approval.conversationId,
+    callSessionId: null,
+    guardianExternalUserId,
+    requesterExternalUserId: approval.requesterExternalUserId,
+    expiresAt: new Date(Date.now() + GRANT_TTL_MS).toISOString(),
+  });
+
+  if (result.ok) {
+    log.info(
+      { toolName: approvalInfo.toolName, conversationId: approval.conversationId },
+      'Minted scoped approval grant for guardian tool-approval decision',
+    );
+  } else {
+    log.error(
+      { reason: result.reason, toolName: approvalInfo.toolName, conversationId: approval.conversationId },
+      'Failed to mint scoped approval grant (non-fatal)',
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Apply guardian decision (unified primitive)
+// ---------------------------------------------------------------------------
+
+export interface ApplyGuardianDecisionParams {
+  /** The guardian approval record from the store. */
+  approval: GuardianApprovalRequest;
+  /** The parsed decision (action + source + optional requestId). */
+  decision: ApprovalDecisionResult;
+  /** External user ID of the actor making the decision. */
+  actorExternalUserId: string | undefined;
+  /** Channel the decision arrived on. */
+  actorChannel: ChannelId;
+  /** Optional decision context passed to handleChannelDecision. */
+  decisionContext?: string;
+}
+
+/**
+ * Apply a guardian decision through the unified primitive.
+ *
+ * This function centralizes the core logic that was previously duplicated
+ * across callback, conversational engine, legacy parser, and requester
+ * self-cancel paths:
+ *
+ *   1. Downgrade `approve_always` to `approve_once` (guardians cannot
+ *      permanently allowlist tools on behalf of requesters)
+ *   2. Capture pending approval info before resolution
+ *   3. Apply the decision atomically via `handleChannelDecision`
+ *   4. Update the guardian approval record
+ *   5. Mint a scoped grant on approve
+ *
+ * Returns a structured result so callers can handle stale/race outcomes.
+ */
+export function applyGuardianDecision(params: ApplyGuardianDecisionParams): ApplyGuardianDecisionResult {
+  const { approval, decision, actorExternalUserId, actorChannel, decisionContext } = params;
+
+  // Guardians cannot approve_always on behalf of requesters -- downgrade.
+  const effectiveDecision: ApprovalDecisionResult = decision.action === 'approve_always'
+    ? { ...decision, action: 'approve_once' }
+    : decision;
+
+  // Capture pending approval info before handleChannelDecision resolves
+  // (and removes) the pending interaction. Needed for grant minting.
+  const approvalInfo = getApprovalInfoByConversation(approval.conversationId);
+  const matchedInfo = effectiveDecision.requestId
+    ? approvalInfo.find(a => a.requestId === effectiveDecision.requestId)
+    : approvalInfo[0];
+
+  // Apply the decision to the underlying session
+  const result = handleChannelDecision(
+    approval.conversationId,
+    effectiveDecision,
+    decisionContext,
+  );
+
+  if (!result.applied) {
+    return { applied: false, reason: 'stale', requestId: effectiveDecision.requestId };
+  }
+
+  // Update the guardian approval request record
+  const approvalStatus = effectiveDecision.action === 'reject' ? 'denied' as const : 'approved' as const;
+  updateApprovalDecision(approval.id, {
+    status: approvalStatus,
+    decidedByExternalUserId: actorExternalUserId,
+  });
+
+  // Mint a scoped grant when a guardian approves a tool-approval request.
+  // Skip when actorExternalUserId is undefined -- minting a grant without
+  // a known guardian identity is meaningless (e.g. requester self-cancel).
+  if (effectiveDecision.action !== 'reject' && matchedInfo && actorExternalUserId) {
+    tryMintToolApprovalGrant({
+      approvalInfo: matchedInfo,
+      approval,
+      decisionChannel: actorChannel,
+      guardianExternalUserId: actorExternalUserId,
+    });
+  }
+
+  return {
+    applied: true,
+    requestId: result.requestId,
+  };
+}