@trillet-ai/mcp 0.7.3

package/dist/tools/textCalls.js

@@ -0,0 +1,223 @@
+/**
+ * Interactive text test calls: hold a turn-by-turn TEXT conversation with a
+ * real agent, exactly like the dashboard Test panel in text mode.
+ *
+ * Verified live against production (2026-08-27/28):
+ *  - POST /v1/api/calls/web/connect with mode:"text" starts a text-mode web
+ *    call for BOTH flow kinds — simple prompt flows and node flows. Node flows
+ *    run the REAL runtime over text: typed turns go through extraction and the
+ *    live router (unlike trillet_simulate_node_graph, whose router is mocked).
+ *  - The reply does NOT include the LiveKit ws URL (the dashboard reads it
+ *    from build-time env), hence the host map below.
+ *  - Text calls are real calls: they create a CallHistory row (transcript,
+ *    post-call analysis, cost — LLM only, no TTS/telephony) and REAL side
+ *    effects run (bookings, webhooks, transfers). stub_incall_apis only stubs
+ *    node-flow In-Call API nodes with their configured testResponse.
+ *  - Text mode relaxes the silence timers (>=90s before the "are you there?"
+ *    nudge), so normal thinking time between tool calls is safe.
+ */
+import { z } from "zod";
+import { ok, guard, workspaceParam } from "../helpers.js";
+import { ensureRtcNode, rtcNodeInstalled, depsDir } from "../textcall/deps.js";
+import { createSession, getSession, unknownSession, activeSessionCount, collectAgentTurns, endSession, rpc, } from "../textcall/session.js";
+/**
+ * LiveKit ws host per backend. The connect response omits it, so mirror the
+ * dashboard's build-time env. Override with TRILLET_LIVEKIT_URL for other
+ * environments; a `connection.url` in the API response (future backend
+ * addition) always wins.
+ */
+const LIVEKIT_URLS = {
+    "api.trillet.ai": "wss://trillet-ai-xdx0dw5r.livekit.cloud",
+    "api-trillet.verlatai.com": "wss://trilletai-ek0j3un1.livekit.cloud",
+    localhost: "wss://trilletai-ek0j3un1.livekit.cloud",
+    "127.0.0.1": "wss://trilletai-ek0j3un1.livekit.cloud",
+};
+function resolveLivekitUrl(baseUrl, connectRes) {
+    if (connectRes?.connection?.url)
+        return connectRes.connection.url;
+    if (process.env.TRILLET_LIVEKIT_URL)
+        return process.env.TRILLET_LIVEKIT_URL;
+    const host = new URL(baseUrl).hostname;
+    const url = LIVEKIT_URLS[host];
+    if (!url) {
+        throw new Error(`Don't know the LiveKit URL for backend host '${host}'. Set TRILLET_LIVEKIT_URL to the environment's wss:// LiveKit URL.`);
+    }
+    return url;
+}
+// Concurrency caps. The session registry is process-wide, so in an embedded
+// multi-tenant host (the dashboard assistant backend) the instance cap guards
+// worker memory while the per-workspace cap keeps one tenant from starving the
+// rest. The stdio MCP server is single-user, where the default instance cap of
+// 4 acts exactly as before; embedders raise it via TRILLET_MCP_MAX_TEXT_CALLS.
+const MAX_ACTIVE_SESSIONS = Number(process.env.TRILLET_MCP_MAX_TEXT_CALLS || 4);
+const MAX_ACTIVE_PER_WORKSPACE = Number(process.env.TRILLET_MCP_MAX_TEXT_CALLS_PER_WORKSPACE || 2);
+function sessionSummary(s) {
+    return {
+        session_id: s.id,
+        agent: s.agentName ?? s.agentId,
+        room_name: s.roomName,
+        call_history_id: s.callHistoryId,
+        ended: s.ended,
+        ...(s.endReason ? { end_reason: s.endReason } : {}),
+    };
+}
+export function registerTextCallTools(server, client) {
+    server.registerTool("trillet_start_text_call", {
+        title: "Start a text test call",
+        description: "Start an interactive TEXT conversation with an agent — the same thing as the dashboard Test panel in text mode. Works for both flow kinds (simple prompt flows and node flows; node flows run the real router and variable extraction). Returns a session_id plus the agent's greeting; continue with trillet_say and finish with trillet_end_text_call. Notes: this is a real call (CallHistory row, LLM cost of a few cents, transcript + post-call analysis) and non-stubbed side effects (bookings, webhooks, transfers) EXECUTE FOR REAL. Pass flow_id to test that flow's ACTIVE EDITOR DRAFT when one exists (exactly like the Test panel while editing). First ever use installs a native LiveKit client (~30-60s, needs npm).",
+        inputSchema: {
+            agent_id: z.string().optional().describe("Agent to talk to. Omit only if flow_id is given (the flow's agent is used)."),
+            flow_id: z
+                .string()
+                .optional()
+                .describe("Call-flow (pathway) id. When provided it is passed like the editor Test panel does: if the flow has an active draft, the DRAFT config is tested instead of production."),
+            dynamic_variables: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe("Per-call variables substituted into the prompt as {{key}}"),
+            direction: z
+                .enum(["inbound", "outbound"])
+                .optional()
+                .describe("Test as this call direction (welcome message + prompt behave accordingly)"),
+            stub_incall_apis: z
+                .boolean()
+                .default(true)
+                .describe("Node flows only: In-Call API nodes return their configured testResponse instead of hitting the real endpoint (the editor Test panel default). Other tools still run for real."),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, guard(async ({ agent_id, flow_id, dynamic_variables, direction, stub_incall_apis, workspace_id }) => {
+        if (!agent_id && !flow_id)
+            throw new Error("Provide agent_id or flow_id.");
+        const sessionWorkspace = workspace_id || client.workspaceId;
+        if (activeSessionCount(sessionWorkspace) >= MAX_ACTIVE_PER_WORKSPACE) {
+            throw new Error(`This workspace already has ${MAX_ACTIVE_PER_WORKSPACE} active text calls. End one with trillet_end_text_call first.`);
+        }
+        if (activeSessionCount() >= MAX_ACTIVE_SESSIONS) {
+            throw new Error('The platform is at its text-call capacity right now. Try again in a minute.');
+        }
+        // Resolve the agent from the flow when only flow_id was given.
+        let agentId = agent_id;
+        if (!agentId) {
+            const flow = await client.request("GET", `/v1/api/call-flows/${flow_id}`, {
+                workspaceId: workspace_id,
+            });
+            const p = flow.pathway ?? flow;
+            agentId = p.agent?._id ?? p.agent ?? p.agentId;
+            if (!agentId)
+                throw new Error(`Call flow ${flow_id} has no agent attached.`);
+        }
+        // First use: install the native LiveKit client into ~/.trillet-mcp.
+        if (!rtcNodeInstalled())
+            await ensureRtcNode();
+        const body = { agentId, mode: "text" };
+        if (dynamic_variables && Object.keys(dynamic_variables).length)
+            body.dynamic_variables = dynamic_variables;
+        if (flow_id)
+            body.pathwayId = flow_id;
+        if (direction)
+            body.test_direction = direction;
+        if (stub_incall_apis)
+            body.isTestCall = true;
+        const res = await client.request("POST", "/v1/api/calls/web/connect", {
+            body,
+            workspaceId: workspace_id,
+        });
+        const url = resolveLivekitUrl(client.baseUrl, res);
+        const session = createSession({
+            // Default: re-fork this same bundle (index.ts dispatches on the env
+            // flag). Embedders that aren't the stdio server (e.g. the backend AI
+            // assistant) point this at a tiny script that calls runTextCallWorker.
+            selfPath: process.env.TRILLET_MCP_TEXTCALL_WORKER_PATH || process.argv[1],
+            agentId: String(agentId),
+            agentName: res.agent?.name ?? null,
+            roomName: res.roomName,
+            callId: res.callId ?? null,
+            callHistoryId: res.callHistoryId ?? null,
+            workspaceId: sessionWorkspace,
+        });
+        try {
+            await rpc(session, "connect", { url, token: res.token }, 20_000);
+        }
+        catch (e) {
+            await endSession(session, "connect_failed");
+            throw e;
+        }
+        // The agent joins ~0.5s after room creation and greets ~2-4s in.
+        const greeting = await collectAgentTurns(session, { timeoutMs: 60_000 });
+        return ok({
+            ...sessionSummary(session),
+            greeting: greeting.turns,
+            ...(greeting.timedOut ? { warning: "No greeting within 60s — the agent may be aiFirst-disabled or failing; try trillet_say anyway or check trillet_get_call." } : {}),
+            next: "Send caller turns with trillet_say; hang up with trillet_end_text_call.",
+        });
+    }));
+    server.registerTool("trillet_say", {
+        title: "Say something in a text test call",
+        description: "Send one caller message in an active text test call and wait for the agent's reply (usually ~1-3s; up to 90s when the agent runs tools). Returns the agent's message(s) plus call_ended when the agent hung up (end_call / transfer / silence policy). Any messages the agent sent unprompted while you were away are returned in unprompted_messages.",
+        inputSchema: {
+            session_id: z.string(),
+            text: z.string().describe("What the caller says"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, guard(async ({ session_id, text }) => {
+        const s = getSession(session_id);
+        if (!s)
+            throw unknownSession(session_id);
+        if (s.ended) {
+            return ok({
+                ...sessionSummary(s),
+                call_ended: true,
+                note: "The call already ended; use trillet_end_text_call for the transcript or start a new call.",
+            });
+        }
+        // Nudges the agent sent while idle ("are you still there?") queue up;
+        // surface them separately so they aren't mistaken for the reply.
+        const unprompted = s.queue.splice(0);
+        s.transcript.push({ role: "caller", text, at: new Date().toISOString() });
+        s.lastActivityAt = Date.now();
+        await rpc(s, "say", { text }, 10_000);
+        const reply = await collectAgentTurns(s, { timeoutMs: 90_000 });
+        return ok({
+            session_id: s.id,
+            ...(unprompted.length ? { unprompted_messages: unprompted } : {}),
+            agent_messages: reply.turns,
+            ...(reply.timedOut ? { warning: "No reply within 90s. The call is still open — retry trillet_say or end the call." } : {}),
+            call_ended: s.ended,
+            ...(s.ended ? { end_reason: s.endReason, note: "Agent ended the call. trillet_end_text_call returns the full transcript." } : {}),
+        });
+    }));
+    server.registerTool("trillet_end_text_call", {
+        title: "End a text test call",
+        description: "Hang up a text test call (or clean up one the agent already ended) and get the full transcript. Post-call analysis and summary land on the call record ~30-60s later — fetch them with trillet_get_call using call_history_id.",
+        inputSchema: {
+            session_id: z.string(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, guard(async ({ session_id }) => {
+        const s = getSession(session_id);
+        if (!s)
+            throw unknownSession(session_id);
+        const alreadyEnded = s.ended;
+        await endSession(s, alreadyEnded ? s.endReason : "ended_by_tester");
+        if (!alreadyEnded) {
+            // Same room teardown the dashboard panel performs on hang-up.
+            await client
+                .request("POST", "/v1/api/calls/web/disconnect", {
+                body: { roomName: s.roomName },
+                workspaceId: s.workspaceId,
+            })
+                .catch(() => undefined);
+        }
+        return ok({
+            ...sessionSummary(s),
+            transcript: s.transcript.map((t) => `[${t.role}] ${t.text}`),
+            turns: s.transcript.length,
+            tip: s.callHistoryId
+                ? `Analysis/summary/cost: trillet_get_call call_id=${s.callHistoryId} (ready ~30-60s after the call ends).`
+                : "No call_history_id was returned for this call.",
+        });
+    }));
+}
+/** Exported for troubleshooting messages elsewhere. */
+export const textCallDepsDir = depsDir;

package/dist/tools/workflows.js

@@ -0,0 +1,415 @@
+import { z } from "zod";
+import { ok, guard, workspaceParam } from "../helpers.js";
+const WORKFLOW_REFERENCE = `# Trillet Workflow Reference (verified against the backend)
+
+Workflows are trigger-driven automation graphs (schemaVersion 2). Lifecycle: create (draft) ->
+test -> activate -> runs. Drafts and paused workflows NEVER fire from real triggers.
+
+## Triggers (7 types) and their {{trigger.*}} payloads
+- inbound_call_completed / outbound_call_completed: phone, disposition, duration, summary,
+  transcript (flattened "role: text" lines), recordingUrl, pathwayId, analyzedData.<field>,
+  responseVariables.<field>. Web/dashboard test calls fire the OUTBOUND trigger.
+- webhook: whole request body + normalized phone/email/full_name. Two URL styles: per-workflow
+  /v1/api/workflow-webhook/<webhookToken>, or the workspace-shared endpoint (requires
+  trigger.config.listenMode:"workspace"). Last payload is captured even for drafts.
+- schedule: trigger.config.cron (5/6-field or @daily style) + trigger.config.timezone
+  (IANA; falls back to settings.timezone then UTC). Payload: source, scheduledAt, lastRunAt.
+  No contact fields, so per-contact dedup is skipped.
+- inbound_message: phone, body, message, channel.
+- ghl_new_contact: phone, email, full_name, tags[]. meta_ads_lead: phone, email, full_name,
+  first_name, last_name, ad_name, page_id, form_id.
+
+## trigger.config extras
+- businessHours: { mode: "after_hours" (run only when closed) | "during_hours" | "none",
+  timezone (REQUIRED when mode set; missing tz = silently never runs),
+  perDay: { Monday..Sunday: {enabled,start,end} }, blockedDates: ["yyyy-MM-dd"] }.
+  There is NO "holidays" key; use blockedDates.
+- contactMapping: { phoneFields[], emailFields[], nameFields[], lastNameFields[],
+  defaultCountry } - ordered fallbacks mapping raw payload fields to phone/email/full_name,
+  applied BEFORE filters (phone normalized to E.164).
+
+## trigger.filters
+[{field (dot-path into payload, e.g. "pathwayId"), operator, value}]. ALL must pass.
+Operators (ONLY these 8): equals, not_equals, equals_ci, not_equals_ci, contains,
+not_contains, is_empty, is_not_empty. gt/lt are NOT valid on trigger filters.
+
+SCOPING TO ONE AGENT: there is no agentIds field. A call-completed workflow is tied to a
+single flow ONLY by a filter row {field: "pathwayId", operator: "equals", value: <pathway id>}.
+With no such row it fires after EVERY agent's calls in the workspace, which is rarely what
+someone means by "a workflow for this agent" - always add the filter unless workspace-wide is
+intended. Note the id mismatch: this filter takes a PATHWAY (call flow) id, while a
+make_ai_call step takes an AGENT id. Get both from the call-flow/node-flow get tools.
+
+## Step types (15) and their config
+Common: { stepId (unique), type, name, config, onError: stop|continue|retry (retry uses
+maxRetries, default 3) }.
+- send_sms: { to (default {{trigger.phone}}), message, from (REQUIRED phone number owned by the
+  workspace; "pool" is rejected) }. Message <=1600 chars, must not start with [ or {, and must
+  not contain {{trigger.transcript}} or {{trigger.analyzedData}}. Needs wallet balance > 0.
+- send_email: { to (default {{trigger.email}}; multi-recipient: comma/semicolon/newline
+  separated or array, "Name <a@x.com>" ok), subject, body (HTML), replyTo }. Sender = workspace
+  email connection / verified domain, else Trillet default.
+- send_email_to_group: { routeVariable (a trigger field name, e.g. an analyzedData field),
+  routes: [{matchValue, recipients[], subject, body}], defaultRoute {recipients[],subject,body} }.
+  Routes on {{trigger.<routeVariable>}} case-insensitively; no match + no defaultRoute = no-op.
+- make_ai_call: { agentId (REQUIRED), to (default {{trigger.phone}}), from (must be one of the
+  agent's numbers), dynamicVariables ({k:v} or [{key,value}]), waitForCompletion,
+  completionTimeout + completionTimeoutUnit (default 2h) }. waitForCompletion pauses the run
+  until the call ends; read results via {{steps.<id>.<callResult field>}}.
+- wait_delay: { duration, unit: seconds|minutes|hours|days (default minutes) }.
+- wait_for_reply: { timeout, timeoutUnit }. Waits for an inbound SMS from the run's contact.
+  Output: { outcome: "reply_received"|"timed_out", reply_text, received_at }.
+- send_webhook: { url, method (default POST), headers (object or [{key,value}]),
+  body (JSON, template-resolved), responseMapping {varName:"a.b.c"} }. GET sends body as query
+  params. Private/loopback IPs are blocked. Secrets: {{_secret.<name>}} or
+  {{_secret.<name>.<field>}} (workspace secrets; ONLY valid in send_webhook url/headers/body).
+- ghl_create_contact / ghl_update_contact: need the workflow's GHL integration connected via the
+  dashboard first. create: {firstName,lastName,email,phone,tags,customFields};
+  update: {lookupField (default {{trigger.phone}}), fields{}}.
+- condition: { matchType: "all"|"any", conditions: [{field, operator, value}] }. Operators: the
+  8 filter operators PLUS gt, gte, lt, lte. Output branch "yes"/"no" (an edge without
+  sourceHandle counts as "yes"). If the taken branch has no edge and the check failed, the run
+  ends with status "filtered".
+- switch: { branches: [{id, label, matchType, conditions[]}] }. First matching branch wins;
+  edges use sourceHandle=<branch id> plus an optional "default" edge.
+- set_variables: { assignments: [{name, value}] }. Read downstream as {{steps.<stepId>.<name>}}.
+  Assignments do not see each other.
+- google_sheets: { googleConnectionId, spreadsheetId, worksheetName, operation: "append"|"upsert",
+  matchColumn (upsert only, must be a mapped column), columnMappings: [{column, value}] }.
+  Google connection is set up in the dashboard.
+- code: { code (JavaScript, REQUIRED), timeoutMs (1000-30000) }. Deployed to Cloudflare Workers
+  when the workflow is SAVED; activation FAILS (502) if the deploy fails. Receives
+  variables = {trigger, steps, item, system} and a secrets object; must return a plain object
+  whose keys become {{steps.<id>.*}} outputs. Runs FOR REAL in test mode.
+- for_each: { items (template resolving to an array, e.g. {{steps.x.list}}), maxItems (REQUIRED,
+  1-1000), contact {phone,email,name} (may use {{item.*}}) }. Needs an "each" edge (loop body,
+  run as a child run per item with {{item.*}} available) and a "done" edge (parent continues
+  immediately; it does NOT wait for children). No nested for_each.
+
+## Edges / graph rules
+[{id, source (stepId or "trigger"), target, sourceHandle?}]. sourceHandle: condition "yes"/"no";
+switch <branch id>/"default"; for_each "each"/"done"; ALL other step types must omit it.
+Max ONE outgoing edge per handle (no fan-out). No cycles. Every step must be reachable from the
+entry step or activation fails.
+
+## settings
+{ timezone (default Australia/Sydney; only used as schedule-tz fallback), maxConcurrentRuns
+(default 50; excess runs queue), maxRunsPerContact (default 1 !) + maxRunsPerContactWindow
+(default 86400s) - repeat calls from the same number are SILENTLY skipped when exceeded,
+deduplicationWindow (default 60s) }. Contact identity = trigger phone else email; no contact =
+limits skipped.
+
+## Template system
+Roots: {{trigger.*}}, {{steps.<stepId>.<field>}} (auto-aliases into .output/.callResult),
+{{item.*}} (inside for_each children only), {{system.now|runId|workflowId|workspaceName}}.
+Interpolating a whole object/array renders '' - only leaf fields interpolate.
+Functions: if, ifempty, upper, lower, concat, replace, switch, formatDate, parseDate, dateAdd,
+addDays, startOf, endOf, now, normalizePhone, digits, random, substring, length, gt, gte, lt,
+lte, eq, and, or, not, add, sub, inTimeWindow. No nested {{ }}.
+
+## Testing vs running
+- test (works on drafts): SIMULATES send_sms, send_email(_to_group), make_ai_call, send_webhook,
+  ghl_*, google_sheets (returns wouldSend previews); delays resolve instantly. condition, switch,
+  set_variables, for_each and CODE run for real.
+- run (active only): full real execution, side effects included.
+
+## Billing
+Completed runs are metered against plan allotments (Basic 500 / Studio 2000 / Agency 10000 per
+month, Enterprise unmetered) with wallet overage per extra run. for_each children each count.`;
+const stepSchema = z.object({
+    stepId: z.string().describe("Unique step id within the workflow"),
+    type: z
+        .enum([
+        "send_sms",
+        "send_email",
+        "send_email_to_group",
+        "make_ai_call",
+        "wait_delay",
+        "wait_for_reply",
+        "send_webhook",
+        "ghl_create_contact",
+        "ghl_update_contact",
+        "condition",
+        "switch",
+        "set_variables",
+        "google_sheets",
+        "code",
+        "for_each",
+    ])
+        .describe("Step type; per-type config fields are in trillet_workflow_reference"),
+    name: z.string().optional(),
+    config: z.record(z.string(), z.unknown()).default({}),
+    onError: z.enum(["stop", "continue", "retry"]).default("stop"),
+    maxRetries: z.number().optional().describe("Retry attempts when onError='retry' (default 3)"),
+});
+const edgeSchema = z.object({
+    id: z.string(),
+    source: z.string().describe("stepId or the literal 'trigger'"),
+    target: z.string(),
+    sourceHandle: z
+        .string()
+        .optional()
+        .describe("'yes'/'no' for condition, branch id or 'default' for switch, 'each'/'done' for for_each; MUST be omitted for all other step types"),
+});
+const triggerTypes = z.enum([
+    "inbound_call_completed",
+    "outbound_call_completed",
+    "webhook",
+    "schedule",
+    "inbound_message",
+    "ghl_new_contact",
+    "meta_ads_lead",
+]);
+function summarizeWorkflow(w) {
+    return {
+        id: w._id,
+        name: w.name,
+        status: w.status,
+        trigger: w.trigger?.type,
+        filters: w.trigger?.filters,
+        steps: (w.steps ?? []).map((s) => `${s.stepId}(${s.type})`),
+        stats: w.stats,
+    };
+}
+function summarizeRun(r) {
+    return {
+        id: r._id,
+        status: r.status,
+        skipReason: r.skipReason,
+        contactPhone: r.contactPhone,
+        contactEmail: r.contactEmail,
+        currentStepId: r.currentStepId,
+        completedSteps: r.completedSteps,
+        totalSteps: r.totalSteps,
+        error: r.error,
+        testMode: r.testMode,
+        createdAt: r.createdAt,
+        finishedAt: r.finishedAt ?? r.completedAt,
+    };
+}
+export function registerWorkflowTools(server, client) {
+    server.registerTool("trillet_workflow_reference", {
+        title: "Workflow reference",
+        description: "Return the complete reference for Trillet automation workflows: all 7 trigger types with their payloads, all 15 step types with exact config fields, edge/graph rules, settings gotchas, the template/function system, test-vs-run semantics, and billing. READ THIS FIRST before creating or editing any workflow.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, guard(async () => ok(WORKFLOW_REFERENCE)));
+    server.registerTool("trillet_list_workflows", {
+        title: "List workflows",
+        description: "List automation workflows in the workspace with compact summaries.",
+        inputSchema: {
+            status: z.enum(["draft", "active", "paused", "archived"]).optional(),
+            trigger_type: triggerTypes.optional(),
+            search: z.string().optional().describe("Name search"),
+            page: z.number().default(1),
+            limit: z.number().default(20),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ status, trigger_type, search, page, limit, workspace_id }) => {
+        const res = await client.request("GET", "/v1/api/workflows", {
+            query: { status, triggerType: trigger_type, search, page, limit },
+            workspaceId: workspace_id,
+        });
+        const list = Array.isArray(res) ? res : res.workflows ?? res.data ?? [];
+        return ok({ total: res.total, workflows: list.map(summarizeWorkflow) });
+    }));
+    server.registerTool("trillet_get_workflow", {
+        title: "Get workflow",
+        description: "Fetch one workflow: full trigger (type, config, filters), steps with configs, edges, settings, status, stats, and webhook token if any.",
+        inputSchema: { workflow_id: z.string(), ...workspaceParam },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ workflow_id, workspace_id }) => {
+        const res = await client.request("GET", `/v1/api/workflows/${workflow_id}`, {
+            workspaceId: workspace_id,
+        });
+        return ok(res.workflow ?? res);
+    }));
+    server.registerTool("trillet_create_workflow", {
+        title: "Create workflow",
+        description: "Create an automation workflow (created as a draft; test with trillet_test_workflow, then trillet_activate_workflow). Consult trillet_workflow_reference for step configs, trigger payloads, and template variables before building. " +
+            "GOTCHA: settings.maxRunsPerContact defaults to 1 per 24h and silently skips repeat runs for the same contact; this tool defaults it to 500. Filter call-completed triggers to one flow with a filter on 'pathwayId'.",
+        inputSchema: {
+            name: z.string(),
+            description: z.string().optional(),
+            trigger_type: triggerTypes,
+            trigger_config: z
+                .record(z.string(), z.unknown())
+                .default({})
+                .describe("Trigger extras: schedule needs {cron, timezone}; webhook may set {listenMode:'workspace'}; optional businessHours gate {mode:'after_hours'|'during_hours', timezone, perDay, blockedDates} and contactMapping (see reference)"),
+            trigger_filters: z
+                .array(z.object({ field: z.string(), operator: z.string(), value: z.unknown() }))
+                .default([])
+                .describe('ALL must pass. Operators: equals, not_equals, equals_ci, not_equals_ci, contains, not_contains, is_empty, is_not_empty (gt/lt NOT valid here). e.g. [{"field":"pathwayId","operator":"equals","value":"<flow id>"}]'),
+            steps: z.array(stepSchema),
+            edges: z
+                .array(edgeSchema)
+                .describe("Graph edges; first edge usually {source:'trigger', target:<first stepId>}. Max one edge per handle, no cycles, all steps must be reachable."),
+            timezone: z.string().default("Australia/Sydney"),
+            max_runs_per_contact: z.number().default(500),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, guard(async ({ name, description, trigger_type, trigger_config, trigger_filters, steps, edges, timezone, max_runs_per_contact, workspace_id, }) => {
+        const res = await client.request("POST", "/v1/api/workflows", {
+            body: {
+                name,
+                description,
+                trigger: { type: trigger_type, filters: trigger_filters, config: trigger_config },
+                steps,
+                edges,
+                schemaVersion: 2,
+                settings: {
+                    timezone,
+                    maxRunsPerContact: max_runs_per_contact,
+                    maxRunsPerContactWindow: 86400,
+                    deduplicationWindow: 5,
+                },
+            },
+            workspaceId: workspace_id,
+        });
+        return ok(summarizeWorkflow(res));
+    }));
+    server.registerTool("trillet_update_workflow", {
+        title: "Update workflow",
+        description: "Partial update of a workflow (name, trigger, steps, edges, settings). Steps and edges replace wholesale when provided. Active workflows keep running the updated definition. stats/webhookToken/ids are server-managed and ignored if sent.",
+        inputSchema: {
+            workflow_id: z.string(),
+            update: z.record(z.string(), z.unknown()),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ workflow_id, update, workspace_id }) => {
+        const res = await client.request("PUT", `/v1/api/workflows/${workflow_id}`, {
+            body: update,
+            workspaceId: workspace_id,
+        });
+        return ok(summarizeWorkflow(res));
+    }));
+    server.registerTool("trillet_activate_workflow", {
+        title: "Activate workflow",
+        description: "Activate a draft or paused workflow so its trigger starts firing. Fails if: no trigger or no steps, invalid cron (schedules), unreachable steps, or a code step that fails to deploy to Cloudflare (502).",
+        inputSchema: { workflow_id: z.string(), ...workspaceParam },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, guard(async ({ workflow_id, workspace_id }) => {
+        // The API 400s on an empty body with a JSON content-type; the client
+        // always sends {} so this is safe.
+        const res = await client.request("POST", `/v1/api/workflows/${workflow_id}/activate`, {
+            workspaceId: workspace_id,
+        });
+        return ok({ id: res._id, status: res.status });
+    }));
+    server.registerTool("trillet_pause_workflow", {
+        title: "Pause workflow",
+        description: "Pause an active workflow: its trigger stops firing (schedules are unregistered). Reactivate with trillet_activate_workflow.",
+        inputSchema: { workflow_id: z.string(), ...workspaceParam },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, guard(async ({ workflow_id, workspace_id }) => {
+        const res = await client.request("POST", `/v1/api/workflows/${workflow_id}/pause`, {
+            workspaceId: workspace_id,
+        });
+        return ok({ id: res._id, status: res.status });
+    }));
+    server.registerTool("trillet_delete_workflow", {
+        title: "Delete workflow",
+        description: "Delete a workflow (soft delete). Cancels its running/waiting/queued runs and unregisters its schedule. Always confirm with the user first; requires confirm=true.",
+        inputSchema: {
+            workflow_id: z.string(),
+            confirm: z
+                .boolean()
+                .describe("Must be true. Only set after the user explicitly approved deleting this workflow."),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, guard(async ({ workflow_id, confirm, workspace_id }) => {
+        if (!confirm) {
+            return ok({
+                blocked: true,
+                message: "Refusing to delete: confirm=false. Ask the user to approve deleting workflow " +
+                    workflow_id +
+                    " and retry with confirm=true.",
+            });
+        }
+        const res = await client.request("DELETE", `/v1/api/workflows/${workflow_id}`, {
+            workspaceId: workspace_id,
+        });
+        return ok(res ?? { deleted: workflow_id });
+    }));
+    server.registerTool("trillet_test_workflow", {
+        title: "Test workflow (simulated)",
+        description: "Run a workflow in test mode with a sample trigger payload. Works on drafts. SMS/email/calls/webhooks/sheets/GHL are SIMULATED (returns wouldSend previews) and delays resolve instantly - but condition/switch/set_variables/for_each and CODE steps run for real. Returns the run id; inspect with trillet_get_workflow_run.",
+        inputSchema: {
+            workflow_id: z.string(),
+            trigger_data: z
+                .record(z.string(), z.unknown())
+                .default({})
+                .describe('Sample trigger payload, e.g. {"phone":"+61412345678","analyzedData":{"outcome":"booked"}}'),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, guard(async ({ workflow_id, trigger_data, workspace_id }) => {
+        const res = await client.request("POST", `/v1/api/workflows/${workflow_id}/test`, {
+            body: { triggerData: trigger_data },
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+    server.registerTool("trillet_run_workflow", {
+        title: "Run workflow now (REAL side effects)",
+        description: "Trigger a REAL run of an ACTIVE workflow immediately: SMS, emails, AI calls, and webhooks actually fire and consume credits. Always confirm with the user first; requires confirm=true. For a dry run use trillet_test_workflow instead.",
+        inputSchema: {
+            workflow_id: z.string(),
+            trigger_data: z
+                .record(z.string(), z.unknown())
+                .default({})
+                .describe("Trigger payload for the run (fields readable as {{trigger.*}})"),
+            confirm: z
+                .boolean()
+                .describe("Must be true. Only set after the user explicitly approved a real run."),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, guard(async ({ workflow_id, trigger_data, confirm, workspace_id }) => {
+        if (!confirm) {
+            return ok({
+                blocked: true,
+                message: "Refusing to run: confirm=false. This executes real side effects (SMS/email/calls). Ask the user to approve and retry with confirm=true, or use trillet_test_workflow for a simulation.",
+            });
+        }
+        const res = await client.request("POST", `/v1/api/workflows/${workflow_id}/run`, {
+            body: { triggerData: trigger_data },
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+    server.registerTool("trillet_list_workflow_runs", {
+        title: "List workflow runs",
+        description: "List runs of a workflow (newest first) with status, contact, progress, and skip/error reasons. Statuses: running, waiting, queued, completed, failed, skipped (see skipReason - 'max_runs_per_contact' means the per-contact cap silently ate the trigger), filtered, cancelled.",
+        inputSchema: {
+            workflow_id: z.string(),
+            status: z.string().optional(),
+            page: z.number().default(1),
+            limit: z.number().default(20),
+            ...workspaceParam,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ workflow_id, status, page, limit, workspace_id }) => {
+        const res = await client.request("GET", `/v1/api/workflows/${workflow_id}/runs`, {
+            query: { status, page, limit },
+            workspaceId: workspace_id,
+        });
+        const runs = res.runs ?? res.data ?? [];
+        return ok({ total: res.total, runs: runs.map(summarizeRun) });
+    }));
+    server.registerTool("trillet_get_workflow_run", {
+        title: "Get workflow run detail",
+        description: "Fetch one workflow run with its per-step logs (inputs, outputs, errors, timings), plus parent/child runs for for_each loops. The primary tool for debugging why a workflow run did what it did.",
+        inputSchema: { run_id: z.string(), ...workspaceParam },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, guard(async ({ run_id, workspace_id }) => {
+        const res = await client.request("GET", `/v1/api/workflows/runs/${run_id}`, {
+            workspaceId: workspace_id,
+        });
+        return ok(res);
+    }));
+}

package/dist/version.js

@@ -0,0 +1,7 @@
+/**
+ * Single source of truth for the server version, used by the MCP handshake,
+ * the startup log, the HTTP user-agent, and the bundle header. Keep in sync
+ * with .claude-plugin/plugin.json, mcpb/manifest.json, and package.json when
+ * releasing (see README "Maintainers").
+ */
+export const VERSION = "0.7.3";