@vellumai/assistant 0.3.4 → 0.3.5

package/src/calls/twilio-rest.ts

@@ -155,6 +155,38 @@ export async function provisionPhoneNumber(
   };
 }
 
+/** Fetch the current status of a Twilio message by SID. */
+export async function fetchMessageStatus(
+  accountSid: string,
+  authToken: string,
+  messageSid: string,
+): Promise<{ status: string; errorCode?: string; errorMessage?: string }> {
+  const res = await fetch(
+    `${twilioBaseUrl(accountSid)}/Messages/${encodeURIComponent(messageSid)}.json`,
+    {
+      method: 'GET',
+      headers: { Authorization: twilioAuthHeader(accountSid, authToken) },
+    },
+  );
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Twilio API error ${res.status}: ${text}`);
+  }
+
+  const data = (await res.json()) as {
+    status?: string;
+    error_code?: number | null;
+    error_message?: string | null;
+  };
+
+  return {
+    status: data.status ?? 'unknown',
+    errorCode: data.error_code != null ? String(data.error_code) : undefined,
+    errorMessage: data.error_message ?? undefined,
+  };
+}
+
 export interface WebhookUrls {
   voiceUrl: string;
   statusCallbackUrl: string;
@@ -224,3 +256,247 @@ export async function updatePhoneNumberWebhooks(
     throw new Error(`Twilio API error ${updateRes.status} updating webhooks: ${text}`);
   }
 }
+
+// ── Toll-Free Verification ──────────────────────────────────────────────
+
+/** Twilio Messaging API base URL for toll-free verification endpoints. */
+const TOLLFREE_VERIFICATION_BASE = 'https://messaging.twilio.com/v1/Tollfree/Verifications';
+
+export interface TollFreeVerification {
+  sid: string;
+  status: string;
+  rejectionReason?: string;
+  rejectionReasons?: string[];
+  errorCode?: string;
+  editAllowed?: boolean;
+  editExpiration?: string;
+  regulationType?: string;
+}
+
+function parseTollFreeVerification(raw: Record<string, unknown>): TollFreeVerification {
+  return {
+    sid: raw.sid as string,
+    status: raw.status as string,
+    rejectionReason: (raw.rejection_reason as string) ?? undefined,
+    rejectionReasons: (raw.rejection_reasons as string[]) ?? undefined,
+    errorCode: (raw.error_code != null ? String(raw.error_code) : undefined),
+    editAllowed: (raw.edit_allowed as boolean) ?? undefined,
+    editExpiration: (raw.edit_expiration as string) ?? undefined,
+    regulationType: (raw.regulation_type as string) ?? undefined,
+  };
+}
+
+/**
+ * Get toll-free verification status for a phone number.
+ * If `phoneNumberSid` is provided, filters by that SID; otherwise returns the
+ * first verification found.
+ */
+export async function getTollFreeVerificationStatus(
+  accountSid: string,
+  authToken: string,
+  phoneNumberSid?: string,
+): Promise<TollFreeVerification | null> {
+  const params = new URLSearchParams();
+  if (phoneNumberSid) params.set('TollfreePhoneNumberSid', phoneNumberSid);
+
+  const url = params.toString()
+    ? `${TOLLFREE_VERIFICATION_BASE}?${params.toString()}`
+    : TOLLFREE_VERIFICATION_BASE;
+
+  const res = await fetch(url, {
+    method: 'GET',
+    headers: { Authorization: twilioAuthHeader(accountSid, authToken) },
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Twilio Toll-Free Verification API error ${res.status}: ${text}`);
+  }
+
+  const data = (await res.json()) as { verifications?: Array<Record<string, unknown>> };
+  const verifications = data.verifications ?? [];
+  if (verifications.length === 0) return null;
+
+  return parseTollFreeVerification(verifications[0]);
+}
+
+export interface TollFreeVerificationSubmitParams {
+  tollfreePhoneNumberSid: string;
+  businessName: string;
+  businessWebsite: string;
+  notificationEmail: string;
+  useCaseCategories: string[];
+  useCaseSummary: string;
+  productionMessageSample: string;
+  optInImageUrls: string[];
+  optInType: string;
+  messageVolume: string;
+  businessType?: string;
+  customerProfileSid?: string;
+}
+
+/** Submit a new toll-free verification request. */
+export async function submitTollFreeVerification(
+  accountSid: string,
+  authToken: string,
+  params: TollFreeVerificationSubmitParams,
+): Promise<TollFreeVerification> {
+  const body = new URLSearchParams();
+  body.set('TollfreePhoneNumberSid', params.tollfreePhoneNumberSid);
+  body.set('BusinessName', params.businessName);
+  body.set('BusinessWebsite', params.businessWebsite);
+  body.set('NotificationEmail', params.notificationEmail);
+  body.set('UseCaseSummary', params.useCaseSummary);
+  body.set('ProductionMessageSample', params.productionMessageSample);
+  body.set('OptInType', params.optInType);
+  body.set('MessageVolume', params.messageVolume);
+  body.set('BusinessType', params.businessType ?? 'SOLE_PROPRIETOR');
+
+  for (const cat of params.useCaseCategories) {
+    body.append('UseCaseCategories', cat);
+  }
+  for (const url of params.optInImageUrls) {
+    body.append('OptInImageUrls', url);
+  }
+  if (params.customerProfileSid) {
+    body.set('CustomerProfileSid', params.customerProfileSid);
+  }
+
+  const res = await fetch(TOLLFREE_VERIFICATION_BASE, {
+    method: 'POST',
+    headers: {
+      Authorization: twilioAuthHeader(accountSid, authToken),
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+    body: body.toString(),
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Twilio Toll-Free Verification submit error ${res.status}: ${text}`);
+  }
+
+  const data = (await res.json()) as Record<string, unknown>;
+  return parseTollFreeVerification(data);
+}
+
+/** Update an existing toll-free verification. */
+export async function updateTollFreeVerification(
+  accountSid: string,
+  authToken: string,
+  verificationSid: string,
+  params: Partial<TollFreeVerificationSubmitParams>,
+): Promise<TollFreeVerification> {
+  const body = new URLSearchParams();
+  if (params.businessName) body.set('BusinessName', params.businessName);
+  if (params.businessWebsite) body.set('BusinessWebsite', params.businessWebsite);
+  if (params.notificationEmail) body.set('NotificationEmail', params.notificationEmail);
+  if (params.useCaseSummary) body.set('UseCaseSummary', params.useCaseSummary);
+  if (params.productionMessageSample) body.set('ProductionMessageSample', params.productionMessageSample);
+  if (params.optInType) body.set('OptInType', params.optInType);
+  if (params.messageVolume) body.set('MessageVolume', params.messageVolume);
+  if (params.businessType) body.set('BusinessType', params.businessType);
+  if (params.useCaseCategories) {
+    for (const cat of params.useCaseCategories) {
+      body.append('UseCaseCategories', cat);
+    }
+  }
+  if (params.optInImageUrls) {
+    for (const url of params.optInImageUrls) {
+      body.append('OptInImageUrls', url);
+    }
+  }
+  if (params.customerProfileSid) body.set('CustomerProfileSid', params.customerProfileSid);
+
+  const res = await fetch(`${TOLLFREE_VERIFICATION_BASE}/${encodeURIComponent(verificationSid)}`, {
+    method: 'POST',
+    headers: {
+      Authorization: twilioAuthHeader(accountSid, authToken),
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+    body: body.toString(),
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Twilio Toll-Free Verification update error ${res.status}: ${text}`);
+  }
+
+  const data = (await res.json()) as Record<string, unknown>;
+  return parseTollFreeVerification(data);
+}
+
+/** Delete a toll-free verification. */
+export async function deleteTollFreeVerification(
+  accountSid: string,
+  authToken: string,
+  verificationSid: string,
+): Promise<void> {
+  const res = await fetch(`${TOLLFREE_VERIFICATION_BASE}/${encodeURIComponent(verificationSid)}`, {
+    method: 'DELETE',
+    headers: { Authorization: twilioAuthHeader(accountSid, authToken) },
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Twilio Toll-Free Verification delete error ${res.status}: ${text}`);
+  }
+}
+
+/**
+ * Get the SID for an incoming phone number.
+ * Looks up the number via `IncomingPhoneNumbers.json?PhoneNumber=...`.
+ */
+export async function getPhoneNumberSid(
+  accountSid: string,
+  authToken: string,
+  phoneNumber: string,
+): Promise<string | null> {
+  const res = await fetch(
+    `${twilioBaseUrl(accountSid)}/IncomingPhoneNumbers.json?PhoneNumber=${encodeURIComponent(phoneNumber)}`,
+    {
+      method: 'GET',
+      headers: { Authorization: twilioAuthHeader(accountSid, authToken) },
+    },
+  );
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Twilio API error ${res.status} looking up phone number SID: ${text}`);
+  }
+
+  const data = (await res.json()) as {
+    incoming_phone_numbers: Array<{ sid: string; phone_number: string }>;
+  };
+
+  const match = data.incoming_phone_numbers.find((n) => n.phone_number === phoneNumber);
+  return match?.sid ?? null;
+}
+
+/**
+ * Release (delete) an incoming phone number from the Twilio account.
+ * Looks up the SID by phone number then sends a DELETE request.
+ */
+export async function releasePhoneNumber(
+  accountSid: string,
+  authToken: string,
+  phoneNumber: string,
+): Promise<void> {
+  const sid = await getPhoneNumberSid(accountSid, authToken, phoneNumber);
+  if (!sid) {
+    throw new Error(`Phone number ${phoneNumber} not found on Twilio account ${accountSid}`);
+  }
+
+  const res = await fetch(
+    `${twilioBaseUrl(accountSid)}/IncomingPhoneNumbers/${sid}.json`,
+    {
+      method: 'DELETE',
+      headers: { Authorization: twilioAuthHeader(accountSid, authToken) },
+    },
+  );
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Twilio API error ${res.status} releasing phone number: ${text}`);
+  }
+}

package/src/calls/twilio-routes.ts

@@ -29,6 +29,10 @@ import { resolveVoiceQualityProfile, isVoiceProfileValid } from './voice-quality
 
 const log = getLogger('twilio-routes');
 
+const CONTEXT_BLOCK_SPLIT_REGEX = /\n\s*\nContext:\s*/i;
+const MAX_TASK_SUMMARY_CHARS = 120;
+const DEFAULT_WELCOME_GREETING = 'Hello, this is an assistant calling. Is now a good time to talk?';
+
 // ── Helpers ──────────────────────────────────────────────────────────
 
 function escapeXml(str: string): string {
@@ -63,6 +67,40 @@ export function generateTwiML(
 </Response>`;
 }
 
+function summarizeTaskForGreeting(task: string | null): string | null {
+  if (!task) return null;
+  const primaryTask = task.split(CONTEXT_BLOCK_SPLIT_REGEX)[0]?.trim() ?? '';
+  if (!primaryTask) return null;
+
+  const compact = primaryTask.replace(/\s+/g, ' ').trim().replace(/[.!?]+$/, '');
+  if (!compact) return null;
+  if (compact.length <= MAX_TASK_SUMMARY_CHARS) return compact;
+  return `${compact.slice(0, MAX_TASK_SUMMARY_CHARS - 3).trimEnd()}...`;
+}
+
+function formatTaskAsCallPurpose(taskSummary: string): string {
+  const lower = taskSummary.toLowerCase();
+  if (
+    lower.startsWith('about ') ||
+    lower.startsWith('to ') ||
+    lower.startsWith('for ') ||
+    lower.startsWith('regarding ')
+  ) {
+    return taskSummary;
+  }
+  return `about ${taskSummary}`;
+}
+
+export function buildWelcomeGreeting(task: string | null, configuredGreeting?: string): string {
+  const override = configuredGreeting?.trim();
+  if (override) return override;
+
+  const taskSummary = summarizeTaskForGreeting(task);
+  if (!taskSummary) return DEFAULT_WELCOME_GREETING;
+
+  return `Hello, I am calling ${formatTaskAsCallPurpose(taskSummary)}. Is now a good time to talk?`;
+}
+
 /**
  * Resolve the WebSocket relay URL from Twilio config.
  *
@@ -183,7 +221,7 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
     // Fallback to legacy resolution when ingress is not configured
     relayUrl = resolveRelayUrl(twilioConfig.wssBaseUrl, twilioConfig.webhookBaseUrl);
   }
-  const welcomeGreeting = process.env.CALL_WELCOME_GREETING ?? 'Hello, how can I help you today?';
+  const welcomeGreeting = buildWelcomeGreeting(session.task, process.env.CALL_WELCOME_GREETING);
 
   const twiml = generateTwiML(callSessionId, relayUrl, welcomeGreeting, profile);
 

package/src/config/bundled-skills/knowledge-graph/SKILL.md

@@ -0,0 +1,15 @@
+# Knowledge Graph
+
+Query the entity knowledge graph to explore relationships between people, projects, tools, and other entities tracked in memory.
+
+## When to use
+
+- When the user asks about relationships between entities ("what tools does project X use?", "who works on project Y?")
+- When the user wants to explore connected entities across the knowledge graph
+- When automatic memory recall doesn't surface the right relationship-based information
+
+## Capabilities
+
+- **Neighbors**: Find entities directly connected to seed entities (optionally filtered by relation and entity type)
+- **Typed traversal**: Multi-step traversal with type constraints at each step (e.g., "me -> works_on -> projects -> uses -> tools")
+- **Intersection**: Find entities reachable from ALL given seeds (e.g., "projects both Alice and Bob work on")

package/src/config/bundled-skills/knowledge-graph/TOOLS.json

@@ -0,0 +1,56 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "knowledge_graph_query",
+      "description": "Query the entity knowledge graph to find related entities and their associated memory items. Supports three query types: 'neighbors' (direct connections), 'typed_traversal' (multi-step with type filters), and 'intersection' (entities reachable from ALL seeds).",
+      "category": "memory",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "query_type": {
+            "type": "string",
+            "enum": ["neighbors", "typed_traversal", "intersection"],
+            "description": "Type of graph query to execute"
+          },
+          "seeds": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Entity names or aliases to use as starting points"
+          },
+          "steps": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "relation_types": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Relation types to follow (e.g., 'uses', 'works_on', 'depends_on')"
+                },
+                "entity_types": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Entity types to include (e.g., 'person', 'project', 'tool')"
+                }
+              }
+            },
+            "description": "Traversal steps for typed_traversal and intersection queries. Each step defines type filters for one hop."
+          },
+          "max_results": {
+            "type": "number",
+            "description": "Maximum number of entities to return (default: 20)"
+          },
+          "include_items": {
+            "type": "boolean",
+            "description": "Include associated memory items for each found entity (default: true)"
+          }
+        },
+        "required": ["query_type", "seeds"]
+      },
+      "executor": "tools/graph-query.ts",
+      "execution_target": "host"
+    }
+  ]
+}

package/src/config/bundled-skills/knowledge-graph/tools/graph-query.ts

@@ -0,0 +1,185 @@
+import { initializeDb, getDb } from '../../../../memory/db.js';
+import { findMatchedEntities, findNeighborEntities, getEntityLinkedItemCandidates, collectTypedNeighbors } from '../../../../memory/search/entity.js';
+import { memoryEntities } from '../../../../memory/schema.js';
+import { inArray } from 'drizzle-orm';
+import type { TraversalStep } from '../../../../memory/search/types.js';
+import type { EntityRelationType, EntityType } from '../../../../memory/entity-extractor.js';
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+
+interface GraphQueryInput {
+  query_type: 'neighbors' | 'typed_traversal' | 'intersection';
+  seeds: string[];
+  steps?: Array<{
+    relation_types?: string[];
+    entity_types?: string[];
+  }>;
+  max_results?: number;
+  include_items?: boolean;
+}
+
+interface EntityResult {
+  id: string;
+  name: string;
+  type: string;
+  aliases: string[];
+  items?: Array<{ subject: string; statement: string }>;
+}
+
+export async function run(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const params = input as unknown as GraphQueryInput;
+
+  initializeDb();
+
+  const maxResults = params.max_results ?? 20;
+  const includeItems = params.include_items ?? true;
+
+  // Resolve seed entity names to IDs
+  const seedEntityIds: string[] = [];
+  const resolvedSeeds: Array<{ name: string; id: string }> = [];
+  for (const seedName of params.seeds) {
+    const matched = findMatchedEntities(seedName, 5);
+    if (matched.length > 0) {
+      seedEntityIds.push(matched[0].id);
+      resolvedSeeds.push({ name: seedName, id: matched[0].id });
+    }
+  }
+
+  if (seedEntityIds.length === 0) {
+    return {
+      content: JSON.stringify({
+        error: 'No matching entities found for the provided seed names',
+        seeds: params.seeds,
+      }),
+      isError: true,
+    };
+  }
+
+  // For intersection queries, all seeds must resolve — dropping any seed silently
+  // changes semantics from "reachable from ALL seeds" to "reachable from resolved seeds"
+  if (params.query_type === 'intersection' && seedEntityIds.length < params.seeds.length) {
+    const unresolvedSeeds = params.seeds.filter(
+      name => !resolvedSeeds.some(s => s.name === name),
+    );
+    return {
+      content: JSON.stringify({
+        error: 'Some seed entities could not be resolved. Intersection requires all seeds to match.',
+        unresolved_seeds: unresolvedSeeds,
+        resolved_seeds: resolvedSeeds,
+      }),
+      isError: true,
+    };
+  }
+
+  let resultEntityIds: string[];
+
+  switch (params.query_type) {
+    case 'neighbors': {
+      const steps = params.steps?.[0];
+      const result = findNeighborEntities(seedEntityIds, {
+        maxEdges: 40,
+        maxNeighborEntities: maxResults,
+        maxDepth: 1,
+        relationTypes: steps?.relation_types as EntityRelationType[] | undefined,
+        entityTypes: steps?.entity_types as EntityType[] | undefined,
+      });
+      resultEntityIds = result.neighborEntityIds;
+      break;
+    }
+
+    case 'typed_traversal': {
+      const traversalSteps: TraversalStep[] = (params.steps ?? []).map(s => ({
+        relationTypes: s.relation_types as EntityRelationType[] | undefined,
+        entityTypes: s.entity_types as EntityType[] | undefined,
+      }));
+      resultEntityIds = collectTypedNeighbors(seedEntityIds, traversalSteps, {
+        maxResultsPerStep: maxResults,
+        maxEdgesPerStep: 40,
+      });
+      break;
+    }
+
+    case 'intersection': {
+      // Run typed traversal from each seed independently, then intersect
+      const traversalSteps: TraversalStep[] = (params.steps ?? []).map(s => ({
+        relationTypes: s.relation_types as EntityRelationType[] | undefined,
+        entityTypes: s.entity_types as EntityType[] | undefined,
+      }));
+
+      const resultSets: Set<string>[] = [];
+      for (const seedId of seedEntityIds) {
+        const result = collectTypedNeighbors([seedId], traversalSteps, {
+          maxResultsPerStep: maxResults,
+          maxEdgesPerStep: 40,
+        });
+        resultSets.push(new Set(result));
+      }
+
+      if (resultSets.length === 0) {
+        resultEntityIds = [];
+      } else {
+        // Intersect all sets
+        const intersection = [...resultSets[0]].filter(id =>
+          resultSets.every(set => set.has(id))
+        );
+        resultEntityIds = intersection;
+      }
+      break;
+    }
+
+    default:
+      return {
+        content: JSON.stringify({ error: `Unknown query_type: ${params.query_type}` }),
+        isError: true,
+      };
+  }
+
+  // Look up entity details
+  const db = getDb();
+  const entities: EntityResult[] = [];
+
+  if (resultEntityIds.length > 0) {
+    const entityRows = db
+      .select()
+      .from(memoryEntities)
+      .where(inArray(memoryEntities.id, resultEntityIds.slice(0, maxResults)))
+      .all();
+
+    for (const row of entityRows) {
+      const entity: EntityResult = {
+        id: row.id,
+        name: row.name,
+        type: row.type,
+        aliases: row.aliases ? JSON.parse(row.aliases) as string[] : [],
+      };
+
+      if (includeItems) {
+        const candidates = getEntityLinkedItemCandidates([row.id], {
+          source: 'entity_direct',
+          scopeIds: _context.memoryScopeId ? [_context.memoryScopeId] : undefined,
+        });
+        entity.items = candidates.slice(0, 5).map(c => {
+          const parts = c.text.split(': ');
+          return {
+            subject: parts[0] ?? '',
+            statement: parts.slice(1).join(': ') || c.text,
+          };
+        });
+      }
+
+      entities.push(entity);
+    }
+  }
+
+  return {
+    content: JSON.stringify({
+      query_type: params.query_type,
+      resolved_seeds: resolvedSeeds,
+      result_count: entities.length,
+      entities,
+    }, null, 2),
+    isError: false,
+  };
+}