@vellumai/assistant 0.3.26 → 0.3.28

package/src/runtime/tool-grant-request-helper.ts

@@ -0,0 +1,195 @@
+/**
+ * Tool grant request creation and guardian notification helper.
+ *
+ * Encapsulates the "create/dedupe canonical tool_grant_request + emit notification"
+ * logic so non-guardian channel actors can escalate tool invocations that require
+ * guardian approval. Modeled after the access-request-helper pattern.
+ *
+ * Invariants preserved:
+ * - Unverified actors are fail-closed (caller must gate before calling).
+ * - Guardians cannot self-approve (grant minting uses guardian identity).
+ * - Notification routing goes through emitNotificationSignal().
+ */
+
+import type { ChannelId } from '../channels/types.js';
+import {
+  createCanonicalGuardianDelivery,
+  createCanonicalGuardianRequest,
+  listCanonicalGuardianRequests,
+} from '../memory/canonical-guardian-store.js';
+import { emitNotificationSignal } from '../notifications/emit-signal.js';
+import { getLogger } from '../util/logger.js';
+import { getGuardianBinding } from './channel-guardian-service.js';
+import { GUARDIAN_APPROVAL_TTL_MS } from './routes/channel-route-shared.js';
+
+const log = getLogger('tool-grant-request-helper');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ToolGrantRequestParams {
+  assistantId: string;
+  sourceChannel: ChannelId;
+  conversationId: string;
+  requesterExternalUserId: string;
+  requesterChatId?: string;
+  requesterIdentifier?: string;
+  toolName: string;
+  inputDigest: string;
+  questionText: string;
+}
+
+export type ToolGrantRequestResult =
+  | { created: true; requestId: string; requestCode: string | null }
+  | { deduped: true; requestId: string; requestCode: string | null }
+  | { failed: true; reason: 'no_guardian_binding' | 'missing_identity' };
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Create/dedupe a canonical tool_grant_request and emit a notification signal
+ * so the guardian can approve or deny the tool invocation.
+ *
+ * Returns a result indicating whether a new request was created, an existing
+ * one was deduped, or the escalation failed (no binding, missing identity).
+ */
+export function createOrReuseToolGrantRequest(
+  params: ToolGrantRequestParams,
+): ToolGrantRequestResult {
+  const {
+    assistantId,
+    sourceChannel,
+    conversationId,
+    requesterExternalUserId,
+    requesterChatId,
+    requesterIdentifier,
+    toolName,
+    inputDigest,
+    questionText,
+  } = params;
+
+  if (!requesterExternalUserId) {
+    return { failed: true, reason: 'missing_identity' };
+  }
+
+  const binding = getGuardianBinding(assistantId, sourceChannel);
+  if (!binding) {
+    log.debug(
+      { sourceChannel, assistantId },
+      'No guardian binding for tool grant request escalation',
+    );
+    return { failed: true, reason: 'no_guardian_binding' };
+  }
+
+  // Deduplicate: skip creation if there is already a pending canonical request
+  // for the same requester + conversation + tool + input digest + guardian.
+  // Guardian identity is included so that after a guardian rebind, old requests
+  // tied to the previous guardian don't block creation of a new approvable request.
+  const existing = listCanonicalGuardianRequests({
+    status: 'pending',
+    requesterExternalUserId,
+    conversationId,
+    kind: 'tool_grant_request',
+    toolName,
+  });
+  const dedupeMatch = existing.find(
+    (r) => r.inputDigest === inputDigest && r.guardianExternalUserId === binding.guardianExternalUserId,
+  );
+  if (dedupeMatch) {
+    log.debug(
+      {
+        sourceChannel,
+        requesterExternalUserId,
+        toolName,
+        existingId: dedupeMatch.id,
+      },
+      'Skipping duplicate tool grant request notification',
+    );
+    return { deduped: true, requestId: dedupeMatch.id, requestCode: dedupeMatch.requestCode };
+  }
+
+  const senderLabel = requesterIdentifier || requesterExternalUserId;
+  const requestId = `tool-grant-${assistantId}-${sourceChannel}-${requesterExternalUserId}-${Date.now()}`;
+
+  const canonicalRequest = createCanonicalGuardianRequest({
+    id: requestId,
+    kind: 'tool_grant_request',
+    sourceType: 'channel',
+    sourceChannel,
+    conversationId,
+    requesterExternalUserId,
+    requesterChatId: requesterChatId ?? undefined,
+    guardianExternalUserId: binding.guardianExternalUserId,
+    toolName,
+    inputDigest,
+    questionText,
+    expiresAt: new Date(Date.now() + GUARDIAN_APPROVAL_TTL_MS).toISOString(),
+  });
+
+  // Emit notification so guardian is alerted. Uses 'guardian.question' as
+  // sourceEventName so that existing request-code guidance in the notification
+  // pipeline is preserved.
+  const signalPromise = emitNotificationSignal({
+    sourceEventName: 'guardian.question',
+    sourceChannel,
+    sourceSessionId: conversationId,
+    assistantId,
+    attentionHints: {
+      requiresAction: true,
+      urgency: 'high',
+      isAsyncBackground: false,
+      visibleInSourceNow: false,
+    },
+    contextPayload: {
+      requestId: canonicalRequest.id,
+      requestCode: canonicalRequest.requestCode,
+      sourceChannel,
+      requesterExternalUserId,
+      requesterChatId: requesterChatId ?? null,
+      requesterIdentifier: senderLabel,
+      toolName,
+      questionText,
+    },
+    dedupeKey: `tool-grant-request:${canonicalRequest.id}`,
+    onThreadCreated: (info) => {
+      createCanonicalGuardianDelivery({
+        requestId: canonicalRequest.id,
+        destinationChannel: 'vellum',
+        destinationConversationId: info.conversationId,
+      });
+    },
+  });
+
+  // Record deliveries from the notification pipeline results (fire-and-forget).
+  void signalPromise.then((signalResult) => {
+    for (const result of signalResult.deliveryResults) {
+      if (result.channel === 'vellum') continue; // handled in onThreadCreated
+      if (result.channel !== 'telegram' && result.channel !== 'sms') continue;
+      createCanonicalGuardianDelivery({
+        requestId: canonicalRequest.id,
+        destinationChannel: result.channel,
+        destinationChatId: result.destination.length > 0 ? result.destination : undefined,
+      });
+    }
+  });
+
+  log.info(
+    {
+      sourceChannel,
+      requesterExternalUserId,
+      toolName,
+      requestId: canonicalRequest.id,
+      requestCode: canonicalRequest.requestCode,
+    },
+    'Guardian notified of tool grant request',
+  );
+
+  return {
+    created: true,
+    requestId: canonicalRequest.id,
+    requestCode: canonicalRequest.requestCode,
+  };
+}

package/src/tools/executor.ts

@@ -13,6 +13,7 @@ import { resolveExecutionTarget } from './execution-target.js';
 import { executeWithTimeout,safeTimeoutMs } from './execution-timeout.js';
 import { PermissionChecker } from './permission-checker.js';
 import { SecretDetectionHandler } from './secret-detection-handler.js';
+import { extractAndSanitize } from './sensitive-output-placeholders.js';
 import { applyEdit } from './shared/filesystem/edit-engine.js';
 import { sandboxPolicy } from './shared/filesystem/path-policy.js';
 import { MAX_FILE_SIZE_BYTES } from './shared/filesystem/size-guard.js';
@@ -182,6 +183,15 @@ export class ToolExecutor {
         );
       }
 
+      // Sensitive output extraction: strip directives, replace raw values
+      // with placeholders, and attach bindings for agent-loop substitution.
+      // Runs before secret detection so that raw sensitive values are already
+      // replaced and won't trigger entropy-based redaction.
+      const { sanitizedContent, bindings } = extractAndSanitize(execResult.content);
+      if (bindings.length > 0) {
+        execResult = { ...execResult, content: sanitizedContent, sensitiveBindings: bindings };
+      }
+
       // Secret detection on tool output
       const secretResult = await this.secretDetectionHandler.handle(
         execResult, name, input, context, executionTarget,
@@ -193,6 +203,8 @@ export class ToolExecutor {
       execResult = secretResult.result;
 
       const durationMs = Date.now() - startTime;
+      // Strip sensitiveBindings from lifecycle event to prevent raw values leaking
+      const { sensitiveBindings: _sb, ...safeResult } = execResult;
       emitLifecycleEvent(context, {
         type: 'executed',
         toolName: name,
@@ -205,7 +217,7 @@ export class ToolExecutor {
         riskLevel,
         decision,
         durationMs,
-        result: execResult,
+        result: safeResult,
       });
 
       void getHookManager().trigger('post-tool-execute', {

package/src/tools/sensitive-output-placeholders.ts

@@ -0,0 +1,203 @@
+/**
+ * Sensitive output placeholder extraction and substitution.
+ *
+ * Tool outputs may contain `<vellum-sensitive-output kind="..." value="..." />`
+ * directives. This module:
+ * 1. Parses and strips those directives from tool output.
+ * 2. Replaces any raw sensitive values remaining in the output with stable,
+ *    high-uniqueness placeholders so the LLM never sees the real values.
+ * 3. Returns bindings (placeholder -> real value) for deterministic
+ *    post-generation substitution in the agent loop.
+ *
+ * Raw sensitive values MUST NOT be logged or emitted in lifecycle events.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type SensitiveOutputKind = 'invite_code';
+
+export interface SensitiveOutputBinding {
+  kind: SensitiveOutputKind;
+  placeholder: string;
+  value: string;
+}
+
+// ---------------------------------------------------------------------------
+// Directive regex
+// ---------------------------------------------------------------------------
+
+const DIRECTIVE_RE =
+  /<vellum-sensitive-output\s+kind="([^"]+)"\s+value="([^"]+)"\s*\/>/g;
+
+// ---------------------------------------------------------------------------
+// Placeholder generation
+// ---------------------------------------------------------------------------
+
+const KIND_PREFIX: Record<SensitiveOutputKind, string> = {
+  invite_code: 'VELLUM_ASSISTANT_INVITE_CODE_',
+};
+
+const VALID_KINDS = new Set<string>(Object.keys(KIND_PREFIX));
+
+/**
+ * Generate an 8-char uppercase base-36 short ID.
+ * Provides ~41 bits of entropy — sufficient for intra-request uniqueness.
+ */
+function generateShortId(): string {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+  let id = '';
+  for (let i = 0; i < 8; i++) {
+    id += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return id;
+}
+
+function makePlaceholder(kind: SensitiveOutputKind): string {
+  return `${KIND_PREFIX[kind]}${generateShortId()}`;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface SanitizeResult {
+  sanitizedContent: string;
+  bindings: SensitiveOutputBinding[];
+}
+
+/**
+ * Extract `<vellum-sensitive-output>` directives from tool output content,
+ * strip them, replace any remaining occurrences of the raw sensitive values
+ * with placeholders, and return the bindings for downstream substitution.
+ *
+ * Guarantees:
+ * - Directives are fully removed from the returned content.
+ * - Empty values are silently dropped.
+ * - Duplicate values produce a single binding (same placeholder).
+ * - Unknown kinds are silently ignored.
+ */
+export function extractAndSanitize(content: string): SanitizeResult {
+  const bindings: SensitiveOutputBinding[] = [];
+  const seenValues = new Map<string, SensitiveOutputBinding>();
+
+  // Step 1: parse directives
+  // Reset lastIndex for safety since the regex is global
+  DIRECTIVE_RE.lastIndex = 0;
+  let match: RegExpExecArray | undefined;
+  while ((match = DIRECTIVE_RE.exec(content) ?? undefined) !== undefined) {
+    const kind = match[1];
+    const value = match[2];
+
+    if (!value || value.trim().length === 0) continue;
+    if (!VALID_KINDS.has(kind)) continue;
+
+    const typedKind = kind as SensitiveOutputKind;
+    if (!seenValues.has(value)) {
+      const binding: SensitiveOutputBinding = {
+        kind: typedKind,
+        placeholder: makePlaceholder(typedKind),
+        value,
+      };
+      bindings.push(binding);
+      seenValues.set(value, binding);
+    }
+  }
+
+  if (bindings.length === 0) {
+    return { sanitizedContent: content, bindings: [] };
+  }
+
+  // Step 2: strip directive tags
+  let sanitized = content.replace(DIRECTIVE_RE, '');
+
+  // Step 3: replace raw values with placeholders throughout remaining content
+  for (const binding of bindings) {
+    sanitized = sanitized.split(binding.value).join(binding.placeholder);
+  }
+
+  return { sanitizedContent: sanitized, bindings };
+}
+
+/**
+ * Apply placeholder->value substitution to a text string.
+ * Used by the agent loop to resolve placeholders in streamed deltas
+ * and final message content.
+ */
+export function applySubstitutions(
+  text: string,
+  substitutionMap: ReadonlyMap<string, string>,
+): string {
+  if (substitutionMap.size === 0) return text;
+
+  let result = text;
+  for (const [placeholder, value] of substitutionMap) {
+    result = result.split(placeholder).join(value);
+  }
+  return result;
+}
+
+/**
+ * Chunk-safe substitution for streaming text deltas.
+ *
+ * Because a placeholder like `VELLUM_ASSISTANT_INVITE_CODE_AB12CD34` may be
+ * split across consecutive streamed chunks, this function buffers a trailing
+ * segment that could be the start of an incomplete placeholder and returns it
+ * as `pending`. The caller must prepend `pending` to the next chunk.
+ *
+ * Returns `{ emit, pending }`:
+ * - `emit`: text safe to send to the client (all complete placeholders resolved).
+ * - `pending`: trailing text that might be an incomplete placeholder prefix.
+ */
+export function applyStreamingSubstitution(
+  text: string,
+  substitutionMap: ReadonlyMap<string, string>,
+): { emit: string; pending: string } {
+  if (substitutionMap.size === 0) {
+    return { emit: text, pending: '' };
+  }
+
+  // First, resolve any complete placeholders
+  let resolved = text;
+  for (const [placeholder, value] of substitutionMap) {
+    resolved = resolved.split(placeholder).join(value);
+  }
+
+  // Check if the tail of resolved text could be an incomplete placeholder prefix.
+  // All current placeholders start with "VELLUM_ASSISTANT_".
+  const PREFIX = 'VELLUM_ASSISTANT_';
+  const minSuffixLen = 1; // At minimum, one char of the prefix
+
+  // Walk backwards from the end to find a trailing partial match of any placeholder prefix
+  let pendingStart = resolved.length;
+  for (let i = Math.max(0, resolved.length - getMaxPlaceholderLength(substitutionMap)); i < resolved.length; i++) {
+    const tail = resolved.slice(i);
+    // Check if any placeholder starts with this tail
+    if (tail.length >= minSuffixLen && PREFIX.startsWith(tail)) {
+      pendingStart = i;
+      break;
+    }
+    // Also check if any full placeholder key starts with this tail
+    for (const placeholder of substitutionMap.keys()) {
+      if (placeholder.startsWith(tail) && tail.length < placeholder.length) {
+        pendingStart = i;
+        break;
+      }
+    }
+    if (pendingStart !== resolved.length) break;
+  }
+
+  return {
+    emit: resolved.slice(0, pendingStart),
+    pending: resolved.slice(pendingStart),
+  };
+}
+
+function getMaxPlaceholderLength(map: ReadonlyMap<string, string>): number {
+  let max = 0;
+  for (const key of map.keys()) {
+    if (key.length > max) max = key.length;
+  }
+  return max;
+}

package/src/tools/tool-approval-handler.ts

@@ -1,4 +1,5 @@
 import { consumeGrantForInvocation } from '../approvals/approval-primitive.js';
+import { createOrReuseToolGrantRequest } from '../runtime/tool-grant-request-helper.js';
 import { computeToolApprovalDigest } from '../security/tool-approval-digest.js';
 import { getTaskRunRules } from '../tasks/ephemeral-permissions.js';
 import { getLogger } from '../util/logger.js';
@@ -266,7 +267,48 @@ export class ToolApprovalHandler {
       }
 
       // No matching grant or race condition — deny.
-      const reason = guardianApprovalDeniedMessage(context.guardianActorRole, name);
+      //
+      // For verified non-guardian actors with sufficient context, escalate to
+      // the guardian by creating a canonical tool_grant_request. Unverified
+      // actors remain fail-closed with no escalation.
+      let escalationMessage: string | undefined;
+      if (
+        context.guardianActorRole === 'non-guardian'
+        && context.assistantId
+        && context.executionChannel
+        && context.requesterExternalUserId
+      ) {
+        const inputDigest = deferredConsumeParams?.inputDigest
+          ?? computeToolApprovalDigest(name, input);
+        const escalation = createOrReuseToolGrantRequest({
+          assistantId: context.assistantId,
+          sourceChannel: context.executionChannel as import('../channels/types.js').ChannelId,
+          conversationId: context.conversationId,
+          requesterExternalUserId: context.requesterExternalUserId,
+          requesterChatId: context.requesterChatId,
+          toolName: name,
+          inputDigest,
+          questionText: `Trusted contact is requesting permission to use "${name}"`,
+        });
+
+        if ('created' in escalation) {
+          const codeSuffix = escalation.requestCode
+            ? ` (request code: ${escalation.requestCode})`
+            : '';
+          escalationMessage = `Permission denied for "${name}": this action requires guardian approval. `
+            + `A request has been sent to the guardian${codeSuffix}. `
+            + `Please retry after the guardian approves.`;
+        } else if ('deduped' in escalation) {
+          const codeSuffix = escalation.requestCode
+            ? ` (request code: ${escalation.requestCode})`
+            : '';
+          escalationMessage = `Permission denied for "${name}": guardian approval is already pending${codeSuffix}. `
+            + `Please retry after the guardian approves.`;
+        }
+        // If escalation.failed, fall through to generic denial message.
+      }
+
+      const reason = escalationMessage ?? guardianApprovalDeniedMessage(context.guardianActorRole, name);
       log.warn({
         toolName: name,
         sessionId: context.sessionId,
@@ -275,6 +317,7 @@ export class ToolApprovalHandler {
         executionTarget,
         reason: 'guardian_approval_required',
         grantMissReason: grantResult.reason,
+        escalated: !!escalationMessage,
       }, 'Guardian approval gate blocked untrusted actor tool invocation (no matching grant)');
       const durationMs = Date.now() - startTime;
       emitLifecycleEvent({

package/src/tools/types.ts

@@ -1,6 +1,7 @@
 import type { SecretPromptResult } from '../permissions/secret-prompter.js';
 import type { AllowlistOption, RiskLevel, ScopeOption } from '../permissions/types.js';
 import type { ContentBlock,ToolDefinition } from '../providers/types.js';
+import type { SensitiveOutputBinding } from './sensitive-output-placeholders.js';
 
 export type ExecutionTarget = 'sandbox' | 'host';
 
@@ -144,6 +145,8 @@ export interface ToolContext {
   callSessionId?: string;
   /** External user ID of the requester (non-guardian actor). Used for scoped grant consumption. */
   requesterExternalUserId?: string;
+  /** Chat ID of the requester (non-guardian actor). Used for tool grant request escalation notifications. */
+  requesterChatId?: string;
 }
 
 export interface DiffInfo {
@@ -161,6 +164,14 @@ export interface ToolExecutionResult {
   status?: string;
   /** Optional rich content blocks (e.g. images) to include alongside text in the tool result. */
   contentBlocks?: ContentBlock[];
+  /**
+   * Runtime-internal sensitive output bindings (placeholder -> real value).
+   * Populated by the executor when tool output contains
+   * `<vellum-sensitive-output>` directives. The agent loop merges these
+   * into a per-run substitution map for deterministic post-generation
+   * replacement. MUST NOT be emitted in client-facing events or logs.
+   */
+  sensitiveBindings?: SensitiveOutputBinding[];
 }
 
 export interface Tool {

package/src/util/bundled-asset.ts

@@ -0,0 +1,31 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/**
+ * Resolve the path to a bundled asset directory, handling compiled Bun binaries
+ * where `import.meta.dirname` points to the `/$bunfs/` virtual filesystem and
+ * non-JS files (.md, .html, .json, etc.) are not embedded.
+ *
+ * Falls back to:
+ *   1. `Contents/Resources/<bundleName>` (macOS .app bundle)
+ *   2. `<execDir>/<bundleName>` (next to the binary, non-app-bundle deployments)
+ *   3. Original resolved path (source mode, or last resort)
+ *
+ * This matches the pattern established by bundled-skills and WASM resolution.
+ *
+ * @param callerDir  `import.meta.dirname ?? __dirname` from the call site
+ * @param relativePath  Relative path from the source file (used in source/dev mode)
+ * @param bundleName  Name of the asset directory in the app bundle
+ */
+export function resolveBundledDir(callerDir: string, relativePath: string, bundleName: string): string {
+  if (callerDir.startsWith('/$bunfs/')) {
+    const execDir = dirname(process.execPath);
+    // macOS .app bundle: binary in Contents/MacOS/, resources in Contents/Resources/
+    const resourcesPath = join(execDir, '..', 'Resources', bundleName);
+    if (existsSync(resourcesPath)) return resourcesPath;
+    // Next to the binary itself (non-app-bundle deployments)
+    const execDirPath = join(execDir, bundleName);
+    if (existsSync(execDirPath)) return execDirPath;
+  }
+  return join(callerDir, relativePath);
+}

package/src/util/canonicalize-identity.ts

@@ -0,0 +1,52 @@
+/**
+ * Channel-agnostic inbound identity canonicalization.
+ *
+ * Normalizes raw sender identifiers into a stable canonical form so that
+ * trust lookups, member matching, and guardian binding comparisons are
+ * immune to formatting variance across channels.
+ *
+ * Phone-like channels (sms, voice, whatsapp) normalize to E.164 using the
+ * existing phone utilities. Non-phone channels (telegram, slack, etc.)
+ * pass through the platform-stable ID as-is after whitespace trimming.
+ */
+
+import type { ChannelId } from '../channels/types.js';
+import { normalizePhoneNumber } from './phone.js';
+
+/** Channels whose raw sender IDs are phone numbers. */
+const PHONE_CHANNELS: ReadonlySet<ChannelId> = new Set(['sms', 'voice', 'whatsapp']);
+
+/**
+ * Canonicalize a raw inbound sender identity for the given channel.
+ *
+ * - For phone-like channels: attempts E.164 normalization. Returns the
+ *   normalized E.164 string on success, or the trimmed raw ID if
+ *   normalization fails (defensive: don't discard an identity just because
+ *   it doesn't parse as a phone number).
+ * - For non-phone channels: returns the trimmed raw ID unchanged (these
+ *   platforms provide stable, unique identifiers that don't need normalization).
+ *
+ * Returns `null` only when `rawId` is empty/whitespace-only.
+ */
+export function canonicalizeInboundIdentity(channel: ChannelId, rawId: string): string | null {
+  const trimmed = rawId.trim();
+  if (trimmed.length === 0) return null;
+
+  if (PHONE_CHANNELS.has(channel)) {
+    const e164 = normalizePhoneNumber(trimmed);
+    // Defensive: if normalization fails, preserve the raw ID so downstream
+    // lookups don't silently lose the identity.
+    return e164 ?? trimmed;
+  }
+
+  return trimmed;
+}
+
+/**
+ * Check whether a channel uses phone-number-based identity.
+ * Useful for call sites that need to know whether E.164 normalization
+ * applies without re-importing the channel set.
+ */
+export function isPhoneChannel(channel: ChannelId): boolean {
+  return PHONE_CHANNELS.has(channel);
+}