@vellumai/assistant 0.3.3 → 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/cli/map.ts

@@ -166,6 +166,12 @@ async function startLearnSession(
           continue;
         }
 
+        if (m.type === 'ride_shotgun_progress') {
+          // Live progress from auto-navigator
+          process.stderr.write(`  ${m.message}\n`);
+          continue;
+        }
+
         if (m.type === 'ride_shotgun_result') {
           clearTimeout(timeoutHandle);
           socket.destroy();

package/src/commands/__tests__/cc-command-registry.test.ts

@@ -276,6 +276,73 @@ describe('summary extraction', () => {
     expect(entry!.summary).toBe('');
   });
 
+  test('returns empty summary when frontmatter is truncated by partial read', () => {
+    // Simulate frontmatter that exceeds SUMMARY_READ_BYTES (1024).
+    // The closing --- delimiter will be cut off, causing FRONTMATTER_REGEX to
+    // fail. extractSummary should return '' instead of '---'.
+    const largeFrontmatter = '---\n' + 'key: ' + 'x'.repeat(1100) + '\n---\n\nActual summary.';
+    createCommandsDir(tmpDir, {
+      'big-frontmatter.md': largeFrontmatter,
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    const entry = registry.entries.get('big-frontmatter');
+    expect(entry).toBeDefined();
+    expect(entry!.summary).toBe('');
+  });
+
+  test('returns empty summary when frontmatter is truncated (CRLF)', () => {
+    const largeFrontmatter = '---\r\n' + 'key: ' + 'x'.repeat(1100) + '\r\n---\r\n\r\nActual summary.';
+    createCommandsDir(tmpDir, {
+      'big-frontmatter-crlf.md': largeFrontmatter,
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    const entry = registry.entries.get('big-frontmatter-crlf');
+    expect(entry).toBeDefined();
+    expect(entry!.summary).toBe('');
+  });
+
+  test('returns empty summary when frontmatter is truncated with multibyte UTF-8 characters', () => {
+    // When frontmatter contains multibyte UTF-8 characters (e.g., CJK text),
+    // the JavaScript string length (UTF-16 code units) is smaller than the
+    // byte length. The truncation guard must compare byte length, not
+    // string length, against SUMMARY_READ_BYTES (1024).
+    //
+    // Each CJK character is 3 bytes in UTF-8 but 1 code unit in UTF-16.
+    // We need the total byte count to reach 1024 while string length stays
+    // well below 1024 to exercise the bug.
+    const cjkChars = '\u4e00'.repeat(340); // 340 chars * 3 bytes = 1020 bytes
+    // '---\n' is 4 bytes, so total = 4 + 1020 = 1024 bytes, but string
+    // length = 4 + 340 = 344 chars — well under 1024.
+    const truncatedContent = '---\n' + cjkChars;
+    createCommandsDir(tmpDir, {
+      'multibyte-frontmatter.md': truncatedContent,
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    const entry = registry.entries.get('multibyte-frontmatter');
+    expect(entry).toBeDefined();
+    // Should return '' because the frontmatter opening delimiter is present
+    // but the closing delimiter is missing and the byte length reached the
+    // read limit — indicating truncation.
+    expect(entry!.summary).toBe('');
+  });
+
+  test('returns summary for small file starting with thematic break ---', () => {
+    // A small markdown file that starts with "---" as a thematic break (not
+    // frontmatter) should still have its first content line extracted as a
+    // summary, rather than being treated as truncated frontmatter.
+    createCommandsDir(tmpDir, {
+      'thematic-break.md': '---\nThis is a valid summary after a thematic break.',
+    });
+
+    const registry = discoverCCCommands(tmpDir);
+    const entry = registry.entries.get('thematic-break');
+    expect(entry).toBeDefined();
+    expect(entry!.summary).toBe('This is a valid summary after a thematic break.');
+  });
+
   test('handles frontmatter with Windows-style line endings', () => {
     createCommandsDir(tmpDir, {
       'crlf.md': '---\r\ntitle: Test\r\n---\r\n\r\nSummary with CRLF.',

package/src/commands/cc-command-registry.ts

@@ -1,5 +1,6 @@
 import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
+import { FRONTMATTER_REGEX } from '../skills/frontmatter.js';
 import { getLogger } from '../util/logger.js';
 
 const log = getLogger('cc-commands');
@@ -27,7 +28,6 @@ export interface CCCommandRegistry {
 // ─── Constants ───────────────────────────────────────────────────────────────
 
 const COMMAND_NAME_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-const FRONTMATTER_REGEX = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/;
 const DEFAULT_CACHE_TTL_MS = 30_000;
 const MAX_SUMMARY_LENGTH = 100;
 
@@ -80,6 +80,19 @@ function extractSummary(content: string): string {
   const fmMatch = content.match(FRONTMATTER_REGEX);
   if (fmMatch) {
     body = content.slice(fmMatch[0].length);
+  } else if (/^---\r?\n/.test(content)) {
+    if (Buffer.byteLength(content, 'utf-8') >= SUMMARY_READ_BYTES) {
+      // Content starts with a frontmatter opening delimiter but the closing
+      // delimiter was not found. The content length reached SUMMARY_READ_BYTES,
+      // so the read was likely truncated — the missing closing `---` is
+      // probably just beyond the read boundary. Return empty rather than
+      // surfacing partial frontmatter fields as a summary.
+      return '';
+    }
+    // Small file that starts with `---` (thematic break or unclosed
+    // frontmatter opener). Skip the leading `---` line and extract the
+    // first real content line from the remainder.
+    body = content.replace(/^---\r?\n/, '');
   }
 
   // Find first non-empty line

package/src/config/bundled-skills/claude-code/TOOLS.json

@@ -11,7 +11,15 @@
         "properties": {
           "prompt": {
             "type": "string",
-            "description": "The coding task or question for Claude Code to work on"
+            "description": "The coding task or question for Claude Code to work on. Use this for free-form tasks. Mutually exclusive with command."
+          },
+          "command": {
+            "type": "string",
+            "description": "Name of a .claude/commands/*.md command template to execute. The template will be loaded and $ARGUMENTS substituted before execution. Use this instead of prompt when invoking a named CC command."
+          },
+          "arguments": {
+            "type": "string",
+            "description": "Arguments to substitute into the command template ($ARGUMENTS placeholder). Only used with the command input."
           },
           "working_dir": {
             "type": "string",
@@ -30,8 +38,7 @@
             "enum": ["general", "researcher", "coder", "reviewer"],
             "description": "Worker profile that scopes tool access. Defaults to general (backward compatible)."
           }
-        },
-        "required": ["prompt"]
+        }
       },
       "executor": "tools/claude-code.ts",
       "execution_target": "host"

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"
+    }
+  ]
+}