@vellumai/assistant 0.3.5 → 0.3.7

package/src/config/bundled-skills/media-processing/tools/query-media-events.ts

@@ -1,178 +1,20 @@
 /**
- * Natural language query tool for media events.
+ * Query media tool — sends natural language queries against video
+ * analysis data (map output) via Claude for intelligent answers.
  *
- * Accepts a free-text query and optional asset_id, parses the query into
- * structured filters via simple keyword matching, then delegates to the
- * generic retrieval service. Domain-specific keyword mappings live here;
- * the retrieval layer remains fully generic.
+ * Replaces the old keyword-matching approach with an LLM-powered
+ * reduce/query step that can answer arbitrary questions about the
+ * video content.
  */
 
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
-import { retrieveEvents, type RetrievalFilters } from '../services/retrieval-service.js';
-import { getTrackingProfile, type CapabilityTier } from '../../../../memory/media-store.js';
-import { getCapabilitiesByTier, getCapabilityByName } from '../services/capability-registry.js';
+import { reduceForAsset, type ReduceOptions, type ReduceResult } from '../services/reduce.js';
 
 // ---------------------------------------------------------------------------
-// NL query parsing
+// Exported function for job handler use (one-shot merge mode)
 // ---------------------------------------------------------------------------
 
-/** Maps domain-specific keywords to canonical event type labels. */
-const EVENT_TYPE_KEYWORDS: Record<string, string> = {
-  // Basketball
-  turnover: 'turnover',
-  turnovers: 'turnover',
-  steal: 'turnover',
-  steals: 'turnover',
-  // Soccer / football
-  goal: 'goal',
-  goals: 'goal',
-  score: 'goal',
-  scores: 'goal',
-  // Generic
-  highlight: 'highlight',
-  highlights: 'highlight',
-  scene_change: 'scene_change',
-  'scene change': 'scene_change',
-  'scene changes': 'scene_change',
-  foul: 'foul',
-  fouls: 'foul',
-  shot: 'shot',
-  shots: 'shot',
-  rebound: 'rebound',
-  rebounds: 'rebound',
-  assist: 'assist',
-  assists: 'assist',
-  block: 'block',
-  blocks: 'block',
-  transition: 'transition',
-  transitions: 'transition',
-  fast_break: 'fast_break',
-  'fast break': 'fast_break',
-  'fast breaks': 'fast_break',
-};
-
-/**
- * Extract a numeric limit from phrases like "top 5", "first 3", "last 10".
- * Returns undefined if no limit phrase is found.
- */
-function parseLimit(query: string): number | undefined {
-  const match = query.match(/(?:top|first|last|show|find|get)\s+(\d+)(?!\s*min)/i);
-  if (match) return parseInt(match[1], 10);
-  // Also match trailing "N events/moments"
-  const trailingMatch = query.match(/(\d+)\s+(?:events?|moments?|plays?|clips?)/i);
-  if (trailingMatch) return parseInt(trailingMatch[1], 10);
-  return undefined;
-}
-
-/**
- * Extract a confidence threshold from the query.
- */
-function parseConfidence(query: string): number | undefined {
-  const lower = query.toLowerCase();
-  if (lower.includes('high confidence') || lower.includes('very confident') || lower.includes('most confident')) {
-    return 0.8;
-  }
-  if (lower.includes('confident') || lower.includes('medium confidence')) {
-    return 0.5;
-  }
-  // Explicit threshold: "confidence > 0.7" or "confidence above 0.7"
-  const explicitMatch = lower.match(/confidence\s*(?:>|above|over|>=)\s*([\d.]+)/);
-  if (explicitMatch) return parseFloat(explicitMatch[1]);
-  return undefined;
-}
-
-/**
- * Extract a time range from the query (returns seconds).
- * Supports phrases like "first half", "second half", "first N minutes",
- * "last N minutes", "between M and N minutes".
- */
-function parseTimeRange(query: string): { startTimeMin?: number; startTimeMax?: number } {
-  const lower = query.toLowerCase();
-
-  // "first half" / "second half" — these are relative and require knowing
-  // total duration, which we don't have. Use reasonable game defaults:
-  // assume ~48 min game → 2880s, half = 1440s
-  if (lower.includes('first half')) {
-    return { startTimeMin: 0, startTimeMax: 1440 };
-  }
-  if (lower.includes('second half')) {
-    return { startTimeMin: 1440 };
-  }
-
-  // "first N minutes"
-  const firstNMin = lower.match(/first\s+(\d+)\s*min/);
-  if (firstNMin) {
-    return { startTimeMin: 0, startTimeMax: parseInt(firstNMin[1], 10) * 60 };
-  }
-
-  // "last N minutes"
-  // Without knowing total duration we can't compute this precisely,
-  // so we skip it and let the retrieval return all results.
-
-  // "between M and N minutes"
-  const betweenMatch = lower.match(/between\s+(\d+)\s*(?:and|to|-)\s*(\d+)\s*min/);
-  if (betweenMatch) {
-    return {
-      startTimeMin: parseInt(betweenMatch[1], 10) * 60,
-      startTimeMax: parseInt(betweenMatch[2], 10) * 60,
-    };
-  }
-
-  return {};
-}
-
-/**
- * Extract the event type from the query by matching known keywords.
- */
-function parseEventType(query: string): string | undefined {
-  const lower = query.toLowerCase();
-
-  // Check multi-word keywords first (longer matches win)
-  const multiWordKeys = Object.keys(EVENT_TYPE_KEYWORDS)
-    .filter((k) => k.includes(' ') || k.includes('_'))
-    .sort((a, b) => b.length - a.length);
-
-  for (const key of multiWordKeys) {
-    if (lower.includes(key)) return EVENT_TYPE_KEYWORDS[key];
-  }
-
-  // Check single-word keywords
-  const words = lower.replace(/[^\w\s]/g, '').split(/\s+/);
-  for (const word of words) {
-    if (EVENT_TYPE_KEYWORDS[word]) return EVENT_TYPE_KEYWORDS[word];
-  }
-
-  return undefined;
-}
-
-/**
- * Parse a natural language query into structured retrieval filters.
- */
-function parseQuery(query: string, assetId?: string): RetrievalFilters {
-  const eventType = parseEventType(query);
-  const limit = parseLimit(query);
-  const minConfidence = parseConfidence(query);
-  const timeRange = parseTimeRange(query);
-
-  return {
-    assetId,
-    eventType,
-    minConfidence,
-    limit: limit ?? 10,
-    sortBy: 'confidence',
-    ...timeRange,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Formatting
-// ---------------------------------------------------------------------------
-
-function formatTimestamp(seconds: number): string {
-  const mins = Math.floor(seconds / 60);
-  const secs = Math.floor(seconds % 60);
-  return `${mins}:${secs.toString().padStart(2, '0')}`;
-}
+export { reduceForAsset } from '../services/reduce.js';
 
 // ---------------------------------------------------------------------------
 // Tool entry point
@@ -180,121 +22,44 @@ function formatTimestamp(seconds: number): string {
 
 export async function run(
   input: Record<string, unknown>,
-  _context: ToolContext,
+  context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const query = input.query as string | undefined;
-  if (!query) {
-    return { content: 'query is required.', isError: true };
-  }
-
   const assetId = input.asset_id as string | undefined;
   if (!assetId) {
-    return { content: 'asset_id is required to scope the query to a specific media asset.', isError: true };
+    return { content: 'asset_id is required.', isError: true };
   }
 
-  const filters = parseQuery(query, assetId);
-
-  // Retrieve without limit so we can apply capability filtering first, then limit
-  const userLimit = filters.limit;
-  const result = retrieveEvents({ ...filters, limit: 0 });
-
-  // Determine which capabilities are allowed based on the tracking profile
-  const profile = getTrackingProfile(assetId);
-
-  let allowedEventTypes: Set<string> | null = null;
-  const tierForEventType = new Map<string, CapabilityTier>();
-
-  if (profile) {
-    // Use the explicit profile: only enabled capabilities pass
-    allowedEventTypes = new Set<string>();
-    for (const [capName, entry] of Object.entries(profile.capabilities)) {
-      if (entry.enabled) {
-        allowedEventTypes.add(capName);
-        tierForEventType.set(capName, entry.tier);
-      }
-    }
-  } else {
-    // No profile: default to 'ready' tier capabilities only
-    const readyCaps = getCapabilitiesByTier('ready');
-    if (readyCaps.length > 0) {
-      allowedEventTypes = new Set(readyCaps.map((c) => c.name));
-      for (const cap of readyCaps) {
-        tierForEventType.set(cap.name, 'ready');
-      }
-    }
-    // If no capabilities are registered at all, allow everything (pass null)
-  }
-
-  // Filter events by allowed capabilities, then apply the user-requested limit
-  let filteredEvents = result.events;
-  if (allowedEventTypes !== null) {
-    filteredEvents = filteredEvents.filter((e) => allowedEventTypes!.has(e.eventType));
-  }
-  if (userLimit && filteredEvents.length > userLimit) {
-    filteredEvents = filteredEvents.slice(0, userLimit);
-  }
-
-  if (filteredEvents.length === 0) {
-    const parts = ['No matching events found'];
-    if (filters.eventType) parts.push(`for event type "${filters.eventType}"`);
-    if (filters.minConfidence) parts.push(`with confidence >= ${filters.minConfidence}`);
-    if (!profile) parts.push('(defaulting to ready-tier capabilities only)');
-    parts.push(`in asset ${assetId}.`);
-    return { content: parts.join(' '), isError: false };
+  const query = input.query as string | undefined;
+  if (!query) {
+    return { content: 'query is required.', isError: true };
   }
 
-  const tierLabels: Record<string, string> = {
-    ready: '[Ready]',
-    beta: '[Beta]',
-    experimental: '[Experimental]',
-  };
+  const systemPrompt = input.system_prompt as string | undefined;
+  const model = input.model as string | undefined;
 
-  const tierDisclaimers: Record<string, string> = {
-    beta: 'Beta results may have accuracy gaps.',
-    experimental: 'Experimental results are early-stage; expect noise.',
+  const options: ReduceOptions = {
+    query,
+    systemPrompt,
+    model,
   };
 
-  const eventSummaries = filteredEvents.map((e, i) => {
-    const tier = tierForEventType.get(e.eventType) ?? getCapabilityByName(e.eventType)?.tier;
-    const tierLabel = tier ? tierLabels[tier] ?? `[${tier}]` : '[Ready]';
-    const disclaimer = tier ? tierDisclaimers[tier] : undefined;
+  try {
+    const result: ReduceResult = await reduceForAsset(assetId, options, context.onOutput);
 
     return {
-      rank: i + 1,
-      id: e.id,
-      eventType: e.eventType,
-      tierLabel,
-      ...(disclaimer ? { confidenceDisclaimer: disclaimer } : {}),
-      timeRange: `${formatTimestamp(e.startTime)} – ${formatTimestamp(e.endTime)}`,
-      startTime: e.startTime,
-      endTime: e.endTime,
-      confidence: Math.round(e.confidence * 100) / 100,
-      reasons: e.reasons,
-      metadata: e.metadata,
+      content: JSON.stringify({
+        query,
+        answer: result.answer,
+        model: result.model,
+        usage: {
+          inputTokens: result.inputTokens,
+          outputTokens: result.outputTokens,
+        },
+      }, null, 2),
+      isError: false,
     };
-  });
-
-  // Collect disclaimers for any non-ready tiers present in results
-  const activeTiers = new Set(eventSummaries.map((e) => e.tierLabel));
-  const disclaimers: string[] = [];
-  if (activeTiers.has('[Beta]')) disclaimers.push(tierDisclaimers.beta);
-  if (activeTiers.has('[Experimental]')) disclaimers.push(tierDisclaimers.experimental);
-
-  return {
-    content: JSON.stringify({
-      query,
-      parsedFilters: {
-        eventType: filters.eventType ?? null,
-        minConfidence: filters.minConfidence ?? null,
-        limit: filters.limit,
-        startTimeMin: filters.startTimeMin ?? null,
-        startTimeMax: filters.startTimeMax ?? null,
-      },
-      trackingProfile: profile ? 'custom' : 'default (ready tier only)',
-      ...(disclaimers.length > 0 ? { disclaimers } : {}),
-      totalResults: eventSummaries.length,
-      events: eventSummaries,
-    }, null, 2),
-    isError: false,
-  };
+  } catch (err) {
+    const msg = (err as Error).message;
+    return { content: msg, isError: true };
+  }
 }

package/src/config/bundled-skills/messaging/SKILL.md

@@ -20,7 +20,12 @@ Gmail, Slack, and Telegram setup all require a publicly reachable URL for OAuth
 2. **If it fails because no client_id is found:** The user needs to create Google Cloud OAuth credentials first. Install and load the **google-oauth-setup** skill (which depends on **public-ingress** for the redirect URI):
    - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "google-oauth-setup"`.
    - Then call `skill_load` with `skill: "google-oauth-setup"`.
-   - Tell the user: *"Gmail isn't connected yet. I've loaded a setup guide that will walk you through creating Google credentials and connecting your account."*
+   - Tell the user Gmail isn't connected yet and briefly explain what the setup involves, then use `ui_show` with `surface_type: "confirmation"` to ask for permission to start:
+     - **message:** "Ready to set up Gmail?"
+     - **detail:** "I'll open a browser where you sign in to Google, then automate everything else — creating a project, enabling APIs, and connecting your account. Takes 2-3 minutes and you can watch in the browser preview panel."
+     - **confirmLabel:** "Get Started"
+     - **cancelLabel:** "Not Now"
+   - If the user confirms, briefly acknowledge (e.g., "Setting up Gmail now...") and proceed with the setup guide. If they decline, acknowledge and let them know they can set it up later.
 3. **If the user provides a client_id directly in chat:** Call `credential_store` with `action: "oauth2_connect"`, `service: "gmail"`, and `client_id: "<their value>"`. Include `client_secret` too if they provide one. Everything else is auto-filled.
 
 ### Slack
@@ -28,7 +33,12 @@ Gmail, Slack, and Telegram setup all require a publicly reachable URL for OAuth
 2. **If it fails because no client_id is found:** The user needs to create a Slack App first. Install and load the **slack-oauth-setup** skill (which depends on **public-ingress** for the redirect URI):
    - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "slack-oauth-setup"`.
    - Then call `skill_load` with `skill: "slack-oauth-setup"`.
-   - Tell the user: *"Slack isn't connected yet. I've loaded a setup guide that will walk you through creating a Slack App and connecting your workspace."*
+   - Tell the user Slack isn't connected yet and briefly explain what the setup involves, then use `ui_show` with `surface_type: "confirmation"` to ask for permission to start:
+     - **message:** "Ready to set up Slack?"
+     - **detail:** "I'll walk you through creating a Slack App and connecting your workspace. The process takes a few minutes, and I'll ask for your approval before each step."
+     - **confirmLabel:** "Get Started"
+     - **cancelLabel:** "Not Now"
+   - Wait for the user to confirm before proceeding with the setup guide. If they decline, acknowledge and let them know they can set it up later.
 3. **If the user provides client_id and client_secret directly in chat:** Call `credential_store` with `action: "oauth2_connect"`, `service: "slack"`, `client_id`, and `client_secret`. Everything else is auto-filled. Note: Slack always requires a client_secret.
 
 ### Telegram

package/src/config/bundled-skills/messaging/tools/messaging-analyze-style.ts

@@ -7,12 +7,9 @@ import { memoryItems } from '../../../../memory/schema.js';
 import { enqueueMemoryJob } from '../../../../memory/jobs-store.js';
 import { extractStylePatterns } from '../../../../messaging/style-analyzer.js';
 import { truncate } from '../../../../util/truncate.js';
+import { clampUnitInterval } from '../../../../memory/validation.js';
 import { resolveProvider, withProviderToken, ok, err } from './shared.js';
 
-function clamp(value: number, min: number, max: number): number {
-  return Math.min(max, Math.max(min, value));
-}
-
 function upsertMemoryItem(opts: {
   kind: string;
   subject: string;
@@ -35,7 +32,7 @@ function upsertMemoryItem(opts: {
       .set({
         statement: opts.statement,
         status: 'active',
-        importance: Math.max(existing.importance ?? 0, opts.importance),
+        importance: clampUnitInterval(Math.max(existing.importance ?? 0, opts.importance)),
         lastSeenAt: now,
         verificationState: 'assistant_inferred',
       })
@@ -51,7 +48,7 @@ function upsertMemoryItem(opts: {
       statement: opts.statement,
       status: 'active',
       confidence: 0.8,
-      importance: opts.importance,
+      importance: clampUnitInterval(opts.importance),
       fingerprint,
       verificationState: 'assistant_inferred',
       scopeId: opts.scopeId,
@@ -90,7 +87,7 @@ export async function run(input: Record<string, unknown>, context: ToolContext):
 
       for (const pattern of result.stylePatterns) {
         const subject = `${provider.id} writing style: ${pattern.aspect}`;
-        const importance = clamp(pattern.importance ?? 0.65, 0.55, 0.85);
+        const importance = clampUnitInterval(Math.min(0.85, Math.max(0.55, pattern.importance ?? 0.65)));
         upsertMemoryItem({ kind: 'style', subject, statement: pattern.summary, importance, scopeId });
         savedCount++;
       }

package/src/config/bundled-skills/messaging/tools/messaging-reply.ts

@@ -1,7 +1,7 @@
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
 import { resolveProvider, withProviderToken, ok, err } from './shared.js';
 
-export async function run(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+export async function run(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
   const platform = input.platform as string | undefined;
   const conversationId = input.conversation_id as string;
   const threadId = input.thread_id as string;
@@ -22,6 +22,7 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
     return withProviderToken(provider, async (token) => {
       const result = await provider.sendMessage(token, conversationId, text, {
         threadId,
+        assistantId: context.assistantId,
       });
 
       return ok(`Reply sent (ID: ${result.id}).`);

package/src/config/bundled-skills/phone-calls/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: "Phone Calls"
-description: "Set up Twilio for outgoing phone calls and place AI-powered voice calls on behalf of the user"
+description: "Set up Twilio for AI-powered voice calls — both outgoing calls on behalf of the user and incoming calls where the assistant answers as a receptionist"
 user-invocable: true
 metadata: {"vellum": {"emoji": "📞", "requires": {"config": ["calls.enabled"]}}}
 includes: ["public-ingress"]
 ---
 
-You are helping the user set up and make outgoing phone calls via Twilio. This skill covers the full lifecycle: Twilio account setup, credential storage, public ingress configuration, enabling the calls feature, placing calls, and monitoring live transcripts.
+You are helping the user set up and manage phone calls via Twilio. This skill covers the full lifecycle: Twilio account setup, credential storage, public ingress configuration, enabling the calls feature, placing outbound calls, receiving inbound calls, and monitoring live transcripts.
 
 ## Prerequisites — Shared Twilio Setup
 
@@ -21,7 +21,9 @@ If Twilio is already configured (check `twilio_config` with `action: "get"`), sk
 
 ## Overview
 
-The calling system uses Twilio's ConversationRelay to place outbound phone calls. Twilio works out of the box as the default voice provider. Optionally, you can enable ElevenLabs integration for higher-quality, more natural-sounding voices — but this is entirely optional.
+The calling system uses Twilio's ConversationRelay for both **outbound** and **inbound** voice calls. Twilio works out of the box as the default voice provider. Optionally, you can enable ElevenLabs integration for higher-quality, more natural-sounding voices — but this is entirely optional.
+
+### Outbound calls
 
 When a call is placed:
 
@@ -31,6 +33,17 @@ When a call is placed:
 4. An LLM-driven orchestrator manages the conversation — receiving caller speech (transcribed by Deepgram), generating responses via Claude, and streaming text back for TTS playback
 5. The transcript is relayed live to the user's conversation thread
 
+### Inbound calls
+
+When someone dials the assistant's Twilio phone number:
+
+1. Twilio sends a voice webhook to the gateway at `/webhooks/twilio/voice` (no `callSessionId` in the URL)
+2. The gateway resolves which assistant owns the dialed number via `resolveAssistantByPhoneNumber`, falling back to the standard routing chain (chat_id, user_id, default/reject). Unmapped numbers are rejected with TwiML `<Reject>`.
+3. The runtime creates a new session keyed by the Twilio CallSid (`createInboundVoiceSession`)
+4. Twilio opens a ConversationRelay WebSocket. The relay detects the call is inbound when `initiatedFromConversationId == null` and optionally gates the call behind **guardian voice verification** if a pending challenge exists.
+5. Once verified (or if no challenge is pending), the LLM orchestrator greets the caller in a receptionist style: "Hello, this is [user]'s assistant. How can I help you today?"
+6. The assistant converses naturally, using ASK_GUARDIAN to consult the user when needed, just like outbound calls.
+
 Three voice quality modes are available:
 - **`twilio_standard`** (default) — Fully supported. Standard Twilio TTS with Google voices. No extra setup required.
 - **`twilio_elevenlabs_tts`** — Fully supported. Uses ElevenLabs voices through Twilio ConversationRelay for more natural speech.
@@ -181,6 +194,25 @@ credential_store action=store service=twilio field=user_phone_number value=+1415
 | `calls.callerIdentity.allowPerCallOverride` | Whether per-call mode selection is allowed | `true` |
 | `calls.callerIdentity.userNumber` | Optional E.164 phone number for user-number mode (alternative to storing via `credential_store`) | *(empty)* |
 
+## DTMF Callee Verification
+
+An optional verification step where the callee must enter a numeric code via their phone's keypad (DTMF tones) before the call proceeds. This ensures the intended person has answered the phone.
+
+### How it works
+
+1. When the call connects and DTMF verification is enabled, a random numeric code is generated (length configured by `calls.verification.codeLength`).
+2. The verification code is shared with the guardian in the initiating conversation so they know what code was issued.
+3. The AI voice agent speaks the code digit-by-digit to the callee and asks them to enter it on their keypad.
+4. The callee enters the code via DTMF (phone keypad tones).
+5. If the code matches, the call proceeds normally. If the code is incorrect, the agent may re-prompt or end the call depending on configuration.
+
+### Configuration
+
+| Setting | Description | Default |
+|---|---|---|
+| `calls.verification.enabled` | Enable DTMF callee verification | `false` |
+| `calls.verification.codeLength` | Number of digits in the verification code | `6` |
+
 ## Optional: Higher Quality Voice with ElevenLabs
 
 ElevenLabs integration is entirely optional. The standard Twilio-only setup works unchanged — this section is only relevant if you want to improve voice quality.
@@ -264,7 +296,7 @@ To go back to the default voice at any time:
 vellum config set calls.voice.mode twilio_standard
 ```
 
-## Making Calls
+## Making Outbound Calls
 
 Use the `call_start` tool to place outbound calls. Every call requires:
 - **phone_number**: The number to call in E.164 format (e.g. `+14155551234`)
@@ -319,6 +351,30 @@ On Twilio trial accounts, outbound calls can ONLY be made to **verified numbers*
 1. Tell the user they need to verify the number at https://console.twilio.com/us1/develop/phone-numbers/manage/verified
 2. Or upgrade to a paid Twilio account to call any number
 
+## Receiving Inbound Calls
+
+Once Twilio is configured and the assistant has a phone number, inbound calls work automatically. When someone dials the assistant's number:
+
+1. The gateway resolves the assistant by phone number and forwards to the runtime
+2. A new voice session is created, keyed by the Twilio CallSid
+3. The LLM-driven orchestrator answers in receptionist mode — greeting the caller warmly and asking how it can help
+4. The conversation proceeds naturally, with ASK_GUARDIAN dispatches to consult the user when needed
+
+No additional configuration is needed beyond the standard Twilio setup (Steps 1-5 above). As long as `calls.enabled` is `true` and the phone number has been provisioned/assigned, inbound calls are handled automatically.
+
+### Guardian voice verification for inbound calls
+
+Optionally, the user can require callers to verify themselves by entering a six-digit code before the call proceeds. This is managed through the **channel guardian verification** system:
+
+1. The user initiates a verification challenge from the desktop UI for the `voice` channel
+2. A six-digit code is generated and shown to the user
+3. When the next inbound call arrives, the relay server detects the pending challenge and prompts the caller: "Please enter your six-digit verification code using your keypad, or speak the digits now."
+4. The caller enters the code via DTMF (keypad) or by speaking the digits
+5. If the code matches, a guardian binding is created and the call proceeds normally
+6. If verification fails after 3 attempts, the call ends with "Verification failed. Goodbye."
+
+This feature is separate from the outbound DTMF callee verification. It uses the `ChannelGuardianService` challenge system rather than the per-call verification config.
+
 ## Live Call Monitoring
 
 ### Showing the live transcript
@@ -343,37 +399,31 @@ By default, always show the live transcript of the call as it happens. When a ca
 
 ### Interacting with a live call
 
-During an active call, the user can type messages in the chat thread to interact with the AI voice agent in real time. Messages are automatically routed to the call via the call bridge, which decides how to handle them based on the call's current state:
-
-#### Mode 1: Answering questions
+During an active call, the user can interact with the AI voice agent via the HTTP API endpoints:
 
-When the AI voice agent encounters something it needs user input for, a **pending question** appears in the chat. The call status changes to `waiting_on_user`.
+#### Answering questions
 
-1. A **pending question** appears in `call_status` output
-2. Present the question prominently to the user:
+When the AI voice agent encounters something it needs user input for, it dispatches an **ASK_GUARDIAN** request to all configured guardian channels (mac desktop, Telegram, SMS). The call status changes to `waiting_on_user`.
 
-```
-❓ The person on the call asked something the assistant needs your help with:
-   "They're asking if you'd prefer the smoking or non-smoking section?"
-```
-
-3. The user replies directly in the chat — since there is a pending question, the reply is automatically routed as an **answer** to the AI voice agent
-4. The AI voice agent receives the answer and continues the conversation naturally
+1. The question is delivered simultaneously to every configured channel. The first channel to respond wins (first-response-wins semantics) -- once one channel provides an answer, the other channels receive a "already answered" notice.
+2. On the mac desktop, a guardian request thread is created with the question. On Telegram/SMS, the question text and a request code are delivered via the gateway.
+3. If DTMF callee verification is enabled, the callee must enter a verification code before the call proceeds (see the **DTMF Callee Verification** section above).
+4. The guardian provides an answer through whichever channel they prefer. The answer is routed to the AI voice agent, which continues the conversation naturally.
 
 **Important:** Respond to pending questions quickly. There is a consultation timeout (default: 2 minutes). If no answer is provided in time, the AI voice agent will move on.
 
-#### Mode 2: Steering with instructions
+#### Steering with instructions
 
-When there is **no pending question** but the call is still active, any message the user types in the chat is treated as a **steering instruction**. This lets the user proactively guide the call in real time — for example:
+When there is **no pending question** but the call is still active, the user can send steering instructions via the HTTP API (`POST /v1/calls/:id/instruction`) to proactively guide the call in real time — for example:
 
 - "Ask them about their cancellation policy too"
 - "Wrap up the call, we have what we need"
 - "Switch to asking about weekend availability instead"
 - "Be more assertive about getting a discount"
 
-The instruction is injected into the AI voice agent's conversation context as high-priority input, and the agent adjusts its behavior accordingly. A confirmation message ("Instruction relayed to active call.") appears in the chat thread.
+The instruction is injected into the AI voice agent's conversation context as high-priority input, and the agent adjusts its behavior accordingly.
 
-**The user does not need to do anything special** — just type a message. The system automatically determines whether it should be an answer or an instruction based on whether a question is pending.
+**Note:** Mid-call steering via the desktop chat thread is no longer supported. The desktop thread only receives pointer/status messages about the call. To steer a call, use the HTTP API endpoints directly.
 
 ### Call status values
 
@@ -414,6 +464,7 @@ The `context` field is powerful — use it to give the agent background that hel
 
 ### Things the AI voice agent handles well
 
+**Outbound calls:**
 - Making reservations and appointments
 - Checking business hours, availability, or pricing
 - Confirming or rescheduling existing appointments
@@ -421,6 +472,12 @@ The `context` field is powerful — use it to give the agent background that hel
 - Simple customer service interactions
 - Leaving voicemails (it will speak the message if voicemail picks up)
 
+**Inbound calls:**
+- Answering as a receptionist and routing caller requests to the user via ASK_GUARDIAN
+- Taking messages when the user is unavailable
+- Answering questions the assistant already knows from memory/context
+- Screening calls with guardian voice verification
+
 ### Things to be aware of
 
 - Calls have a maximum duration (configurable via `calls.maxDurationSeconds`, default: 1 hour)
@@ -470,6 +527,14 @@ vellum config set calls.disclosure.text "Just so you know, this is an assistant
 vellum config set calls.userConsultTimeoutSeconds 300
 ```
 
+## Accepted Regressions
+
+The following behavioral changes were introduced with the cross-channel guardian architecture (voice-cross-guardian):
+
+- **No more mid-call steering via desktop chat.** The call bridge that routed desktop chat messages to the active call has been removed. The desktop chat thread only receives pointer/status messages about the call. To steer a call, use the HTTP API endpoints directly (`POST /v1/calls/:id/instruction`).
+- **No live transcript mirror in the initiating chat.** The initiating desktop conversation no longer receives a real-time mirror of the call transcript. The initiating chat only gets pointer/status messages (call started, call ended, question asked, etc.).
+- **Guardian questions are dispatched cross-channel.** Rather than appearing only in the initiating desktop thread, ASK_GUARDIAN questions are now dispatched to all configured guardian channels (mac desktop, Telegram, SMS) simultaneously. The first channel to respond wins.
+
 ## Troubleshooting
 
 ### "Twilio credentials not configured"

package/src/config/bundled-skills/twitter/icon.svg

@@ -0,0 +1,14 @@
+<svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+<rect width="16" height="16" fill="#ffffff"/>
+<rect x="2" y="2" width="12" height="12" fill="#000000"/>
+<rect x="4" y="5" width="2" height="1" fill="#ffffff"/>
+<rect x="5" y="4" width="1" height="3" fill="#ffffff"/>
+<rect x="6" y="5" width="2" height="1" fill="#ffffff"/>
+<rect x="10" y="5" width="2" height="1" fill="#ffffff"/>
+<rect x="11" y="4" width="1" height="3" fill="#ffffff"/>
+<rect x="12" y="5" width="2" height="1" fill="#ffffff"/>
+<rect x="4" y="9" width="1" height="2" fill="#ffffff"/>
+<rect x="5" y="8" width="6" height="1" fill="#ffffff"/>
+<rect x="11" y="9" width="1" height="2" fill="#ffffff"/>
+<rect x="5" y="11" width="6" height="1" fill="#ffffff"/>
+</svg>