@spekoai/mcp-calls 0.4.0 → 0.4.1

package/README.md

@@ -47,7 +47,7 @@ backing server instead of running in-process, set `SPEKO_MCP_SERVER_URL`.
 | --- | --- |
 | `lookup_business(name, location?, phone_number?)` | Resolve a business → dialable candidates + a signed `dial_token` per callable one (the only path that can authorize a call). Pass `phone_number` (E.164 — e.g. found via the agent's web search) to skip the directory lookup; still carrier-verified as a business line. |
 | `make_call(dial_token, objective, caller_name, context?)` | Place the disclosed, objective-scoped call; wait for it to finish; return the `OUTCOME` + transcript. Honest `connected`/`answered`/`not_connected`. |
-| `call_number(phone_number, objective, caller_name)` | Disclosed PERSONAL call to a specific number (e.g. a friend) — mobiles allowed. On by default (set `SPEKO_ALLOW_DIRECT_DIAL=0` to restrict to business lines). |
+| `call_number(phone_number, objective, caller_name)` | Disclosed call to a number you have or found via web search (business or personal) — the default path once you have the number. Mobiles allowed. On by default (`SPEKO_ALLOW_DIRECT_DIAL=0` restricts to business lines). |
 | `get_call(call_id)` | Read-only: re-check a call's status, `OUTCOME`, and transcript. Never dials. |
 | `check_call_readiness()` | Read-only preflight: auth, credit balance, outbound caller-ID. Never dials. |
 

package/dist/index.js

@@ -147,13 +147,32 @@ var init_client = __esm({
        */
       async getSession(sessionId) {
         const resp = await fetch(`${this.baseUrl}/v1/sessions/${encodeURIComponent(sessionId)}`, {
-          headers: { accept: "application/json", authorization: `Bearer ${this.apiKey}` }
+          headers: { accept: "application/json", authorization: `Bearer ${this.apiKey}` },
+          signal: AbortSignal.timeout(3e4)
         });
         if (!resp.ok) {
           throw new SpekoApiError(`GET /v1/sessions/${sessionId} failed`, resp.status, "session_fetch_failed");
         }
         return await resp.json();
       }
+      /**
+       * Raw `GET /v1/calls/{id}/events` — the call's event timeline. We poll this to find
+       * the AUTHORITATIVE end of the call (`room_finished`), because the call `status` can
+       * flip to "failed" early (a first-audio SLA timeout) while the call is still live and
+       * a full conversation follows. Returns a best-effort array (each event carries an
+       * `event_type`); an empty array on an unexpected shape.
+       */
+      async getEvents(callId) {
+        const resp = await fetch(`${this.baseUrl}/v1/calls/${encodeURIComponent(callId)}/events`, {
+          headers: { accept: "application/json", authorization: `Bearer ${this.apiKey}` },
+          signal: AbortSignal.timeout(3e4)
+        });
+        if (!resp.ok) {
+          throw new SpekoApiError(`GET /v1/calls/${callId}/events failed`, resp.status, "events_fetch_failed");
+        }
+        const body = await resp.json();
+        return Array.isArray(body.events) ? body.events : [];
+      }
     };
   }
 });
@@ -195,7 +214,7 @@ var init_errors = __esm({
 });
 
 // ../server/dist/constants.js
-var MAX_CALL_SECONDS, MIN_CALL_SECONDS, FAST_POLLS, FAST_POLL_SECONDS, SLOW_POLL_SECONDS, STUB_DIAL_STATUS, NOT_PLACED_STATUS, NOT_CONNECTED_STATUS, MIN_CALL_BALANCE_USD, TERMINAL_STATUSES, OUTCOME_MARKER, DIAL_INTENT_LANGUAGE, DIAL_STT_KEYWORDS, MAX_CALLER_NAME_CHARS, OBJECTIVE_MIN_CHARS, E164_RE, ALLOWED_LINE_TYPES, US_PREMIUM_RE, EMERGENCY_NUMBERS, OBJECTIVE_BLOCK_RE, DIAL_TOKEN_DEFAULT_TTL_SECONDS, DIAL_TOKEN_SECRET_ENV, QUIET_START_HOUR, QUIET_END_HOUR, MAKE_CALL_NEXT_STEP, MAKE_CALL_DIAL_NEXT_STEP, CHECK_READINESS_NEXT_STEP, AUTH_NEXT_STEP;
+var MAX_CALL_SECONDS, MIN_CALL_SECONDS, FAST_POLLS, FAST_POLL_SECONDS, SLOW_POLL_SECONDS, STUB_DIAL_STATUS, NOT_PLACED_STATUS, NOT_CONNECTED_STATUS, MIN_CALL_BALANCE_USD, HARD_TERMINAL_STATUSES, ROOM_END_EVENTS, HARD_FAILURE_EVENTS, OUTCOME_MARKER, BARE_OUTCOME_RE, DIAL_INTENT_LANGUAGE, DIAL_STT_KEYWORDS, MAX_CALLER_NAME_CHARS, OBJECTIVE_MIN_CHARS, E164_RE, ALLOWED_LINE_TYPES, US_PREMIUM_RE, EMERGENCY_NUMBERS, OBJECTIVE_BLOCK_RE, DIAL_TOKEN_DEFAULT_TTL_SECONDS, DIAL_TOKEN_SECRET_ENV, QUIET_START_HOUR, QUIET_END_HOUR, MAKE_CALL_NEXT_STEP, MAKE_CALL_DIAL_NEXT_STEP, CHECK_READINESS_NEXT_STEP, AUTH_NEXT_STEP;
 var init_constants = __esm({
   "../server/dist/constants.js"() {
     "use strict";
@@ -208,19 +227,20 @@ var init_constants = __esm({
     NOT_PLACED_STATUS = "not_placed";
     NOT_CONNECTED_STATUS = "not_connected";
     MIN_CALL_BALANCE_USD = 0.5;
-    TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+    HARD_TERMINAL_STATUSES = /* @__PURE__ */ new Set([
       "completed",
       "ended",
-      "failed",
       "no_answer",
       "no-answer",
       "busy",
       "canceled",
       "cancelled",
-      "error",
       "hangup"
     ]);
+    ROOM_END_EVENTS = /* @__PURE__ */ new Set(["room_finished", "call.end_tool.completed"]);
+    HARD_FAILURE_EVENTS = /* @__PURE__ */ new Set(["agent.dispatch_failed", "sip.dial_failed"]);
     OUTCOME_MARKER = "OUTCOME:";
+    BARE_OUTCOME_RE = /^(failed|abandoned|completed?|error|no[_-]?answer|busy|canceled|cancelled|ended|success|unknown|in[_-]?progress|dialing)$/i;
     DIAL_INTENT_LANGUAGE = "en";
     DIAL_STT_KEYWORDS = ["reservation", "table for", "tonight", "8 PM"];
     MAX_CALLER_NAME_CHARS = 80;
@@ -457,6 +477,12 @@ var init_timezone = __esm({
       "925": "America/Los_Angeles",
       "949": "America/Los_Angeles",
       "971": "America/Los_Angeles",
+      // Bay Area / NorCal overlays (628=SF, 669=San Jose, 341=Oakland) + Central Valley (209/279)
+      "628": "America/Los_Angeles",
+      "669": "America/Los_Angeles",
+      "341": "America/Los_Angeles",
+      "209": "America/Los_Angeles",
+      "279": "America/Los_Angeles",
       // Mountain (Phoenix = no DST)
       "303": "America/Denver",
       "385": "America/Denver",
@@ -916,7 +942,7 @@ function assessConnection(session, transcript) {
   const ccidRaw = session.phoneCall?.callControlId;
   const callControlId = typeof ccidRaw === "string" && ccidRaw.trim() ? ccidRaw : null;
   const carrierBilled = Array.isArray(session.usage) && session.usage.some(isCarrierUsage);
-  const connected = Boolean(callControlId) || carrierBilled || answered;
+  const connected = answered || Boolean(callControlId) || carrierBilled;
   return { connected, answered, callControlId, carrierBilled };
 }
 var CARRIER_PROVIDERS, CARRIER_METRIC_RE;
@@ -951,7 +977,10 @@ function shapeCallSummary(input) {
     summary.status = NOT_CONNECTED_STATUS;
     summary.reason = NOT_CONNECTED_REASON;
   } else if (connected && !assessment.answered) {
+    summary.status = "no_answer";
     summary.reason = NO_ANSWER_REASON;
+  } else if (connected && assessment.answered) {
+    summary.status = "completed";
   }
   return summary;
 }
@@ -961,7 +990,7 @@ var init_summary = __esm({
     "use strict";
     init_constants();
     init_assess();
-    NOT_CONNECTED_REASON = "The session and AI agent started, but no telephony leg reached the carrier (callControlId null, no carrier minutes) \u2014 the phone never rang.";
+    NOT_CONNECTED_REASON = "No real two-way call took place \u2014 the AI agent started but the other party was never heard (no answer, voicemail, or the call did not truly connect).";
     NO_ANSWER_REASON = "The call connected but the other party never spoke (no answer / voicemail / hung up before responding).";
   }
 });
@@ -1004,7 +1033,8 @@ async function makeCall(input, deps) {
   const offset = typeof payload.utc_offset_minutes === "number" ? payload.utc_offset_minutes : null;
   const quietReason = quietHoursReason(offset);
   if (quietReason) {
-    const next = offset == null ? MAKE_CALL_NEXT_STEP : "Wait until destination business hours (08:00-21:00 local time) and run make_call again.";
+    const direct = deps.allowAnyLineType === true;
+    const next = offset == null ? direct ? "Re-run call_number with utc_offset_minutes for the destination's city (e.g. -420 US Pacific summer, -300 US Eastern)." : MAKE_CALL_NEXT_STEP : `Wait until destination business hours (08:00-21:00 local time) and run ${direct ? "call_number" : "make_call"} again.`;
     throw new RejectionError(quietReason, next);
   }
   const objectiveReason = objectiveBlockedReason(input.objective);
@@ -1021,9 +1051,10 @@ async function makeCall(input, deps) {
   const body = {
     to: e164,
     ...fromNumber ? { from: fromNumber } : {},
-    // optimizeFor=latency is best for a LIVE call: the selector keeps gpt-5 (best time-to-
-    // first-token) + a fast streaming STT, avoiding the multi-second dead air the other modes
-    // route to. Benchmark-driven via Speko's selector.
+    // optimizeFor=latency is best for a LIVE call: it routes to a fast streaming STT + a low
+    // time-to-first-token LLM, avoiding the multi-second dead air the balanced/accuracy modes
+    // introduce. The actual LLM/TTS/STT models are pinned below via constraints
+    // (cfg.llmPin / cfg.ttsPin / cfg.sttPin), not left to the selector.
     intent: { language: DIAL_INTENT_LANGUAGE, optimizeFor: deps.cfg.optimizeFor },
     // A specific `voice` (cfg.voice) is safe ONLY because it's an ElevenLabs voice matching the
     // ElevenLabs TTS pin below — always verify a voice with scripts/verify-tts.mjs first. A voice
@@ -1092,43 +1123,68 @@ async function runPhoneCall(body, maxSeconds, deps, sleep) {
   }
   let elapsed = 0;
   let polls = 0;
-  while (!TERMINAL_STATUSES.has(status) && elapsed < maxSeconds) {
+  let ended = false;
+  while (elapsed < maxSeconds) {
     const interval = polls < FAST_POLLS ? FAST_POLL_SECONDS : SLOW_POLL_SECONDS;
     await sleep(interval * 1e3);
     elapsed += interval;
     polls += 1;
+    let events;
     try {
-      const d = await deps.client.getCall(callId);
-      status = String(d.status ?? "").toLowerCase();
-    } catch (e) {
-      throw new AppError(e.message, {
-        statusCode: 502,
-        nextStep: `Do not dial again; the call (call_id '${callId}') may still be in progress. Check it with get_call('${callId}').`
-      });
+      events = await deps.client.getEvents(callId);
+    } catch {
+      try {
+        const d = await deps.client.getCall(callId);
+        status = String(d.status ?? "").toLowerCase();
+      } catch (e) {
+        throw new AppError(e.message, {
+          statusCode: 502,
+          nextStep: `Do not dial again; the call (call_id '${callId}') may still be in progress. Check it with get_call('${callId}').`
+        });
+      }
+      if (HARD_TERMINAL_STATUSES.has(status)) {
+        ended = true;
+        break;
+      }
+      continue;
+    }
+    const types = new Set(events.map((e) => String(e.event_type ?? e.type ?? "").toLowerCase()));
+    if ([...ROOM_END_EVENTS].some((t) => types.has(t)) || [...HARD_FAILURE_EVENTS].some((t) => types.has(t))) {
+      ended = true;
+      break;
     }
   }
-  if (!TERMINAL_STATUSES.has(status)) {
+  if (!ended) {
     return {
       ...baseSummary(callId, to, from),
       status: "timeout",
       duration_seconds: elapsed,
       connected: true,
-      reason: "Reached the wait limit before the call reached a terminal state; it may still be in progress."
+      reason: "Reached the wait limit before the call ended; it may still be in progress."
     };
   }
   return finalize(callId, to, from, status, elapsed, deps);
 }
 async function finalize(callId, to, from, status, elapsed, deps) {
+  const sleep = deps.sleep ?? defaultSleep;
   let transcript = null;
   let transcriptError;
   let outcome = null;
-  try {
-    const detail = await deps.client.getCall(callId);
-    transcript = detail.transcript ?? null;
-    const reportOutcome = detail.report?.outcome;
-    outcome = typeof reportOutcome === "string" && reportOutcome.trim() ? reportOutcome.trim() : extractOutcome(transcript);
-  } catch (e) {
-    transcriptError = e.message;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      const detail = await deps.client.getCall(callId);
+      transcript = detail.transcript ?? null;
+      const reportOutcome = typeof detail.report?.outcome === "string" ? detail.report.outcome.trim() : "";
+      const substantive = reportOutcome && !BARE_OUTCOME_RE.test(reportOutcome) ? reportOutcome : "";
+      outcome = substantive || extractOutcome(transcript);
+      transcriptError = void 0;
+    } catch (e) {
+      transcriptError = e.message;
+    }
+    if (extractReply(transcript) !== null)
+      break;
+    if (attempt < 2)
+      await sleep(3e3);
   }
   let session = null;
   try {
@@ -1172,7 +1228,7 @@ async function callNumber(input, deps) {
   if (!deps.cfg.allowDirectDial) {
     throw new RejectionError("Direct dialing has been turned off on this deployment (SPEKO_ALLOW_DIRECT_DIAL is set to off), so call_number is disabled and cannot place this call. (Direct dialing is on by default.)", "To call a business, use lookup_business + make_call instead. To use call_number, unset SPEKO_ALLOW_DIRECT_DIAL (or set it to 1) in the MCP's env and restart, then retry.");
   }
-  const e164 = typeof input.phoneNumber === "string" ? input.phoneNumber.trim() : "";
+  const e164 = typeof input.phoneNumber === "string" ? input.phoneNumber.replace(/[^\d+]/g, "") : "";
   const blocked = dialBlockedReason(e164);
   if (blocked) {
     throw new RejectionError(blocked, "Pass a valid E.164 number (e.g. +77011234567) that you have consent to call.");
@@ -1328,8 +1384,9 @@ async function describeCall(callId, client) {
   const transcript = detail.transcript ?? null;
   const to = strField(detail.metadata, "to") ?? strField(detail.metadata, "dialedNumber");
   const from = strField(detail.metadata, "from");
-  const reportOutcome = detail.report?.outcome;
-  const outcome = typeof reportOutcome === "string" && reportOutcome.trim() ? reportOutcome.trim() : extractOutcome(transcript);
+  const reportOutcome = typeof detail.report?.outcome === "string" ? detail.report.outcome.trim() : "";
+  const substantive = reportOutcome && !BARE_OUTCOME_RE.test(reportOutcome) ? reportOutcome : "";
+  const outcome = substantive || extractOutcome(transcript);
   let session = null;
   try {
     session = await client.getSession(callId);
@@ -2049,7 +2106,9 @@ function getServerClient() {
 
 // src/tools/CallNumberTool.ts
 var schema2 = z2.object({
-  phone_number: z2.string().describe("Number to call, E.164 (e.g. +77011234567). A real number the user has consent to call."),
+  phone_number: z2.string().describe(
+    "Number to call in full international E.164 \u2014 leading + and country code (e.g. +14152857117, NOT (415) 285-7117). A number the user asked you to call or explicitly provided."
+  ),
   objective: z2.string().describe("What to say / accomplish, e.g. 'Tell Sam that John says happy birthday and misses him.'"),
   caller_name: z2.string().describe("Name of the human the call is on behalf of (1-80 chars); spoken in the AI-disclosure opening."),
   recipient_name: z2.string().optional().describe("Who you're calling, used in the greeting (e.g. 'Sam')."),
@@ -2085,7 +2144,7 @@ function summarize(s) {
 }
 var CallNumberTool = class extends MCPTool2 {
   name = "call_number";
-  description = "Place a disclosed PERSONAL call to a specific phone number (e.g. a friend) \u2014 NOT a business lookup. Available by default. Every call opens with the non-removable AI disclosure, and quiet hours + the no-sell/no-spam screen still apply (mobiles are allowed here, unlike make_call). Use lookup_business + make_call for businesses; use this only for a number the user explicitly provides and has consent to call.";
+  description = "Place a disclosed call to a phone number you HAVE or FOUND (e.g. via web search) \u2014 the DEFAULT path for calling any business or person. Works with just the user's Speko key, no extra setup. Every call opens with the non-removable AI disclosure; quiet hours and the no-sell/no-spam screen still apply (mobiles allowed). lookup_business + make_call is the OPTIONAL verified-directory path (it needs the server's carrier/directory keys); prefer call_number when you already have or found the number. Only dial a number the user asked you to call or explicitly provided \u2014 never one you invented.";
   schema = schema2;
   annotations = {
     title: "Call a Number",
@@ -2098,6 +2157,8 @@ var CallNumberTool = class extends MCPTool2 {
     const maxWait = clamp2(input.max_duration_seconds ?? MAX_WAIT, MIN_WAIT, MAX_WAIT);
     const client = getServerClient();
     let elapsed = 0;
+    void this.reportProgress(0, maxWait, "Placing the call\u2026").catch(() => {
+    });
     const timer = setInterval(() => {
       elapsed += HEARTBEAT_MS / 1e3;
       void this.reportProgress(elapsed, maxWait, `Call in progress \u2014 ${elapsed}s elapsed`).catch(() => {
@@ -2261,6 +2322,8 @@ var MakeCallTool = class extends MCPTool6 {
     const maxWait = clamp3(input.max_duration_seconds ?? MAX_WAIT2, MIN_WAIT2, MAX_WAIT2);
     const client = getServerClient();
     let elapsed = 0;
+    void this.reportProgress(0, maxWait, "Placing the call\u2026").catch(() => {
+    });
     const timer = setInterval(() => {
       elapsed += HEARTBEAT_MS2 / 1e3;
       void this.reportProgress(elapsed, maxWait, `Call in progress \u2014 ${elapsed}s elapsed`).catch(() => {
@@ -2294,7 +2357,7 @@ if (cmd === "init" || cmd === "setup" || cmd === "login") {
 loadEnv();
 var server = new MCPServer({
   name: "speko-calls",
-  version: "0.4.0",
+  version: "0.4.1",
   transport: { type: "stdio" }
 });
 server.addTool(LookupBusinessTool);