@trillet-ai/mcp 0.7.3

package/dist/tools/nodeFlows.js

@@ -0,0 +1,317 @@
+import { z } from "zod";
+import { ok, guard, workspaceParam } from "../helpers.js";
+const NODE_FLOW_REFERENCE = `# Trillet Node Flow Reference (verified against the runtime)
+
+Node flows are graph-based call flows (pathway.promptType "nodes"). The graph lives in its own
+NodeGraph document; the companion agent and pathway are AUTO-CREATED when you create a node flow.
+Edits save to the live graph WITHOUT validation; calls only ever run the last PUBLISHED version.
+Lifecycle: create -> update graph -> validate -> publish -> call. An unpublished flow fails calls
+with NODE_FLOW_NOT_PUBLISHED.
+
+## Graph document fields you can update
+- startNodeId: entry node id (falls back to the only node without incoming edges)
+- variables[]: { key, label, type: string|number|boolean|date|time|enum|phone|email|object|array,
+  enumValues[], validation{pattern,min,max,minLength,maxLength}, required, extractionPrompt, redact }
+  Every requiredFields/resultVariable key MUST be declared here (UNDECLARED_VARIABLE otherwise).
+- globals: { persona (the node-flow analogue of a prompt), guardrails,
+  knowledgeBases[knowledge base ids],
+  interrupts[{ id, name, utterancePatterns[], targetNodeId, returnAfter }] }
+  Interrupts are GRAPH-GLOBAL jumps (e.g. "speak to a human" from anywhere); returnAfter resumes
+  where the caller was. There is no interrupt node type.
+- router: { model, maxCandidates=8, historyTurns=4, confidenceFloor=0.5 }
+- nodes[], edges[]
+
+## Node types (11)
+Every node: { nodeId, type, name, config{}, behaviour{}, onError: fallback|end|transfer, maxTurns=8 }
+behaviour (per-node overrides, only set what you mean): temperature (0-2), model,
+blockInterruptions, interruptionThreshold, responseEagerness, resumptionSpeed, reminderSeconds,
+reminderTimes, disableSilenceRepeat, skipUserResponse, overridesInterrupts, excludeFromHistory.
+
+- conversation ("Talk"): config { objective (REQUIRED), prompt, requiredFields[varKey],
+  exitCriteria, skipIfSatisfied, confirmBeforeExit, clearFieldsOnReentry, knowledgeBases[],
+  knowledgeBaseInstruction, abilities[{toolName, instruction}], examples[{caller, agent}] }.
+  Abilities are mid-turn tools: cal.com/Google/GHL/ModMed/ServiceM8 calendar actions,
+  get_time_for_timezone, next_available_callback_time. NOT transfer_call or end_call.
+- say: config { text (REQUIRED), interruptible (default true) }. Speaks then moves on. Set
+  interruptible false to pin a line that must land whole (disclaimer, callback number).
+  API/MCP only - there is no editor control for it.
+- decision ("Rule"): no config; routes purely via condition edges. EVERY condition row needs a
+  conditional_variable: a row without one is treated as TRUE, and since condition edges are
+  evaluated first, that silently makes the edge an unconditional exit taken on every turn.
+  Nothing validates this.
+- classify ("Choice"): config { question, options: [{handle, description}] } (>=2, unique handles).
+  Each option handle needs its own out-edge.
+- tool ("Action"): config { toolName, arguments{}, resultVariable, retry{attempts 0-3, backoffMs} }.
+  Allowed toolNames: realtime_api, execute_code_action, search_knowledge_base, transfer_call,
+  end_call, get_time_for_timezone, next_available_callback_time, trigger_workflow.
+  TRANSFERS ARE A TOOL NODE with toolName "transfer_call". Outputs: success | error handles.
+- end: config { message, disposition (free string, e.g. "completed"), messageMode:
+  instruction|verbatim }. Terminal; no outgoing edges allowed. messageMode defaults to
+  instruction (the message is a directive the model words); verbatim speaks it exactly.
+  Leave message empty and the runtime generates a brief goodbye instead - EXCEPT when the
+  same settle already spoke, so Say("goodbye") -> end does not say goodbye twice. Farewells
+  always play to completion (not interruptible). ALWAYS set a disposition: it is not
+  validated and defaults to null, which leaves outcome reporting blank.
+- wait ("Listen"): config { requiredFields[] (REQUIRED non-empty), prompt }. Collects without talking much.
+- subflow: config { nodeGraphId (REQUIRED), returnAfter }. returnAfter outputs: returned | error.
+- code: config { code (REQUIRED, JavaScript), resultVariable, arguments }. Runs on Cloudflare
+  Workers deployed at publish time; no local fallback. Outputs: success | error.
+- parallel: config { tools: [>=2 of {toolName, arguments, resultVariable}], joinPolicy:
+  all_success|any_success }. Outputs: success | error.
+- ivr: ENTRY-ONLY node (pickup-time menu navigation before the graph starts; must have NO incoming
+  edges, max one per graph): config { mode: sequence|auto, keySequence[] (digits/*/#),
+  priorityList[], holdQueue{enabled, maxWaitSeconds 15-900}, screeningAction: respond|hangup }.
+  Optional outputs: human | exhausted | voicemail (unwired outcomes fall back to startNodeId).
+
+## Edges
+{ id (REQUIRED), source, target, sourceHandle?, kind: auto|condition|intent|fallback, label,
+  condition, priority }
+- kind=auto: unconditional, no model call. kind=condition: deterministic on call state.
+  kind=intent: the router model matches on the edge LABEL (label required).
+  kind=fallback: taken when nothing else matches (max one per node; collection nodes should have one).
+- Evaluation order: condition (ascending priority) -> auto -> intent -> fallback.
+- Nodes with declared output handles (classify, tool, subflow, code, parallel) REQUIRE
+  sourceHandle on their out-edges and each handle wires at most one edge.
+- Cycles are legal (bounded by maxTurns and chain guards).
+
+## Condition syntax
+Operators: exists, not_empty, equals, not_equals, equals_ci, not_equals_ci, contains,
+not_contains, greater_than, less_than. Values/fields use placeholders:
+{{_variable.x}} (extracted -> response -> dynamic -> metadata precedence), {{_response.x}},
+{{_dynamic_variable.x}}, {{_metadata.x}}, {{_time_context.currentDate|currentTime|currentDay}}.
+The runtime seeds {{_dynamic_variable.call_direction}} ("inbound" | "outbound") before the start
+chain runs, so a condition edge at the start node can branch inbound vs outbound (the editor's
+Simulate-as-inbound/outbound toggle resolves it too; web calls count as outbound). A per-call
+dynamic variable named call_direction overrides the seeded value.
+For a value the flow COLLECTED, use {{_variable.key}}. A bare {{key}} resolves against dynamic
+variables ONLY, so a bare placeholder for a collected value never matches, with no warning.
+A conditional_variable that is not a {{...}} placeholder is compared as a literal string
+(so "exists" on it is permanently true).
+
+## Greeting (the first line)
+Node flows do NOT run the simple-flow welcome pipeline; the first conversational node opens the
+call, honoring pathway welcomeMessageConfig[Inbound|Outbound] (set via trillet_set_welcome_message
+on the companion pathway): selected "customMessage" speaks the configured text verbatim (dynamic
+variables substituted); "userFirst" stays silent so the caller speaks first (use this on Outbound
+to wait for the callee's "hello"); "aiFirst" or unset (the default on auto-created node-flow
+pathways) generates the opening from the landing node's objective. To script a greeting inside
+the graph instead, instruct the start conversation node to speak it word-for-word; do not ALSO
+set a customMessage or the call greets twice.
+
+## Common blocking validation errors
+CONVERSATION_WITHOUT_OBJECTIVE, REQUIRED_FIELD_UNDECLARED, UNDECLARED_VARIABLE, NO_START_NODE,
+NO_OUTGOING (non-terminal node with no exits), MISSING_FALLBACK, HANDLE_MISSING/UNKNOWN_HANDLE
+(declared-output nodes), CONDITION_EDGE_WITHOUT_CONDITION, INTENT_EDGE_WITHOUT_LABEL,
+TERMINAL_HAS_OUTGOING, TOOL_NOT_ALLOWED, WAIT_WITHOUT_FIELDS, CLASSIFY_DUPLICATE_HANDLE.
+Warnings (do not block publish): UNREACHABLE_NODE, NO_END_NODE, TOOL_ERROR_PATH_UNWIRED,
+CLASSIFY_NO_FALLBACK, END_WITHOUT_MESSAGE.
+
+## Gotchas
+- PUT and draft saves NEVER validate; run validate before publish to catch problems early.
+- Publish snapshots a version, compiles the graph, deploys code nodes to Cloudflare, and is what
+  live calls consume. Editing after publish changes nothing on calls until the next publish.
+- pathway.settings (voice, transfers config, office hours, recording, speech settings) still
+  applies to node flows unchanged; configure it via the call-flow tools using the companion
+  pathway id returned by get.
+- end node disposition is a hint; keep dispositions consistent (e.g. completed, transferred,
+  voicemail) for reporting.`;
+function summarizeGraph(g) {
+    return {
+        id: g._id,
+        name: g.name,
+        status: g.status,
+        startNodeId: g.startNodeId,
+        nodes: (g.nodes ?? []).map((n) => `${n.nodeId}(${n.type})`),
+        edges: (g.edges ?? []).length,
+        variables: (g.variables ?? []).map((v) => v.key),
+        interrupts: (g.globals?.interrupts ?? []).map((i) => i.name),
+        hasDraft: g.hasDraft,
+        publishedVersion: g.publishedVersion,
+        publishedAt: g.publishedAt,
+    };
+}
+export function registerNodeFlowTools(server, client) {
+    server.registerTool("trillet_node_flow_reference", {
+        title: "Node flow reference",
+        description: "Return the complete reference for Trillet node flows (graph call flows): node types and their config fields, edge kinds and handle rules, condition syntax, validation errors, and lifecycle gotchas. READ THIS FIRST before creating or editing any node graph.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, guard(async () => ok(NODE_FLOW_REFERENCE)));
+    server.registerTool("trillet_list_node_flows", {
+        title: "List node flows",
+        description: "List node-graph call flows in the workspace (summaries; graphs excluded).",
+        inputSchema: {
+            page: z.number().default(1),
+            limit: z.number().default(20),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ page, limit, workspace_id }) => {
+        const res = await client.request("GET", "/v2/api/node-graphs/", {
+            query: { page, limit },
+            workspaceId: workspace_id,
+        });
+        const list = res.docs ?? res.data ?? (Array.isArray(res) ? res : []);
+        return ok(list.map((g) => ({
+            id: g._id,
+            name: g.name,
+            status: g.status,
+            publishedVersion: g.publishedVersion,
+            hasDraft: g.hasDraft,
+            stats: g.stats,
+        })));
+    }));
+    server.registerTool("trillet_get_node_flow", {
+        title: "Get node flow",
+        description: "Fetch a node flow: the graph (nodes, edges, variables, globals, router), plus the companion pathway (its id is what the call-flow settings tools operate on).",
+        inputSchema: {
+            graph_id: z.string(),
+            full_graph: z
+                .boolean()
+                .default(false)
+                .describe("true returns complete nodes/edges configs; false returns a summary"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ graph_id, full_graph, workspace_id }) => {
+        const res = await client.request("GET", `/v2/api/node-graphs/${graph_id}`, {
+            workspaceId: workspace_id,
+        });
+        const g = res.graph ?? res;
+        const pathway = res.pathway
+            ? {
+                id: res.pathway._id,
+                name: res.pathway.name,
+                direction: res.pathway.direction,
+                agentId: typeof res.pathway.agent === "object" ? res.pathway.agent?._id : res.pathway.agent,
+            }
+            : null;
+        return ok({
+            graph: full_graph ? g : summarizeGraph(g),
+            pathway,
+        });
+    }));
+    server.registerTool("trillet_create_node_flow", {
+        title: "Create node flow",
+        description: "Create a new node-graph call flow. This ALSO auto-creates a companion agent and pathway. Optionally start from a platform template (see trillet_list_node_flow_templates). After creating: update the graph, validate, then PUBLISH (calls fail with NODE_FLOW_NOT_PUBLISHED until published).",
+        inputSchema: {
+            name: z.string(),
+            description: z.string().optional(),
+            template: z.string().optional().describe("Template key from the templates list"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, guard(async ({ name, description, template, workspace_id }) => {
+        const body = { name };
+        if (description)
+            body.description = description;
+        if (template)
+            body.template = template;
+        const res = await client.request("POST", "/v2/api/node-graphs/", {
+            body,
+            workspaceId: workspace_id,
+        });
+        const g = res.graph ?? res;
+        return ok({ created: summarizeGraph(g), pathwayId: res.pathway?._id ?? g.pathwayId });
+    }));
+    server.registerTool("trillet_list_node_flow_templates", {
+        title: "List node flow templates",
+        description: "List available node-flow starter templates.",
+        inputSchema: { ...workspaceParam },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ workspace_id }) => {
+        const res = await client.request("GET", "/v2/api/node-graphs/templates", {
+            workspaceId: workspace_id,
+        });
+        return ok(res.templates ?? res);
+    }));
+    server.registerTool("trillet_update_node_graph", {
+        title: "Update node graph",
+        description: "Update graph fields: name, description, startNodeId, variables, globals, router, nodes, edges. Arrays replace wholesale, so send complete nodes/edges lists. IMPORTANT: updates are saved WITHOUT validation, and live calls keep running the previously PUBLISHED version. Always trillet_validate_node_graph then trillet_publish_node_graph afterwards. Consult trillet_node_flow_reference for node/edge schemas before building.",
+        inputSchema: {
+            graph_id: z.string(),
+            update: z
+                .record(z.string(), z.unknown())
+                .describe("Any of: name, description, startNodeId, variables, globals, router, nodes, edges"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ graph_id, update, workspace_id }) => {
+        const res = await client.request("PUT", `/v2/api/node-graphs/${graph_id}`, {
+            body: update,
+            workspaceId: workspace_id,
+        });
+        return ok(summarizeGraph(res.graph ?? res));
+    }));
+    server.registerTool("trillet_validate_node_graph", {
+        title: "Validate node graph",
+        description: "Validate the saved graph (or a proposed unsaved graph passed inline). Returns problems with severity: 'error' blocks publish, 'warning' does not. Problem codes are documented in trillet_node_flow_reference.",
+        inputSchema: {
+            graph_id: z.string(),
+            graph: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Optional full graph object to validate without saving"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ graph_id, graph, workspace_id }) => {
+        const res = await client.request("POST", `/v2/api/node-graphs/${graph_id}/validate`, {
+            body: graph ? { graph } : {},
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+    server.registerTool("trillet_publish_node_graph", {
+        title: "Publish node graph",
+        description: "Publish the graph: validates (400 NODE_GRAPH_INVALID with problems if blocking errors), snapshots a version, compiles, deploys any code nodes to Cloudflare, and makes it live for calls. This is the ONLY way edits reach live calls.",
+        inputSchema: {
+            graph_id: z.string(),
+            note: z.string().optional().describe("Version note"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ graph_id, note, workspace_id }) => {
+        const res = await client.request("POST", `/v2/api/node-graphs/${graph_id}/publish`, {
+            body: note ? { note } : {},
+            workspaceId: workspace_id,
+        });
+        return ok({
+            published: summarizeGraph(res.graph ?? res),
+            warnings: res.problems ?? [],
+        });
+    }));
+    server.registerTool("trillet_simulate_node_graph", {
+        title: "Simulate node graph",
+        description: "Run a text simulation of the graph without a live call: pass caller turns and optional initial variable state; returns the traversal trace. Verifies STRUCTURE (edges wire up, conditions evaluate, handles resolve, guards fire) - it does NOT verify routing quality, because the router is mocked and intent edges are not judged by a model. To test real routing/extraction conversationally, use trillet_start_text_call (runs the live runtime).",
+        inputSchema: {
+            graph_id: z.string(),
+            turns: z.array(z.string()).describe("Caller utterances in order"),
+            initial_state: z.record(z.string(), z.unknown()).optional(),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ graph_id, turns, initial_state, workspace_id }) => {
+        const res = await client.request("POST", `/v2/api/node-graphs/${graph_id}/simulate`, {
+            body: { turns, initialState: initial_state ?? {} },
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+    server.registerTool("trillet_list_node_flow_runs", {
+        title: "List node flow runs",
+        description: "List recent runs (call traversals) of a node graph: path taken, disposition, counters. Use for debugging why calls routed the way they did.",
+        inputSchema: {
+            graph_id: z.string(),
+            run_id: z.string().optional().describe("Fetch one run with full trace events"),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ graph_id, run_id, workspace_id }) => {
+        const path = run_id
+            ? `/v2/api/node-graphs/${graph_id}/runs/${run_id}`
+            : `/v2/api/node-graphs/${graph_id}/runs`;
+        const res = await client.request("GET", path, { workspaceId: workspace_id });
+        return ok(res);
+    }));
+}

package/dist/tools/phoneNumbers.js

@@ -0,0 +1,221 @@
+import { z } from "zod";
+import { ok, guard, workspaceParam } from "../helpers.js";
+const officeHoursNumberSchema = z
+    .object({
+    enabled: z.boolean(),
+    start: z.string().describe('"HH:MM"'),
+    end: z.string().describe('"HH:MM"'),
+    timezone: z.string().describe("IANA timezone"),
+    allowedDays: z
+        .array(z.string())
+        .describe('ABBREVIATED day names: ["Mon","Tue","Wed","Thu","Fri"] (number-level format)'),
+    blockedDates: z.array(z.string()).default([]).describe('["YYYY-MM-DD"]'),
+})
+    .describe("Phone-number-level office hours (flat shape with abbreviated day names)");
+export function registerPhoneNumberTools(server, client) {
+    server.registerTool("trillet_list_phone_numbers", {
+        title: "List phone numbers",
+        description: "List the workspace's phone numbers: number, status, provider, bound agent/flow, recording, office hours, label.",
+        inputSchema: { ...workspaceParam },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ workspace_id }) => {
+        const res = await client.request("GET", "/v1/api/twilio/user-phone-numbers", {
+            workspaceId: workspace_id,
+        });
+        const list = Array.isArray(res) ? res : [];
+        return ok(list.map((n) => ({
+            id: n._id,
+            phoneNumber: n.phoneNumber,
+            label: n.label,
+            status: n.status,
+            provider: n.provider,
+            flowType: n.flowType,
+            agent: n.agentId ? { id: n.agentId._id ?? n.agentId, name: n.agentId.name } : null,
+            callFlowId: n.pathwayId?._id ?? n.pathwayId ?? null,
+            recordingEnabled: n.recordingEnabled,
+            officeHours: n.officeHours,
+            metadataTags: n.metadataTags,
+            secretBindings: n.secretBindings,
+            monthlyPrice: n.monthlyPrice,
+        })));
+    }));
+    server.registerTool("trillet_search_available_numbers", {
+        title: "Search available numbers",
+        description: "Search purchasable phone numbers. type is required except for AU. Toll-free numbers are not purchasable.",
+        inputSchema: {
+            country: z.string().describe('ISO country, e.g. "US", "AU", "GB"'),
+            type: z.string().optional().describe('"local" | "mobile" | "tollfree" (varies by country)'),
+            area_code: z.string().optional(),
+            contains: z.string().optional().describe("Digit pattern the number should contain"),
+            limit: z.number().default(10),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ country, type, area_code, contains, limit, workspace_id }) => {
+        const res = await client.request("GET", "/v1/api/twilio/available-numbers", {
+            query: { country, type, areaCode: area_code, contains, limit },
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+    server.registerTool("trillet_purchase_phone_number", {
+        title: "Purchase phone number (COSTS MONEY)",
+        description: "Purchase a phone number found via search. Free-plan allocations complete immediately (201 with mode 'free'); otherwise the response contains a Stripe Checkout URL the user must open to pay. Requires confirm=true after the user explicitly approves the purchase. type required except AU; addressSid required outside US/CA/AU/GB.",
+        inputSchema: {
+            country: z.string(),
+            phone_number: z.string().describe("Exact E.164 number from search results"),
+            type: z.string().optional(),
+            address_sid: z.string().optional(),
+            confirm: z.boolean().describe("Must be true. Only after the user explicitly approved."),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ country, phone_number, type, address_sid, confirm, workspace_id }) => {
+        if (!confirm) {
+            return ok({
+                blocked: true,
+                message: "Refusing: confirm=false. Purchasing a number bills the workspace. Ask the user first.",
+            });
+        }
+        const body = { country, phoneNumber: phone_number };
+        if (type)
+            body.type = type;
+        if (address_sid)
+            body.addressSid = address_sid;
+        const res = await client.request("POST", "/v1/api/twilio/purchase-number", {
+            body,
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+    server.registerTool("trillet_bind_phone_number", {
+        title: "Bind phone number to agent",
+        description: "Bind a workspace phone number to an agent so calls route to it (sets the number active, provisions SIP trunks for the flow's direction). The agent MUST already have a call flow. Omitted optional fields keep their current values. metadataTags values become {{_metadata.<key>}} in prompts/tools; secretBindings maps alias -> workspace secret NAME (both slug-safe lowercase) enabling per-number {{_secret.<alias>}}.",
+        inputSchema: {
+            agent_id: z.string(),
+            phone_number_id: z.string(),
+            record_calls: z.boolean().optional(),
+            recording_public: z.boolean().optional(),
+            office_hours: officeHoursNumberSchema.optional(),
+            metadata_tags: z.record(z.string(), z.string()).optional(),
+            secret_bindings: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe("alias -> existing workspace secret name; 400 if a name doesn't exist"),
+            label: z.string().optional(),
+            transfer_caller_id_mode: z.enum(["from-transferee", "from-transferor"]).optional(),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async (a) => {
+        const body = {};
+        if (a.record_calls !== undefined)
+            body.recordCalls = a.record_calls;
+        if (a.recording_public !== undefined)
+            body.recordingPublic = a.recording_public;
+        if (a.office_hours !== undefined)
+            body.officeHours = a.office_hours;
+        if (a.metadata_tags !== undefined)
+            body.metadataTags = a.metadata_tags;
+        if (a.secret_bindings !== undefined)
+            body.secretBindings = a.secret_bindings;
+        if (a.label !== undefined)
+            body.label = a.label;
+        if (a.transfer_caller_id_mode !== undefined)
+            body.transferCallerIdMode = a.transfer_caller_id_mode;
+        const res = await client.request("POST", `/v1/api/agents/${a.agent_id}/bind/${a.phone_number_id}`, { body, workspaceId: a.workspace_id });
+        return ok({
+            bound: true,
+            phoneNumber: res.phoneNumber?.phoneNumber,
+            agent: res.agent?.name,
+            direction: res.direction,
+        });
+    }));
+    server.registerTool("trillet_release_phone_number", {
+        title: "Release phone number from agent",
+        description: "Unbind a phone number from an agent (the number stays owned by the workspace, it just stops routing to the agent). Fails if the number is not currently bound to that agent.",
+        inputSchema: { agent_id: z.string(), phone_number_id: z.string(), ...workspaceParam },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ agent_id, phone_number_id, workspace_id }) => {
+        const res = await client.request("POST", `/v1/api/agents/${agent_id}/release/${phone_number_id}`, { workspaceId: workspace_id });
+        return ok(res);
+    }));
+    server.registerTool("trillet_get_phone_number_config", {
+        title: "Get phone number config",
+        description: "Fetch a number's routing config: agent, direction, recording, office hours, tags, bindings.",
+        inputSchema: { phone_number_id: z.string(), ...workspaceParam },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ phone_number_id, workspace_id }) => {
+        const res = await client.request("GET", `/v1/api/twilio/phone-numbers/${phone_number_id}/config`, { workspaceId: workspace_id });
+        return ok(res);
+    }));
+    server.registerTool("trillet_update_phone_number_config", {
+        title: "Update phone number config",
+        description: "Update a number's routing config in place: agent, max call duration, recording, office hours, caller-id mode on transfers, metadata tags, secret bindings, label. Only the fields you send change. Every secret name in secret_bindings must already exist as a workspace secret (400 otherwise).",
+        inputSchema: {
+            phone_number_id: z.string(),
+            agent_id: z.string().optional(),
+            max_call_duration: z.number().optional().describe("Seconds"),
+            recording_enabled: z.boolean().optional(),
+            office_hours: officeHoursNumberSchema.optional(),
+            transfer_caller_id_mode: z.enum(["from-transferee", "from-transferor"]).optional(),
+            metadata_tags: z.record(z.string(), z.string()).optional(),
+            secret_bindings: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe("alias -> existing workspace secret name"),
+            label: z.string().optional(),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async (a) => {
+        const body = {};
+        if (a.agent_id !== undefined)
+            body.agentId = a.agent_id;
+        if (a.max_call_duration !== undefined)
+            body.maxCallDuration = a.max_call_duration;
+        if (a.recording_enabled !== undefined)
+            body.recordingEnabled = a.recording_enabled;
+        if (a.office_hours !== undefined)
+            body.officeHours = a.office_hours;
+        if (a.transfer_caller_id_mode !== undefined)
+            body.transferCallerIdMode = a.transfer_caller_id_mode;
+        if (a.metadata_tags !== undefined)
+            body.metadataTags = a.metadata_tags;
+        if (a.secret_bindings !== undefined)
+            body.secretBindings = a.secret_bindings;
+        if (a.label !== undefined)
+            body.label = a.label;
+        const res = await client.request("PUT", `/v1/api/twilio/phone-numbers/${a.phone_number_id}/config`, { body, workspaceId: a.workspace_id });
+        return ok(res);
+    }));
+    server.registerTool("trillet_register_external_number", {
+        title: "Register BYO / SIP number",
+        description: "Register an externally-owned number (bring-your-own Twilio number or a SIP trunk from another carrier, e.g. CommsChannel) so Trillet can route calls on it. provider 'twilio' needs {accountSid, authToken}; provider 'sip' needs trunk credentials {address, username, password, sipType, appendPlus}. After registering, bind it to an agent like any other number. GOTCHA: DTMF keypresses are known to be dropped on some CommsChannel trunks.",
+        inputSchema: {
+            phone_number: z.string().describe("E.164 number being brought over"),
+            provider: z.enum(["twilio", "sip"]),
+            credentials: z
+                .record(z.string(), z.unknown())
+                .describe("Provider credentials. twilio: {accountSid, authToken}. sip: {address, username, password, sipType, appendPlus}"),
+            confirm: z
+                .boolean()
+                .describe("Must be true. Only set after the user explicitly approved registering this number."),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ phone_number, provider, credentials, confirm, workspace_id }) => {
+        if (!confirm) {
+            return ok({
+                blocked: true,
+                message: "Refusing: confirm=false. Registering an external number provisions trunks; ask the user to approve first.",
+            });
+        }
+        const workspaceId = workspace_id || (process.env.TRILLET_WORKSPACE_ID || "").trim();
+        const res = await client.request("POST", "/v1/api/twilio/register-external-number", {
+            body: { phoneNumber: phone_number, provider, credentials, workspaceId },
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+}

package/dist/tools/secrets.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { ok, guard, workspaceParam } from "../helpers.js";
+export function registerSecretTools(server, client) {
+    server.registerTool("trillet_list_secrets", {
+        title: "List workspace secrets",
+        description: "List workspace secrets (names and field names only; values are always masked and can never be read back). Reference syntax: {{_secret.<name>}} reads the api_key field, {{_secret.<name>.<field>}} reads a specific field. Code steps read them as secrets.<name>.<field>.",
+        inputSchema: { ...workspaceParam },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ workspace_id }) => {
+        const res = await client.request("GET", "/v2/api/workspaces/secrets", {
+            workspaceId: workspace_id,
+        });
+        return ok(res.secrets ?? res);
+    }));
+    server.registerTool("trillet_set_secret", {
+        title: "Create or update workspace secret",
+        description: "Create a workspace secret or merge fields into an existing one (upsert). Name must be slug-safe lowercase (letters, numbers, hyphen, underscore); field keys alphanumeric/underscore; values non-empty strings, encrypted at rest. Store third-party API keys here instead of pasting them into tool headers, then reference {{_secret.<name>}} in in-call API tool headers/urls.",
+        inputSchema: {
+            name: z.string().describe('Slug-safe, e.g. "airtable" or "stripe-test"'),
+            values: z
+                .record(z.string(), z.string())
+                .describe('Fields, e.g. {"api_key": "...", "base_url": "..."}. api_key is the default field.'),
+            description: z.string().optional(),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, guard(async ({ name, values, description, workspace_id }) => {
+        const res = await client.request("POST", "/v2/api/workspaces/secrets", {
+            body: { name, values, description },
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+    server.registerTool("trillet_delete_secret", {
+        title: "Delete workspace secret",
+        description: "Delete a workspace secret by name. Any {{_secret.<name>}} references in tools or workflows will resolve to empty strings afterwards.",
+        inputSchema: { name: z.string(), ...workspaceParam },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ name, workspace_id }) => {
+        const res = await client.request("DELETE", `/v2/api/workspaces/secrets/${encodeURIComponent(name)}`, {
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+}