@trillet-ai/mcp 0.7.3

package/dist/tools/calls.js

@@ -0,0 +1,391 @@
+import { z } from "zod";
+import { ok, guard, workspaceParam } from "../helpers.js";
+/**
+ * Call-history rows carry epoch-seconds in `timestamp` (there is no startTime
+ * field) — but the underlying startTime is written in mixed units by different
+ * services (backend TRI-839), and web test calls have been seen with the value
+ * off by exactly 1000x low. Detect the scale instead of trusting the unit.
+ */
+function toIso(epoch) {
+    if (typeof epoch !== "number" || !Number.isFinite(epoch) || epoch <= 0)
+        return null;
+    let ms;
+    if (epoch >= 1e12)
+        ms = epoch; // already milliseconds
+    else if (epoch >= 1e9)
+        ms = epoch * 1000; // seconds (the documented unit)
+    else if (epoch >= 1e6)
+        ms = epoch * 1e6; // seconds/1000 (buggy web-call rows)
+    else
+        return null;
+    return new Date(ms).toISOString();
+}
+/**
+ * Billing fields on a call row. customer_charge already INCLUDES the warm-transfer
+ * infra charge; warmTransferCharge/Minutes are the stored line-item split.
+ */
+function costFields(c) {
+    return {
+        cost: c.cost,
+        chargedDuration: c.charged_duration,
+        telephonyCost: c.telephonyCost,
+        warmTransferCharge: c.warmTransferCharge,
+        warmTransferMinutes: c.warmTransferMinutes,
+    };
+}
+const filterParams = {
+    agent_id: z.string().optional(),
+    flow_id: z.string().optional().describe("Filter to one call flow (pathway) id"),
+    direction: z.enum(["inbound", "outbound", "web"]).optional(),
+    status: z.string().optional(),
+    call_type: z.enum(["sip", "web"]).optional().describe("sip = real phone calls, web = browser calls"),
+    search: z.string().optional().describe("Free-text search (numbers, names, call ids)"),
+    from_date: z.string().optional().describe("ISO date, inclusive start of the window"),
+    to_date: z.string().optional().describe("ISO date, inclusive end of the window"),
+};
+function filterQuery(a) {
+    return {
+        agentId: a.agent_id,
+        pathwayId: a.flow_id,
+        direction: a.direction,
+        status: a.status,
+        callType: a.call_type,
+        search: a.search,
+        dateRange: a.from_date || a.to_date
+            ? JSON.stringify({
+                startDate: a.from_date ?? "1970-01-01",
+                endDate: a.to_date ?? new Date().toISOString(),
+            })
+            : undefined,
+    };
+}
+/** Heuristic markers a person would look for when skimming a bad call. */
+const HUMAN_REQUEST = /\b(speak|talk|put me through|transfer me|connect me)\b.{0,30}\b(person|human|someone|somebody|real|representative|agent|staff|manager|operator|receptionist)\b|\b(a|an) (real )?(person|human)\b/i;
+const MISUNDERSTOOD = /\b(sorry|apologi[sz]e|didn'?t (catch|get|hear|understand)|could you (repeat|say that again)|not sure i (understood|got that)|one more time)\b/i;
+const TRANSFER_FAILED = /\b(fail|no.?answer|busy|declin|timed? ?out|unavailable|not reachable|error|cancell?ed|not found)\b/i;
+/** transfer_call looks the destination up by exact friendly_name; a prompt that names a person or alias fails here. */
+const TRANSFER_NAME_MISMATCH = /Team '.*' not found/i;
+const SILENCE_END = /silence|inactiv|unresponsive|no.?input|no.?response/i;
+const VOICEMAIL = /voicemail|voice mail|answering machine|leave a message/i;
+const clip = (t, n = 160) => {
+    const s = String(t ?? "").replace(/\s+/g, " ").trim();
+    return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+};
+/**
+ * Compact digest of one call for trillet_review_calls: outcome, transfers and
+ * the transcript moments worth a human's attention. Pure, so it is testable.
+ */
+export function reviewCall(c) {
+    const transcript = Array.isArray(c.transcript)
+        ? c.transcript.map((t) => ({ role: String(t.role ?? ""), content: String(t.content ?? "") }))
+        : [];
+    const flags = [];
+    const excerpts = [];
+    const excerptAt = (i) => {
+        const lines = transcript.slice(Math.max(0, i - 1), i + 2).map((t) => `[${t.role}] ${clip(t.content)}`);
+        const text = lines.join(" / ");
+        if (text && excerpts.length < 4 && !excerpts.includes(text))
+            excerpts.push(text);
+    };
+    const duration = typeof c.duration === "number" ? c.duration : undefined;
+    const functionCalls = Array.isArray(c.functionCalls) ? c.functionCalls : [];
+    const transfers = functionCalls
+        .filter((f) => /transfer/i.test(String(f.name ?? f.function ?? "")))
+        .map((f) => {
+        // Call rows store the tool reply in `output`; older shapes used `result`.
+        const raw = f.output ?? f.result;
+        const result = clip(typeof raw === "string" ? raw : JSON.stringify(raw ?? ""), 120);
+        let args = f.arguments;
+        if (typeof args === "string") {
+            try {
+                args = JSON.parse(args);
+            }
+            catch {
+                /* keep the raw string */
+            }
+        }
+        const destination = args && typeof args === "object" ? args.team_name : undefined;
+        return { name: f.name ?? f.function, destination, result };
+    });
+    // Some rows carry the literal strings "None" or "null" in error.
+    const errorText = String(c.error ?? "").trim();
+    const hasError = errorText !== "" && !/^(none|null|undefined|false)$/i.test(errorText);
+    if (c._detailError)
+        flags.push("detail_unavailable");
+    if (hasError || /fail|error/i.test(String(c.status ?? "")))
+        flags.push("error");
+    // Browser test calls are short by nature; only phone calls count as suspiciously short.
+    if (duration !== undefined && duration < 20 && c.direction !== "web")
+        flags.push("very_short");
+    // A cold transfer ends the AI side of the call by design; an empty tool reply
+    // means the handoff went through, so that is not an early hang-up.
+    const coldHandoff = /transfer_cold/i.test(String(c.callEndReason ?? "")) &&
+        transfers.length > 0 &&
+        transfers[transfers.length - 1].result.replace(/"/g, "").trim() === "";
+    if (c.callEndedBy === "agent" && duration !== undefined && duration < 45 && !coldHandoff) {
+        flags.push("agent_ended_early");
+    }
+    if (SILENCE_END.test(String(c.callEndReason ?? "")))
+        flags.push("ended_on_silence");
+    // analyzedData carries keys like voicemail_left: false; only a true value or
+    // the words in the end reason / summary mean a voicemail actually happened.
+    const analyzed = c.analyzedData && typeof c.analyzedData === "object" ? c.analyzedData : {};
+    const voicemailFlag = Object.entries(analyzed).some(([k, v]) => /voicemail|answering_machine/i.test(k) && (v === true || v === "true"));
+    if (voicemailFlag || VOICEMAIL.test(`${c.callEndReason ?? ""} ${c.summary ?? ""}`))
+        flags.push("voicemail");
+    const failedTransfers = transfers.filter((t) => TRANSFER_FAILED.test(t.result));
+    if (failedTransfers.length)
+        flags.push("transfer_failed");
+    if (transfers.some((t) => TRANSFER_NAME_MISMATCH.test(t.result)))
+        flags.push("transfer_name_mismatch");
+    // Failed transfer, then the call died on silence: the prompt told the agent
+    // not to speak once a transfer starts and gave it no failure branch.
+    if (failedTransfers.length && SILENCE_END.test(String(c.callEndReason ?? ""))) {
+        flags.push("silent_after_failed_transfer");
+    }
+    let misunderstood = 0;
+    transcript.forEach((t, i) => {
+        const isUser = /user|caller|customer|human/i.test(t.role);
+        const isAgent = /agent|assistant|bot|ai/i.test(t.role);
+        if (isUser && HUMAN_REQUEST.test(t.content)) {
+            if (transfers.length === 0 && !flags.includes("asked_for_human_no_transfer")) {
+                flags.push("asked_for_human_no_transfer");
+            }
+            excerptAt(i);
+        }
+        if (isAgent && MISUNDERSTOOD.test(t.content)) {
+            misunderstood += 1;
+            if (misunderstood <= 2)
+                excerptAt(i);
+        }
+    });
+    if (misunderstood >= 2)
+        flags.push("repeated_misunderstanding");
+    if (flags.includes("transfer_failed") || flags.includes("agent_ended_early")) {
+        excerptAt(Math.max(0, transcript.length - 2));
+    }
+    return {
+        id: c._id,
+        time: toIso(c.timestamp) ?? (c.startTime ? new Date(c.startTime).toISOString() : null),
+        direction: c.direction,
+        duration,
+        status: c.status,
+        endedBy: c.callEndedBy,
+        endReason: c.callEndReason,
+        transfers,
+        flags,
+        excerpts,
+        summary: clip(c.summary, 200) || undefined,
+    };
+}
+export function registerCallTools(server, client) {
+    server.registerTool("trillet_list_calls", {
+        title: "List call history",
+        description: "List recent calls in the workspace (newest first) with time, duration, status, and full billing fields per call: cost (customer charge in USD, includes any warm-transfer charge), chargedDuration, telephonyCost, warmTransferCharge + warmTransferMinutes (flat-rate human-to-human leg after a warm/whisper transfer, stored as its own line item). Filterable by agent, flow, direction, status, call type, date window, and free text. Use trillet_get_call for one call's transcript and analysis, trillet_get_call_metrics for aggregates.",
+        inputSchema: {
+            ...filterParams,
+            page: z.number().default(1),
+            limit: z.number().default(15),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async (a) => {
+        const res = await client.request("GET", "/v2/api/call-history/", {
+            query: {
+                ...filterQuery(a),
+                page: a.page,
+                limit: a.limit,
+                slim: "true",
+                includeTranscripts: "false",
+            },
+            workspaceId: a.workspace_id,
+        });
+        const calls = res.data ?? [];
+        return ok({
+            totalCount: res.pagination?.totalCount,
+            calls: calls.map((c) => ({
+                id: c._id,
+                time: toIso(c.timestamp),
+                direction: c.direction,
+                duration: c.duration,
+                status: c.status,
+                agent: c.agent,
+                callFlow: c.callFlowName,
+                from: c.fromPhoneNumber,
+                to: c.toPhoneNumber,
+                batchId: c.batchId,
+                ...costFields(c),
+            })),
+        });
+    }));
+    server.registerTool("trillet_get_call_metrics", {
+        title: "Get call metrics (aggregates)",
+        description: "Aggregate call-history metrics for a filter window without paging individual calls: totalCalls, avgDuration (m:ss string), completionRate. For exact minutes per month use trillet_get_usage include_minutes_breakdown=true (last 3 months) or sum durations from trillet_list_calls; for what was actually charged use trillet_list_transactions.",
+        inputSchema: { ...filterParams, ...workspaceParam },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async (a) => {
+        const res = await client.request("GET", "/v2/api/call-history/metrics", {
+            query: filterQuery(a),
+            workspaceId: a.workspace_id,
+        });
+        return ok(res);
+    }));
+    server.registerTool("trillet_get_call", {
+        title: "Get call transcript and analysis",
+        description: "Fetch one call: transcript, post-call analyzedData, summary, recording URL, and the billing breakdown (cost = customer charge incl. warm-transfer component; warmTransferCharge/Minutes split out; agentSegments for multi-agent calls; transferTiming). include_function_calls=true adds the in-call tool/function invocations (including IVR navigator decisions and DTMF sends, invokedBy 'ivr_navigator'). The primary debugging tool.",
+        inputSchema: {
+            call_id: z.string(),
+            include_function_calls: z
+                .boolean()
+                .default(false)
+                .describe("Include functionCalls: every in-call tool invocation with args and results (can be long)"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ call_id, include_function_calls, workspace_id }) => {
+        const res = await client.request("GET", `/v2/api/call-history/${call_id}`, {
+            workspaceId: workspace_id,
+        });
+        const c = res.callHistory ?? res.data ?? res;
+        const out = {
+            id: c._id,
+            time: toIso(c.timestamp),
+            direction: c.direction,
+            duration: c.duration,
+            status: c.status,
+            error: c.error,
+            agent: c.agent,
+            callFlow: c.callFlowName,
+            from: c.fromPhoneNumber,
+            to: c.toPhoneNumber,
+            ...costFields(c),
+            transferTiming: c.transferTiming,
+            agentSegments: c.agentSegments,
+            summary: c.summary,
+            analyzedData: c.analyzedData,
+            recordingUrl: c.recordingUrl ?? c.publicRecordingUrl,
+            transcript: Array.isArray(c.transcript)
+                ? c.transcript.map((t) => `[${t.role}] ${t.content}`)
+                : c.transcript,
+        };
+        if (include_function_calls)
+            out.functionCalls = c.functionCalls;
+        return ok(out);
+    }));
+    server.registerTool("trillet_review_calls", {
+        title: "Review recent calls for problems",
+        description: "Read the recent calls of one flow (flow_id), one agent (agent_id) or the whole workspace and return a compact problem digest: per call the outcome, who ended it and why, transfers and how they went (destination + tool reply; an empty reply on a cold transfer means the call was handed off), and the flagged moments (the caller asked for a person but no transfer happened, transfer_failed, transfer_name_mismatch = the agent asked for a destination that is not an exact transfer friendly_name, silent_after_failed_transfer, the agent kept saying it did not understand, the call was very short or ended in silence, voicemail, errors) with the transcript lines around each. Use it for \"what went wrong\", \"how are calls going\", \"improve the agent from real calls\"; then group the findings, cite call ids, and propose or apply fixes. Use trillet_get_call for a full transcript when a flag needs more context.",
+        inputSchema: {
+            flow_id: z.string().optional().describe("Review one call flow (pathway) id"),
+            agent_id: z.string().optional(),
+            hours: z.number().min(1).max(720).default(24).describe("Look-back window in hours (default 24, max 30 days)"),
+            limit: z.number().min(1).max(40).default(20).describe("How many of the most recent calls to read in detail"),
+            include_ok: z.boolean().default(false).describe("Also list the calls that raised no flag"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async (a) => {
+        const to = new Date();
+        const from = new Date(to.getTime() - a.hours * 3600 * 1000);
+        const list = await client.request("GET", "/v2/api/call-history/", {
+            query: {
+                pathwayId: a.flow_id,
+                agentId: a.agent_id,
+                dateRange: JSON.stringify({ startDate: from.toISOString(), endDate: to.toISOString() }),
+                page: 1,
+                limit: a.limit,
+                slim: "true",
+                includeTranscripts: "false",
+            },
+            workspaceId: a.workspace_id,
+        });
+        const rows = list.data ?? [];
+        const details = [];
+        for (let i = 0; i < rows.length; i += 5) {
+            // Five at a time: enough to be quick, gentle on the API.
+            // eslint-disable-next-line no-await-in-loop
+            const batch = await Promise.all(rows.slice(i, i + 5).map(async (r) => {
+                try {
+                    const res = await client.request("GET", `/v2/api/call-history/${r._id}`, {
+                        workspaceId: a.workspace_id,
+                    });
+                    return res.callHistory ?? res.data ?? res;
+                }
+                catch {
+                    return { ...r, _detailError: true };
+                }
+            }));
+            details.push(...batch);
+        }
+        const reviewed = details.map(reviewCall);
+        const flagged = reviewed.filter((c) => c.flags.length > 0);
+        const byStatus = {};
+        const endedBy = {};
+        const flagCounts = {};
+        let totalDuration = 0;
+        reviewed.forEach((c) => {
+            byStatus[c.status ?? "unknown"] = (byStatus[c.status ?? "unknown"] ?? 0) + 1;
+            endedBy[c.endedBy ?? "unknown"] = (endedBy[c.endedBy ?? "unknown"] ?? 0) + 1;
+            totalDuration += c.duration ?? 0;
+            c.flags.forEach((f) => {
+                flagCounts[f] = (flagCounts[f] ?? 0) + 1;
+            });
+        });
+        return ok({
+            window: { hours: a.hours, from: from.toISOString(), to: to.toISOString() },
+            totals: {
+                callsInWindow: list.pagination?.totalCount ?? rows.length,
+                reviewed: reviewed.length,
+                flagged: flagged.length,
+                avgDurationSec: reviewed.length ? Math.round(totalDuration / reviewed.length) : 0,
+                byStatus,
+                endedBy,
+                flagCounts,
+            },
+            flagged,
+            ok: a.include_ok
+                ? reviewed.filter((c) => c.flags.length === 0)
+                : { count: reviewed.length - flagged.length },
+            note: reviewed.length === 0
+                ? "No calls in this window. Widen hours or check the flow id."
+                : "Group the flags into at most three problems, cite the call ids and excerpts as evidence, and say what change fixes each. Flags are heuristics: read the excerpt before concluding.",
+        });
+    }));
+    server.registerTool("trillet_start_outbound_call", {
+        title: "Start outbound call (REAL CALL)",
+        description: "Place a REAL outbound phone call from an agent to a phone number. This dials a real person and consumes call minutes. Always confirm with the user before calling; requires confirm=true.",
+        inputSchema: {
+            to: z.string().describe("Destination number in E.164 format, e.g. +61412345678"),
+            agent_id: z.string(),
+            dynamic_variables: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe("Per-call variables substituted into the prompt as {{key}}"),
+            from_phone_number_id: z.string().optional(),
+            confirm: z
+                .boolean()
+                .describe("Must be true. Only set after the user has explicitly approved this call."),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, guard(async ({ to, agent_id, dynamic_variables, from_phone_number_id, confirm, workspace_id }) => {
+        if (!confirm) {
+            return ok({
+                blocked: true,
+                message: "Refusing to place the call: confirm=false. Ask the user to approve dialing " +
+                    to +
+                    " and retry with confirm=true.",
+            });
+        }
+        const body = { to, call_agent_id: agent_id };
+        if (dynamic_variables)
+            body.dynamic_variables = dynamic_variables;
+        if (from_phone_number_id)
+            body.from_phone_number_id = from_phone_number_id;
+        const res = await client.request("POST", "/v1/api/call", {
+            body,
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+}