@aigentyc/mcp 0.2.2 → 0.4.0

package/dist/tools/forms.js

@@ -0,0 +1,833 @@
+import { z } from "zod";
+import { pid, projectIdArg } from "./helpers.js";
+import { defineTool } from "./types.js";
+// ── Field-level shapes ─────────────────────────────────────────────
+//
+// Mirrors `FormField` in the frontend (`src/types/forms.ts`). Kept as
+// passthrough on the JSON-shaped inner objects so the backend stays the source
+// of truth — we just block obvious typos at the MCP boundary.
+const formFieldType = z.enum([
+    "text",
+    "textarea",
+    "number",
+    "email",
+    "phone",
+    "date",
+    "time",
+    "select",
+    "multi_select",
+    "checkbox",
+    "radio",
+    "file",
+]);
+const formFieldOption = z.object({
+    value: z.string(),
+    label: z.string(),
+});
+const formFieldOptionsSource = z
+    .object({
+    sourceId: z
+        .string()
+        .min(1)
+        .describe("ID of a row in form_option_sources (see form_option_sources_list / form_option_sources_create)."),
+    dependsOn: z
+        .array(z.object({
+        fieldKey: z.string().min(1),
+        paramName: z.string().min(1),
+    }))
+        .optional(),
+    searchMode: z.enum(["server", "client", "off"]).optional(),
+})
+    .passthrough();
+const formField = z
+    .object({
+    id: z.string().min(1),
+    key: z
+        .string()
+        .min(1)
+        .describe("camelCase or snake_case field key. Used in templates as `{{field.key}}`."),
+    label: z.string().min(1),
+    type: formFieldType,
+    required: z.boolean().default(false),
+    placeholder: z.string().optional(),
+    helpText: z.string().optional(),
+    defaultValue: z.unknown().optional(),
+    options: z.array(formFieldOption).optional(),
+    optionsSource: formFieldOptionsSource.optional(),
+    validation: z
+        .object({
+        minLength: z.number().int().optional(),
+        maxLength: z.number().int().optional(),
+        min: z.number().optional(),
+        max: z.number().optional(),
+        pattern: z.string().optional(),
+        message: z.string().optional(),
+        maxFileSize: z
+            .number()
+            .int()
+            .optional()
+            .describe("Bytes. File fields only."),
+        allowedMimeTypes: z
+            .array(z.string())
+            .optional()
+            .describe("File fields only. Empty/omit = any."),
+    })
+        .partial()
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+// ── Action shapes ──────────────────────────────────────────────────
+//
+// Post-submit actions run in `order` on each submission. They form a chain:
+// every action with a `name` exposes its output under `{{steps.<name>.<path>}}`
+// for later actions. All string values flow through the template engine, which
+// understands `{{field.key}}` (submitted values), `{{meta.x}}` (submission
+// metadata), and `{{steps.<name>.x}}` (a prior action's output).
+//
+// The schema is a discriminated union on `type` so each action's `config` is
+// validated against its own shape. Every config object is `.passthrough()` so
+// any new key the backend introduces still flows through unblocked.
+const formActionRunIf = z
+    .object({
+    fieldKey: z.string(),
+    operator: z.enum([
+        "eq",
+        "neq",
+        "contains",
+        "exists",
+        "not_exists",
+        "lt",
+        "lte",
+        "gt",
+        "gte",
+    ]),
+    value: z.union([z.string(), z.number(), z.boolean()]).optional(),
+})
+    .describe("Run this action only when the named submitted field matches.");
+const emailActionConfig = z
+    .object({
+    to: z.string().min(1),
+    cc: z.string().optional(),
+    bcc: z.string().optional(),
+    replyTo: z.string().optional(),
+    subject: z.string(),
+    bodyTemplate: z.string(),
+    bodyType: z.enum(["html", "text"]).optional(),
+    attachments: z
+        .array(z.object({
+        fieldKey: z.string().min(1).describe("File field whose file to send."),
+        mode: z
+            .enum(["attach", "link"])
+            .describe("'attach' = binary attachment; 'link' = signed URL in body."),
+    }))
+        .optional()
+        .describe("Files to ship with the email, sourced from file fields."),
+})
+    .passthrough();
+const webhookActionConfig = z
+    .object({
+    url: z.string().url(),
+    method: z.enum(["POST", "PUT", "PATCH"]),
+    headers: z.record(z.string()).optional(),
+    bodyMode: z
+        .enum(["template", "auto_json", "multipart"])
+        .optional()
+        .describe("'auto_json' sends { form, meta, fields } (ignores bodyTemplate); 'template' renders bodyTemplate; 'multipart' sends form-data with bodyTemplate as the JSON part + binary parts from attachmentFieldKeys."),
+    bodyTemplate: z.string(),
+    attachmentFieldKeys: z
+        .array(z.string())
+        .optional()
+        .describe("File field keys sent as binary parts in 'multipart' mode."),
+    hmacSecret: z.string().optional(),
+    hmacHeaderName: z.string().optional(),
+})
+    .passthrough();
+const dataStoreActionConfig = z
+    .object({
+    storeId: z.string().min(1),
+    fieldMapping: z
+        .record(z.string())
+        .describe("Map of {data-store column → templated value}."),
+})
+    .passthrough();
+const toolCallActionConfig = z
+    .object({
+    toolId: z.string().min(1),
+    inputMapping: z
+        .record(z.string())
+        .describe("Map of {tool input param → templated value}."),
+})
+    .passthrough();
+const showMessageActionConfig = z
+    .object({ message: z.string() })
+    .passthrough();
+const salesforceActionConfig = z
+    .object({
+    integrationId: z
+        .string()
+        .min(1)
+        .describe("provider_integrations id (provider='salesforce')."),
+    sobject: z.string().min(1).describe("Target sObject, e.g. 'Lead'."),
+    fieldMapping: z
+        .record(z.string())
+        .describe("Map of {SF field name → templated value}."),
+    updatePolicy: z
+        .enum(["create_only", "upsert"])
+        .optional()
+        .describe("'create_only' (default) always inserts; 'upsert' matches via matchField."),
+    matchField: z
+        .string()
+        .optional()
+        .describe("For upsert: SF field to find an existing row (e.g. 'Email')."),
+    matchFieldIsExternalId: z
+        .boolean()
+        .optional()
+        .describe("Set true when matchField is a SF external ID (native PATCH-by-extId)."),
+    attachFileFieldKeys: z
+        .array(z.string())
+        .optional()
+        .describe("File field keys uploaded as ContentVersion + linked to the record."),
+})
+    .passthrough();
+const salesforceAttachActionConfig = z
+    .object({
+    integrationId: z.string().min(1),
+    targetRecordIdTemplate: z
+        .string()
+        .min(1)
+        .describe("Template resolving to the LinkedEntityId, e.g. '{{steps.case.id}}'."),
+    attachFileFieldKeys: z
+        .array(z.string())
+        .describe("File field keys whose files are attached to the target record."),
+})
+    .passthrough();
+const salesforceLookupActionConfig = z
+    .object({
+    integrationId: z.string().min(1),
+    soqlTemplate: z
+        .string()
+        .min(1)
+        .describe("SOQL with {{field.x}}/{{steps.y.z}} tokens (SOQL-escaped). LIMIT 1 enforced; first row exposed at {{steps.<name>.record.<field>}}."),
+    onNotFound: z
+        .enum(["fail", "continue"])
+        .optional()
+        .describe("Behavior when zero rows match. Defaults to 'fail'."),
+})
+    .passthrough();
+// Fields common to every action, regardless of type.
+const actionBase = {
+    id: z
+        .string()
+        .min(1)
+        .describe("Stable unique id for this action (generate one, e.g. a uuid)."),
+    order: z.number().int().min(0).describe("Execution order, ascending."),
+    continueOnError: z
+        .boolean()
+        .default(false)
+        .describe("When true, a failure here doesn't abort later actions."),
+    isActive: z.boolean().default(true),
+    name: z
+        .string()
+        .optional()
+        .describe("Slug used as the `{{steps.<name>}}` key for downstream actions. Keep it stable — renaming breaks references. Falls back to `step_<index+1>` when blank."),
+    runIf: formActionRunIf.optional(),
+    discoveredOutputPaths: z
+        .array(z.string())
+        .optional()
+        .describe("Dot-paths discovered by the last successful test run; powers `{{steps.<name>.<path>}}` hints. Normally written by forms_actions_test_run — rarely set by hand."),
+};
+const formAction = z.discriminatedUnion("type", [
+    z.object({ ...actionBase, type: z.literal("email"), config: emailActionConfig }),
+    z.object({
+        ...actionBase,
+        type: z.literal("webhook"),
+        config: webhookActionConfig,
+    }),
+    z.object({
+        ...actionBase,
+        type: z.literal("data_store"),
+        config: dataStoreActionConfig,
+    }),
+    z.object({
+        ...actionBase,
+        type: z.literal("tool_call"),
+        config: toolCallActionConfig,
+    }),
+    z.object({
+        ...actionBase,
+        type: z.literal("show_message"),
+        config: showMessageActionConfig,
+    }),
+    z.object({
+        ...actionBase,
+        type: z.literal("salesforce"),
+        config: salesforceActionConfig,
+    }),
+    z.object({
+        ...actionBase,
+        type: z.literal("salesforce_attach"),
+        config: salesforceAttachActionConfig,
+    }),
+    z.object({
+        ...actionBase,
+        type: z.literal("salesforce_lookup"),
+        config: salesforceLookupActionConfig,
+    }),
+]);
+// ── Settings ───────────────────────────────────────────────────────
+const formSettings = z
+    .object({
+    submitButtonText: z.string().optional(),
+    successMessage: z.string().optional(),
+    errorMessage: z.string().optional(),
+    direction: z.enum(["ltr", "rtl"]).optional(),
+    theme: z.enum(["default", "compact"]).optional(),
+    messages: z.record(z.string()).optional(),
+    rules: z.array(z.record(z.unknown())).optional(),
+})
+    .partial()
+    .passthrough();
+// ── Tool schemas ───────────────────────────────────────────────────
+const createFormSchema = z.object({
+    projectId: projectIdArg,
+    name: z.string().min(1).max(255),
+    description: z.string().optional(),
+    fields: z.array(formField).default([]),
+    settings: formSettings.default({}),
+    postSubmitActions: z.array(formAction).default([]),
+});
+const updateFormSchema = z.object({
+    projectId: projectIdArg,
+    formId: z.string().min(1),
+    patch: z
+        .object({
+        name: z.string().min(1).max(255).optional(),
+        description: z.string().nullable().optional(),
+        fields: z.array(formField).optional(),
+        settings: formSettings.optional(),
+        postSubmitActions: z.array(formAction).optional(),
+        isActive: z.boolean().optional(),
+    })
+        .describe("Any subset of form fields to update."),
+});
+export function formsTools(client) {
+    return [
+        defineTool({
+            name: "forms_list",
+            title: "List forms",
+            description: "List every form in the project — id, name, description, field count, action count, isActive, submission count.",
+            inputSchema: z.object({ projectId: projectIdArg }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.get(`/api/dashboard/${projectId}/forms`);
+            },
+        }),
+        defineTool({
+            name: "forms_get",
+            title: "Get a form",
+            description: "Fetch a single form with its full definition: fields, settings, post-submit actions.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                formId: z.string().min(1),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.get(`/api/dashboard/${projectId}/forms/${encodeURIComponent(args.formId)}`);
+            },
+        }),
+        defineTool({
+            name: "forms_create",
+            title: "Create a form",
+            description: [
+                "Create a form. Fields, post-submit actions, and conditional rules are all set up here.",
+                "",
+                "**Field types**: text, textarea, number, email, phone, date, time, select, multi_select, checkbox, radio, file.",
+                "Select-style fields can either inline `options` OR pull `optionsSource` from a form_option_sources row (HTTP or Salesforce-driven).",
+                "",
+                "**Actions** run on submission. Use `salesforce` to push to a configured provider integration (see integrations_list).",
+                "",
+                "**Linking to a chat tool**: create the form, then call `forms_link_to_tool` to expose it as a renderable tool inside the assistant.",
+            ].join("\n"),
+            inputSchema: createFormSchema,
+            handler: async (args) => {
+                const { projectId: rawPid, ...body } = args;
+                const projectId = pid(client, rawPid);
+                return client.post(`/api/dashboard/${projectId}/forms`, body);
+            },
+        }),
+        defineTool({
+            name: "forms_update",
+            title: "Update a form",
+            description: "Patch any subset of form fields, settings, or actions. Send the full new array for `fields`/`postSubmitActions` — they're not deep-merged.",
+            inputSchema: updateFormSchema,
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.patch(`/api/dashboard/${projectId}/forms/${encodeURIComponent(args.formId)}`, args.patch);
+            },
+        }),
+        defineTool({
+            name: "forms_delete",
+            title: "Delete a form",
+            description: "Delete a form. Destructive. Submissions and post-submit-action history are lost. By default refuses if the form is linked to a tool — pass `force=true` to override.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                formId: z.string().min(1),
+                force: z.boolean().default(false),
+                confirm: z.boolean().default(false),
+            }),
+            handler: async (args) => {
+                if (!args.confirm) {
+                    return {
+                        deleted: false,
+                        reason: "Destructive. Re-invoke with confirm=true.",
+                    };
+                }
+                const projectId = pid(client, args.projectId);
+                const path = args.force
+                    ? `/api/dashboard/${projectId}/forms/${encodeURIComponent(args.formId)}?force=true`
+                    : `/api/dashboard/${projectId}/forms/${encodeURIComponent(args.formId)}`;
+                return client.delete(path);
+            },
+        }),
+        defineTool({
+            name: "forms_export",
+            title: "Export a form bundle",
+            description: "Export a self-contained JSON bundle of the form plus every option source it references and every provider integration those sources point at. Secrets (auth headers, integration credentials) are STRIPPED — re-enter them in the target project after import.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                formId: z.string().min(1),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.get(`/api/dashboard/${projectId}/forms/${encodeURIComponent(args.formId)}/export`);
+            },
+        }),
+        defineTool({
+            name: "forms_import",
+            title: "Import a form bundle",
+            description: "Import a form bundle (from forms_export) into a project. New IDs are generated for the form, every option source, and every provider integration. Returns warnings for any references that couldn't be remapped (data stores, tool calls, missing integrations) — review before relying on the form.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                bundle: z
+                    .record(z.unknown())
+                    .describe("Bundle object as returned by forms_export."),
+                nameSuffix: z
+                    .string()
+                    .optional()
+                    .describe("Appended to the imported form's name (e.g. ' (imported)') to avoid collisions."),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.post(`/api/dashboard/${projectId}/forms/import`, {
+                    bundle: args.bundle,
+                    nameSuffix: args.nameSuffix,
+                });
+            },
+        }),
+        defineTool({
+            name: "forms_linked_tools",
+            title: "List tools linked to a form",
+            description: "Find every chat tool whose `formConfig.formId` references this form. Use before deleting to know what would break.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                formId: z.string().min(1),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.get(`/api/dashboard/${projectId}/forms/${encodeURIComponent(args.formId)}/linked-tools`);
+            },
+        }),
+        defineTool({
+            name: "forms_link_to_tool",
+            title: "Wire a form into a chat tool",
+            description: [
+                "Create a chat tool that renders the form inside the assistant.",
+                "Internally this is a `data_store` tool with `displayType: json_render` and a `_formConfig.formId` set to the form. Call this instead of building the tool by hand.",
+                "Returns the new tool row.",
+            ].join("\n"),
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                formId: z.string().min(1),
+                toolName: z
+                    .string()
+                    .min(1)
+                    .max(100)
+                    .describe("camelCase name the AI sees (e.g. `bookDemo`)."),
+                displayName: z.string().min(1).max(255),
+                description: z
+                    .string()
+                    .min(1)
+                    .describe("How the AI should understand when to surface this form (e.g. 'Use when the user asks to schedule a demo')."),
+                prefillFromInput: z
+                    .record(z.string())
+                    .optional()
+                    .describe("Map of {form field key → tool input parameter name}. The AI fills the form with values it has in scope."),
+                postSubmitMessage: z
+                    .string()
+                    .optional()
+                    .describe("Free-text shown to the user (and to the AI) right after a successful submission."),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                const formConfig = {
+                    formId: args.formId,
+                    ...(args.prefillFromInput
+                        ? { prefillFromInput: args.prefillFromInput }
+                        : {}),
+                    ...(args.postSubmitMessage
+                        ? { postSubmitMessage: args.postSubmitMessage }
+                        : {}),
+                };
+                const inputSchema = args.prefillFromInput
+                    ? Array.from(new Set(Object.values(args.prefillFromInput))).map((paramName) => ({
+                        name: paramName,
+                        description: `Value to prefill into a form field. Source: tool param ${paramName}.`,
+                        type: "string",
+                        required: false,
+                    }))
+                    : [];
+                return client.post(`/api/dashboard/${projectId}/tools`, {
+                    name: args.toolName,
+                    displayName: args.displayName,
+                    description: args.description,
+                    toolType: "form",
+                    inputSchema,
+                    formConfig,
+                    stopWhen: 1,
+                    timeoutMs: 5000,
+                    category: "forms",
+                });
+            },
+        }),
+        defineTool({
+            name: "forms_submissions_list",
+            title: "List form submissions",
+            description: "Paginated list of submissions for a form. Returns decrypted submission data + per-action results.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                formId: z.string().min(1),
+                page: z.number().int().min(1).default(1),
+                pageSize: z.number().int().min(1).max(200).default(50),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.get(`/api/dashboard/${projectId}/forms/${encodeURIComponent(args.formId)}/submissions`, { page: args.page, pageSize: args.pageSize });
+            },
+        }),
+        // ── Action lifecycle: test, retry, skip, replay ──────────────────
+        defineTool({
+            name: "forms_actions_test_run",
+            title: "Test-run a form's post-submit actions",
+            description: [
+                "Run a form's post-submit actions against sample data and return per-action results, rendered payloads, and the dot-paths discovered from each action's output (used for `{{steps.<name>.<path>}}` chaining).",
+                "",
+                "⚠️ This executes against LIVE integrations — Salesforce records, webhooks, and emails it produces are REAL, not mocked. Requires `confirm=true`.",
+                "",
+                "Pass `actions` to test an unsaved draft array (otherwise the form's saved actions run). `sampleData` is a `{ fieldKey: value }` map fed in as the submission. `untilActionId` stops the chain after that action. Discovered paths are persisted onto saved actions automatically.",
+            ].join("\n"),
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                formId: z.string().min(1),
+                actions: z
+                    .array(formAction)
+                    .optional()
+                    .describe("Draft action array to test. Omit to run the form's saved actions."),
+                sampleData: z
+                    .record(z.unknown())
+                    .optional()
+                    .describe("Map of { form field key → value } used as the test submission."),
+                untilActionId: z
+                    .string()
+                    .optional()
+                    .describe("Stop after running the action with this id."),
+                confirm: z.boolean().default(false),
+            }),
+            handler: async (args) => {
+                if (!args.confirm) {
+                    return {
+                        ran: false,
+                        reason: "Runs against LIVE integrations (real Salesforce records / webhooks / emails). Re-invoke with confirm=true.",
+                    };
+                }
+                const projectId = pid(client, args.projectId);
+                return client.post(`/api/dashboard/${projectId}/forms/${encodeURIComponent(args.formId)}/actions/test-run`, {
+                    actions: args.actions,
+                    sampleData: args.sampleData,
+                    untilActionId: args.untilActionId,
+                });
+            },
+        }),
+        defineTool({
+            name: "forms_submission_action_retry",
+            title: "Retry one action on a submission",
+            description: "Re-run a single failed/skipped action for a specific submission. Returns the updated submission status and action results.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                formId: z.string().min(1),
+                submissionId: z.string().min(1),
+                actionId: z.string().min(1),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.post(`/api/dashboard/${projectId}/forms/${encodeURIComponent(args.formId)}/submissions/${encodeURIComponent(args.submissionId)}/actions/${encodeURIComponent(args.actionId)}/retry`);
+            },
+        }),
+        defineTool({
+            name: "forms_submission_action_skip",
+            title: "Skip one action on a submission",
+            description: "Mark a single action as skipped for a submission so it no longer blocks the submission from being considered processed.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                formId: z.string().min(1),
+                submissionId: z.string().min(1),
+                actionId: z.string().min(1),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.post(`/api/dashboard/${projectId}/forms/${encodeURIComponent(args.formId)}/submissions/${encodeURIComponent(args.submissionId)}/actions/${encodeURIComponent(args.actionId)}/skip`);
+            },
+        }),
+        defineTool({
+            name: "forms_submission_replay",
+            title: "Replay a submission's actions",
+            description: "Re-run a submission's full action chain. Pass `fromActionId` to resume from a specific action instead of the start (earlier successful steps are reused).",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                formId: z.string().min(1),
+                submissionId: z.string().min(1),
+                fromActionId: z
+                    .string()
+                    .optional()
+                    .describe("Resume from this action id. Omit to replay the whole chain."),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.post(`/api/dashboard/${projectId}/forms/${encodeURIComponent(args.formId)}/submissions/${encodeURIComponent(args.submissionId)}/replay`, { fromActionId: args.fromActionId ?? null });
+            },
+        }),
+        defineTool({
+            name: "forms_submissions_bulk_retry",
+            title: "Bulk-retry recent failed submissions",
+            description: "Re-queue every submission with failed actions in the last `withinHours`. Defaults to a DRY RUN that only counts candidates — pass `dryRun=false` to actually enqueue the retries.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                formId: z.string().min(1),
+                withinHours: z.number().int().min(1).max(168).default(24),
+                dryRun: z
+                    .boolean()
+                    .default(true)
+                    .describe("True (default) only counts candidates. Set false to enqueue retries."),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.post(`/api/dashboard/${projectId}/forms/${encodeURIComponent(args.formId)}/submissions/bulk-retry`, { withinHours: args.withinHours, dryRun: args.dryRun });
+            },
+        }),
+        // ── Retry queue ──────────────────────────────────────────────────
+        defineTool({
+            name: "forms_retry_queue_list",
+            title: "List the action retry queue",
+            description: "List queued action retries across the project, with attempt counts, last error class/message, and next-retry time. Filter by `state`.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                state: z
+                    .string()
+                    .default("pending,in_progress,exhausted")
+                    .describe("Comma-separated states: pending, in_progress, succeeded, exhausted, cancelled."),
+                limit: z.number().int().min(1).max(200).default(50),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.get(`/api/dashboard/${projectId}/forms/retry-queue`, {
+                    state: args.state,
+                    limit: args.limit,
+                });
+            },
+        }),
+        defineTool({
+            name: "forms_retry_queue_item",
+            title: "Act on a retry-queue item",
+            description: "Operate on a single retry-queue item: `retry-now` schedules an immediate retry; `cancel` removes it from the queue.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                queueId: z.string().min(1),
+                op: z.enum(["retry-now", "cancel"]),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.patch(`/api/dashboard/${projectId}/forms/retry-queue/${encodeURIComponent(args.queueId)}`, { op: args.op });
+            },
+        }),
+        // ── Observability & alerting ─────────────────────────────────────
+        defineTool({
+            name: "forms_observability",
+            title: "Forms action health dashboard",
+            description: "Project-wide forms health: per-form 24h/7d success rates, needs_manual / needs_retry counts, top failure error codes (7d), retry-queue totals by state, and the recent alert dispatch summary.",
+            inputSchema: z.object({ projectId: projectIdArg }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.get(`/api/dashboard/${projectId}/forms/observability`);
+            },
+        }),
+        defineTool({
+            name: "forms_alert_rules_list",
+            title: "List form alert rules",
+            description: "List alert rules. Pass `formId` to scope to one form; omit for project-wide rules too.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                formId: z
+                    .string()
+                    .optional()
+                    .describe("Filter to rules scoped to this form."),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.get(`/api/dashboard/${projectId}/forms/alert-rules`, {
+                    formId: args.formId,
+                });
+            },
+        }),
+        defineTool({
+            name: "forms_alert_rules_create",
+            title: "Create a form alert rule",
+            description: [
+                "Create an alert rule that fires on form action events. At least one channel is required.",
+                "",
+                "Events: action_failed, submission_needs_manual, submission_needs_retry, retry_exhausted, rate_drop, critical_action_failed.",
+                "Channels: email (list of addresses), webhook ({ url, hmacSecret? }), inApp (boolean). `throttleMs` suppresses duplicates within the window (default 900000 = 15m). Omit `formId` to scope to the whole project.",
+            ].join("\n"),
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                name: z.string().min(1),
+                formId: z.string().nullable().optional(),
+                eventType: z.enum([
+                    "action_failed",
+                    "submission_needs_manual",
+                    "submission_needs_retry",
+                    "retry_exhausted",
+                    "rate_drop",
+                    "critical_action_failed",
+                ]),
+                filters: z
+                    .record(z.unknown())
+                    .nullable()
+                    .optional()
+                    .describe("Optional event-specific match filters."),
+                channels: z
+                    .object({
+                    email: z.array(z.string()).optional(),
+                    webhook: z
+                        .object({ url: z.string().url(), hmacSecret: z.string().optional() })
+                        .optional(),
+                    inApp: z.boolean().optional(),
+                })
+                    .describe("At least one of email / webhook / inApp must be set."),
+                throttleMs: z.number().int().min(0).optional(),
+                isActive: z.boolean().optional(),
+            }),
+            handler: async (args) => {
+                const { projectId: rawPid, ...body } = args;
+                const projectId = pid(client, rawPid);
+                return client.post(`/api/dashboard/${projectId}/forms/alert-rules`, body);
+            },
+        }),
+        defineTool({
+            name: "forms_alert_rules_update",
+            title: "Update a form alert rule",
+            description: "Patch any subset of an alert rule's fields. `channels` and `filters` replace wholesale (not deep-merged).",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                ruleId: z.string().min(1),
+                patch: z
+                    .object({
+                    name: z.string().min(1).optional(),
+                    formId: z.string().nullable().optional(),
+                    eventType: z
+                        .enum([
+                        "action_failed",
+                        "submission_needs_manual",
+                        "submission_needs_retry",
+                        "retry_exhausted",
+                        "rate_drop",
+                        "critical_action_failed",
+                    ])
+                        .optional(),
+                    filters: z.record(z.unknown()).nullable().optional(),
+                    channels: z
+                        .object({
+                        email: z.array(z.string()).optional(),
+                        webhook: z
+                            .object({
+                            url: z.string().url(),
+                            hmacSecret: z.string().optional(),
+                        })
+                            .optional(),
+                        inApp: z.boolean().optional(),
+                    })
+                        .optional(),
+                    throttleMs: z.number().int().min(0).optional(),
+                    isActive: z.boolean().optional(),
+                })
+                    .describe("Subset of fields to update."),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.patch(`/api/dashboard/${projectId}/forms/alert-rules/${encodeURIComponent(args.ruleId)}`, args.patch);
+            },
+        }),
+        defineTool({
+            name: "forms_alert_rules_delete",
+            title: "Delete a form alert rule",
+            description: "Delete an alert rule. Destructive — requires confirm=true.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                ruleId: z.string().min(1),
+                confirm: z.boolean().default(false),
+            }),
+            handler: async (args) => {
+                if (!args.confirm) {
+                    return {
+                        deleted: false,
+                        reason: "Destructive. Re-invoke with confirm=true.",
+                    };
+                }
+                const projectId = pid(client, args.projectId);
+                return client.delete(`/api/dashboard/${projectId}/forms/alert-rules/${encodeURIComponent(args.ruleId)}`);
+            },
+        }),
+        defineTool({
+            name: "forms_alert_rule_test",
+            title: "Test-fire an alert rule",
+            description: "Send a synthetic alert through a rule's channels, bypassing the throttle and event filter — confirms email/webhook delivery actually works. Returns the dispatch outcome per channel.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                ruleId: z.string().min(1),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.post(`/api/dashboard/${projectId}/forms/alert-rules/${encodeURIComponent(args.ruleId)}/test`);
+            },
+        }),
+        defineTool({
+            name: "forms_alert_rules_dispatch_log",
+            title: "Alert dispatch log",
+            description: "Recent alert dispatch attempts (delivered, throttled, failed). Filter by `ruleId` and look-back window.",
+            inputSchema: z.object({
+                projectId: projectIdArg,
+                ruleId: z.string().optional(),
+                sinceHours: z.number().int().min(1).default(24),
+                limit: z.number().int().min(1).max(200).default(50),
+            }),
+            handler: async (args) => {
+                const projectId = pid(client, args.projectId);
+                return client.get(`/api/dashboard/${projectId}/forms/alert-rules/dispatch-log`, {
+                    ruleId: args.ruleId,
+                    sinceHours: args.sinceHours,
+                    limit: args.limit,
+                });
+            },
+        }),
+    ];
+}
+//# sourceMappingURL=forms.js.map