@vellumai/assistant 0.4.3 → 0.4.4

package/src/__tests__/twilio-config.test.ts

@@ -86,25 +86,14 @@ describe('twilio-config', () => {
     expect(config.phoneNumber).toBe('+15558888888');
   });
 
-  test('resolves assistant-scoped phone number when assistantId is provided', () => {
+  test('returns global phone number when assistantPhoneNumbers mapping exists', () => {
     mockLoadConfigResult = {
       sms: {
         phoneNumber: '+15551234567',
         assistantPhoneNumbers: { 'ast-1': '+15557777777' },
       },
     };
-    const config = getTwilioConfig('ast-1');
-    expect(config.phoneNumber).toBe('+15557777777');
-  });
-
-  test('falls back to global phone number when assistant has no dedicated number', () => {
-    mockLoadConfigResult = {
-      sms: {
-        phoneNumber: '+15551234567',
-        assistantPhoneNumbers: { 'ast-1': '+15557777777' },
-      },
-    };
-    const config = getTwilioConfig('ast-unknown');
+    const config = getTwilioConfig();
     expect(config.phoneNumber).toBe('+15551234567');
   });
 });

package/src/agent/loop.ts

@@ -41,7 +41,7 @@ export type AgentEvent =
 
 const DEFAULT_CONFIG: AgentLoopConfig = {
   maxTokens: 16000,
-  maxToolUseTurns: 60,
+  maxToolUseTurns: 0,
   minTurnIntervalMs: 150,
 };
 

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

@@ -53,6 +53,7 @@ import {
   type ActorContext,
   type ChannelDeliveryContext,
   getResolver,
+  type ResolverEmissionContext,
 } from './guardian-request-resolvers.js';
 
 const log = getLogger('guardian-decision-primitive');
@@ -295,10 +296,12 @@ export interface ApplyCanonicalGuardianDecisionParams {
   userText?: string;
   /** Optional channel delivery context — present when the decision arrived via a channel message. */
   channelDeliveryContext?: ChannelDeliveryContext;
+  /** Optional emission context threaded to handleConfirmationResponse for correct source attribution. */
+  emissionContext?: ResolverEmissionContext;
 }
 
 export type CanonicalDecisionResult =
-  | { applied: true; requestId: string; grantMinted: boolean; resolverFailed?: boolean; resolverFailureReason?: string }
+  | { applied: true; requestId: string; grantMinted: boolean; resolverFailed?: boolean; resolverFailureReason?: string; resolverReplyText?: string }
   | { applied: false; reason: 'not_found' | 'already_resolved' | 'identity_mismatch' | 'invalid_action' | 'expired'; detail?: string };
 
 /**
@@ -319,7 +322,7 @@ export type CanonicalDecisionResult =
 export async function applyCanonicalGuardianDecision(
   params: ApplyCanonicalGuardianDecisionParams,
 ): Promise<CanonicalDecisionResult> {
-  const { requestId, action, actorContext, userText, channelDeliveryContext } = params;
+  const { requestId, action, actorContext, userText, channelDeliveryContext, emissionContext } = params;
 
   // 1. Look up the canonical request
   const request = getCanonicalGuardianRequest(requestId);
@@ -427,6 +430,7 @@ export async function applyCanonicalGuardianDecision(
   // 5. Dispatch to kind-specific resolver
   let resolverFailed = false;
   let resolverFailureReason: string | undefined;
+  let resolverReplyText: string | undefined;
   const resolver = getResolver(request.kind);
   if (resolver) {
     const resolverResult = await resolver.resolve({
@@ -434,6 +438,7 @@ export async function applyCanonicalGuardianDecision(
       decision: { action: effectiveAction, userText },
       actor: actorContext,
       channelDeliveryContext,
+      emissionContext,
     });
 
     if (!resolverResult.ok) {
@@ -452,6 +457,8 @@ export async function applyCanonicalGuardianDecision(
       // still being informed that the resolver had an issue.
       resolverFailed = true;
       resolverFailureReason = resolverResult.reason;
+    } else {
+      resolverReplyText = resolverResult.guardianReplyText;
     }
   } else {
     log.info(
@@ -494,5 +501,6 @@ export async function applyCanonicalGuardianDecision(
     requestId,
     grantMinted,
     ...(resolverFailed ? { resolverFailed, resolverFailureReason } : {}),
+    ...(resolverReplyText ? { resolverReplyText } : {}),
   };
 }

package/src/approvals/guardian-request-resolvers.ts

@@ -12,7 +12,8 @@
  */
 
 import { answerCall } from '../calls/call-domain.js';
-import type { CanonicalGuardianRequest } from '../memory/canonical-guardian-store.js';
+import { getGatewayInternalBaseUrl } from '../config/env.js';
+import { type CanonicalGuardianRequest,getCanonicalGuardianRequest } from '../memory/canonical-guardian-store.js';
 import { upsertMember } from '../memory/ingress-member-store.js';
 import { emitNotificationSignal } from '../notifications/emit-signal.js';
 import { addRule } from '../permissions/trust-store.js';
@@ -22,7 +23,9 @@ import { createOutboundSession } from '../runtime/channel-guardian-service.js';
 import { deliverChannelReply } from '../runtime/gateway-client.js';
 import * as pendingInteractions from '../runtime/pending-interactions.js';
 import { getTool } from '../tools/registry.js';
+import { TC_GRANT_WAIT_MAX_MS } from '../tools/tool-approval-handler.js';
 import { getLogger } from '../util/logger.js';
+import { readHttpToken } from '../util/platform.js';
 
 const log = getLogger('guardian-request-resolvers');
 
@@ -64,6 +67,13 @@ export interface ChannelDeliveryContext {
   bearerToken?: string;
 }
 
+/** Emission context threaded from callers to handleConfirmationResponse. */
+export interface ResolverEmissionContext {
+  source?: 'button' | 'inline_nl' | 'auto_deny' | 'timeout' | 'system';
+  causedByRequestId?: string;
+  decisionText?: string;
+}
+
 /** Context passed to each resolver after CAS resolution succeeds. */
 export interface ResolverContext {
   /** The canonical request record (already resolved to its terminal status). */
@@ -74,13 +84,27 @@ export interface ResolverContext {
   actor: ActorContext;
   /** Optional channel delivery context — present when the decision arrived via a channel message. */
   channelDeliveryContext?: ChannelDeliveryContext;
+  /** Optional emission context threaded to handleConfirmationResponse for correct source attribution. */
+  emissionContext?: ResolverEmissionContext;
 }
 
 /** Discriminated result from a resolver. */
 export type ResolverResult =
-  | { ok: true; applied: true; grantMinted?: boolean }
+  | { ok: true; applied: true; grantMinted?: boolean; guardianReplyText?: string }
   | { ok: false; reason: string };
 
+function resolveDeliverCallbackUrlForChannel(channel: string): string | null {
+  switch (channel) {
+    case 'telegram':
+    case 'sms':
+    case 'whatsapp':
+    case 'slack':
+      return `${getGatewayInternalBaseUrl()}/deliver/${channel}`;
+    default:
+      return null;
+  }
+}
+
 /** Interface that kind-specific resolvers implement. */
 export interface GuardianRequestResolver {
   /** The request kind this resolver handles (matches canonical_guardian_requests.kind). */
@@ -139,11 +163,13 @@ const pendingInteractionResolver: GuardianRequestResolver = {
         decision.action === 'approve_always' &&
         details &&
         details.persistentDecisionsAllowed !== false &&
-        details.allowlistOptions?.length &&
-        details.scopeOptions?.length
+        details.allowlistOptions?.length
       ) {
         const pattern = details.allowlistOptions[0].pattern;
-        const scope = details.scopeOptions[0].scope;
+        // Non-scoped tools (web_fetch, network_request, etc.) have empty
+        // scopeOptions — default to 'everywhere' so approve_always still
+        // persists a trust rule instead of silently degrading to one-time.
+        const scope = details.scopeOptions?.length ? details.scopeOptions[0].scope : 'everywhere';
         const tool = getTool(details.toolName);
         const executionTarget = tool?.origin === 'skill' ? details.executionTarget : undefined;
         addRule(details.toolName, pattern, scope, 'allow', 100, { executionTarget });
@@ -166,7 +192,7 @@ const pendingInteractionResolver: GuardianRequestResolver = {
 
     // Map action to the permission system's UserDecision type and notify session.
     const userDecision = decision.action === 'reject' ? 'deny' as const : 'allow' as const;
-    resolved.session.handleConfirmationResponse(request.id, userDecision);
+    resolved.session.handleConfirmationResponse(request.id, userDecision, undefined, undefined, undefined, ctx.emissionContext);
 
     log.info(
       {
@@ -283,8 +309,11 @@ const accessRequestResolver: GuardianRequestResolver = {
     const channel = request.sourceChannel ?? 'unknown';
     const requesterExternalUserId = request.requesterExternalUserId ?? '';
     const requesterChatId = request.requesterChatId ?? request.requesterExternalUserId ?? '';
+    const requesterLabel = requesterExternalUserId || requesterChatId || 'the requester';
     const decidedByExternalUserId = ctx.actor.externalUserId ?? '';
     const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
+    const desktopDeliverUrl = resolveDeliverCallbackUrlForChannel(channel);
+    const desktopBearerToken = readHttpToken() ?? undefined;
 
     if (decision.action === 'reject') {
       log.info(
@@ -341,9 +370,23 @@ const accessRequestResolver: GuardianRequestResolver = {
           contextPayload: deniedPayload,
           dedupeKey: `trusted-contact:denied:${request.id}`,
         });
+      } else if (desktopDeliverUrl && requesterChatId) {
+        try {
+          await deliverChannelReply(desktopDeliverUrl, {
+            chatId: requesterChatId,
+            text: 'Your access request has been denied by the guardian.',
+            assistantId,
+          }, desktopBearerToken);
+        } catch (err) {
+          log.error({ err, requesterChatId }, 'Failed to notify requester of access request denial (desktop decision path)');
+        }
       }
 
-      return { ok: true, applied: true };
+      return {
+        ok: true,
+        applied: true,
+        ...(ctx.actor.isTrusted ? { guardianReplyText: `Access denied for ${requesterLabel}.` } : {}),
+      };
     }
 
     // Voice approvals: directly activate the trusted contact without minting
@@ -404,6 +447,7 @@ const accessRequestResolver: GuardianRequestResolver = {
 
     // Deliver the verification code to the guardian and notify the requester
     // when channel delivery context is available (channel message path).
+    let requesterNotified = false;
     if (channelDeliveryContext) {
       let codeDelivered = true;
 
@@ -434,6 +478,7 @@ const accessRequestResolver: GuardianRequestResolver = {
               + 'Please enter the 6-digit verification code you receive from the guardian.',
             assistantId,
           }, channelDeliveryContext.bearerToken);
+          requesterNotified = true;
         } catch (err) {
           log.error({ err, requesterChatId }, 'Failed to notify requester of access request approval');
         }
@@ -473,9 +518,29 @@ const accessRequestResolver: GuardianRequestResolver = {
           dedupeKey: `trusted-contact:verification-sent:${session.sessionId}`,
         });
       }
+    } else if (desktopDeliverUrl && requesterChatId) {
+      try {
+        await deliverChannelReply(desktopDeliverUrl, {
+          chatId: requesterChatId,
+          text: 'Your access request has been approved! '
+            + 'Please enter the 6-digit verification code you receive from the guardian.',
+          assistantId,
+        }, desktopBearerToken);
+        requesterNotified = true;
+      } catch (err) {
+        log.error({ err, requesterChatId }, 'Failed to notify requester of access request approval (desktop decision path)');
+      }
     }
 
-    return { ok: true, applied: true };
+    const verificationReplyText = requesterNotified
+      ? `Access approved for ${requesterLabel}. Give them this verification code: ${session.secret}. The code expires in 10 minutes.`
+      : `Access approved for ${requesterLabel}. Give them this verification code: ${session.secret}. The code expires in 10 minutes. I could not notify them automatically, so please tell them to send the code manually.`;
+
+    return {
+      ok: true,
+      applied: true,
+      ...(ctx.actor.isTrusted ? { guardianReplyText: verificationReplyText } : {}),
+    };
   },
 };
 
@@ -534,7 +599,61 @@ const toolGrantRequestResolver: GuardianRequestResolver = {
       'Tool grant request resolver: approved (grant minting deferred to canonical primitive)',
     );
 
-    if (channelDeliveryContext && requesterChatId) {
+    // Re-read the canonical request to check whether an inline grant waiter
+    // has already claimed this request. When followupState is
+    // 'inline_wait_active', the requester's original tool call is blocking
+    // on the grant and will resume automatically — sending a "please retry"
+    // notification would be stale and confusing (and could cause duplicate
+    // attempts or one-time-grant denials).
+    //
+    // Staleness guard: the inline_wait_active marker is persisted in DB and
+    // can outlive the actual waiter if the daemon crashes or restarts during
+    // the wait. To avoid permanently suppressing the retry notification, we
+    // treat the marker as stale if the encoded start timestamp is older than
+    // the maximum wait budget plus a 30s buffer.
+    const INLINE_WAIT_STALENESS_BUFFER_MS = 30_000;
+    const freshRequest = getCanonicalGuardianRequest(request.id);
+    const followupState = freshRequest?.followupState ?? '';
+    let inlineWaitActive = followupState.startsWith('inline_wait_active');
+    if (inlineWaitActive && freshRequest) {
+      // The followupState encodes the wall-clock epoch when the inline wait
+      // started (e.g. 'inline_wait_active:1700000000000'). We use this
+      // instead of updatedAt because resolveCanonicalGuardianRequest sets
+      // updatedAt = now during CAS resolution, making updatedAt always fresh
+      // by the time this resolver runs.
+      const colonIdx = followupState.indexOf(':');
+      const waitStartMs = colonIdx !== -1 ? Number(followupState.slice(colonIdx + 1)) : NaN;
+      const markerAgeMs = Number.isFinite(waitStartMs)
+        ? Date.now() - waitStartMs
+        : Infinity; // Treat unparseable timestamps as stale for safety.
+      const stalenessThresholdMs = TC_GRANT_WAIT_MAX_MS + INLINE_WAIT_STALENESS_BUFFER_MS;
+      if (markerAgeMs > stalenessThresholdMs) {
+        log.warn(
+          {
+            event: 'resolver_tool_grant_request_stale_inline_wait',
+            requestId: request.id,
+            toolName: request.toolName,
+            markerAgeMs,
+            stalenessThresholdMs,
+            waitStartMs,
+          },
+          'inline_wait_active marker is stale (daemon likely crashed during wait) — sending retry notification',
+        );
+        inlineWaitActive = false;
+      }
+    }
+
+    if (inlineWaitActive) {
+      log.info(
+        {
+          event: 'resolver_tool_grant_request_skip_retry_notification',
+          requestId: request.id,
+          toolName: request.toolName,
+          followupState: freshRequest?.followupState,
+        },
+        'Skipping requester retry notification — inline grant wait is active and will resume the original invocation',
+      );
+    } else if (channelDeliveryContext && requesterChatId) {
       try {
         await deliverChannelReply(channelDeliveryContext.replyCallbackUrl, {
           chatId: requesterChatId,

package/src/calls/call-constants.ts

@@ -49,6 +49,27 @@ export function getAccessRequestPollIntervalMs(): number {
   return getConfig().calls.accessRequestPollIntervalMs;
 }
 
+export function getGuardianWaitUpdateInitialIntervalMs(): number {
+  return getConfig().calls.guardianWaitUpdateInitialIntervalMs;
+}
+
+export function getGuardianWaitUpdateInitialWindowMs(): number {
+  return getConfig().calls.guardianWaitUpdateInitialWindowMs;
+}
+
+export function getGuardianWaitUpdateSteadyMinIntervalMs(): number {
+  return getConfig().calls.guardianWaitUpdateSteadyMinIntervalMs;
+}
+
+export function getGuardianWaitUpdateSteadyMaxIntervalMs(): number {
+  return getConfig().calls.guardianWaitUpdateSteadyMaxIntervalMs;
+}
+
+export function getSilenceTimeoutMs(): number {
+  return 30 * 1000; // 30 seconds
+}
+
+/** @deprecated Use getSilenceTimeoutMs() for mockability in tests. */
 export const SILENCE_TIMEOUT_MS = 30 * 1000; // 30 seconds
 
 // Legacy named exports for backward compatibility (use functions above for config-backed values)

package/src/calls/call-controller.ts

@@ -22,7 +22,7 @@ import { DAEMON_INTERNAL_ASSISTANT_ID } from '../runtime/assistant-scope.js';
 import { computeToolApprovalDigest } from '../security/tool-approval-digest.js';
 import { getLogger } from '../util/logger.js';
 import { readHttpToken } from '../util/platform.js';
-import { getMaxCallDurationMs, getUserConsultationTimeoutMs, SILENCE_TIMEOUT_MS } from './call-constants.js';
+import { getMaxCallDurationMs, getSilenceTimeoutMs, getUserConsultationTimeoutMs } from './call-constants.js';
 import { persistCallCompletionMessage } from './call-conversation-messages.js';
 import { addPointerMessage, formatDuration } from './call-pointer-messages.js';
 import { fireCallCompletionNotifier, fireCallQuestionNotifier, fireCallTranscriptNotifier,registerCallController, unregisterCallController } from './call-state.js';
@@ -1049,8 +1049,15 @@ export class CallController {
   private resetSilenceTimer(): void {
     if (this.silenceTimer) clearTimeout(this.silenceTimer);
     this.silenceTimer = setTimeout(() => {
+      // During guardian wait states, the relay heartbeat timer handles
+      // periodic updates — suppress the generic "Are you still there?"
+      // which is confusing when the caller is waiting on a decision.
+      if (this.relay.getConnectionState() === 'awaiting_guardian_decision') {
+        log.debug({ callSessionId: this.callSessionId }, 'Silence timeout suppressed during guardian wait');
+        return;
+      }
       log.info({ callSessionId: this.callSessionId }, 'Silence timeout triggered');
       this.relay.sendTextToken('Are you still there?', true);
-    }, SILENCE_TIMEOUT_MS);
+    }, getSilenceTimeoutMs());
   }
 }

package/src/calls/call-domain.ts

@@ -9,6 +9,7 @@ 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';
@@ -101,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.
@@ -134,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 };
   }
 
@@ -358,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 });
@@ -687,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)}`;
+    }
+  }
+}