@vellumai/assistant 0.4.2 → 0.4.4

package/src/calls/call-domain.ts

@@ -9,11 +9,13 @@ import { getTwilioUserPhoneNumber } from '../config/env.js';
 import { loadConfig } from '../config/loader.js';
 import { VALID_CALLER_IDENTITY_MODES } from '../config/schema.js';
 import type { AssistantConfig } from '../config/types.js';
+import { resolveCallbackUrl } from '../inbound/platform-callback-registration.js';
 import { getTwilioStatusCallbackUrl,getTwilioVoiceWebhookUrl } from '../inbound/public-ingress-urls.js';
 import { getOrCreateConversation } from '../memory/conversation-key-store.js';
 import { queueGenerateConversationTitle } from '../memory/conversation-title-service.js';
 import { upsertBinding } from '../memory/external-conversation-store.js';
 import { revokeScopedApprovalGrantsForContext } from '../memory/scoped-approval-grants.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from '../runtime/assistant-scope.js';
 import { isGuardian } from '../runtime/channel-guardian-service.js';
 import { getSecureKey } from '../security/secure-keys.js';
 import { getLogger } from '../util/logger.js';
@@ -100,8 +102,7 @@ export type CallerIdentityResult =
  * - Otherwise, always use `assistant_number` (implicit default).
  *
  * For `assistant_number`: uses the Twilio phone number from
- *   `getTwilioConfig(assistantId)` so multi-assistant mappings are honored.
- *   No eligibility check is performed — this is a fast path.
+ *   `getTwilioConfig()`. No eligibility check is performed — this is a fast path.
  * For `user_number`: uses `config.calls.callerIdentity.userNumber` or the
  *   secure key `credential:twilio:user_phone_number`, then validates that the
  *   number is usable as an outbound caller ID via the Twilio API.
@@ -133,7 +134,7 @@ export async function resolveCallerIdentity(
 
   if (mode === 'assistant_number') {
     const twilioConfig = getTwilioConfig(assistantId);
-    log.info({ mode, source, fromNumber: twilioConfig.phoneNumber, assistantId }, 'Resolved caller identity');
+    log.info({ mode, source, fromNumber: twilioConfig.phoneNumber }, 'Resolved caller identity');
     return { ok: true, mode, fromNumber: twilioConfig.phoneNumber, source };
   }
 
@@ -208,7 +209,7 @@ export type CreateInboundVoiceSessionResult = {
 export function createInboundVoiceSession(
   input: CreateInboundVoiceSessionInput,
 ): CreateInboundVoiceSessionResult {
-  const { callSid, fromNumber, toNumber, assistantId = 'self' } = input;
+  const { callSid, fromNumber, toNumber, assistantId = DAEMON_INTERNAL_ASSISTANT_ID } = input;
 
   // Check if a session already exists for this CallSid (replay protection)
   const existing = getCallSessionByCallSid(callSid);
@@ -219,7 +220,7 @@ export function createInboundVoiceSession(
 
   // Create a dedicated voice conversation keyed by CallSid so inbound calls
   // get their own conversation thread.
-  const voiceConvKey = assistantId && assistantId !== 'self'
+  const voiceConvKey = assistantId && assistantId !== DAEMON_INTERNAL_ASSISTANT_ID
     ? `asst:${assistantId}:voice:inbound:${callSid}`
     : `voice:inbound:${callSid}`;
   const { conversationId: voiceConversationId } = getOrCreateConversation(voiceConvKey);
@@ -272,7 +273,7 @@ export function createInboundVoiceSession(
  * Initiate a new outbound call.
  */
 export async function startCall(input: StartCallInput): Promise<StartCallResult | CallError> {
-  const { phoneNumber, task, context: callContext, conversationId, callerIdentityMode, assistantId = 'self' } = input;
+  const { phoneNumber, task, context: callContext, conversationId, callerIdentityMode, assistantId = DAEMON_INTERNAL_ASSISTANT_ID } = input;
 
   if (!phoneNumber || typeof phoneNumber !== 'string') {
     return { ok: false, error: 'phone_number is required and must be a string', status: 400 };
@@ -357,11 +358,23 @@ export async function startCall(input: StartCallInput): Promise<StartCallResult
 
     log.info({ callSessionId: session.id, voiceConversationId, initiatedFrom: conversationId, to: phoneNumber, from: fromNumber, task }, 'Initiating outbound call');
 
+    const webhookUrl = await resolveCallbackUrl(
+      () => getTwilioVoiceWebhookUrl(ingressConfig, session.id),
+      'webhooks/twilio/voice',
+      'twilio_voice',
+      { callSessionId: session.id },
+    );
+    const statusCallbackUrl = await resolveCallbackUrl(
+      () => getTwilioStatusCallbackUrl(ingressConfig),
+      'webhooks/twilio/status',
+      'twilio_status',
+    );
+
     const { callSid } = await provider.initiateCall({
       from: fromNumber,
       to: phoneNumber,
-      webhookUrl: getTwilioVoiceWebhookUrl(ingressConfig, session.id),
-      statusCallbackUrl: getTwilioStatusCallbackUrl(ingressConfig),
+      webhookUrl,
+      statusCallbackUrl,
     });
 
     updateCallSession(session.id, { providerCallSid: callSid });
@@ -644,7 +657,7 @@ export type StartGuardianVerificationCallResult =
 export async function startGuardianVerificationCall(
   input: StartGuardianVerificationCallInput,
 ): Promise<StartGuardianVerificationCallResult> {
-  const { phoneNumber, guardianVerificationSessionId, assistantId = 'self', originConversationId } = input;
+  const { phoneNumber, guardianVerificationSessionId, assistantId = DAEMON_INTERNAL_ASSISTANT_ID, originConversationId } = input;
 
   if (!phoneNumber || !E164_REGEX.test(phoneNumber)) {
     return { ok: false, error: 'phone_number must be in E.164 format', status: 400 };
@@ -686,8 +699,17 @@ export async function startGuardianVerificationCall(
     });
     sessionId = session.id;
 
-    const webhookUrl = getTwilioVoiceWebhookUrl(config, session.id);
-    const statusCallbackUrl = getTwilioStatusCallbackUrl(config);
+    const webhookUrl = await resolveCallbackUrl(
+      () => getTwilioVoiceWebhookUrl(config, session.id),
+      'webhooks/twilio/voice',
+      'twilio_voice',
+      { callSessionId: session.id },
+    );
+    const statusCallbackUrl = await resolveCallbackUrl(
+      () => getTwilioStatusCallbackUrl(config),
+      'webhooks/twilio/status',
+      'twilio_status',
+    );
 
     const { callSid } = await provider.initiateCall({
       from: identityResult.fromNumber,

package/src/calls/call-pointer-message-composer.ts

@@ -0,0 +1,154 @@
+/**
+ * Layered call pointer message composition system.
+ *
+ * Generates pointer/status copy through a priority chain:
+ *   1. Generator-produced text (when provided by daemon and audience is trusted)
+ *   2. Deterministic fallback templates (preserving existing semantics)
+ *
+ * Follows the same pattern as approval-message-composer.ts and
+ * guardian-action-message-composer.ts.
+ */
+import type { PointerCopyGenerator } from '../runtime/http-types.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('call-pointer-message-composer');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type CallPointerMessageScenario =
+  | 'started'
+  | 'completed'
+  | 'failed'
+  | 'guardian_verification_succeeded'
+  | 'guardian_verification_failed';
+
+export interface CallPointerMessageContext {
+  scenario: CallPointerMessageScenario;
+  phoneNumber: string;
+  duration?: string;
+  reason?: string;
+  verificationCode?: string;
+  channel?: string;
+}
+
+export interface ComposeCallPointerMessageOptions {
+  fallbackText?: string;
+  requiredFacts?: string[];
+  maxTokens?: number;
+  timeoutMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Constants (exported for the daemon-injected generator implementation)
+// ---------------------------------------------------------------------------
+
+export const POINTER_COPY_TIMEOUT_MS = 3_000;
+export const POINTER_COPY_MAX_TOKENS = 120;
+export const POINTER_COPY_SYSTEM_PROMPT =
+  'You are an assistant writing a brief status update about a phone call. '
+  + 'Keep it concise (1-2 sentences), natural, and informative. '
+  + 'Preserve all factual details exactly (phone numbers, durations, failure reasons, verification status). '
+  + 'Do not mention internal systems or technical details. '
+  + 'Return plain text only.';
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compose pointer copy using the daemon-injected generator when available,
+ * with deterministic fallback for reliability.
+ *
+ * The generator parameter is the daemon-provided function that knows about
+ * providers. When absent (or in test env), only the deterministic fallback
+ * is used.
+ */
+export async function composeCallPointerMessageGenerative(
+  context: CallPointerMessageContext,
+  options: ComposeCallPointerMessageOptions = {},
+  generator?: PointerCopyGenerator,
+): Promise<string> {
+  const fallbackText = options.fallbackText?.trim() || getPointerFallbackMessage(context);
+
+  if (process.env.NODE_ENV === 'test') {
+    return fallbackText;
+  }
+
+  if (generator) {
+    try {
+      const generated = await generator(context, options);
+      if (generated) return generated;
+    } catch (err) {
+      log.warn({ err, scenario: context.scenario }, 'Failed to generate pointer copy, using fallback');
+    }
+  }
+
+  return fallbackText;
+}
+
+/** @internal Exported for use by the daemon-injected generator implementation. */
+export function buildPointerGenerationPrompt(
+  context: CallPointerMessageContext,
+  fallbackText: string,
+  requiredFacts: string[] | undefined,
+): string {
+  const factClause = requiredFacts && requiredFacts.length > 0
+    ? `Required facts to include: ${requiredFacts.join(', ')}.\n`
+    : '';
+  return [
+    'Rewrite the following call status message as a natural, conversational update.',
+    'Keep the same concrete facts (phone number, duration, failure reason, verification status).',
+    factClause,
+    `Context JSON: ${JSON.stringify(context)}`,
+    `Fallback message: ${fallbackText}`,
+  ].filter(Boolean).join('\n\n');
+}
+
+/** @internal Exported for use by the daemon-injected generator implementation. */
+export function includesRequiredFacts(text: string, requiredFacts: string[] | undefined): boolean {
+  if (!requiredFacts || requiredFacts.length === 0) return true;
+  return requiredFacts.every((fact) => text.includes(fact));
+}
+
+// ---------------------------------------------------------------------------
+// Deterministic fallback templates
+// ---------------------------------------------------------------------------
+
+/**
+ * Return a scenario-specific deterministic fallback message.
+ *
+ * These preserve the exact semantics of the original hard-coded pointer
+ * templates from call-pointer-messages.ts.
+ */
+export function getPointerFallbackMessage(context: CallPointerMessageContext): string {
+  switch (context.scenario) {
+    case 'started':
+      return context.verificationCode
+        ? `\u{1F4DE} Call to ${context.phoneNumber} started. Verification code: ${context.verificationCode}`
+        : `\u{1F4DE} Call to ${context.phoneNumber} started.`;
+    case 'completed':
+      return context.duration
+        ? `\u{1F4DE} Call to ${context.phoneNumber} completed (${context.duration}).`
+        : `\u{1F4DE} Call to ${context.phoneNumber} completed.`;
+    case 'failed':
+      return context.reason
+        ? `\u{1F4DE} Call to ${context.phoneNumber} failed: ${context.reason}.`
+        : `\u{1F4DE} Call to ${context.phoneNumber} failed.`;
+    case 'guardian_verification_succeeded': {
+      const ch = context.channel ?? 'voice';
+      return `\u{2705} Guardian verification (${ch}) for ${context.phoneNumber} succeeded.`;
+    }
+    case 'guardian_verification_failed': {
+      const ch = context.channel ?? 'voice';
+      return context.reason
+        ? `\u{274C} Guardian verification (${ch}) for ${context.phoneNumber} failed: ${context.reason}.`
+        : `\u{274C} Guardian verification (${ch}) for ${context.phoneNumber} failed.`;
+    }
+    default: {
+      const _exhaustive: never = context.scenario;
+      return `Call status update. ${String(_exhaustive)}`;
+    }
+  }
+}

package/src/calls/call-pointer-messages.ts

@@ -2,47 +2,126 @@
  * Concise pointer/status messages posted to the initiating conversation
  * so the user sees call lifecycle events without the full transcript
  * (which lives in the dedicated voice conversation).
+ *
+ * Trust-aware: trusted audiences receive assistant-generated copy when a
+ * generator is available; untrusted/unknown audiences always receive
+ * deterministic fallback text.
  */
 
 import * as conversationStore from '../memory/conversation-store.js';
+import type { PointerCopyGenerator } from '../runtime/http-types.js';
+import { getLogger } from '../util/logger.js';
+import {
+  type CallPointerMessageContext,
+  composeCallPointerMessageGenerative,
+  getPointerFallbackMessage,
+} from './call-pointer-message-composer.js';
+
+const log = getLogger('call-pointer-messages');
 
 export type PointerEvent = 'started' | 'completed' | 'failed' | 'guardian_verification_succeeded' | 'guardian_verification_failed';
 
+export type PointerAudienceMode = 'auto' | 'trusted' | 'untrusted';
+
+// ---------------------------------------------------------------------------
+// Module-level generator injection (set by daemon lifecycle at startup)
+// ---------------------------------------------------------------------------
+
+let pointerCopyGenerator: PointerCopyGenerator | undefined;
+
+/**
+ * Inject the daemon-provided pointer copy generator.
+ * Called from daemon/lifecycle.ts at startup, following the same pattern
+ * as setRelayBroadcast.
+ */
+export function setPointerCopyGenerator(generator: PointerCopyGenerator): void {
+  pointerCopyGenerator = generator;
+}
+
+/** @internal Reset for tests. */
+export function resetPointerCopyGenerator(): void {
+  pointerCopyGenerator = undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Trust resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve whether the audience for a pointer message is trusted.
+ *
+ * Trusted when:
+ * - conversation threadType is 'private' (local desktop-origin context)
+ * - conversation origin channel is 'vellum' (desktop app)
+ *
+ * Untrusted by default when insufficient evidence.
+ */
+function resolvePointerAudienceTrust(conversationId: string): boolean {
+  try {
+    const threadType = conversationStore.getConversationThreadType(conversationId);
+    if (threadType === 'private') return true;
+
+    const originChannel = conversationStore.getConversationOriginChannel(conversationId);
+    if (originChannel === 'vellum') return true;
+  } catch {
+    // Conversation may not exist or DB may be unavailable — default untrusted.
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
 export async function addPointerMessage(
   conversationId: string,
   event: PointerEvent,
   phoneNumber: string,
   extra?: { duration?: string; reason?: string; verificationCode?: string; channel?: string },
+  audienceMode: PointerAudienceMode = 'auto',
 ): Promise<void> {
+  const context: CallPointerMessageContext = {
+    scenario: event,
+    phoneNumber,
+    duration: extra?.duration,
+    reason: extra?.reason,
+    verificationCode: extra?.verificationCode,
+    channel: extra?.channel,
+  };
+
+  // Build required-facts list so generated text cannot drop key details.
+  const requiredFacts: string[] = [phoneNumber];
+  if (extra?.duration) requiredFacts.push(extra.duration);
+  if (extra?.verificationCode) requiredFacts.push(extra.verificationCode);
+  if (extra?.reason) requiredFacts.push(extra.reason);
+
+  // Enforce lifecycle outcome keywords so the LLM cannot rewrite e.g. a
+  // "failed" event as a success — the generated text must contain the
+  // outcome word verbatim.
+  const eventOutcomeKeywords: Record<PointerEvent, string | undefined> = {
+    started: 'started',
+    completed: 'completed',
+    failed: 'failed',
+    guardian_verification_succeeded: 'succeeded',
+    guardian_verification_failed: 'failed',
+  };
+  const outcomeKeyword = eventOutcomeKeywords[event];
+  if (outcomeKeyword) requiredFacts.push(outcomeKeyword);
+
   let text: string;
-  switch (event) {
-    case 'started':
-      text = extra?.verificationCode
-        ? `\u{1F4DE} Call to ${phoneNumber} started. Verification code: ${extra.verificationCode}`
-        : `\u{1F4DE} Call to ${phoneNumber} started.`;
-      break;
-    case 'completed':
-      text = extra?.duration
-        ? `\u{1F4DE} Call to ${phoneNumber} completed (${extra.duration}).`
-        : `\u{1F4DE} Call to ${phoneNumber} completed.`;
-      break;
-    case 'failed':
-      text = extra?.reason
-        ? `\u{1F4DE} Call to ${phoneNumber} failed: ${extra.reason}.`
-        : `\u{1F4DE} Call to ${phoneNumber} failed.`;
-      break;
-    case 'guardian_verification_succeeded': {
-      const ch = extra?.channel ?? 'voice';
-      text = `\u{2705} Guardian verification (${ch}) for ${phoneNumber} succeeded.`;
-      break;
-    }
-    case 'guardian_verification_failed': {
-      const ch = extra?.channel ?? 'voice';
-      text = extra?.reason
-        ? `\u{274C} Guardian verification (${ch}) for ${phoneNumber} failed: ${extra.reason}.`
-        : `\u{274C} Guardian verification (${ch}) for ${phoneNumber} failed.`;
-      break;
+
+  const isTrusted =
+    audienceMode === 'trusted' ||
+    (audienceMode === 'auto' && resolvePointerAudienceTrust(conversationId));
+
+  if (isTrusted && pointerCopyGenerator) {
+    text = await composeCallPointerMessageGenerative(context, { requiredFacts }, pointerCopyGenerator);
+  } else {
+    if (!isTrusted && pointerCopyGenerator) {
+      log.debug({ event, conversationId }, 'Untrusted audience — using deterministic pointer copy');
     }
+    text = getPointerFallbackMessage(context);
   }
 
   // Pointer messages are assistant-generated status updates in the initiating

package/src/calls/guardian-dispatch.ts

@@ -149,6 +149,7 @@ async function dispatchGuardianQuestionInner(params: GuardianDispatchParams): Pr
     // Route through the canonical notification pipeline. The paired vellum
     // conversation from this pipeline is the canonical guardian thread.
     let vellumDeliveryId: string | null = null;
+    const requestCode = request.requestCode ?? request.id.slice(0, 6).toUpperCase();
     const signalResult = await emitNotificationSignal({
       sourceEventName: 'guardian.question',
       sourceChannel: 'voice',
@@ -163,10 +164,11 @@ async function dispatchGuardianQuestionInner(params: GuardianDispatchParams): Pr
       },
       contextPayload: {
         requestId: request.id,
-        requestCode: request.requestCode,
+        requestKind: 'pending_question',
+        requestCode,
         callSessionId,
+        toolName,
         questionText: pendingQuestion.questionText,
-        pendingQuestionId: pendingQuestion.id,
         activeGuardianRequestCount,
       },
       conversationAffinityHint,