@trillet-ai/mcp 0.7.3

package/dist/textcall/session.js

@@ -0,0 +1,209 @@
+/**
+ * Parent-side text-call session manager: forks the worker (see worker.ts for
+ * why it must be a child process), speaks the IPC protocol, and turns the
+ * stream of agent events into blocking "send a turn, get the reply" calls.
+ */
+import { fork } from "node:child_process";
+import { randomUUID } from "node:crypto";
+const sessions = new Map();
+export function getSession(id) {
+    return sessions.get(id);
+}
+export function activeSessionCount(workspaceId) {
+    let n = 0;
+    for (const s of sessions.values()) {
+        if (s.ended)
+            continue;
+        if (workspaceId && s.workspaceId !== workspaceId)
+            continue;
+        n += 1;
+    }
+    return n;
+}
+export function listSessions() {
+    return [...sessions.values()];
+}
+/** An unknown-session error that explains the two ways sessions disappear. */
+export function unknownSession(id) {
+    return new Error(`Unknown text-call session '${id}'. Sessions live only inside one MCP server process — ` +
+        `start a new call with trillet_start_text_call. (Active: ${[...sessions.values()]
+            .filter((s) => !s.ended)
+            .map((s) => s.id)
+            .join(", ") || "none"})`);
+}
+function notify(s) {
+    const waiters = s.waiters.splice(0);
+    for (const w of waiters)
+        w();
+}
+function markEnded(s, reason) {
+    if (!s.ended) {
+        s.ended = true;
+        s.endReason = reason;
+    }
+    notify(s);
+}
+/** Fork the worker and wire IPC. `selfPath` is this server's own entry file. */
+export function createSession(opts) {
+    const child = fork(opts.selfPath, [], {
+        env: { ...process.env, TRILLET_MCP_TEXTCALL_WORKER: "1" },
+        // stdout MUST be discarded: rtc-node's pino logs there, and in the parent
+        // stdout is the MCP transport. stderr is forwarded for debuggability.
+        stdio: ["ignore", "ignore", "pipe", "ipc"],
+        execArgv: [],
+    });
+    const s = {
+        id: `tc_${randomUUID().slice(0, 8)}`,
+        child,
+        roomName: opts.roomName,
+        callId: opts.callId,
+        callHistoryId: opts.callHistoryId,
+        agentId: opts.agentId,
+        agentName: opts.agentName,
+        workspaceId: opts.workspaceId,
+        transcript: [],
+        queue: [],
+        ended: false,
+        endReason: null,
+        lastActivityAt: Date.now(),
+        waiters: [],
+        notifyWaiters: () => notify(s),
+        nextIpcId: 1,
+        pending: new Map(),
+    };
+    child.stderr?.on("data", (d) => process.stderr.write(`[textcall ${s.id}] ${d}`));
+    child.on("message", (msg) => {
+        if (msg && typeof msg.id === "number" && s.pending.has(msg.id)) {
+            const p = s.pending.get(msg.id);
+            s.pending.delete(msg.id);
+            if (msg.ok)
+                p.resolve(msg);
+            else
+                p.reject(new Error(msg.error || "worker error"));
+            return;
+        }
+        if (msg?.event === "agent_turn") {
+            const identity = String(msg.identity ?? "");
+            const text = String(msg.text ?? "").trim();
+            // Transcription streams also echo caller turns under the caller's own
+            // identity; only agent-identity streams are agent speech.
+            const isAgent = identity.startsWith("agent-") || identity.startsWith("web-agent");
+            if (!isAgent || !text)
+                return;
+            // The agent occasionally re-emits an identical segment; drop exact
+            // repeats of the latest turn (same dedup the dashboard panel applies).
+            const last = s.transcript[s.transcript.length - 1];
+            if (last?.role === "agent" && last.text === text)
+                return;
+            s.transcript.push({ role: "agent", text, at: new Date().toISOString() });
+            s.queue.push(text);
+            s.lastActivityAt = Date.now();
+            notify(s);
+        }
+        else if (msg?.event === "disconnected") {
+            markEnded(s, "call_ended");
+        }
+    });
+    child.on("exit", () => markEnded(s, s.ended ? s.endReason : "worker_exited"));
+    child.on("error", () => markEnded(s, "worker_error"));
+    sessions.set(s.id, s);
+    return s;
+}
+/** Send an IPC command and await the worker's reply. */
+export function rpc(s, cmd, params, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        if (!s.child.connected) {
+            reject(new Error("text-call worker is not running (call already ended?)"));
+            return;
+        }
+        const id = s.nextIpcId++;
+        const timer = setTimeout(() => {
+            s.pending.delete(id);
+            reject(new Error(`worker '${cmd}' timed out after ${timeoutMs / 1000}s`));
+        }, timeoutMs);
+        s.pending.set(id, {
+            resolve: (m) => {
+                clearTimeout(timer);
+                resolve(m);
+            },
+            reject: (e) => {
+                clearTimeout(timer);
+                reject(e);
+            },
+        });
+        s.child.send({ id, cmd, ...params });
+    });
+}
+/** Resolve when the session sees a new event, or after ms. True = event. */
+function waitEvent(s, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), ms);
+        s.waiters.push(() => {
+            clearTimeout(timer);
+            resolve(true);
+        });
+    });
+}
+/**
+ * Collect the agent's next turn(s): wait for the first completed turn (or the
+ * call ending), then keep draining until `quietMs` passes with nothing new —
+ * node flows can chain several messages (say node + conversation node) in one
+ * logical turn, and a farewell is often followed ~1s later by the disconnect.
+ */
+export async function collectAgentTurns(s, { timeoutMs, quietMs = 1500 }) {
+    const deadline = Date.now() + timeoutMs;
+    const turns = [];
+    while (s.queue.length === 0 && !s.ended && Date.now() < deadline) {
+        await waitEvent(s, Math.min(500, Math.max(50, deadline - Date.now())));
+    }
+    const timedOut = s.queue.length === 0 && !s.ended;
+    for (;;) {
+        while (s.queue.length)
+            turns.push(s.queue.shift());
+        if (s.ended)
+            break;
+        const sawEvent = await waitEvent(s, quietMs);
+        if (!sawEvent && s.queue.length === 0)
+            break;
+    }
+    return { turns, timedOut };
+}
+/** Tear a session down: disconnect the room, kill the worker, keep the record. */
+export async function endSession(s, reason) {
+    try {
+        if (s.child.connected)
+            await rpc(s, "end", {}, 5_000);
+    }
+    catch {
+        /* worker already gone */
+    }
+    try {
+        s.child.kill();
+    }
+    catch {
+        /* already dead */
+    }
+    markEnded(s, reason);
+}
+/** Kill workers whose session has been idle too long (agent-side timers will
+ * have ended the call server-side well before this fires). */
+const REAPER_IDLE_MS = 15 * 60 * 1000;
+const reaper = setInterval(() => {
+    for (const s of sessions.values()) {
+        if (!s.ended && Date.now() - s.lastActivityAt > REAPER_IDLE_MS) {
+            void endSession(s, "idle_reaped");
+        }
+    }
+}, 60_000);
+reaper.unref();
+// Never leave orphan workers holding rooms open.
+process.on("exit", () => {
+    for (const s of sessions.values()) {
+        try {
+            s.child.kill();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+});

package/dist/textcall/worker.js

@@ -0,0 +1,101 @@
+/**
+ * Text-call worker: the actual LiveKit room participant.
+ *
+ * Runs as a forked child of the MCP server (same bundled file, selected by
+ * TRILLET_MCP_TEXTCALL_WORKER=1) and talks to the parent over the IPC channel.
+ * It MUST be a separate process: @livekit/rtc-node's pino logger writes JSON
+ * lines to STDOUT (verified — not configurable), which would corrupt the
+ * parent's stdio MCP transport. The fork also isolates native FFI crashes.
+ *
+ * Protocol (verified live against production 2026-08-27/28, identical to the
+ * dashboard Test panel):
+ *   - caller turns are sent with sendText(text, { topic: "lk.chat" })
+ *   - agent turns arrive as text streams on topic "lk.transcription"
+ *   - the "lk.transcription_final" attribute is NOT trustworthy (it is "false"
+ *     on completed turns); a turn is simply one stream read to close
+ *   - agent identities start with "agent-" (or "web-agent")
+ *
+ * IPC messages
+ *   parent -> worker: {id, cmd:"connect", url, token} | {id, cmd:"say", text} | {id, cmd:"end"}
+ *   worker -> parent: {id, ok, ...} replies, plus unsolicited events:
+ *     {event:"agent_turn", identity, text}
+ *     {event:"participant", identity}
+ *     {event:"disconnected"}
+ */
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { depsDir } from "./deps.js";
+function send(msg) {
+    try {
+        process.send?.(msg);
+    }
+    catch {
+        /* parent gone; the disconnect handler exits us */
+    }
+}
+/** The handler's 2nd arg is a participant info OBJECT in rtc-node (a plain identity string in the browser SDK). */
+function identityOf(participant) {
+    if (typeof participant === "string")
+        return participant;
+    return String(participant?.identity ?? "");
+}
+export function runTextCallWorker() {
+    let room = null;
+    process.on("message", async (msg) => {
+        try {
+            if (msg.cmd === "connect") {
+                const req = createRequire(join(depsDir(), "package.json"));
+                const lk = req("@livekit/rtc-node");
+                room = new lk.Room();
+                const relay = (topic) => async (reader, participant) => {
+                    const identity = identityOf(participant);
+                    let text = "";
+                    try {
+                        for await (const chunk of reader)
+                            text += chunk;
+                    }
+                    catch {
+                        /* stream aborted mid-read (room closing); forward what we have */
+                    }
+                    send({ event: "agent_turn", topic, identity, text });
+                };
+                // Handlers must be registered before connect or early streams are lost.
+                room.registerTextStreamHandler("lk.transcription", relay("lk.transcription"));
+                room.registerTextStreamHandler("lk.chat", relay("lk.chat"));
+                room.on(lk.RoomEvent.ParticipantConnected, (p) => send({ event: "participant", identity: identityOf(p) }));
+                room.on(lk.RoomEvent.Disconnected, () => send({ event: "disconnected" }));
+                // autoSubscribe:false matches the Test panel in text mode — text
+                // streams are data packets, not tracks, so nothing is lost.
+                await room.connect(msg.url, msg.token, { autoSubscribe: false, dynacast: false });
+                send({
+                    id: msg.id,
+                    ok: true,
+                    roomName: room.name,
+                    localIdentity: identityOf(room.localParticipant),
+                });
+            }
+            else if (msg.cmd === "say") {
+                if (!room)
+                    throw new Error("not connected");
+                await room.localParticipant.sendText(msg.text ?? "", { topic: "lk.chat" });
+                send({ id: msg.id, ok: true });
+            }
+            else if (msg.cmd === "end") {
+                try {
+                    await room?.disconnect();
+                }
+                catch {
+                    /* already closed */
+                }
+                send({ id: msg.id, ok: true });
+                // FFI threads keep the loop alive; exit explicitly once the ack flushed.
+                setTimeout(() => process.exit(0), 200);
+            }
+        }
+        catch (e) {
+            send({ id: msg.id, ok: false, error: e?.message ?? String(e) });
+        }
+    });
+    // Parent died or ended the session: never outlive it.
+    process.on("disconnect", () => process.exit(0));
+}

package/dist/tools/account.js

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { ok, guard, workspaceParam } from "../helpers.js";
+export function registerAccountTools(server, client) {
+    server.registerTool("trillet_get_usage", {
+        title: "Get wallet balance and usage",
+        description: "Fetch the workspace's wallet/billing dashboard summary: balance, subscription, and usage. include_minutes_breakdown adds the per-month minutes usage breakdown for the last 3 months. Check this first when calls or workflow steps mysteriously don't run - outbound calls and SMS steps require a positive wallet balance.",
+        inputSchema: {
+            include_minutes_breakdown: z
+                .boolean()
+                .default(false)
+                .describe("Also fetch the 3-month minutes usage breakdown"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ include_minutes_breakdown, workspace_id }) => {
+        const summary = await client.request("GET", "/v1/api/wallet/dashboard-summary", {
+            workspaceId: workspace_id,
+        });
+        const out = { summary };
+        if (include_minutes_breakdown) {
+            out.minutesBreakdown = await client
+                .request("GET", "/v1/api/billing/minutes-usage-breakdown/self", {
+                workspaceId: workspace_id,
+            })
+                .catch((e) => ({ error: String(e?.message ?? e) }));
+        }
+        return ok(out);
+    }));
+    server.registerTool("trillet_list_transactions", {
+        title: "List billing transactions",
+        description: "The workspace's wallet transaction ledger - the source of truth for what was actually charged. Types include call_charge, sms_charge, message_charge, workflow_charge, phone_number_charge, voice_generation_charge, rate_adjustment, deposits/auto-recharges, plan credits/debits. " +
+            "mode='summary' (default) groups by calendar month x type with count and total USD - use this to reconcile spend month over month (e.g. an effective per-minute rate change: compare call_charge totals against minutes from trillet_get_call_metrics, and check whether other charge types or a rate_adjustment explain the difference). mode='list' returns individual transactions, newest first, capped at `limit`.",
+        inputSchema: {
+            mode: z.enum(["summary", "list"]).default("summary"),
+            types: z
+                .array(z.string())
+                .optional()
+                .describe('Only include these transaction types, e.g. ["call_charge","sms_charge"]'),
+            from_date: z.string().optional().describe("ISO date, inclusive"),
+            to_date: z.string().optional().describe("ISO date, inclusive"),
+            limit: z.number().default(50).describe("mode='list' only: max transactions returned"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ mode, types, from_date, to_date, limit, workspace_id }) => {
+        // The API returns the full unpaginated ledger; filter and aggregate here.
+        const res = await client.request("GET", "/v1/api/billing/transactions", {
+            workspaceId: workspace_id,
+        });
+        let txs = Array.isArray(res) ? res : res.transactions ?? res.data ?? [];
+        const from = from_date ? new Date(from_date).getTime() : -Infinity;
+        const to = to_date ? new Date(to_date).getTime() + 86_399_999 : Infinity;
+        txs = txs.filter((t) => {
+            const ts = new Date(t.timestamp ?? t.createdAt).getTime();
+            return ts >= from && ts <= to && (!types || types.includes(t.type));
+        });
+        if (mode === "list") {
+            txs.sort((a, b) => new Date(b.timestamp ?? b.createdAt).getTime() -
+                new Date(a.timestamp ?? a.createdAt).getTime());
+            return ok({
+                totalMatching: txs.length,
+                transactions: txs.slice(0, limit).map((t) => ({
+                    type: t.type,
+                    amount: t.amount,
+                    description: t.description,
+                    timestamp: t.timestamp ?? t.createdAt,
+                })),
+            });
+        }
+        const buckets = {};
+        for (const t of txs) {
+            const d = new Date(t.timestamp ?? t.createdAt);
+            const key = `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, "0")} ${t.type}`;
+            buckets[key] ??= { count: 0, total: 0 };
+            buckets[key].count += 1;
+            buckets[key].total += t.amount ?? 0;
+        }
+        const summary = Object.entries(buckets)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, v]) => {
+            const [month, ...type] = key.split(" ");
+            return { month, type: type.join(" "), count: v.count, totalUsd: Number(v.total.toFixed(4)) };
+        });
+        return ok({ totalMatching: txs.length, monthlySummary: summary });
+    }));
+}

package/dist/tools/agents.js

@@ -0,0 +1,178 @@
+import { z } from "zod";
+import { ok, guard, workspaceParam } from "../helpers.js";
+const ttsModelSchema = z
+    .object({
+    provider: z.enum(["rime", "elevenlabs", "cartesia", "openai"]).describe("TTS provider"),
+    voiceId: z.string().describe('Voice id, e.g. "arcana_eucalyptus" (Rime Australian voice)'),
+    name: z.string().describe("Human-readable voice name shown in the dashboard"),
+    language: z.string().default("en"),
+    rimeModel: z.string().optional().describe('Rime model family, e.g. "coda", "arcana", "mistv3"'),
+})
+    .describe("Text-to-speech voice configuration");
+function summarizeAgent(a) {
+    return {
+        id: a._id,
+        name: a.name,
+        llmModel: a.llmModel,
+        voice: a.ttsModel ? `${a.ttsModel.provider}/${a.ttsModel.voiceId}` : null,
+        stt: a.sttProvider?.id,
+        callFlowId: a.pathway,
+        callFlowName: a.flowName,
+        phoneNumbers: (a.phoneNumberIds ?? []).length,
+        updatedAt: a.updatedAt,
+    };
+}
+export function registerAgentTools(server, client) {
+    server.registerTool("trillet_list_agents", {
+        title: "List agents",
+        description: "List all voice agents in the workspace with a compact summary (id, name, LLM, voice, linked call flow).",
+        inputSchema: { ...workspaceParam },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ workspace_id }) => {
+        const agents = await client.request("GET", "/v1/api/agents", {
+            workspaceId: workspace_id,
+        });
+        return ok(agents.map(summarizeAgent));
+    }));
+    server.registerTool("trillet_get_agent", {
+        title: "Get agent",
+        description: "Fetch one agent's full configuration by id.",
+        inputSchema: { agent_id: z.string(), ...workspaceParam },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ agent_id, workspace_id }) => {
+        const agents = await client.request("GET", "/v1/api/agents", {
+            workspaceId: workspace_id,
+        });
+        const agent = agents.find((a) => a._id === agent_id);
+        if (!agent)
+            return ok({ error: `Agent ${agent_id} not found in workspace` });
+        return ok(agent);
+    }));
+    server.registerTool("trillet_create_agent", {
+        title: "Create agent",
+        description: "Create a new voice agent. ttsModel is REQUIRED by the API (requests without it fail with a 500). " +
+            "Creating an agent usually also creates a linked call flow; check the response's pathway field. " +
+            'Sensible defaults: Rime voice, llmModel "platform-llm".',
+        inputSchema: {
+            name: z.string().describe("Agent display name"),
+            // Brand-free by design (TRI-835): llmModel is returned on the public v1
+            // API, so whitelabel customers see this string. The example matters as
+            // much as the default here, since the model copies it.
+            llmModel: z
+                .string()
+                .default("platform-llm")
+                .describe('LLM id, e.g. "platform-llm", "gemini-2.5-flash", "gpt-5.2"'),
+            ttsModel: ttsModelSchema,
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, guard(async ({ name, llmModel, ttsModel, workspace_id }) => {
+        const res = await client.request("POST", "/v1/api/agents", {
+            body: { name, llmModel, ttsModel },
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+    server.registerTool("trillet_update_agent", {
+        title: "Update agent",
+        description: "Update an agent's name, LLM model, voice, settings, or TTS pronunciation dictionary. Only send the fields you want to change. " +
+            "ttsDictionary is the agent-level pronunciation list (ElevenLabs voices): the API syncs it to the voice provider and manages the dictionary locator ids itself; send only words.",
+        inputSchema: {
+            agent_id: z.string(),
+            name: z.string().optional(),
+            llmModel: z.string().optional(),
+            ttsModel: ttsModelSchema.optional(),
+            ttsDictionary: z
+                .object({
+                words: z
+                    .array(z.object({
+                    word: z.string().describe("The word or phrase to override pronunciation for"),
+                    alias: z.string().describe("How it should be pronounced (phonetic spelling or an alternate word)"),
+                }))
+                    .describe("COMPLETE list; replaces the agent's existing words"),
+            })
+                .optional()
+                .describe("Agent-level TTS pronunciation dictionary (agent.ttsDictionary). Applies to ElevenLabs voices; other providers keep the words but do not sync them."),
+            settings: z
+                .object({
+                speed: z.number().optional().describe("Voice speed, e.g. 0.94"),
+                volume: z.number().optional(),
+                temperature: z.number().optional(),
+            })
+                .optional(),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, guard(async ({ agent_id, workspace_id, ...fields }) => {
+        const body = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+        const res = await client.request("PUT", `/v1/api/agents/${agent_id}`, {
+            body,
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+    server.registerTool("trillet_delete_agent", {
+        title: "Delete agent",
+        description: "Delete an agent from the workspace. Unbind its phone numbers first (a bound number stops routing). Always confirm with the user; requires confirm=true. The linked call flow is a separate document and is not deleted.",
+        inputSchema: {
+            agent_id: z.string(),
+            confirm: z
+                .boolean()
+                .describe("Must be true. Only set after the user explicitly approved deleting this agent."),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ agent_id, confirm, workspace_id }) => {
+        if (!confirm) {
+            return ok({
+                blocked: true,
+                message: "Refusing to delete: confirm=false. Ask the user to approve deleting agent " +
+                    agent_id +
+                    " and retry with confirm=true.",
+            });
+        }
+        const res = await client.request("DELETE", `/v1/api/agents/${agent_id}`, {
+            workspaceId: workspace_id,
+        });
+        return ok(res ?? { deleted: agent_id });
+    }));
+    server.registerTool("trillet_search_voices", {
+        title: "Search voices",
+        description: "Search the built-in voice catalog across providers (Rime, ElevenLabs, Cartesia, OpenAI, Hume). All filters optional; with no filters returns the full catalog (trimmed to `limit`). Use the returned provider + voiceId in an agent's ttsModel.",
+        inputSchema: {
+            name: z.string().optional(),
+            provider: z.string().optional(),
+            gender: z.string().optional(),
+            accent: z.string().optional().describe('e.g. "australian", "british", "american"'),
+            category: z.string().optional(),
+            age: z.string().optional(),
+            use_case: z.string().optional(),
+            limit: z.number().default(50).describe("Max results returned (applied client-side)"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ name, provider, gender, accent, category, age, use_case, limit, workspace_id }) => {
+        const filters = { name, provider, gender, accent, category, age, useCase: use_case };
+        // Always the search endpoint: with no filters it returns the whole flat
+        // catalog. GET /voices returns a provider-keyed object, which is why the
+        // no-filter path used to come back empty.
+        const res = await client.request("POST", "/v1/api/agents/voices/search", {
+            body: Object.fromEntries(Object.entries(filters).filter(([, v]) => v !== undefined)),
+            workspaceId: workspace_id,
+        });
+        const list = Array.isArray(res) ? res : res.voices ?? res.data ?? [];
+        const trimmed = list.slice(0, limit).map((v) => ({
+            provider: v.provider,
+            voiceId: v.voiceId ?? v.id ?? v._id,
+            name: v.name,
+            gender: v.gender,
+            accent: v.accent,
+            language: v.language,
+            category: v.category,
+            age: v.age,
+            useCase: v.useCase,
+            model: v.rimeModel ?? v.model,
+        }));
+        return ok({ total: list.length, returned: trimmed.length, voices: trimmed });
+    }));
+}