vellum 0.2.13 → 0.2.14

package/src/calls/twilio-provider.ts

@@ -131,6 +131,97 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
     return data.status;
   }
 
+  // ── Caller ID eligibility ───────────────────────────────────────────
+
+  /**
+   * Check whether a phone number can be used as an outbound caller ID
+   * by the current Twilio account. A number is eligible if it appears as
+   * either an Incoming Phone Number (owned) or an Outgoing Caller ID
+   * (verified) on the account.
+   */
+  async checkCallerIdEligibility(
+    phoneNumber: string,
+  ): Promise<{ eligible: boolean; reason?: string }> {
+    const { accountSid, authToken } = this.getCredentials();
+    const encodedNumber = encodeURIComponent(phoneNumber);
+
+    let incomingOk = false;
+    let outgoingOk = false;
+
+    // Check incoming phone numbers (owned by this account)
+    const incomingRes = await fetch(
+      `${this.baseUrl(accountSid)}/IncomingPhoneNumbers.json?PhoneNumber=${encodedNumber}`,
+      {
+        method: 'GET',
+        headers: {
+          Authorization: this.authHeader(accountSid, authToken),
+        },
+      },
+    );
+
+    if (incomingRes.ok) {
+      incomingOk = true;
+      const incomingData = (await incomingRes.json()) as {
+        incoming_phone_numbers: unknown[];
+      };
+      if (incomingData.incoming_phone_numbers.length > 0) {
+        log.info({ phoneNumber }, 'Number found in IncomingPhoneNumbers — eligible as caller ID');
+        return { eligible: true };
+      }
+    } else {
+      log.warn(
+        { status: incomingRes.status, phoneNumber },
+        'Failed to query IncomingPhoneNumbers — falling through to OutgoingCallerIds',
+      );
+    }
+
+    // Check outgoing caller IDs (verified with this account)
+    const outgoingRes = await fetch(
+      `${this.baseUrl(accountSid)}/OutgoingCallerIds.json?PhoneNumber=${encodedNumber}`,
+      {
+        method: 'GET',
+        headers: {
+          Authorization: this.authHeader(accountSid, authToken),
+        },
+      },
+    );
+
+    if (outgoingRes.ok) {
+      outgoingOk = true;
+      const outgoingData = (await outgoingRes.json()) as {
+        outgoing_caller_ids: unknown[];
+      };
+      if (outgoingData.outgoing_caller_ids.length > 0) {
+        log.info({ phoneNumber }, 'Number found in OutgoingCallerIds — eligible as caller ID');
+        return { eligible: true };
+      }
+    } else {
+      log.warn(
+        { status: outgoingRes.status, phoneNumber },
+        'Failed to query OutgoingCallerIds',
+      );
+    }
+
+    // If any API call failed, the eligibility check is inconclusive —
+    // propagate as an error rather than returning a false negative.
+    if (!incomingOk || !outgoingOk) {
+      const failedEndpoints = [
+        ...(!incomingOk ? [`IncomingPhoneNumbers: ${incomingRes.status}`] : []),
+        ...(!outgoingOk ? [`OutgoingCallerIds: ${outgoingRes.status}`] : []),
+      ].join(', ');
+      throw new Error(
+        `Unable to verify caller ID eligibility for ${phoneNumber}: Twilio API error (${failedEndpoints}). The number may be eligible but could not be confirmed. Please check your Twilio credentials and try again.`,
+      );
+    }
+
+    log.info({ phoneNumber }, 'Number not found in either IncomingPhoneNumbers or OutgoingCallerIds');
+    return {
+      eligible: false,
+      reason:
+        'Number is not owned by or verified with your Twilio account. To use this number as caller ID, either: (1) add it as an Incoming Phone Number, or (2) verify it as an Outgoing Caller ID in the Twilio Console.',
+    };
+  }
+
   // ── Webhook signature verification ──────────────────────────────────
 
   /**

package/src/calls/twilio-routes.ts

@@ -25,9 +25,7 @@ import { getTwilioConfig } from './twilio-config.js';
 import { loadConfig } from '../config/loader.js';
 import { getTwilioRelayUrl } from '../inbound/public-ingress-urls.js';
 import { fireCallCompletionNotifier } from './call-state.js';
-import { resolveVoiceQualityProfile } from './voice-quality.js';
-import { getElevenLabsConfig } from './elevenlabs-config.js';
-import { ElevenLabsClient } from './elevenlabs-client.js';
+import { resolveVoiceQualityProfile, isVoiceProfileValid } from './voice-quality.js';
 
 const log = getLogger('twilio-routes');
 
@@ -139,7 +137,7 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
     log.info({ callSessionId, callSid }, 'Stored CallSid from voice webhook');
   }
 
-  const profile = resolveVoiceQualityProfile(loadConfig());
+  let profile = resolveVoiceQualityProfile(loadConfig());
 
   log.info({ callSessionId, mode: profile.mode, ttsProvider: profile.ttsProvider, voice: profile.voice }, 'Voice quality profile resolved');
 
@@ -147,6 +145,36 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
     log.warn({ callSessionId, errors: profile.validationErrors }, 'Voice quality profile has validation warnings');
   }
 
+  // WS-A: Enforce strict fallback semantics — reject invalid profiles when fallback is disabled
+  if (!isVoiceProfileValid(profile)) {
+    if (!profile.fallbackToStandardOnError) {
+      const errorMsg = `Voice quality configuration error: ${profile.validationErrors.join('; ')}`;
+      log.error({ callSessionId, errors: profile.validationErrors }, errorMsg);
+      return new Response(errorMsg, { status: 500 });
+    }
+    // Fallback is enabled — profile already resolved to standard; log explicitly
+    log.info({ callSessionId }, 'Profile invalid with fallback enabled; proceeding with standard mode');
+  }
+
+  // WS-B: Guard elevenlabs_agent until consultation bridge exists.
+  // This fires BEFORE any ElevenLabs API calls, blocking the entire mode.
+  if (profile.mode === 'elevenlabs_agent') {
+    if (!profile.fallbackToStandardOnError) {
+      const msg = 'elevenlabs_agent mode is restricted: consultation bridging (waiting_on_user) is not yet supported. Set calls.voice.fallbackToStandardOnError=true to fall back to standard mode.';
+      log.error({ callSessionId }, msg);
+      return new Response(msg, { status: 501 });
+    }
+    log.warn({ callSessionId }, 'elevenlabs_agent mode is restricted/experimental — consultation bridging is not yet supported; falling back to standard ConversationRelay TwiML');
+    const standardConfig = loadConfig();
+    profile = resolveVoiceQualityProfile({
+      ...standardConfig,
+      calls: {
+        ...standardConfig.calls,
+        voice: { ...standardConfig.calls.voice, mode: 'twilio_standard' },
+      },
+    });
+  }
+
   const twilioConfig = getTwilioConfig();
   let relayUrl: string;
   try {
@@ -157,39 +185,6 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
   }
   const welcomeGreeting = process.env.CALL_WELCOME_GREETING ?? 'Hello, how can I help you today?';
 
-  if (profile.mode === 'elevenlabs_agent') {
-    try {
-      const elevenLabsConfig = getElevenLabsConfig();
-      const client = new ElevenLabsClient({
-        apiBaseUrl: elevenLabsConfig.apiBaseUrl,
-        apiKey: elevenLabsConfig.apiKey,
-        timeoutMs: elevenLabsConfig.registerCallTimeoutMs,
-      });
-
-      const result = await client.registerCall({
-        agent_id: elevenLabsConfig.agentId,
-        from_number: formBody.get('From') || session.fromNumber,
-        to_number: formBody.get('To') || session.toNumber,
-        direction: 'outbound',
-      });
-
-      log.info({ callSessionId }, 'ElevenLabs register-call succeeded');
-      return new Response(result.twiml, {
-        status: 200,
-        headers: { 'Content-Type': 'text/xml' },
-      });
-    } catch (err) {
-      log.error({ err, callSessionId }, 'ElevenLabs register-call failed');
-      if (profile.fallbackToStandardOnError) {
-        log.warn({ callSessionId }, 'Falling back to twilio_standard mode');
-        const standardProfile = resolveVoiceQualityProfile({ ...loadConfig(), calls: { ...loadConfig().calls, voice: { ...loadConfig().calls.voice, mode: 'twilio_standard' } } });
-        const twiml = generateTwiML(callSessionId, relayUrl, welcomeGreeting, standardProfile);
-        return new Response(twiml, { status: 200, headers: { 'Content-Type': 'text/xml' } });
-      }
-      return new Response('ElevenLabs service unavailable', { status: 502 });
-    }
-  }
-
   const twiml = generateTwiML(callSessionId, relayUrl, welcomeGreeting, profile);
 
   log.info({ callSessionId }, 'Returning ConversationRelay TwiML');

package/src/calls/types.ts

@@ -1,5 +1,5 @@
 export type CallStatus = 'initiated' | 'ringing' | 'in_progress' | 'waiting_on_user' | 'completed' | 'failed' | 'cancelled';
-export type CallEventType = 'call_started' | 'call_connected' | 'caller_spoke' | 'assistant_spoke' | 'user_question_asked' | 'user_answered' | 'call_ended' | 'call_failed';
+export type CallEventType = 'call_started' | 'call_connected' | 'caller_spoke' | 'assistant_spoke' | 'user_question_asked' | 'user_answered' | 'user_instruction_relayed' | 'call_ended' | 'call_failed';
 export type PendingQuestionStatus = 'pending' | 'answered' | 'expired' | 'cancelled';
 
 export interface CallSession {
@@ -11,6 +11,8 @@ export interface CallSession {
   toNumber: string;
   task: string | null;
   status: CallStatus;
+  callerIdentityMode: string | null;
+  callerIdentitySource: string | null;
   startedAt: number | null;
   endedAt: number | null;
   lastError: string | null;

package/src/calls/voice-quality.ts

@@ -13,17 +13,34 @@ export interface VoiceQualityProfile {
 
 /**
  * Build a Twilio-compatible ElevenLabs voice string.
- * Format: voiceId or voiceId-modelId-stability_similarity_style
+ *
+ * Twilio ConversationRelay accepts:
+ *   - bare voiceId
+ *   - voiceId-model-speed_stability_similarity
+ *
+ * We default to bare voiceId unless a model is explicitly configured.
+ * This avoids forcing model/tuning suffixes that may be rejected for some
+ * voice + model combinations.
+ *
+ * See: https://www.twilio.com/docs/voice/conversationrelay/voice-configuration
  */
 export function buildElevenLabsVoiceSpec(config: {
   voiceId: string;
-  voiceModelId: string;
-  stability: number;
-  similarityBoost: number;
-  style: number;
+  voiceModelId?: string;
+  speed?: number;
+  stability?: number;
+  similarityBoost?: number;
 }): string {
-  if (!config.voiceId) return '';
-  return `${config.voiceId}-${config.voiceModelId}-${config.stability}_${config.similarityBoost}_${config.style}`;
+  const voiceId = config.voiceId?.trim();
+  if (!voiceId) return '';
+
+  const voiceModelId = config.voiceModelId?.trim();
+  if (!voiceModelId) return voiceId;
+
+  const speed = config.speed ?? 1.0;
+  const stability = config.stability ?? 0.5;
+  const similarityBoost = config.similarityBoost ?? 0.75;
+  return `${voiceId}-${voiceModelId}-${speed}_${stability}_${similarityBoost}`;
 }
 
 /**
@@ -90,3 +107,8 @@ export function resolveVoiceQualityProfile(config?: ReturnType<typeof loadConfig
 
   return standardProfile;
 }
+
+/** Returns false when the profile has any validation errors. */
+export function isVoiceProfileValid(profile: VoiceQualityProfile): boolean {
+  return profile.validationErrors.length === 0;
+}

package/src/cli/twitter.ts

@@ -13,7 +13,6 @@ import {
   clearSession,
 } from '../twitter/session.js';
 import {
-  postTweet,
   getUserByScreenName,
   getUserTweets,
   getTweetDetail,
@@ -27,6 +26,7 @@ import {
   getUserMedia,
   SessionExpiredError,
 } from '../twitter/client.js';
+import { routedPostTweet } from '../twitter/router.js';
 import { getSocketPath, readSessionToken } from '../util/platform.js';
 import {
   serialize,
@@ -69,11 +69,32 @@ async function run(cmd: Command, fn: () => Promise<unknown>): Promise<void> {
       getJson(cmd),
     );
   } catch (err) {
+    const meta = err as Record<string, unknown>;
     if (err instanceof SessionExpiredError) {
-      output(
-        { ok: false, error: 'session_expired', message: SESSION_EXPIRED_MSG },
-        getJson(cmd),
-      );
+      // Preserve backward-compatible error code while surfacing router metadata
+      const payload: Record<string, unknown> = {
+        ok: false,
+        error: 'session_expired',
+        message: SESSION_EXPIRED_MSG,
+      };
+      if (meta.pathUsed !== undefined) payload.pathUsed = meta.pathUsed;
+      if (meta.suggestAlternative !== undefined) payload.suggestAlternative = meta.suggestAlternative;
+      if (meta.oauthError !== undefined) payload.oauthError = meta.oauthError;
+      output(payload, getJson(cmd));
+      process.exitCode = 1;
+      return;
+    }
+    // For routed errors with any router metadata, emit structured JSON
+    // so callers can see dual-path diagnostics (pathUsed, oauthError, etc.)
+    if (err instanceof Error && (meta.pathUsed !== undefined || meta.suggestAlternative !== undefined || meta.oauthError !== undefined)) {
+      const payload: Record<string, unknown> = {
+        ok: false,
+        error: err.message,
+      };
+      if (meta.pathUsed !== undefined) payload.pathUsed = meta.pathUsed;
+      if (meta.suggestAlternative !== undefined) payload.suggestAlternative = meta.suggestAlternative;
+      if (meta.oauthError !== undefined) payload.oauthError = meta.oauthError;
+      output(payload, getJson(cmd));
       process.exitCode = 1;
       return;
     }
@@ -90,7 +111,7 @@ export function registerTwitterCommand(program: Command): void {
     .command('x')
     .alias('twitter')
     .description(
-      'Post on X and manage sessions. Requires a session imported from a Ride Shotgun recording.',
+      'Post on X and manage connections. Supports OAuth (official API) and browser session paths.',
     )
     .option('--json', 'Machine-readable JSON output');
 
@@ -172,25 +193,95 @@ export function registerTwitterCommand(program: Command): void {
     });
 
   // =========================================================================
-  // status — check session status
+  // status — check session status + OAuth and strategy info
   // =========================================================================
   tw.command('status')
-    .description('Check if a Twitter session is active')
-    .action((_opts: unknown, cmd: Command) => {
+    .description('Check Twitter session, OAuth, and strategy status')
+    .action(async (_opts: unknown, cmd: Command) => {
       const session = loadSession();
-      if (session) {
-        output(
-          {
-            ok: true,
-            loggedIn: true,
+      const browserInfo: Record<string, unknown> = session
+        ? {
+            browserSessionActive: true,
             cookieCount: session.cookies.length,
             importedAt: session.importedAt,
             recordingId: session.recordingId,
-          },
-          getJson(cmd),
-        );
-      } else {
-        output({ ok: true, loggedIn: false }, getJson(cmd));
+          }
+        : { browserSessionActive: false };
+
+      // Query daemon for OAuth / strategy config
+      let oauthInfo: Record<string, unknown> = {};
+      try {
+        const daemonResponse = await sendDaemonMessage({
+          type: 'twitter_integration_config',
+          action: 'get',
+        } as import('../daemon/ipc-protocol.js').ClientMessage, 'twitter_integration_config_response');
+        const r = daemonResponse as Record<string, unknown>;
+        oauthInfo = {
+          oauthConnected: r.connected ?? false,
+          oauthAccount: r.accountInfo ?? undefined,
+          preferredStrategy: r.strategy ?? 'auto',
+          strategyConfigured: r.strategyConfigured ?? false,
+        };
+      } catch {
+        // Daemon may not be running; report what we can from the local session
+        oauthInfo = {
+          oauthConnected: undefined,
+          oauthAccount: undefined,
+          preferredStrategy: undefined,
+          strategyConfigured: undefined,
+        };
+      }
+
+      output(
+        {
+          ok: true,
+          loggedIn: !!session,
+          ...browserInfo,
+          ...oauthInfo,
+        },
+        getJson(cmd),
+      );
+    });
+
+  // =========================================================================
+  // strategy — get or set the Twitter operation strategy
+  // =========================================================================
+  const strategyCli = tw.command('strategy')
+    .description('Get or set the Twitter operation strategy (oauth, browser, auto)')
+    .action(async (_opts: unknown, cmd: Command) => {
+      const json = getJson(cmd);
+      try {
+        const daemonResponse = await sendDaemonMessage({
+          type: 'twitter_integration_config',
+          action: 'get_strategy',
+        } as import('../daemon/ipc-protocol.js').ClientMessage, 'twitter_integration_config_response');
+        const r = daemonResponse as Record<string, unknown>;
+        output({ ok: true, strategy: r.strategy ?? 'auto' }, json);
+      } catch (err) {
+        outputError(err instanceof Error ? err.message : String(err));
+      }
+    });
+
+  strategyCli.command('set')
+    .description('Set the Twitter operation strategy')
+    .argument('<value>', 'Strategy value: oauth, browser, or auto')
+    .action(async (value: string, _opts: unknown, cmd: Command) => {
+      const json = getJson(cmd);
+      try {
+        const daemonResponse = await sendDaemonMessage({
+          type: 'twitter_integration_config',
+          action: 'set_strategy',
+          strategy: value,
+        } as import('../daemon/ipc-protocol.js').ClientMessage, 'twitter_integration_config_response');
+        const r = daemonResponse as Record<string, unknown>;
+        if (r.success) {
+          output({ ok: true, strategy: r.strategy }, json);
+        } else {
+          output({ ok: false, error: r.error ?? 'Failed to set strategy' }, json);
+          process.exitCode = 1;
+        }
+      } catch (err) {
+        outputError(err instanceof Error ? err.message : String(err));
       }
     });
 
@@ -202,11 +293,12 @@ export function registerTwitterCommand(program: Command): void {
     .argument('<text>', 'Tweet text')
     .action(async (text: string, _opts: unknown, cmd: Command) => {
       await run(cmd, async () => {
-        const result = await postTweet(text);
+        const { result, pathUsed } = await routedPostTweet(text);
         return {
           tweetId: result.tweetId,
           text: result.text,
           url: result.url,
+          pathUsed,
         };
       });
     });
@@ -226,12 +318,13 @@ export function registerTwitterCommand(program: Command): void {
           throw new Error(`Could not extract tweet ID from: ${tweetUrl}`);
         }
         const inReplyToTweetId = idMatch[1];
-        const result = await postTweet(text, { inReplyToTweetId });
+        const { result, pathUsed } = await routedPostTweet(text, { inReplyToTweetId });
         return {
           tweetId: result.tweetId,
           text: result.text,
           url: result.url,
           inReplyToTweetId,
+          pathUsed,
         };
       });
     });
@@ -382,6 +475,92 @@ export function registerTwitterCommand(program: Command): void {
     });
 }
 
+// ---------------------------------------------------------------------------
+// Daemon IPC helper — send a message and wait for the first response
+// ---------------------------------------------------------------------------
+
+function sendDaemonMessage(
+  message: import('../daemon/ipc-protocol.js').ClientMessage,
+  expectedResponseType: string,
+): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const socketPath = getSocketPath();
+    const sessionToken = readSessionToken();
+    const socket = net.createConnection(socketPath);
+    const parser = createMessageParser();
+
+    const timeoutHandle = setTimeout(() => {
+      socket.destroy();
+      reject(new Error('Daemon request timed out after 10s'));
+    }, 10_000);
+    timeoutHandle.unref();
+
+    let authenticated = !sessionToken;
+    let messageSent = false;
+
+    const sendPayload = () => {
+      if (messageSent) return;
+      messageSent = true;
+      socket.write(serialize(message));
+    };
+
+    socket.on('error', (err) => {
+      clearTimeout(timeoutHandle);
+      reject(new Error(`Cannot connect to daemon: ${err.message}. Is the daemon running?`));
+    });
+
+    socket.on('data', (chunk) => {
+      const messages = parser.feed(chunk.toString('utf-8'));
+      for (const msg of messages) {
+        const m = msg as unknown as Record<string, unknown>;
+
+        if (!authenticated && m.type === 'auth_result') {
+          if ((m as { success: boolean }).success) {
+            authenticated = true;
+            sendPayload();
+          } else {
+            clearTimeout(timeoutHandle);
+            socket.destroy();
+            reject(new Error('Daemon authentication failed'));
+          }
+          continue;
+        }
+
+        // Reject immediately on daemon error frames so the CLI surfaces the
+        // real failure reason instead of hanging until the timeout fires.
+        if (m.type === 'error') {
+          clearTimeout(timeoutHandle);
+          socket.destroy();
+          reject(new Error((m as { message?: string }).message ?? 'Daemon returned an error'));
+          return;
+        }
+
+        // Only resolve on the expected response type; skip everything else
+        if (m.type === expectedResponseType) {
+          clearTimeout(timeoutHandle);
+          socket.destroy();
+          resolve(m);
+          return;
+        }
+        // Skip all other message types (auth_result, daemon_status, pong, session_info, tasks_changed, etc.)
+      }
+    });
+
+    socket.on('connect', () => {
+      if (sessionToken) {
+        socket.write(
+          serialize({
+            type: 'auth',
+            token: sessionToken,
+          } as unknown as import('../daemon/ipc-protocol.js').ClientMessage),
+        );
+      } else {
+        sendPayload();
+      }
+    });
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Chrome CDP restart helper
 // ---------------------------------------------------------------------------

package/src/cli.ts

@@ -20,7 +20,6 @@ import { ensureDaemonRunning } from './daemon/lifecycle.js';
 import { shouldAutoStartDaemon } from './daemon/connection-policy.js';
 import { renderMainScreen, updateStatusText, updateDaemonText, type MainScreenLayout } from './cli/main-screen.jsx';
 
-const SHORT_HASH_LENGTH = 8;
 const HEARTBEAT_INTERVAL_MS = 30_000;
 const HEARTBEAT_TIMEOUT_MS = 10_000;
 const RECONNECT_BASE_DELAY_MS = 1_000;
@@ -43,21 +42,6 @@ export function sanitizeUrlForDisplay(rawUrl: unknown): string {
   }
 }
 
-/**
- * Format a human-readable principal tag for display in permission prompts.
- * Core principals are omitted (empty string) since they're the default.
- * Skill principals show the skill name, shortened version hash, and target.
- */
-export function formatPrincipalTag(req: Pick<ConfirmationRequest, 'principalKind' | 'principalId' | 'principalVersion' | 'executionTarget'>): string {
-  if (!req.principalKind || req.principalKind === 'core') return '';
-  const name = req.principalId ?? req.principalKind;
-  // Show a shortened version hash when available (first 8 hex chars after any scheme prefix)
-  const versionSuffix = req.principalVersion
-    ? `@${req.principalVersion.replace(/^[^:]+:/, '').slice(0, SHORT_HASH_LENGTH)}`
-    : '';
-  const target = req.executionTarget ? ` \u2192 ${req.executionTarget}` : '';
-  return `[${req.principalKind}: ${name}${versionSuffix}${target}]`;
-}
 
 export async function startCli(): Promise<void> {
   const socketPath = getSocketPath();
@@ -186,13 +170,10 @@ export async function startCli(): Promise<void> {
 
   function renderConfirmationPrompt(req: ConfirmationRequest): void {
     const preview = formatCommandPreview(req);
-    const principalTag = formatPrincipalTag(req);
     process.stdout.write('\n');
     process.stdout.write(`\u250C ${req.toolName}: ${preview}\n`);
     process.stdout.write(`\u2502 Risk: ${req.riskLevel}${req.sandboxed ? '  [sandboxed]' : ''}\n`);
-    if (principalTag) {
-      process.stdout.write(`\u2502 Principal: ${principalTag}\n`);
-    } else if (req.executionTarget) {
+    if (req.executionTarget) {
       process.stdout.write(`\u2502 Target: ${req.executionTarget}\n`);
     }
     if (req.diff) {

package/src/config/bundled-skills/contacts/tools/contact-merge.ts

@@ -1,9 +1,57 @@
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
-import { executeContactMerge } from '../../../../tools/contacts/contact-merge.js';
+import { mergeContacts, getContact } from '../../../../contacts/contact-store.js';
 
-export async function run(
+export async function executeContactMerge(
   input: Record<string, unknown>,
-  context: ToolContext,
+  _context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  return executeContactMerge(input, context);
+  const keepId = input.keep_id as string | undefined;
+  const mergeId = input.merge_id as string | undefined;
+
+  if (!keepId || typeof keepId !== 'string') {
+    return { content: 'Error: keep_id is required', isError: true };
+  }
+  if (!mergeId || typeof mergeId !== 'string') {
+    return { content: 'Error: merge_id is required', isError: true };
+  }
+
+  // Show what will be merged for clarity
+  const keepContact = getContact(keepId);
+  const mergeContact = getContact(mergeId);
+
+  if (!keepContact) {
+    return { content: `Error: Contact "${keepId}" not found`, isError: true };
+  }
+  if (!mergeContact) {
+    return { content: `Error: Contact "${mergeId}" not found`, isError: true };
+  }
+
+  try {
+    const merged = mergeContacts(keepId, mergeId);
+
+    const channelList = merged.channels
+      .map((ch) => `  - ${ch.type}: ${ch.address}${ch.isPrimary ? ' (primary)' : ''}`)
+      .join('\n');
+
+    return {
+      content: [
+        `Merged "${mergeContact.displayName}" into "${keepContact.displayName}".`,
+        ``,
+        `Surviving contact (${merged.id}):`,
+        `  Name: ${merged.displayName}`,
+        `  Importance: ${merged.importance.toFixed(2)}`,
+        `  Interactions: ${merged.interactionCount}`,
+        merged.relationship ? `  Relationship: ${merged.relationship}` : null,
+        merged.channels.length > 0 ? `  Channels:\n${channelList}` : null,
+        ``,
+        `Deleted contact: ${mergeContact.displayName} (${mergeId})`,
+      ].filter(Boolean).join('\n'),
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
+  }
 }
+
+export { executeContactMerge as run };