@wilnertech/halopsa-mcp-server 1.4.0 → 1.6.0

package/dist/tools/tickets.js

@@ -15,10 +15,11 @@
  * or pass `format_options.format = 'detailed'` / `full: true`.
  */
 import { z } from 'zod';
-import { formatResponse, stripWriteResponse } from '../utils/formatter.js';
-import { TTL } from '../cache/memory-cache.js';
+import { formatResponse, stripWriteResponse, withCompactDefaults } from '../utils/formatter.js';
+import { TTL, generateCacheKey } from '../cache/memory-cache.js';
 import { FormatOptionsSchema } from '../schemas/common.js';
 import { linkTicketToMilestone } from './milestones.js';
+import { getOutcomesForTicketType } from './ticket-reference-data.js';
 // =============================================================================
 // Schemas
 // =============================================================================
@@ -44,11 +45,11 @@ export const ListTicketsArgsSchema = z.object({
         .describe('Filter by site/location ID'),
     user_id: z.number().int().optional()
         .describe('Filter by end-user ID'),
-    agent_id: z.number().int().optional()
+    agent_id: z.number().int().positive().optional()
         .describe('Filter by assigned agent ID (single int). Use agent for multiple.'),
     agent: IntOrIntArray.optional()
         .describe('Filter by one or more agent IDs (int or array of int, serialised comma-separated). Swagger param: agent (array of int).'),
-    team_id: z.number().int().optional()
+    team_id: z.number().int().positive().optional()
         .describe('Filter by team ID'),
     tickettype_id: IntOrIntArray.optional()
         .describe('Filter by ticket type ID(s) (int or array of int, serialised comma-separated).'),
@@ -109,9 +110,9 @@ export const CreateTicketArgsSchema = z.object({
         .describe('Initial status ID — see list_halopsa_ticket_statuses'),
     source: z.number().int().optional()
         .describe('Source enum (tenant-specific integer). Halo auto-sets source=3 (API) when omitted.'),
-    agent_id: z.number().int().optional()
+    agent_id: z.number().int().positive().optional()
         .describe('Assigned agent'),
-    team_id: z.number().int().optional()
+    team_id: z.number().int().positive().optional()
         .describe('Assigned team'),
     site_id: z.number().int().optional()
         .describe('Site/location'),
@@ -131,6 +132,11 @@ export const CreateTicketArgsSchema = z.object({
         .describe('Estimated business days. Companion to estimate; pass either or neither — Halo auto-computes both from startdate/targetdate when both omitted.'),
     milestone_id: z.number().int().optional()
         .describe('Link this ticket to an existing milestone on its parent project ticket. milestone_id orchestrates: the MCP transparently translates this to a parent-project milestones[].tickets[] update. Single milestone per task — setting milestone_id automatically unlinks from any previous milestone. Pass 0 to unlink entirely. Find milestone ids via list_halopsa_ticket_milestones on the parent ticket.'),
+    // Bug 9: Asset linking fields.
+    asset_id: z.number().int().optional()
+        .describe('Single asset to link to this ticket. For multiple, use asset_ids.'),
+    asset_ids: z.array(z.number().int()).optional()
+        .describe('Multiple asset IDs to link to this ticket. Halo will populate the ticket.assets[] array. If both asset_id and asset_ids are set, they are combined.'),
     format_options: FormatOptionsSchema,
 });
 export const UpdateTicketArgsSchema = z.object({
@@ -143,8 +149,8 @@ export const UpdateTicketArgsSchema = z.object({
     status_id: z.number().int().optional(),
     priority_id: z.number().int().optional(),
     category_1: z.string().optional(),
-    agent_id: z.number().int().optional(),
-    team_id: z.number().int().optional(),
+    agent_id: z.number().int().positive().optional(),
+    team_id: z.number().int().positive().optional(),
     site_id: z.number().int().optional(),
     user_id: z.number().int().optional(),
     parent_id: z.number().int().optional()
@@ -162,19 +168,34 @@ export const UpdateTicketArgsSchema = z.object({
         .describe('Estimated business days. Companion to estimate; pass either or neither — Halo auto-computes both from startdate/targetdate when both omitted.'),
     milestone_id: z.number().int().optional()
         .describe('Link this ticket to an existing milestone on its parent project ticket. milestone_id orchestrates: the MCP transparently translates this to a parent-project milestones[].tickets[] update. Single milestone per task — setting milestone_id automatically unlinks from any previous milestone. Pass 0 to unlink entirely. Find milestone ids via list_halopsa_ticket_milestones on the parent ticket.'),
+    // Bug 9: Asset linking fields.
+    asset_id: z.number().int().optional()
+        .describe('Single asset to link to this ticket. For multiple, use asset_ids.'),
+    asset_ids: z.array(z.number().int()).optional()
+        .describe('Multiple asset IDs to link to this ticket. Halo will populate the ticket.assets[] array. If both asset_id and asset_ids are set, they are combined.'),
     format_options: FormatOptionsSchema,
 });
 export const CloseTicketArgsSchema = z.object({
     ticket_id: z.number().int()
         .describe('HaloPSA ticket ID to close'),
     resolution_note: z.string().optional()
-        .describe('Optional final action note added before status change'),
+        .describe('Optional final action note added before status change. When provided, a ticket action is posted before the status flip. Requires an outcome_id — supply resolution_outcome_id explicitly, or the MCP will auto-resolve the first is_resolution outcome for this tickettype.'),
+    resolution_outcome_id: z.number().int().positive().optional()
+        .describe('Outcome ID to use for the resolution note action. When omitted but resolution_note is set, the MCP auto-resolves the first outcome with is_resolution=true for the ticket\'s tickettype. Pass explicitly when the auto-resolve picks the wrong outcome.'),
 });
 export const DeleteTicketArgsSchema = z.object({
     ticket_id: z.number().int().describe('HaloPSA ticket ID to delete'),
     reason: z.string().min(5).describe('REQUIRED audit-trail reason. To bypass safety blocks, the reason MUST include the substring "OVERRIDE" (case-sensitive) AND confirm_destructive must be true.'),
     confirm_destructive: z.boolean().optional().default(false).describe('When safety pre-flight checks would block the delete, set true AND include "OVERRIDE" in `reason` to proceed. Default false.'),
 });
+// Bug 8: Schema for validate_halopsa_create_ticket.
+export const ValidateCreateTicketArgsSchema = z.object({
+    tickettype_id: z.number().int()
+        .describe('Ticket type ID to validate against — see list_halopsa_tickettypes'),
+    fields: z.record(z.string(), z.unknown())
+        .describe('Proposed ticket payload as a key-value map. Keys should be field names (e.g. summary, client_id, customfields).'),
+    format_options: FormatOptionsSchema,
+});
 // =============================================================================
 // Helpers
 // =============================================================================
@@ -251,6 +272,24 @@ async function resolveClosedStatusId(client) {
         `(received ${items.length} statuses; "Closed" matches: ${exactClosed.length}, "Completed" matches: ${exactCompleted.length}) ` +
         'Pass status_id explicitly via update_halopsa_ticket.');
 }
+/**
+ * Build the Halo assets[] array payload from asset_id / asset_ids args.
+ * Halo Faults.assets[] accepts elements with at minimum { id: number }.
+ * Returns undefined when neither arg is set (no-op).
+ */
+function buildAssetsPayload(asset_id, asset_ids) {
+    if (asset_id === undefined && asset_ids === undefined) {
+        return undefined;
+    }
+    const idSet = [];
+    if (asset_ids !== undefined) {
+        idSet.push(...asset_ids);
+    }
+    if (asset_id !== undefined && !idSet.includes(asset_id)) {
+        idSet.push(asset_id);
+    }
+    return idSet.map((id) => ({ id }));
+}
 // =============================================================================
 // Implementations
 // =============================================================================
@@ -298,7 +337,10 @@ export async function listTickets(client, args) {
     if (args.page_no !== undefined)
         params.page_no = args.page_no;
     const formatOpts = resolveListFormat(args.format_options);
-    const cacheKey = `tickets:client_${args.client_id ?? 'all'}:status_${args.status_id ?? 'all'}`;
+    // B3 fix: use generateCacheKey so ALL filter params (agent_id, tickettype_id,
+    // date_from, open_only, etc.) participate in the cache key. The previous
+    // hand-rolled key silently ignored those params, causing cache collisions.
+    const cacheKey = generateCacheKey('tickets', params);
     const response = await client.getCached('/Tickets', params, {
         enabled: true,
         ttl: TTL.TICKET_LIST,
@@ -364,14 +406,22 @@ export async function createTicket(client, args) {
     // milestone_id is NOT sent to Halo as a direct field — writing it to the
     // child record is a no-op for Project Task tickets (tickettype_id=20).
     // Milestone membership is orchestrated via linkTicketToMilestone below.
+    // Bug 9: Asset linking. Build assets[] from asset_id / asset_ids args.
+    // Halo Faults.assets[] accepts elements with at minimum { id: number }.
+    const assetsPayload = buildAssetsPayload(args.asset_id, args.asset_ids);
+    if (assetsPayload !== undefined) {
+        payload.assets = assetsPayload;
+    }
     const created = unwrapWriteResponse(await client.post('/Tickets', [payload]));
     client.invalidateCache('tickets:*');
     // Bug 1: Orchestrate milestone linkage via parent project if requested.
     if (args.milestone_id !== undefined) {
         await linkTicketToMilestone(client, created.id, args.milestone_id, args.parent_id);
     }
-    const format = args.format_options?.format ?? 'compact';
-    return formatResponse(stripWriteResponse(created, format, 'ticket'), { format });
+    // Bug 5: Pass full format_options so fields/omit_empty flow through to formatResponse.
+    const formatOpts = args.format_options ?? { format: 'compact' };
+    const format = formatOpts.format ?? 'compact';
+    return formatResponse(stripWriteResponse(created, format, 'ticket'), formatOpts);
 }
 export async function updateTicket(client, args) {
     const partial = {};
@@ -412,6 +462,11 @@ export async function updateTicket(client, args) {
     // milestone_id is NOT sent to Halo as a direct field — writing it to the
     // child record is a no-op for Project Task tickets (tickettype_id=20).
     // Milestone membership is orchestrated via linkTicketToMilestone below.
+    // Bug 9: Asset linking. Build assets[] from asset_id / asset_ids args.
+    const assetsPayload = buildAssetsPayload(args.asset_id, args.asset_ids);
+    if (assetsPayload !== undefined) {
+        partial.assets = assetsPayload;
+    }
     // Determine which fields count for the "at least one" check. We include
     // milestone_id in the check so that a milestone-only update is valid.
     const fieldCount = Object.keys(partial).length + (args.milestone_id !== undefined ? 1 : 0);
@@ -421,8 +476,30 @@ export async function updateTicket(client, args) {
             message: 'At least one field must be provided for update',
         }, null, 2);
     }
-    // Halo POST /Tickets is REPLACE not PATCH — read-before-write merge to
-    // preserve fields the caller didn't touch (mirrors updateAsset).
+    // Halo POST /Tickets serves both create AND update (Halo has no PATCH/PUT
+    // anywhere — verified 2026-05-12 against the authoritative OpenAPI 3.0.1 spec:
+    // zero PATCH operations across all 952 paths; zero PUT operations). The swagger
+    // does not document whether absent fields are preserved or cleared on update.
+    // The Faults schema has no `required[]` constraint (984 nullable properties),
+    // and no description on POST /Tickets.
+    //
+    // Two sources of truth conflict:
+    //   - .claude/api-docs/halopsa.md:494 (curated): "partial updates supported".
+    //   - This codebase (observed, Bug 3): Halo's scheduler recomputes startdate/
+    //     targetdate on estimate changes even when the same values are resent
+    //     (see Bug 3 below). That recomputation is irrefutable evidence that
+    //     POST /Tickets is NOT a pure PATCH model — at minimum, server-side
+    //     computed fields drift on partial-body update.
+    //
+    // The safe choice: keep the read-before-write merge. The downside is request
+    // size (20-60 KB per update, since Faults has 984 properties many of which
+    // are populated). If a future iteration wants to reduce request size, the
+    // migration would need per-field empirical testing on a non-production
+    // tenant — start with leaf scalars (summary, status_id), avoid arrays/objects
+    // (customfields, assets, actions, attachments), and never drop a field whose
+    // absence could trigger a billing-relevant default.
+    //
+    // Reference: thoughts/shared/research/2026-05-12_halopsa-mcp-v16-deferred-items-swagger-research.md
     const existing = await client.get(`/Tickets/${args.ticket_id}`, { includedetails: true });
     // Bug 3 — schedule drift on estimate updates:
     // Halo's scheduler treats estimate/estimatedays changes as a recompute
@@ -462,8 +539,10 @@ export async function updateTicket(client, args) {
     if (args.milestone_id !== undefined) {
         await linkTicketToMilestone(client, args.ticket_id, args.milestone_id, args.parent_id);
     }
-    const format = args.format_options?.format ?? 'compact';
-    return formatResponse(stripWriteResponse(response, format, 'ticket'), { format });
+    // Bug 5: Pass full format_options so fields/omit_empty flow through to formatResponse.
+    const formatOpts = args.format_options ?? { format: 'compact' };
+    const format = formatOpts.format ?? 'compact';
+    return formatResponse(stripWriteResponse(response, format, 'ticket'), formatOpts);
 }
 /**
  * Permanently delete a HaloPSA ticket by ID after running four safety
@@ -589,11 +668,122 @@ export async function closeTicket(client, args) {
     // If a resolution note was supplied, post it as a final action first so
     // the close-out is auditable.
     if (args.resolution_note) {
-        await client.post('/Actions', [{
+        // Resolve the outcome_id to use for the resolution note action.
+        let outcomeId;
+        if (args.resolution_outcome_id !== undefined) {
+            // Explicit override — use directly.
+            outcomeId = args.resolution_outcome_id;
+        }
+        else {
+            // Auto-resolve: fetch the ticket to get tickettype_id, then find the
+            // first is_resolution outcome for that tickettype (cached 1h).
+            // Use the same keyPrefix as getTicket so a prior get_halopsa_ticket call
+            // seeds this cache hit — avoids a second Halo round-trip in the typical
+            // "get then close" workflow. updateTicket invalidates ticket:${id}* so
+            // the unified key cannot become stale.
+            const ticketForClose = await client.getCached(`/Tickets/${args.ticket_id}`, { includedetails: true }, {
+                enabled: true,
+                ttl: TTL.TICKET_LIST,
+                keyPrefix: `ticket:${args.ticket_id}`,
+            });
+            const tickettypeId = ticketForClose.tickettype_id;
+            const outcomeList = await getOutcomesForTicketType(client, tickettypeId);
+            // Find the first outcome with is_resolution===true, sorted by id ascending.
+            const resolutionOutcomes = outcomeList
+                .filter((o) => o.is_resolution === true)
+                .sort((a, b) => a.id - b.id);
+            if (resolutionOutcomes.length === 0) {
+                // S5 fix: sort outcomes by sequence ascending (fallback to id) before slicing,
+                // matching buildOutcomeDiscoveryRefusal behavior.
+                const sortedOutcomes = outcomeList.slice().sort((a, b) => {
+                    const seqA = a.sequence ?? 999999;
+                    const seqB = b.sequence ?? 999999;
+                    return seqA !== seqB ? seqA - seqB : a.id - b.id;
+                });
+                return JSON.stringify({
+                    error: true,
+                    message: `No outcome with is_resolution=true found for tickettype_id=${tickettypeId}. ` +
+                        'Pass resolution_outcome_id explicitly or close without resolution_note.',
+                    tickettype_id: tickettypeId,
+                    available_outcomes: sortedOutcomes.slice(0, 5).map((o) => ({ id: o.id, name: o.name })),
+                });
+            }
+            outcomeId = resolutionOutcomes[0].id;
+        }
+        // B2 fix: wrap the action POST in try/catch for structured failure handling.
+        // If the POST throws, return a structured failure instead of propagating the
+        // exception. If the POST returns an unexpected shape (no id in response),
+        // treat as failure with a clear message.
+        let actionId;
+        try {
+            const actionRaw = await client.post('/Actions', [{
+                    ticket_id: args.ticket_id,
+                    note: args.resolution_note,
+                    outcome_id: outcomeId,
+                }]);
+            const actionObj = Array.isArray(actionRaw) ? actionRaw[0] : actionRaw;
+            if (actionObj === null ||
+                typeof actionObj !== 'object' ||
+                !('id' in actionObj)) {
+                return JSON.stringify({
+                    closed: false,
+                    action_created: false,
+                    ticket_id: args.ticket_id,
+                    message: 'Resolution-note action POST returned an unexpected shape (no id in response); ticket NOT closed.',
+                });
+            }
+            actionId = actionObj['id'];
+        }
+        catch (actionErr) {
+            const raw = actionErr instanceof Error ? actionErr.message : String(actionErr);
+            const truncated = raw.length > 500 ? raw.slice(0, 500) + '…' : raw;
+            return JSON.stringify({
+                closed: false,
+                action_created: false,
                 ticket_id: args.ticket_id,
-                note: args.resolution_note,
-            }]);
+                halo_error: truncated,
+                message: 'Resolution-note action POST failed; ticket NOT closed.',
+            });
+        }
         client.invalidateCache(`ticket-actions:${args.ticket_id}*`);
+        // B2 fix: if the status flip (updateTicket) throws, return a partial-failure
+        // result that tells the caller the action was posted but status was not changed.
+        let closedStatusId;
+        try {
+            closedStatusId = await resolveClosedStatusId(client);
+        }
+        catch (statusErr) {
+            const raw = statusErr instanceof Error ? statusErr.message : String(statusErr);
+            const truncated = raw.length > 500 ? raw.slice(0, 500) + '…' : raw;
+            return JSON.stringify({
+                closed: false,
+                action_created: true,
+                ticket_id: args.ticket_id,
+                action_id: actionId,
+                halo_error: truncated,
+                message: `Resolution note was posted (action id=${actionId}) but status flip failed; ticket left in original state. ` +
+                    'Retry close_halopsa_ticket without resolution_note to flip status.',
+            });
+        }
+        try {
+            return await updateTicket(client, {
+                ticket_id: args.ticket_id,
+                status_id: closedStatusId,
+            });
+        }
+        catch (updateErr) {
+            const raw = updateErr instanceof Error ? updateErr.message : String(updateErr);
+            const truncated = raw.length > 500 ? raw.slice(0, 500) + '…' : raw;
+            return JSON.stringify({
+                closed: false,
+                action_created: true,
+                ticket_id: args.ticket_id,
+                action_id: actionId,
+                halo_error: truncated,
+                message: `Resolution note was posted (action id=${actionId}) but status flip failed; ticket left in original state. ` +
+                    'Retry close_halopsa_ticket without resolution_note to flip status.',
+            });
+        }
     }
     const closedStatusId = await resolveClosedStatusId(client);
     return updateTicket(client, {
@@ -602,6 +792,182 @@ export async function closeTicket(client, args) {
     });
 }
 // =============================================================================
+// Bug 8 / Bug 5: validate_halopsa_create_ticket implementation
+// =============================================================================
+/**
+ * Default compact fields for validate_halopsa_create_ticket (Bug 3 wiring).
+ * Ensures compact responses return the key validation fields rather than the
+ * legacy compactItem() heuristic which strips unrecognised shapes.
+ */
+const VALIDATE_COMPACT_DEFAULTS = [
+    'valid',
+    'missing_required',
+    'unknown_fields',
+    'required_fields',
+    'tickettype_id',
+    'tickettype_name',
+];
+/**
+ * Map a Halo-internal field name to the equivalent MCP parameter name.
+ *
+ * Halo uses `category2`..`category6` internally while the MCP exposes
+ * `category_1`..`category_5`. Custom fields (CF* names) are not mapped to a
+ * standard param — they are returned in a separate `required_customfields`
+ * array. All other names are returned unchanged.
+ *
+ * Returns null for custom fields (CF* prefix) — callers handle these
+ * separately.
+ */
+export function mcpParamForHaloField(haloName) {
+    const categoryMap = {
+        category2: 'category_1',
+        category3: 'category_2',
+        category4: 'category_3',
+        category5: 'category_4',
+        category6: 'category_5',
+    };
+    if (haloName in categoryMap) {
+        return categoryMap[haloName];
+    }
+    // Custom fields (CF prefix): signal to caller that this is a CF, not a param
+    if (/^CF/i.test(haloName)) {
+        return null;
+    }
+    return haloName;
+}
+/**
+ * Recursively walk a Halo TicketType fields[] tree (which can nest groups),
+ * accumulating required standard fields and required custom fields.
+ *
+ * Mutation: adds to `requiredFields` and `requiredCustomFields` arrays.
+ * `allSchemaNames` accumulates every field name seen (for "unknown" detection).
+ */
+function walkSchemaFields(entries, requiredFields, requiredCustomFields, allSchemaNames) {
+    for (const f of entries) {
+        // Recurse into group nesting (either shape)
+        if (f.group?.fields && f.group.fields.length > 0) {
+            walkSchemaFields(f.group.fields, requiredFields, requiredCustomFields, allSchemaNames);
+        }
+        if (f.fields && f.fields.length > 0) {
+            walkSchemaFields(f.fields, requiredFields, requiredCustomFields, allSchemaNames);
+        }
+        // Field info is on fieldinfo sub-object OR directly on the field entry
+        const info = f.fieldinfo ?? f;
+        const haloName = info.name ?? '';
+        const label = info.label ?? haloName;
+        const isCustom = info.custom ?? false;
+        if (!haloName)
+            continue;
+        // Track all halo-internal names AND their MCP equivalents for known-field set
+        allSchemaNames.add(haloName);
+        const mcpName = mcpParamForHaloField(haloName);
+        if (mcpName !== null) {
+            allSchemaNames.add(mcpName);
+        }
+        // A field is required if mandatory===true OR technew===3.
+        // Skip display_type=3 (read-only) and display_type=4 (hidden) — these are
+        // server-computed and cannot be provided by callers.
+        const dt = info.display_type;
+        const isReadOnly = dt === 3 || dt === 4;
+        const isRequired = !isReadOnly && (info.mandatory === true || info.technew === 3);
+        if (!isRequired)
+            continue;
+        if (isCustom || mcpName === null) {
+            // Custom field (CF*): append to required_customfields
+            const cfId = info.id ?? 0;
+            requiredCustomFields.push({ id: cfId, name: haloName });
+        }
+        else {
+            // Standard field — use the MCP-translated name
+            requiredFields.push({ name: mcpName, label, custom: false });
+        }
+    }
+}
+/**
+ * Pure-local validation of a proposed ticket payload against the cached
+ * tickettype schema. No write is performed — this is a dry-run helper.
+ *
+ * Required-field detection logic:
+ * Halo's TicketType details response includes a `fields[]` array where each
+ * entry has a `fieldinfo` sub-object. The `mandatory` flag on `fieldinfo`
+ * indicates a required field. Additionally, `technew` on `fieldinfo` where
+ * the value equals 3 indicates "required for tech/API create". When either
+ * condition is true, the field is counted as required.
+ *
+ * Fields nested inside `group.fields[]` or `fields[]` (both group-nesting
+ * shapes Halo uses across versions) are also walked — not just top-level.
+ *
+ * Halo-internal category field names (category2..category6) are translated
+ * to MCP equivalents (category_1..category_5). Custom fields (CF* prefix)
+ * are reported in a separate `required_customfields` array.
+ *
+ * Standard ticket fields (summary, client_id, tickettype_id) are always
+ * required regardless of the tickettype schema.
+ */
+export async function validateCreateTicket(client, args) {
+    // Fetch the tickettype with full field details.
+    const tickettype = await client.getCached(`/TicketType/${args.tickettype_id}`, { includedetails: true }, {
+        enabled: true,
+        ttl: TTL.TICKET_TYPES,
+        keyPrefix: `tickettype:${args.tickettype_id}:details`,
+    });
+    // Standard fields always required on create.
+    const STANDARD_REQUIRED = ['summary', 'client_id', 'tickettype_id'];
+    // Build the list of required fields from the tickettype schema.
+    const schemaFields = Array.isArray(tickettype.fields)
+        ? tickettype.fields
+        : [];
+    const requiredFromSchema = [];
+    const requiredCustomFields = [];
+    const allSchemaNames = new Set();
+    // Recursively walk field tree (handles nested groups)
+    walkSchemaFields(schemaFields, requiredFromSchema, requiredCustomFields, allSchemaNames);
+    // Combine standard required fields with schema-derived required fields,
+    // deduplicating by name.
+    const allRequiredFields = [
+        ...STANDARD_REQUIRED.map((n) => ({ name: n, label: n, custom: false })),
+        ...requiredFromSchema.filter((f) => !STANDARD_REQUIRED.includes(f.name)),
+    ];
+    const providedKeys = new Set(Object.keys(args.fields));
+    // Missing: required fields not in the provided payload.
+    const missingRequired = allRequiredFields
+        .filter((f) => !providedKeys.has(f.name))
+        .map((f) => f.name);
+    // Unknown: provided fields not in the standard set and not in the schema.
+    // Include both Halo-internal names and MCP equivalents in the known set
+    // so callers passing either form are not flagged.
+    const knownFieldNames = new Set([
+        ...STANDARD_REQUIRED,
+        ...allSchemaNames,
+        // Common optional standard fields that are always valid.
+        'details_html', 'category_1', 'category_2', 'category_3', 'category_4', 'category_5',
+        'priority_id', 'status_id', 'source',
+        'agent_id', 'team_id', 'site_id', 'user_id', 'parent_id',
+        'dateoccurred', 'startdate', 'customfields', 'estimate', 'estimatedays',
+        'milestone_id', 'asset_id', 'asset_ids', 'assets',
+        // Halo-internal category names always valid
+        'category2', 'category3', 'category4', 'category5', 'category6',
+    ]);
+    const unknownFields = [...providedKeys].filter((k) => !knownFieldNames.has(k));
+    const valid = missingRequired.length === 0 && unknownFields.length === 0;
+    const result = {
+        valid,
+        missing_required: missingRequired,
+        unknown_fields: unknownFields,
+        required_fields: allRequiredFields,
+        tickettype_id: args.tickettype_id,
+        tickettype_name: tickettype.name ?? '',
+    };
+    // Only include required_customfields when there are any, to keep compact
+    // responses lean for ticket types with no custom field requirements.
+    if (requiredCustomFields.length > 0) {
+        result['required_customfields'] = requiredCustomFields;
+    }
+    // Bug 3: wire compact defaults so compact mode returns the key validation fields.
+    const formatOpts = withCompactDefaults(args.format_options ?? { format: 'standard' }, VALIDATE_COMPACT_DEFAULTS);
+    return formatResponse(result, formatOpts);
+}
+// =============================================================================
 // Tool Definitions
 // =============================================================================
 export const listTicketsTool = {
@@ -624,19 +990,19 @@ export const searchTicketsTool = {
 };
 export const createTicketTool = {
     name: 'create_halopsa_ticket',
-    description: 'Create a new HaloPSA ticket. Required: summary, tickettype_id, client_id. Body is sent as POST /Tickets with array wrapper [{ ... }] (HaloPSA convention). Invalidates ticket cache. Estimate auto-computed from startdate->targetdate (5x8 business hrs) if omitted; pass `estimate` to override.',
+    description: 'Create a new HaloPSA ticket. Required: summary, tickettype_id, client_id. Invalidates ticket cache. Estimate auto-computed from startdate->targetdate (5x8 business hrs) if omitted; pass `estimate` to override. Pass asset_id/asset_ids to link assets on creation.',
     schema: CreateTicketArgsSchema,
     handler: createTicket,
 };
 export const updateTicketTool = {
     name: 'update_halopsa_ticket',
-    description: 'Update an existing HaloPSA ticket. Performs read-before-write merge (Halo POST is REPLACE not PATCH). Update by explicit id only — no force/dedup flags (tickets are append-only events). Invalidates ticket cache.',
+    description: 'Update an existing HaloPSA ticket. Performs read-before-write merge (REPLACE not PATCH). Update by explicit id only. Invalidates ticket cache. Pass asset_id/asset_ids to link assets on update.',
     schema: UpdateTicketArgsSchema,
     handler: updateTicket,
 };
 export const closeTicketTool = {
     name: 'close_halopsa_ticket',
-    description: 'Close a HaloPSA ticket. Resolves the closed-status id dynamically via /Status (cached). Optionally posts a resolution note as a final action before status change.',
+    description: 'Close a HaloPSA ticket. Resolves the closed-status id dynamically via /Status (cached). Optionally posts a resolution note as a final action before status change. When resolution_note is supplied, an outcome_id is required by Halo — provide resolution_outcome_id explicitly or the MCP auto-resolves the first is_resolution outcome for the tickettype (cached 1h).',
     schema: CloseTicketArgsSchema,
     handler: closeTicket,
 };
@@ -646,4 +1012,10 @@ export const deleteTicketTool = {
     schema: DeleteTicketArgsSchema,
     handler: deleteTicket,
 };
+export const validateCreateTicketTool = {
+    name: 'validate_halopsa_create_ticket',
+    description: 'Pure local dry-run validation of a proposed ticket payload against the cached tickettype schema. No Halo write is performed. Returns {valid, missing_required[], unknown_fields[], required_fields[]} so callers can catch missing mandatory fields before calling create_halopsa_ticket. Fetches tickettype via GET /TicketType/{id}?includedetails=true (cached 1h). Use list_halopsa_tickettypes to look up tickettype_id values. v1.6: recurses into nested group.fields[] and translates Halo-internal category2..6 to MCP category_1..5 field names; required-customfield ids surfaced separately when present.',
+    schema: ValidateCreateTicketArgsSchema,
+    handler: validateCreateTicket,
+};
 //# sourceMappingURL=tickets.js.map