@trillet-ai/mcp 0.7.3

package/dist/tools/callFlows.js

@@ -0,0 +1,337 @@
+import { z } from "zod";
+import { ok, guard, workspaceParam } from "../helpers.js";
+/** In-call API tool ("webhook") definition, mirrors the Pathway schema. */
+const incallApiToolSchema = z.object({
+    name: z.string().describe('Tool name the LLM will call, e.g. "lookup_customer"'),
+    description: z
+        .string()
+        .describe("Tells the LLM what the tool does and when to call it. Be specific."),
+    url: z
+        .string()
+        .describe("Request URL. Supports placeholders: {{_variable.<name>}} (LLM-passed args), {{_dynamic_variable.<key>}}, {{_secret.<name>}}, {{_metadata.<key>}}."),
+    method: z.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).default("POST"),
+    headers: z
+        .array(z.object({ name: z.string(), value: z.string() }))
+        .default([])
+        .describe("Header list as name/value pairs (NOT an object). Values support placeholders."),
+    body: z
+        .string()
+        .optional()
+        .describe("JSON string template. For GET/DELETE the parsed body is flattened into query parameters. Placeholders resolve per-value, so exact-match placeholders keep their native JSON type."),
+    bodyType: z.enum(["json", "text"]).default("json"),
+    variables: z
+        .array(z.object({ name: z.string(), description: z.string() }))
+        .default([])
+        .describe("Parameters the LLM may pass (name + description only; no types). These become {{_variable.<name>}} in url/headers/body. The LLM is told these are the ONLY valid keys."),
+    responseVariables: z
+        .array(z.object({ key: z.string(), path: z.string() }))
+        .default([])
+        .describe('Extract values from the JSON response via dot-path (e.g. "records.0.fields.Name") into {{_response.<key>}} for later tools. Also lands in post-call analyzedData.'),
+    textToSpeak: z
+        .string()
+        .optional()
+        .describe('Optional phrase spoken while the request runs, e.g. "One moment while I check that."'),
+    timeout: z.number().default(15).describe("Request timeout in seconds (platform default 20)"),
+    status: z.boolean().default(true).describe("false disables the tool without deleting it"),
+});
+const postCallFieldSchema = z.object({
+    name: z.string().describe("snake_case field name; becomes a key in analyzedData"),
+    type: z.enum(["text", "boolean", "number", "selector"]).default("text"),
+    description: z
+        .string()
+        .describe("Extraction instruction for the analysis model. Be explicit about when to return null."),
+    options: z
+        .array(z.string())
+        .optional()
+        .describe("For type=selector: the exact allowed values (becomes an enum)"),
+});
+function summarizeFlow(p) {
+    const s = p.settings ?? {};
+    const wm = s.welcomeMessageConfig ?? {};
+    return {
+        id: p._id,
+        name: p.name,
+        direction: p.direction,
+        promptType: p.promptType,
+        agentId: typeof p.agent === "object" ? p.agent?._id : p.agent,
+        promptLength: (p.prompt || "").length,
+        inCallApiTools: (p.webhooks ?? []).map((w) => w.name),
+        knowledgeBases: s.knowledgeBases ?? [],
+        postCallAnalysisFields: (s.postCallAnalysis ?? []).map((f) => f.name),
+        // Settings the assistant most often writes, echoed so a read-back after an
+        // update shows the value instead of looking like the write was lost.
+        settings: {
+            callSetting: s.callSetting ?? {},
+            customerLocation: s.customerLocation ?? null,
+            timeContextEnabled: s.timeContextEnabled ?? null,
+            enableRecording: s.enableRecording ?? null,
+            security: s.security ?? {},
+            backgroundNoise: s.backgroundNoise ?? null,
+            officeHoursEnabled: s.OfficeHoursSettings?.enabled ?? null,
+            welcomeMessage: {
+                inbound: wm.Inbound?.selected ?? null,
+                outbound: wm.Outbound?.selected ?? null,
+            },
+            transfers: (s.transfers ?? []).map((t) => `${t.friendly_name} (${t.method ?? "cold"} -> ${t.destination})`),
+            enableHumanLikeVoiceAndTone: s.enableHumanLikeVoiceAndTone ?? null,
+            enableTransferInstructions: s.enableTransferInstructions ?? null,
+            enableEndCallInstructions: s.enableEndCallInstructions ?? null,
+        },
+        hasActiveDraft: p._hasDraft ?? undefined,
+        updatedAt: p.updatedAt,
+    };
+}
+export function registerCallFlowTools(server, client) {
+    server.registerTool("trillet_list_call_flows", {
+        title: "List call flows",
+        description: "List all call flows (pathways) in the workspace with compact summaries.",
+        inputSchema: { ...workspaceParam },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ workspace_id }) => {
+        const res = await client.request("GET", "/v1/api/call-flows", {
+            workspaceId: workspace_id,
+        });
+        const list = Array.isArray(res) ? res : res.pathways ?? [];
+        return ok(list.map(summarizeFlow));
+    }));
+    server.registerTool("trillet_get_call_flow", {
+        title: "Get call flow",
+        description: "Fetch one call flow. IMPORTANT: if the flow has an active editor draft, this endpoint returns the DRAFT merged over production, and test calls also run the draft. The response includes a has_active_draft flag; use trillet_deactivate_drafts to return to production.",
+        inputSchema: {
+            flow_id: z.string(),
+            include_prompt: z
+                .boolean()
+                .default(false)
+                .describe("true returns the full prompt text (can be long)"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, include_prompt, workspace_id }) => {
+        const res = await client.request("GET", `/v1/api/call-flows/${flow_id}`, {
+            workspaceId: workspace_id,
+        });
+        const p = res.pathway ?? res;
+        const drafts = await client
+            .request("GET", `/v1/api/call-flows/${flow_id}/drafts`, { workspaceId: workspace_id })
+            .catch(() => []);
+        const draftList = Array.isArray(drafts) ? drafts : drafts.drafts ?? [];
+        const summary = summarizeFlow(p);
+        const out = {
+            ...summary,
+            has_active_draft: draftList.some((d) => d.isActive),
+            // Keep the summary's settings echo (the assistant reads this back after
+            // every write) and add the full shapes this endpoint is used for.
+            settings: {
+                ...summary.settings,
+                welcomeMessageConfig: p.settings?.welcomeMessageConfig,
+                transfersFull: p.settings?.transfers,
+                postCallAnalysis: p.settings?.postCallAnalysis,
+            },
+            inCallApiToolsFull: p.webhooks,
+            dynamicVariableCollections: p.dynamicVariableCollections,
+        };
+        if (include_prompt)
+            out.prompt = p.prompt;
+        return ok(out);
+    }));
+    server.registerTool("trillet_create_call_flow", {
+        title: "Create call flow",
+        description: "Create a new call flow. GOTCHA: on CREATE, a partial `settings` object replaces ALL defaults, so this tool intentionally does not accept settings; create first, then configure with the update tools (updates deep-merge safely).",
+        inputSchema: {
+            name: z.string(),
+            direction: z
+                .enum(["outbound", "bidirectional"])
+                .default("bidirectional")
+                .describe("bidirectional answers inbound calls (there is no separate inbound mode: the platform stores inbound as bidirectional); outbound is dial-out only"),
+            prompt: z.string().optional(),
+            agent_id: z.string().optional().describe("Link to an existing agent"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, guard(async ({ name, direction, prompt, agent_id, workspace_id }) => {
+        const body = { name, direction, promptType: "simple" };
+        if (prompt)
+            body.prompt = prompt;
+        if (agent_id)
+            body.agent = agent_id;
+        const res = await client.request("POST", "/v1/api/call-flows", {
+            body,
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+    server.registerTool("trillet_update_call_flow", {
+        title: "Update call flow (advanced)",
+        description: "Partial update of any call-flow fields. Merge semantics (verified): objects DEEP-MERGE (sending settings.callSetting.x preserves siblings), but ARRAYS REPLACE WHOLESALE (webhooks, transfers, postCallAnalysis must be sent complete), and null values are ignored (you cannot null a field). Prefer the dedicated tools for prompt, in-call APIs, and post-call analysis. Top-level settings toggles reachable ONLY through this tool: settings.enableHumanLikeVoiceAndTone (expressive delivery), settings.enableTransferInstructions and settings.enableEndCallInstructions (whether the transfer / end-call prompt blocks are injected; both default on), settings.customerLocation (IANA timezone) and settings.timeContextEnabled (agent knows the current date/time; default on).",
+        inputSchema: {
+            flow_id: z.string(),
+            update: z
+                .record(z.string(), z.unknown())
+                .describe('Fields to update, e.g. {"name": "...", "settings": {"callSetting": {"maxCallDuration": 900}}}'),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, update, workspace_id }) => {
+        const res = await client.request("PUT", `/v1/api/call-flows/${flow_id}`, {
+            body: update,
+            workspaceId: workspace_id,
+        });
+        return ok(summarizeFlow(res.pathway ?? res));
+    }));
+    server.registerTool("trillet_update_prompt", {
+        title: "Update prompt",
+        description: "Replace a call flow's prompt. The API auto-snapshots a prompt version on every update. " +
+            "Prompt conventions: reference in-call API tools as {{realtime_api \"tool_name\" \"var1, var2\"}} (the canonical token the runtime documents to the model); " +
+            "{{key}} placeholders are substituted from per-call dynamic variables; do NOT hardcode a scripted greeting in the prompt because the platform welcome message already plays it (a scripted 'Begin with' line causes the agent to greet twice).",
+        inputSchema: { flow_id: z.string(), prompt: z.string(), ...workspaceParam },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, prompt, workspace_id }) => {
+        const res = await client.request("PUT", `/v1/api/call-flows/${flow_id}`, {
+            body: { prompt },
+            workspaceId: workspace_id,
+        });
+        const p = res.pathway ?? res;
+        return ok({
+            id: p._id,
+            promptLength: (p.prompt || "").length,
+            promptVersions: (p.promptVersions ?? []).length,
+        });
+    }));
+    server.registerTool("trillet_set_incall_api_tools", {
+        title: "Set in-call API tools",
+        description: "Replace the flow's in-call API tools (LLM-invokable HTTP calls during the call). Sends the COMPLETE array (arrays replace wholesale). " +
+            "GOTCHA: the runtime auto-appends call metadata into request bodies/query params unless callSetting.disableMetadata is true; strict APIs like Airtable reject unknown body keys, so disable_metadata defaults to true here.",
+        inputSchema: {
+            flow_id: z.string(),
+            tools: z.array(incallApiToolSchema).describe("Complete list of in-call API tools"),
+            disable_metadata: z
+                .boolean()
+                .default(true)
+                .describe("Set callSetting.disableMetadata (recommended true for strict third-party APIs)"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, tools, disable_metadata, workspace_id }) => {
+        const body = { webhooks: tools };
+        if (disable_metadata !== undefined) {
+            body.settings = { callSetting: { disableMetadata: disable_metadata } };
+        }
+        const res = await client.request("PUT", `/v1/api/call-flows/${flow_id}`, {
+            body,
+            workspaceId: workspace_id,
+        });
+        const p = res.pathway ?? res;
+        return ok({
+            id: p._id,
+            inCallApiTools: (p.webhooks ?? []).map((w) => w.name),
+            disableMetadata: p.settings?.callSetting?.disableMetadata,
+            promptReminder: 'Reference each tool in the prompt as {{realtime_api "<name>" "<comma-separated variable names>"}}.',
+        });
+    }));
+    server.registerTool("trillet_set_post_call_analysis", {
+        title: "Set post-call analysis fields",
+        description: "Replace the flow's post-call analysis fields (structured extraction after each call; results land in the call's analyzedData and are available to workflows as {{trigger.analyzedData.<name>}}). The platform always adds summary, call_disposition, and call_sentiment automatically. Tip: make selector options exactly match any downstream system's allowed values.",
+        inputSchema: {
+            flow_id: z.string(),
+            fields: z.array(postCallFieldSchema),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, fields, workspace_id }) => {
+        const res = await client.request("PUT", `/v1/api/call-flows/${flow_id}`, {
+            body: { settings: { postCallAnalysis: fields } },
+            workspaceId: workspace_id,
+        });
+        const p = res.pathway ?? res;
+        return ok({
+            id: p._id,
+            postCallAnalysisFields: (p.settings?.postCallAnalysis ?? []).map((f) => f.name),
+        });
+    }));
+    server.registerTool("trillet_list_drafts", {
+        title: "List editor drafts",
+        description: "List builder drafts for a call flow. An ACTIVE draft silently overrides production for dashboard test calls and the editor view; it is the number-one cause of 'my changes are not taking effect'.",
+        inputSchema: { flow_id: z.string(), ...workspaceParam },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, workspace_id }) => {
+        const res = await client.request("GET", `/v1/api/call-flows/${flow_id}/drafts`, {
+            workspaceId: workspace_id,
+        });
+        const list = Array.isArray(res) ? res : res.drafts ?? [];
+        return ok(list.map((d) => ({
+            id: d._id,
+            name: d.name,
+            isActive: d.isActive,
+            updatedAt: d.updatedAt,
+        })));
+    }));
+    server.registerTool("trillet_deactivate_drafts", {
+        title: "Deactivate drafts (use production)",
+        description: "Deactivate all editor drafts on a call flow so test calls and the editor use the production version. Run this after API-side edits if a stale builder tab created a draft. Drafts are recoverable, not deleted. Warn the user that anyone with the flow open in a browser should refresh before editing, or their stale tab may re-create the draft or publish over the changes.",
+        inputSchema: { flow_id: z.string(), ...workspaceParam },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, workspace_id }) => {
+        const res = await client.request("POST", `/v1/api/call-flows/${flow_id}/drafts/deactivate`, {
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+    server.registerTool("trillet_publish_draft", {
+        title: "Publish draft to production",
+        description: "Publish a specific draft/version snapshot into the flow's PRODUCTION config (live calls pick it up immediately). Get draft ids from trillet_list_drafts. This overwrites production wholesale with the draft's contents.",
+        inputSchema: { flow_id: z.string(), draft_id: z.string(), ...workspaceParam },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, draft_id, workspace_id }) => {
+        const res = await client.request("POST", `/v1/api/call-flows/${flow_id}/drafts/${draft_id}/publish`, { workspaceId: workspace_id });
+        return ok(res);
+    }));
+    server.registerTool("trillet_duplicate_call_flow", {
+        title: "Duplicate call flow",
+        description: "Duplicate a call flow (prompt, settings, in-call API tools, post-call analysis) as a new flow in the same workspace.",
+        inputSchema: { flow_id: z.string(), ...workspaceParam },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, guard(async ({ flow_id, workspace_id }) => {
+        const res = await client.request("POST", `/v1/api/call-flows/${flow_id}/duplicate`, {
+            workspaceId: workspace_id,
+        });
+        return ok(summarizeFlow(res.pathway ?? res));
+    }));
+    server.registerTool("trillet_archive_call_flow", {
+        title: "Archive / restore call flow",
+        description: "Archive a call flow (hides it from the default list and takes it out of use without deleting) or restore an archived one.",
+        inputSchema: {
+            flow_id: z.string(),
+            restore: z.boolean().default(false).describe("true un-archives the flow"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, restore, workspace_id }) => {
+        const res = await client.request("PATCH", `/v1/api/call-flows/${flow_id}/${restore ? "restore" : "archive"}`, { workspaceId: workspace_id });
+        return ok(res);
+    }));
+    server.registerTool("trillet_delete_call_flow", {
+        title: "Delete call flow",
+        description: "Permanently delete a call flow. Prefer trillet_archive_call_flow unless the flow is definitely disposable (e.g. cleaning up a demo). Always confirm with the user; requires confirm=true.",
+        inputSchema: {
+            flow_id: z.string(),
+            confirm: z
+                .boolean()
+                .describe("Must be true. Only set after the user explicitly approved deleting this flow."),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ flow_id, confirm, workspace_id }) => {
+        if (!confirm) {
+            return ok({
+                blocked: true,
+                message: "Refusing to delete: confirm=false. Ask the user to approve deleting flow " +
+                    flow_id +
+                    " and retry with confirm=true (or archive it instead).",
+            });
+        }
+        const res = await client.request("DELETE", `/v1/api/call-flows/${flow_id}`, {
+            workspaceId: workspace_id,
+        });
+        return ok(res ?? { deleted: flow_id });
+    }));
+}