formbro-mcp-server 1.0.0 → 1.0.2

package/dist/tools/write.js

@@ -0,0 +1,786 @@
+import { z } from "zod";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { makeApiRequest, handleApiError } from "../services/api-client.js";
+import { getProgramInfo, buildApplicationPatchUrl } from "./patch.js";
+// ============================================================================
+// Input Schemas
+// ============================================================================
+const QuickCreatePersonSchema = z.object({
+    program_key: z.string().describe("Program key: TR programs use any key (dispatches to /api/tr/applicants/quick-create). " +
+        "PR programs: pgp, sps, general, express-entry, renewal, caregiver. " +
+        "LMIA streams: hws, lws, ee. Call describe_program first if unsure."),
+    role: z.enum(["applicant", "spouse", "dependent", "sponsor", "co_signer", "employer"]).describe("Person role within the program."),
+    first_name: z.string().optional().describe("Person's first name (required unless role=employer)."),
+    last_name: z.string().optional().describe("Person's last name."),
+    email: z.string().optional().describe("Email address."),
+    company_name: z.string().optional().describe("Company name (required when role=employer)."),
+}).strict();
+const QuickCreateEmployerSchema = z.object({
+    company_name: z.string().describe("Legal company name (required)."),
+    business_number: z.string().optional().describe("CRA business number."),
+    contact_first_name: z.string().optional().describe("Primary contact first name. Requires contact_email, contact_phone, and contact_position to be set together."),
+    contact_last_name: z.string().optional().describe("Primary contact last name."),
+    contact_email: z.string().optional().describe("Primary contact email (required if any contact_* field is set)."),
+    contact_phone: z.string().optional().describe("Primary contact phone (required if any contact_* field is set)."),
+    contact_position: z.string().optional().describe("Primary contact job title (required if any contact_* field is set)."),
+}).strict();
+const StartApplicationSchema = z.object({
+    program_key: z.string().describe("Program key identifying the program type. Call describe_program first if unsure."),
+    applicant_id: z.string().optional().describe("Applicant ID to associate with the application."),
+}).strict();
+const AttachPersonSchema = z.object({
+    application_id: z.string().describe("Application MongoDB ObjectId."),
+    role: z.string().describe("Role to assign (applicant|spouse|dependent|sponsor|co_signer|employer|rcic)."),
+    person_id: z.string().describe("Person/employer MongoDB ObjectId to attach."),
+}).strict();
+const ReplacePersonSchema = z.object({
+    application_id: z.string().describe("Application MongoDB ObjectId."),
+    role: z.string().describe("Role to replace (applicant|spouse|sponsor|co_signer|employer|rcic)."),
+    new_person_id: z.string().describe("New person/employer MongoDB ObjectId."),
+}).strict();
+const RemovePersonSchema = z.object({
+    application_id: z.string().describe("Application MongoDB ObjectId."),
+    role: z.string().describe("Role to remove (spouse|dependent|co_signer|rcic). Required roles cannot be removed."),
+    person_id: z.string().describe("Person ID to remove. Required for all roles — the backend DELETE route requires it in the URL path. " +
+        "For spouse/rcic/co_signer, pass the current person's ID (fetch from get_application_persons). " +
+        "For dependent, this identifies which dependent to remove."),
+}).strict();
+const VALID_UPLOAD_ENTITY_TYPES = [
+    "applicant", "tr_applicant", "pr_applicant",
+    "employer", "lmia_employer",
+    "lmia_hws_application", "lmia_lws_application", "lmia_ee_application",
+    "sponsor_sps", "sponsor_pgp", "co_signer", "lmia_applicant", "lmia_position",
+];
+const RequestUploadSlotsSchema = z.object({
+    entity_id: z.string().describe("Entity MongoDB ObjectId."),
+    entity_type: z.enum(VALID_UPLOAD_ENTITY_TYPES).describe("Entity type for upload slot lookup. Valid values: applicant (TR/PR persons), " +
+        "employer (LMIA employers), lmia_hws_application / lmia_lws_application / lmia_ee_application (LMIA apps). " +
+        "Generic 'application' is NOT valid — use the specific LMIA application type instead."),
+}).strict();
+const CheckWebformRuntimeSchema = z.object({}).strict();
+const CheckWebformPreflightSchema = z.object({
+    application_id: z.string().describe("Application MongoDB ObjectId."),
+    program_key: z.string().describe("Program key (e.g. sp-out, pgp, hws). Used to route to correct endpoint."),
+    case_id: z.string().optional().describe("Existing portal case ID for PR Renewal validation, e.g. hardcoded PR Card case 4351370."),
+}).strict();
+const StartWebformFillSchema = z.object({
+    application_id: z.string().describe("Application MongoDB ObjectId."),
+    program_key: z.string().describe("Program key to compute local webform actions."),
+    case_id: z.string().optional().describe("Existing portal case ID for PR Renewal validation. Use hardcoded bug-report-manager PR Card case 4351370 when validating PR Renewal."),
+    confirmed: z.boolean().describe("Must be true to trigger the fill. Set to false to get a dry-run description."),
+    headless: z.boolean().default(true).describe("Launch the local browser headless by default. Set false for local headed debugging."),
+}).strict();
+const GetWebformTaskStatusSchema = z.object({
+    application_id: z.string().describe("Application MongoDB ObjectId."),
+    program_key: z.string().describe("Program key to route to the correct status endpoint."),
+}).strict();
+const ChangeApplicationStatusSchema = z.object({
+    application_id: z.string().describe("Application MongoDB ObjectId."),
+    program_key: z.string().describe("Program key to route to the correct PATCH endpoint."),
+    new_status: z.enum([
+        "draft",
+        "in_progress",
+        "submitted",
+        "in_review",
+        "approved",
+        "refused",
+        "withdrawn",
+        "cancelled",
+        "completed",
+        "archived",
+    ]).describe("New status value. 'archived' soft-deletes the application via the backend DELETE endpoint."),
+    expected_version: z.number().optional().describe("Optimistic locking version; include to prevent concurrent edits."),
+}).strict();
+// ============================================================================
+// Helpers
+// ============================================================================
+async function getProgramCategory(program_key) {
+    const info = await getProgramInfo(program_key);
+    return info?.category ?? null;
+}
+export function buildStartApplicationBody(applicant_id) {
+    if (!applicant_id)
+        return {};
+    return { case: { applicant_id } };
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function extractValidationFields(source) {
+    const fields = new Set();
+    function visit(value) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        if (!isRecord(value))
+            return;
+        const field = value.field;
+        if (typeof field === "string" && field.trim()) {
+            fields.add(field.trim());
+        }
+        const path = value.path;
+        if (Array.isArray(path) && path.length > 0) {
+            fields.add(path.map(String).join("."));
+        }
+        for (const child of Object.values(value)) {
+            if (isRecord(child) || Array.isArray(child))
+                visit(child);
+        }
+    }
+    visit(source);
+    const text = typeof source === "string" ? source : JSON.stringify(source ?? "");
+    for (const match of text.matchAll(/"field"\s*:\s*"([^"]+)"/g)) {
+        if (match[1]?.trim())
+            fields.add(match[1].trim());
+    }
+    for (const match of text.matchAll(/"path"\s*:\s*\[([^\]]+)\]/g)) {
+        const path = match[1]
+            .split(",")
+            .map((part) => part.trim().replace(/^"|"$/g, ""))
+            .filter(Boolean)
+            .join(".");
+        if (path)
+            fields.add(path);
+    }
+    return [...fields];
+}
+function explainWebformIssue(source) {
+    const text = typeof source === "string" ? source : JSON.stringify(source ?? "");
+    const normalized = text.toLowerCase();
+    const validationFields = extractValidationFields(source);
+    if (normalized.includes("cannot find module") && normalized.includes("playwright") ||
+        normalized.includes("no module named") && normalized.includes("playwright")) {
+        return {
+            reason: "The local runtime is missing Playwright.",
+            recommended_action: "Run `cd desktop && npm install && npx playwright install chromium`, then retry.",
+        };
+    }
+    if (normalized.includes("executable doesn't exist") || normalized.includes("playwright install")) {
+        return {
+            reason: "The local runtime cannot find Chromium for Playwright.",
+            recommended_action: "Run `cd desktop && npx playwright install chromium`, then retry.",
+        };
+    }
+    if (normalized.includes("host system is missing dependencies")) {
+        return {
+            reason: "Chromium is present but required OS libraries are missing.",
+            recommended_action: "Install Playwright system dependencies on this machine, then retry.",
+        };
+    }
+    if (normalized.includes("timeout")) {
+        return {
+            reason: "The browser timed out while waiting for a portal page, action, or selector.",
+            recommended_action: "Check portal reachability, login state/IP allowlisting, and whether the filler actions still match the portal UI.",
+        };
+    }
+    if (normalized.includes("selector") || normalized.includes("locator") || normalized.includes("strict mode violation")) {
+        return {
+            reason: "A webform action could not find or uniquely resolve the expected portal element.",
+            recommended_action: "Review the failing action and update the fillergraph only after confirming the portal UI changed.",
+        };
+    }
+    if (normalized.includes("credential") || normalized.includes("sign-in") || normalized.includes("login")) {
+        return {
+            reason: "The portal login step likely failed or the application is missing portal credentials.",
+            recommended_action: "Verify the account/password fields and run preflight again before retrying.",
+        };
+    }
+    if (validationFields.length > 0 ||
+        normalized.includes("validation") ||
+        normalized.includes("missing_fields") ||
+        normalized.includes("preflight_failed") ||
+        normalized.includes("invalid request")) {
+        const fieldList = validationFields.slice(0, 10).join(", ");
+        return {
+            reason: fieldList
+                ? `The application data failed backend validation. Missing or invalid fields include: ${fieldList}.`
+                : "The application data is incomplete or failed preflight validation.",
+            recommended_action: "Fix the reported missing or invalid fields in FormBro, then rerun check_webform_preflight before live filling.",
+        };
+    }
+    return {
+        reason: "The webform failure could not be classified from the MCP response alone.",
+        recommended_action: "Inspect the raw error/status payload and backend logs before retrying live filling.",
+    };
+}
+function formatWebformPayload(data) {
+    if (!isRecord(data)) {
+        return JSON.stringify(data, null, 2);
+    }
+    const issueSource = data.filling_error ??
+        data.error ??
+        data.message ??
+        data.raw_error ??
+        (isRecord(data.validation) && data.validation.valid === false ? data.validation : undefined) ??
+        (Array.isArray(data.validation_fields) && data.validation_fields.length > 0 ? data.validation_fields : undefined) ??
+        (data.ready === false ? data : undefined);
+    if (!issueSource) {
+        return JSON.stringify(data, null, 2);
+    }
+    return JSON.stringify({
+        ...data,
+        agent_explanation: explainWebformIssue(issueSource),
+    }, null, 2);
+}
+function webformErrorResult(error) {
+    const raw_error = handleApiError(error);
+    const validation_fields = extractValidationFields(raw_error);
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    raw_error,
+                    ...(validation_fields.length > 0 ? { validation_fields } : {}),
+                    agent_explanation: explainWebformIssue(raw_error),
+                }, null, 2),
+            },
+        ],
+    };
+}
+/**
+ * Derive the compute-actions and status URL segment for a program_key.
+ * Returns { computeUrl, statusUrl } or null if the category cannot be determined.
+ *
+ * TR  → /api/form-filling/tr/{program}/applications/{app_id}/compute-actions
+ *        (TR has no status endpoint — returns filling_status from the application itself)
+ * PR  → /api/form-filling/pr/{program_key}/applications/{app_id}/compute-actions
+ *        status: /api/form-filling/pr/{program_key}/applications/{app_id}/filling-status
+ * LMIA→ /api/form-filling/lmia/{stream}/cases/{case_id}/compute-actions
+ *        status: /api/form-filling/lmia/{stream}/cases/{case_id}/filling-status
+ */
+function buildFormFillingUrls(category, program_key, application_id) {
+    const cat = category.toUpperCase();
+    if (cat === "TR") {
+        const program = trWebformProgram(program_key);
+        return {
+            computeUrl: `/api/form-filling/tr/${encodeURIComponent(program)}/applications/${encodeURIComponent(application_id)}/compute-actions`,
+            statusUrl: null, // TR has no dedicated status endpoint
+        };
+    }
+    else if (cat === "PR") {
+        return {
+            computeUrl: `/api/form-filling/pr/${encodeURIComponent(program_key)}/applications/${encodeURIComponent(application_id)}/compute-actions`,
+            statusUrl: `/api/form-filling/pr/${encodeURIComponent(program_key)}/applications/${encodeURIComponent(application_id)}/filling-status`,
+        };
+    }
+    else if (cat === "LMIA") {
+        return {
+            computeUrl: `/api/form-filling/lmia/${encodeURIComponent(program_key)}/cases/${encodeURIComponent(application_id)}/compute-actions`,
+            statusUrl: `/api/form-filling/lmia/${encodeURIComponent(program_key)}/cases/${encodeURIComponent(application_id)}/filling-status`,
+        };
+    }
+    return {
+        computeUrl: `/api/form-filling/${cat.toLowerCase()}/${encodeURIComponent(program_key)}/applications/${encodeURIComponent(application_id)}/compute-actions`,
+        statusUrl: null,
+    };
+}
+function trWebformProgram(program) {
+    switch (program) {
+        case "sp-out":
+        case "sp-in":
+        case "study-permit-out":
+        case "study-permit-in":
+            return "study-permit";
+        case "wp-out":
+        case "wp-in":
+        case "work-permit-out":
+        case "work-permit-in":
+            return "work-permit";
+        case "visa-out":
+        case "visa-in":
+        case "visitor-visa-out":
+        case "visitor-visa-in":
+            return "visitor-visa";
+        default:
+            return program;
+    }
+}
+function findLocalWebformRunner() {
+    const envPath = process.env.FORMBRO_WEBFORM_RUNNER;
+    if (envPath && existsSync(envPath))
+        return envPath;
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        path.resolve(process.cwd(), "scripts/local-webform-runner.cjs"),
+        path.resolve(process.cwd(), "../scripts/local-webform-runner.cjs"),
+        path.resolve(here, "../../../scripts/local-webform-runner.cjs"),
+    ];
+    const found = candidates.find((candidate) => existsSync(candidate));
+    if (!found) {
+        throw new Error("Local webform runner not found. Set FORMBRO_WEBFORM_RUNNER to scripts/local-webform-runner.cjs.");
+    }
+    return found;
+}
+function runLocalWebformRunner(args, input) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("node", [findLocalWebformRunner(), ...args], {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            let parsed = null;
+            try {
+                parsed = stdout.trim() ? JSON.parse(stdout) : null;
+            }
+            catch (error) {
+                reject(new Error(`Local webform runner returned invalid JSON: ${String(error)}. stderr=${stderr}`));
+                return;
+            }
+            if (code === 0) {
+                resolve(parsed);
+            }
+            else {
+                reject({ runner_result: parsed, stderr, exit_code: code });
+            }
+        });
+        if (input !== undefined) {
+            child.stdin.write(JSON.stringify(input));
+        }
+        child.stdin.end();
+    });
+}
+// ============================================================================
+// Tool Registration
+// ============================================================================
+export function registerWriteTools(server) {
+    // 1. quick_create_person
+    server.registerTool("quick_create_person", {
+        title: "Quick Create Person",
+        description: "Create a minimal person record (applicant/spouse/dependent/sponsor/co_signer) or employer with just a name. " +
+            "Dispatches to the correct TR/PR/LMIA endpoint based on program_key. " +
+            "Call describe_program first to verify the supported roles for the program. " +
+            "Returns id, display_name, and identifier of the created entity.",
+        inputSchema: QuickCreatePersonSchema.shape,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ program_key, role, first_name, last_name, email, company_name }) => {
+        try {
+            const info = await getProgramInfo(program_key);
+            const category = info?.category ?? null;
+            if (role === "employer") {
+                if (category !== "LMIA") {
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: "Error: role=employer is only supported for LMIA program keys (hws, lws, ee)." }],
+                    };
+                }
+                if (!company_name) {
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: "Error: company_name is required when role=employer." }],
+                    };
+                }
+                const employerBody = {
+                    general: {
+                        legal_name: company_name,
+                        ...(email ? { recruit_email: email } : {}),
+                    },
+                };
+                const data = await makeApiRequest("/api/lmia/employers", "POST", employerBody);
+                return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+            }
+            if (!first_name) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: "Error: first_name is required unless role=employer." }],
+                };
+            }
+            const body = { role, first_name };
+            if (last_name)
+                body.last_name = last_name;
+            if (email)
+                body.email = email;
+            if (company_name)
+                body.company_name = company_name;
+            let url;
+            if (category === "TR") {
+                url = "/api/tr/applicants/quick-create";
+            }
+            else if (category === "PR" && info?.api_endpoint) {
+                url = `${info.api_endpoint}/persons/quick-create`;
+            }
+            else if (category === "LMIA" && info?.api_endpoint) {
+                url = `${info.api_endpoint}/persons/quick-create`;
+            }
+            else {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Error: Unknown program_key '${program_key}'. Use list_programs to find valid program keys.` }],
+                };
+            }
+            const data = await makeApiRequest(url, "POST", body);
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: "text", text: handleApiError(error) }] };
+        }
+    });
+    // 2. quick_create_employer
+    server.registerTool("quick_create_employer", {
+        title: "Quick Create LMIA Employer",
+        description: "Create a minimal LMIA employer record with company name and optional contact details. " +
+            "Employers are shared across all LMIA streams (hws/lws/ee). " +
+            "Returns the created employer with id and company details.",
+        inputSchema: QuickCreateEmployerSchema.shape,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ company_name, business_number, contact_first_name, contact_last_name, contact_email, contact_phone, contact_position }) => {
+        try {
+            // Build a minimal LMIAEmployer payload
+            const body = {
+                general: {
+                    legal_name: company_name,
+                },
+            };
+            if (business_number) {
+                body.general.business_number = business_number;
+            }
+            // Only include contacts if all required fields are provided (backend strict validation)
+            if (contact_first_name && contact_email && contact_phone && contact_position) {
+                body.contacts = {
+                    primary_contact: {
+                        first_name: contact_first_name,
+                        last_name: contact_last_name ?? undefined,
+                        email: contact_email,
+                        phone: contact_phone,
+                        position: contact_position,
+                    },
+                };
+            }
+            const data = await makeApiRequest("/api/lmia/employers", "POST", body);
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: "text", text: handleApiError(error) }] };
+        }
+    });
+    // 3. start_application
+    server.registerTool("start_application", {
+        title: "Start Application",
+        description: "Create a new immigration application for a given program_key. " +
+            "Dispatches to TR, PR, or LMIA endpoint based on program category. " +
+            "Optionally link an applicant_id at creation time. " +
+            "Returns the created application object.",
+        inputSchema: StartApplicationSchema.shape,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ program_key, applicant_id }) => {
+        try {
+            const info = await getProgramInfo(program_key);
+            if (!info) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Error: Unknown program_key '${program_key}'. Use list_programs to find valid program keys.` }],
+                };
+            }
+            const body = buildStartApplicationBody(applicant_id);
+            // TR/PR create at api_endpoint root; LMIA stream APIs nest applications under /applications.
+            const createUrl = info.category === "LMIA" ? `${info.api_endpoint}/applications` : info.api_endpoint;
+            const data = await makeApiRequest(createUrl, "POST", body);
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: "text", text: handleApiError(error) }] };
+        }
+    });
+    // 4. attach_person_to_application
+    server.registerTool("attach_person_to_application", {
+        title: "Attach Person to Application",
+        description: "Add a person to a multi-person role in an application (e.g., add a dependent). " +
+            "For single-value roles (applicant, spouse, sponsor), use replace_person instead. " +
+            "Currently only 'dependent' role supports the add operation.",
+        inputSchema: AttachPersonSchema.shape,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ application_id, role, person_id }) => {
+        try {
+            const url = `/api/applications/${encodeURIComponent(application_id)}/persons/${encodeURIComponent(role)}`;
+            const data = await makeApiRequest(url, "POST", { person_id });
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: "text", text: handleApiError(error) }] };
+        }
+    });
+    // 5. replace_person
+    server.registerTool("replace_person", {
+        title: "Replace Person in Application",
+        description: "Replace the person for a specific role in an application. " +
+            "Valid roles: applicant, spouse, sponsor, co_signer, employer, rcic. " +
+            "Use this to change which applicant/sponsor/employer is linked to an application.",
+        inputSchema: ReplacePersonSchema.shape,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ application_id, role, new_person_id }) => {
+        try {
+            const url = `/api/applications/${encodeURIComponent(application_id)}/persons/${encodeURIComponent(role)}`;
+            const data = await makeApiRequest(url, "PATCH", { person_id: new_person_id });
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: "text", text: handleApiError(error) }] };
+        }
+    });
+    // 6. remove_person
+    server.registerTool("remove_person", {
+        title: "Remove Person from Application",
+        description: "Remove an optional person from an application. " +
+            "Only optional roles can be removed: spouse, dependent, co_signer, rcic. " +
+            "person_id is always required (use get_application_persons to find current IDs). " +
+            "Required roles (applicant, employer, sponsor) cannot be removed.",
+        inputSchema: RemovePersonSchema.shape,
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    }, async ({ application_id, role, person_id }) => {
+        try {
+            const personIdSegment = person_id ? `/${encodeURIComponent(person_id)}` : "";
+            const url = `/api/applications/${encodeURIComponent(application_id)}/persons/${encodeURIComponent(role)}${personIdSegment}`;
+            await makeApiRequest(url, "DELETE");
+            return { content: [{ type: "text", text: JSON.stringify({ success: true, message: `Removed ${role} from application ${application_id}` }, null, 2) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: "text", text: handleApiError(error) }] };
+        }
+    });
+    // 7. request_upload_slots
+    server.registerTool("request_upload_slots", {
+        title: "Get Upload Slots for Entity",
+        description: "Returns information about document upload slots available for an entity. " +
+            "entity_type must be one of: applicant/tr_applicant/pr_applicant (for persons), " +
+            "employer/lmia_employer (for employers), or lmia_hws_application/lmia_lws_application/lmia_ee_application (for LMIA apps). " +
+            "The response shows which document slots exist and their current upload status.",
+        inputSchema: RequestUploadSlotsSchema.shape,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ entity_id, entity_type }) => {
+        try {
+            const url = `/api/uploads/${encodeURIComponent(entity_type)}/${encodeURIComponent(entity_id)}`;
+            const data = await makeApiRequest(url, "GET");
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: "text", text: handleApiError(error) }] };
+        }
+    });
+    // 8. check_webform_runtime
+    server.registerTool("check_webform_runtime", {
+        title: "Check Local Webform Browser Runtime",
+        description: "Check whether this MCP host can import local Playwright and launch local Chromium before live webform filling. " +
+            "Use this before start_webform_fill_live. If not ready, the response explains the missing local runtime dependency.",
+        inputSchema: CheckWebformRuntimeSchema.shape,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async () => {
+        try {
+            const data = await runLocalWebformRunner(["--check"]);
+            return { content: [{ type: "text", text: formatWebformPayload(data) }] };
+        }
+        catch (error) {
+            return webformErrorResult(error);
+        }
+    });
+    // 9. check_webform_preflight
+    server.registerTool("check_webform_preflight", {
+        title: "Check Webform Preflight Status",
+        description: "Check current webform filling status and any blocking issues for an application. " +
+            "Returns filling_status (not_started|pending|in_progress|completed|failed|preflight_failed|validation_failed), " +
+            "missing_fields, and review_items. " +
+            "Use before start_webform_fill_live to verify the application is ready.",
+        inputSchema: CheckWebformPreflightSchema.shape,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ application_id, program_key, case_id }) => {
+        try {
+            const info = await getProgramInfo(program_key);
+            if (!info) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Error: Unknown program_key '${program_key}'.` }],
+                };
+            }
+            const { computeUrl } = buildFormFillingUrls(info.category, program_key, application_id);
+            const operation = info.category.toUpperCase() === "TR" ? "fill_webform_tr" : "fill_webform";
+            const entityType = info.form_ids?.application;
+            let validationData = null;
+            if (entityType) {
+                validationData = await makeApiRequest("/api/validate/operation", "POST", {
+                    entity_id: application_id,
+                    entity_type: entityType,
+                    operation,
+                });
+            }
+            const computeData = await makeApiRequest(computeUrl, "POST", case_id ? { case_id } : {});
+            const actions = isRecord(computeData) ? computeData.actions : undefined;
+            const validationFields = extractValidationFields(validationData);
+            return {
+                content: [{
+                        type: "text",
+                        text: formatWebformPayload({
+                            status: "ready",
+                            execution_model: "local_playwright_compute_actions",
+                            action_count: Array.isArray(actions) ? actions.length : null,
+                            case_id,
+                            validation: validationData,
+                            compute_result: computeData,
+                            ...(validationFields.length > 0 ? { validation_fields: validationFields } : {}),
+                        }),
+                    }],
+            };
+        }
+        catch (error) {
+            return webformErrorResult(error);
+        }
+    });
+    // 10. start_webform_fill_live
+    server.registerTool("start_webform_fill_live", {
+        title: "Start Webform Fill (Live)",
+        description: "Trigger live webform filling for an application. DESTRUCTIVE: this computes actions from FormBro API " +
+            "and executes them with local Playwright/Chromium on this MCP host. It does not use server-side backend Playwright. " +
+            "You MUST set confirmed=true to proceed. Call check_webform_runtime and check_webform_preflight first.",
+        inputSchema: StartWebformFillSchema.shape,
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async ({ application_id, program_key, case_id, confirmed, headless }) => {
+        try {
+            if (!confirmed) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                dry_run: true,
+                                message: "Webform fill NOT started. Set confirmed=true to trigger the actual fill.",
+                                next_required_checks: ["check_webform_runtime", "check_webform_preflight"],
+                                execution_model: "local_playwright_compute_actions",
+                                program_key,
+                                application_id,
+                                case_id,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const category = await getProgramCategory(program_key);
+            if (!category) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Error: Unknown program_key '${program_key}'.` }],
+                };
+            }
+            const runtime = await runLocalWebformRunner(["--check"]);
+            if (isRecord(runtime) && runtime.ready === false) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: formatWebformPayload(runtime) }],
+                };
+            }
+            const { computeUrl } = buildFormFillingUrls(category, program_key, application_id);
+            const actionData = await makeApiRequest(computeUrl, "POST", case_id ? { case_id } : {});
+            const actions = isRecord(actionData) ? actionData.actions : undefined;
+            if (!Array.isArray(actions)) {
+                return {
+                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: formatWebformPayload({
+                                error: "compute-actions did not return an actions array",
+                                compute_result: actionData,
+                            }),
+                        }],
+                };
+            }
+            const data = await runLocalWebformRunner([], {
+                actions,
+                headless: headless ?? true,
+                timeout_ms: 120000,
+                program_type: category,
+                program_key,
+                application_id,
+                case_id,
+            });
+            return { content: [{ type: "text", text: formatWebformPayload(data) }] };
+        }
+        catch (error) {
+            return webformErrorResult(error);
+        }
+    });
+    // 11. get_webform_task_status
+    server.registerTool("get_webform_task_status", {
+        title: "Get Webform Task Status",
+        description: "Poll the current status of a running or completed webform fill task. " +
+            "Returns filling_status, progress, error details, and screenshot path if failed. " +
+            "Call repeatedly until status is 'completed' or 'failed'.",
+        inputSchema: GetWebformTaskStatusSchema.shape,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ application_id, program_key }) => {
+        try {
+            const category = await getProgramCategory(program_key);
+            if (!category) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Error: Unknown program_key '${program_key}'.` }],
+                };
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: formatWebformPayload({
+                            status: "not_applicable",
+                            execution_model: "local_playwright_sync",
+                            program_key,
+                            application_id,
+                            message: "Local MCP webform filling runs synchronously on this machine and does not create a backend Playwright task to poll.",
+                        }),
+                    }],
+            };
+        }
+        catch (error) {
+            return webformErrorResult(error);
+        }
+    });
+    // 12. change_application_status
+    server.registerTool("change_application_status", {
+        title: "Change Application Status",
+        description: "Update the status of an application. Passing 'archived' soft-deletes the application. " +
+            "Optionally provide expected_version for optimistic locking to prevent concurrent edits. " +
+            "Use the unified applications PATCH endpoint.",
+        inputSchema: ChangeApplicationStatusSchema.shape,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ application_id, program_key, new_status, expected_version }) => {
+        try {
+            const progInfo = await getProgramInfo(program_key);
+            if (!progInfo) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Error: Unknown program_key '${program_key}'. Use list_programs to find valid keys.` }],
+                };
+            }
+            const params = { skip_validation: true };
+            if (expected_version !== undefined) {
+                params.if_match = expected_version;
+            }
+            const url = buildApplicationPatchUrl(progInfo.api_endpoint, progInfo.category, application_id);
+            if (new_status === "archived") {
+                await makeApiRequest(url, "DELETE", undefined, params);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({ success: true, archived: true, application_id }, null, 2),
+                        }],
+                };
+            }
+            // Status is nested under case.status in all program types
+            const data = await makeApiRequest(url, "PATCH", { case: { status: new_status } }, params);
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: "text", text: handleApiError(error) }] };
+        }
+    });
+}
+//# sourceMappingURL=write.js.map