@wilnertech/halopsa-mcp-server 1.5.0 → 1.7.0

package/dist/tools/registrations.js

@@ -5,14 +5,19 @@
  * Tool inventory (71 total):
  *   Assets (11), Users (7), Sites (4), Clients (3),
  *   Reference data (4), Ticket reference data (6 — incl. outcomes),
- *   Tickets (8 — incl. validateCreateTicket), Ticket actions (4 — incl. SLA hold/release),
+ *   Tickets (8 — incl. validateCreateTicket; getTicketsBatch counted under Batch),
+ *   Ticket actions (4 — incl. SLA hold/release),
  *   Ticket custom fields (2),
  *   Batch operations (5 — assets, users, sites, tickets, bulk-update),
  *   Ticket links (1 — read-side only),
  *   Workflows (6 — list/get/list-steps/create/update/delete),
  *   Ticket milestones (5 — list/set/add/remove + get-current),
  *   Budgets (5 — list/create/delete BudgetType, get/set per-ticket)
+ *
+ * COUNT BREAKDOWN: 11+7+4+3+4+6+8+4+2+5+1+6+5+5 = 71
+ * The `allTools` array is the authoritative source; verify with allTools.length.
  */
+import { z } from 'zod';
 // Asset tools (11)
 import { listAssetsTool, getAssetTool, searchAssetsBySerialTool, searchAssetsByHostnameTool, createAssetTool, updateAssetTool, deleteAssetTool, listAssetCustomFieldsTool, getAssetFieldSchemaTool, findAssetMatchTool, scanAssetDuplicatesTool, } from './assets.js';
 // User tools (7)
@@ -25,7 +30,7 @@ import { listClientsTool, getClientTool, searchClientsTool, } from './clients.js
 import { listAssetTypesTool, listAssetStatusesTool, listContactTypesTool, listAgentsTool, } from './reference-data.js';
 // Ticket reference data tools (6)
 import { listTicketTypesTool, getTicketTypeTool, listTicketStatusesTool, listTicketPrioritiesTool, listTicketCategoriesTool, listTicketOutcomesTool, } from './ticket-reference-data.js';
-// Ticket tools (9 here; getTicketsBatchTool is the 10th and lives in batch-operations.ts)
+// Ticket tools (8 — getTicketsBatchTool lives in batch-operations.ts and is counted there)
 import { listTicketsTool, getTicketTool, searchTicketsTool, createTicketTool, updateTicketTool, closeTicketTool, deleteTicketTool, validateCreateTicketTool, } from './tickets.js';
 // Ticket action tools (4)
 import { addTicketActionTool, listTicketActionsTool, holdTicketSlaTool, releaseTicketSlaTool, } from './ticket-actions.js';
@@ -83,7 +88,7 @@ const allTools = [
     listTicketPrioritiesTool,
     listTicketCategoriesTool,
     listTicketOutcomesTool,
-    // Tickets (9)
+    // Tickets (8 — getTicketsBatchTool counted under Batch operations below)
     listTicketsTool,
     getTicketTool,
     searchTicketsTool,
@@ -128,9 +133,29 @@ const allTools = [
     getTicketBudgetTool,
     setTicketBudgetTool,
 ];
+/**
+ * Diagnostic meta-tool — returns the names of every tool currently reachable
+ * in the registry. Use to verify the server\'s exposed surface, or to confirm
+ * a registration succeeded when a tool call returns "not found".
+ */
+function createListLoadedToolsMeta(registry) {
+    return {
+        name: 'list_halopsa_loaded_tools',
+        description: 'List every HaloPSA tool currently reachable in the registry. Diagnostic helper for verifying the server\'s exposed surface — useful when a tool call returns "not found" and you need to confirm whether registration succeeded.',
+        schema: z.object({}),
+        handler: async () => {
+            const tools = registry.getToolSchemas().map((t) => t.name).sort();
+            return JSON.stringify({
+                total: tools.length,
+                tools,
+            });
+        },
+    };
+}
 export function registerAllTools(registry) {
     for (const tool of allTools) {
         registry.registerZod(tool);
     }
+    registry.registerZod(createListLoadedToolsMeta(registry));
 }
 //# sourceMappingURL=registrations.js.map

package/dist/tools/registrations.js.map

@@ -1 +1 @@
-{"version":3,"file":"registrations.js","sourceRoot":"","sources":["../../src/tools/registrations.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registrations.js","sourceRoot":"","sources":["../../src/tools/registrations.ts"],"names":[],"mappings":"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"}

package/dist/tools/ticket-actions.d.ts

@@ -17,6 +17,7 @@ export declare const AddTicketActionArgsSchema: z.ZodObject<{
     ticket_id: z.ZodNumber;
     note: z.ZodString;
     outcome_id: z.ZodOptional<z.ZodNumber>;
+    outcome_name: z.ZodOptional<z.ZodString>;
     email_reply: z.ZodOptional<z.ZodBoolean>;
     hiddenfromuser: z.ZodOptional<z.ZodBoolean>;
     timetaken: z.ZodOptional<z.ZodNumber>;
@@ -52,27 +53,9 @@ export declare const ListTicketActionsArgsSchema: z.ZodObject<{
 export declare const HoldTicketSlaArgsSchema: z.ZodObject<{
     ticket_id: z.ZodNumber;
     reason: z.ZodOptional<z.ZodString>;
-    format_options: z.ZodOptional<z.ZodObject<{
-        format: z.ZodOptional<z.ZodEnum<{
-            compact: "compact";
-            standard: "standard";
-            detailed: "detailed";
-        }>>;
-        fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        omit_empty: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const ReleaseTicketSlaArgsSchema: z.ZodObject<{
     ticket_id: z.ZodNumber;
-    format_options: z.ZodOptional<z.ZodObject<{
-        format: z.ZodOptional<z.ZodEnum<{
-            compact: "compact";
-            standard: "standard";
-            detailed: "detailed";
-        }>>;
-        fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        omit_empty: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare function addTicketAction(client: HaloPSAAPIClient, args: z.infer<typeof AddTicketActionArgsSchema>): Promise<string>;
 export declare function listTicketActions(client: HaloPSAAPIClient, args: z.infer<typeof ListTicketActionsArgsSchema>): Promise<string>;

package/dist/tools/ticket-actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ticket-actions.d.ts","sourceRoot":"","sources":["../../src/tools/ticket-actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAevD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;iBAyBpC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;iBAQtC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;iBAMlC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;;;;;;;iBAIrC,CAAC;AA2IH,wBAAsB,eAAe,CACnC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,GAC9C,OAAO,CAAC,MAAM,CAAC,CAsDjB;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,GAChD,OAAO,CAAC,MAAM,CAAC,CA0BjB;AAaD;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,GAC5C,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,GAC/C,OAAO,CAAC,MAAM,CAAC,CAgBjB;AAMD,eAAO,MAAM,mBAAmB,EAAE,iBAKjC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,iBAKnC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,iBAK/B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,iBAKlC,CAAC"}
+{"version":3,"file":"ticket-actions.d.ts","sourceRoot":"","sources":["../../src/tools/ticket-actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAgBvD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;iBA8BpC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;iBAQtC,CAAC;AAMH,eAAO,MAAM,uBAAuB;;;iBAKlC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;iBAGrC,CAAC;AA0MH,wBAAsB,eAAe,CACnC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,GAC9C,OAAO,CAAC,MAAM,CAAC,CAmKjB;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,GAChD,OAAO,CAAC,MAAM,CAAC,CAiCjB;AAaD;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,GAC5C,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,GAC/C,OAAO,CAAC,MAAM,CAAC,CAoBjB;AAMD,eAAO,MAAM,mBAAmB,EAAE,iBAKjC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,iBAKnC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,iBAK/B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,iBAKlC,CAAC"}

package/dist/tools/ticket-actions.js

@@ -12,9 +12,10 @@
  */
 import { z } from 'zod';
 import { HaloPSAError } from '../api/errors.js';
-import { formatResponse, stripWriteResponse } from '../utils/formatter.js';
+import { formatResponse, stripWriteResponse, withCompactDefaults } from '../utils/formatter.js';
 import { TTL } from '../cache/memory-cache.js';
 import { FormatOptionsSchema } from '../schemas/common.js';
+import { getOutcomesForTicketType, getOutcomeByName } from './ticket-reference-data.js';
 // =============================================================================
 // Schemas
 // =============================================================================
@@ -24,20 +25,25 @@ export const AddTicketActionArgsSchema = z.object({
     note: z.string().min(1)
         .describe('Note body (plain text or HTML)'),
     outcome_id: z.number().int().optional()
-        .describe('Outcome enum ID (Public Note, Private Note, Email Reply, etc.). Halo REQUIRES this on most tenants — without it, POST /Actions returns 400 "An Outcome must be entered for this Action". Look up valid outcomes for your agent in Halo admin → Configuration → Tickets → Outcomes.'),
+        .describe('Outcome enum ID (Public Note, Private Note, Email Reply, etc.). Halo REQUIRES this on most tenants — without it, POST /Actions returns 400 "An Outcome must be entered for this Action". Use list_halopsa_ticket_outcomes with the same tickettype_id to discover the IDs. Either outcome_id OR outcome_name must be supplied; if both are supplied, outcome_id wins.'),
+    outcome_name: z.string().optional()
+        .describe('Outcome name as an alternative to outcome_id (e.g. "Private Note", "Email Reply"). Case-insensitive exact match against the global outcomes list (cached 1h). Either outcome_id OR outcome_name must be supplied; if both, outcome_id wins.'),
     email_reply: z.boolean().optional()
         .describe('If true, sends the note as an email reply to the ticket requester'),
     hiddenfromuser: z.boolean().optional()
         .describe('If true, hides the action from the customer portal'),
     // Time-entry fields (Bug 1 — billing)
-    timetaken: z.number().optional()
-        .describe('Hours worked on this action (decimal). Drives ticket.timetaken rollup and billing.'),
-    chargehours: z.number().optional()
-        .describe('Chargeable hours (may differ from timetaken if some time is non-chargeable).'),
+    timetaken: z.number().min(0).optional()
+        // Hours must be non-negative — wire-key fix in v1.6.0 activated live billing path.
+        .describe('Hours worked on this action (decimal, >= 0). Drives ticket.timetaken rollup and billing.'),
+    chargehours: z.number().min(0).optional()
+        // Hours must be non-negative — wire-key fix in v1.6.0 activated live billing path.
+        .describe('Chargeable hours (>= 0; may differ from timetaken if some time is non-chargeable).'),
     nonchargeable: z.boolean().optional()
         .describe('True to mark this action non-billable. Default false.'),
-    chargerate: z.number().optional()
-        .describe('Override hourly rate. Defaults to the ticket\'s contract rate.'),
+    chargerate: z.number().int().min(0).optional()
+        // non-negative integer FK per v1.6.0 billing-guard principle
+        .describe('Override hourly rate (non-negative integer FK). Defaults to the ticket\'s contract rate.'),
     start_datetime: z.string().optional()
         .describe('ISO 8601 when work started (e.g., 2026-05-12T09:00:00Z). If both start/end supplied, timetaken can be derived.'),
     end_datetime: z.string().optional()
@@ -53,65 +59,86 @@ export const ListTicketActionsArgsSchema = z.object({
         .describe('Page number (1-indexed)'),
     format_options: FormatOptionsSchema,
 });
+// R3 Finding 4: format_options dropped — both SLA tools return fixed-shape
+// sentinel objects (held/released boolean + ticket_id + note). Accepting
+// format_options without honoring it was a broken contract; the shape is
+// authoritative and small, so a single pretty-printed JSON output is correct.
 export const HoldTicketSlaArgsSchema = z.object({
     ticket_id: z.number().int()
         .describe('HaloPSA ticket ID whose SLA clock should be held'),
     reason: z.string().optional()
         .describe('Note to attach to the hold action. Defaults to "SLA hold — waiting on customer".'),
-    format_options: FormatOptionsSchema,
 });
 export const ReleaseTicketSlaArgsSchema = z.object({
     ticket_id: z.number().int()
         .describe('HaloPSA ticket ID whose SLA clock should be released'),
-    format_options: FormatOptionsSchema,
 });
 // =============================================================================
 // Helpers
 // =============================================================================
 const ACTION_PREVIEW_LEN = 200;
+/**
+ * Default compact fields for add_halopsa_ticket_action (Bug 3 wiring).
+ * Matches the shape that compactAction() produces plus standard billing fields.
+ *
+ * Note: Halo's Actions schema does not declare a "date work performed" field
+ * separately from datetime (action submission). The field `actiondate` is NOT
+ * declared on components.schemas.Actions in halopsa-swagger.json — it appears
+ * only on components.schemas.Outgoingemail. Future v1.7+ work item: live-tenant
+ * probe to confirm whether datetime suffices for work-performed semantics.
+ */
+const ACTION_COMPACT_DEFAULTS = [
+    'id', 'ticket_id', 'outcome_id', 'outcome', 'timetaken', 'actionchargehours', 'chargerate',
+    'who', 'datetime', 'note_preview',
+];
 /**
  * Regex to detect Halo 400 messages that indicate a missing or invalid
  * outcome_id — covers both "An Outcome must be entered for this Action"
  * and "You do not have access to this Action at the moment."
  */
 const OUTCOME_ERROR_RE = /Outcome must be entered|access to this Action/i;
-/**
- * Scan an arbitrary object for any key whose name contains "outcome"
- * (case-insensitive) and whose value is an array. Returns that array,
- * or an empty array if nothing is found.
- */
-function extractOutcomeHint(obj) {
-    for (const key of Object.keys(obj)) {
-        if (/outcome/i.test(key)) {
-            const val = obj[key];
-            if (Array.isArray(val)) {
-                return val;
-            }
-        }
-    }
-    return [];
-}
 /**
  * When POST /Actions returns a 400 matching the outcome-required pattern,
  * fetch the parent ticket and its tickettype config, then return a structured
  * "refusal" object (not a thrown error) so the caller sees discovery info.
+ *
+ * Bug 4 enrichments:
+ * - tickettype_name resolved from cached /TicketType list (not from ticket.tickettype_name
+ *   which is often absent); falls back to ticket.tickettype_name only if cache misses.
+ * - valid_outcomes_hint populated via getOutcomesForTicketType() helper (sorted by
+ *   sequence then id, sliced to first 10), not via fragile extractOutcomeHint regex.
+ * - If any secondary lookup fails, discovery_warning documents what failed; the refusal
+ *   is always returned (never re-thrown).
+ */
+/**
+ * Clamp a halo error message to 500 characters for inclusion in refusal objects.
+ * 500 chars matches the bodyExcerpt budget in errors.ts and gives enough context
+ * to diagnose most API errors without bloating token output.
+ * If truncated, appends the ellipsis character and sets halo_error_truncated: true
+ * on the result object. Returns the (possibly clamped) message string.
  */
+function clampHaloError(msg, result) {
+    const MAX = 500;
+    if (msg.length <= MAX)
+        return msg;
+    result['halo_error_truncated'] = true;
+    return msg.slice(0, MAX) + '…';
+}
 async function buildOutcomeDiscoveryRefusal(client, ticketId, haloError) {
     const discoveryWarnings = [];
     // --- Step 1: fetch the parent ticket ---
     let tickettypeId;
-    let tickettypeName;
+    let tickettypeNameFallback;
     try {
         const ticket = await client.get(`/Tickets/${ticketId}`, { includedetails: true });
         tickettypeId = ticket.tickettype_id;
-        tickettypeName = ticket.tickettype_name;
+        tickettypeNameFallback = ticket.tickettype_name;
     }
     catch (innerErr) {
         const msg = innerErr instanceof Error ? innerErr.message : String(innerErr);
         discoveryWarnings.push('ticket lookup failed: ' + msg);
-        return {
+        const earlyResult = {
             action_created: false,
-            halo_error: haloError,
             diagnosis: 'outcome_id is required for this tickettype and was either missing or invalid',
             tickettype_id: null,
             tickettype_name: null,
@@ -120,29 +147,62 @@ async function buildOutcomeDiscoveryRefusal(client, ticketId, haloError) {
             remediation: 'Either retry with a valid outcome_id (check Halo admin: Configuration > Tickets > Outcomes), ' +
                 'or fall back to update_halopsa_ticket to set details_html / status_id without going through the Actions surface.',
         };
+        earlyResult['halo_error'] = clampHaloError(haloError, earlyResult);
+        return earlyResult;
+    }
+    // --- Step 2: resolve tickettype_name from cached /TicketType list (Bug 4) ---
+    // ticket.tickettype_name is often absent from the detail response; the global
+    // tickettypes list (cached 1h) is more reliable.
+    let tickettypeName = null;
+    if (tickettypeId !== undefined) {
+        try {
+            const ttList = await client.getCached('/TicketType', { count: 500 }, {
+                enabled: true,
+                ttl: TTL.TICKET_TYPES,
+                keyPrefix: 'tickettypes:all',
+            });
+            const ttItems = Array.isArray(ttList)
+                ? ttList
+                : (ttList.tickettypes ?? []);
+            const found = ttItems.find((t) => t.id === tickettypeId);
+            tickettypeName = found?.name ?? tickettypeNameFallback ?? null;
+        }
+        catch (innerErr) {
+            const msg = innerErr instanceof Error ? innerErr.message : String(innerErr);
+            discoveryWarnings.push('tickettypes list lookup failed: ' + msg);
+            // Fall back to the field on the ticket (often absent)
+            tickettypeName = tickettypeNameFallback ?? null;
+        }
     }
-    // --- Step 2: fetch the tickettype config ---
+    // --- Step 3: fetch valid outcomes via shared helper (Bug 4) ---
+    // Sort by sequence (ascending), then by id (ascending) as tiebreaker.
+    // Slice to first 10 for response compactness.
     let validOutcomesHint = [];
     if (tickettypeId !== undefined) {
         try {
-            const ttConfig = await client.get(`/TicketType/${tickettypeId}`, { includedetails: true });
-            validOutcomesHint = extractOutcomeHint(ttConfig);
+            const outcomes = await getOutcomesForTicketType(client, tickettypeId);
+            const sorted = outcomes.slice().sort((a, b) => {
+                const seqA = a.sequence ?? 999999;
+                const seqB = b.sequence ?? 999999;
+                return seqA !== seqB ? seqA - seqB : a.id - b.id;
+            });
+            validOutcomesHint = sorted.slice(0, 10).map((o) => ({ id: o.id, name: o.name }));
         }
         catch (innerErr) {
             const msg = innerErr instanceof Error ? innerErr.message : String(innerErr);
-            discoveryWarnings.push('tickettype lookup failed: ' + msg);
+            discoveryWarnings.push('outcomes lookup failed: ' + msg);
         }
     }
     const result = {
         action_created: false,
-        halo_error: haloError,
         diagnosis: 'outcome_id is required for this tickettype and was either missing or invalid',
         tickettype_id: tickettypeId ?? null,
-        tickettype_name: tickettypeName ?? null,
+        tickettype_name: tickettypeName,
         valid_outcomes_hint: validOutcomesHint,
         remediation: 'Either retry with a valid outcome_id from the list above, ' +
             'or fall back to update_halopsa_ticket to set details_html / status_id without going through the Actions surface.',
     };
+    result['halo_error'] = clampHaloError(haloError, result);
     if (discoveryWarnings.length > 0) {
         result['discovery_warning'] = discoveryWarnings.join('; ');
     }
@@ -160,6 +220,13 @@ function compactAction(action) {
         who: action.who,
         datetime: action.datetime,
         outcome: action.outcome,
+        outcome_id: action.outcome_id,
+        // Q5 billing fields — must be carried through the compact projection so the
+        // caller can verify what hours/rate landed on the action (POST /Actions is
+        // at-most-once; the compact response is the only audit signal on success).
+        timetaken: action.timetaken,
+        actionchargehours: action.actionchargehours,
+        chargerate: action.chargerate,
         note_preview: note.length > ACTION_PREVIEW_LEN
             ? note.slice(0, ACTION_PREVIEW_LEN) + '…'
             : note,
@@ -178,25 +245,73 @@ function unwrapActionList(response) {
 // Implementations
 // =============================================================================
 export async function addTicketAction(client, args) {
+    // Resolve outcome_name → outcome_id when the caller passed a name only.
+    // outcome_id wins when both are supplied so the explicit ID never gets
+    // accidentally overridden by a name lookup.
+    //
+    // Phase 1.4 swagger: getOutcomeByName (ticket-reference-data.ts:642-660)
+    // matches against the raw `TOutcome.outcome` property — the canonical
+    // name field in halopsa-swagger.json. The compactor remaps it to `name`
+    // for the response shape, but the lookup uses the swagger-declared
+    // field. See tools/phase1-audit.sh item 1.4.
+    let effectiveOutcomeId = args.outcome_id;
+    let resolvedOutcomeName;
+    if (effectiveOutcomeId === undefined && args.outcome_name !== undefined) {
+        const resolved = await getOutcomeByName(client, args.outcome_name);
+        if (resolved === null) {
+            // Surface the same structured-refusal shape used for outcome-required 400s
+            // so the caller sees a discovery hint rather than a bare error.
+            const refusal = {
+                action_created: false,
+                diagnosis: `outcome_name "${args.outcome_name}" did not match any outcome (case-insensitive). The outcomes list is cached 1h — if the name was recently added, expect up to 1h cache-staleness.`,
+                outcome_name_requested: args.outcome_name,
+                remediation: 'Call list_halopsa_ticket_outcomes (optionally with tickettype_id) to discover valid names and IDs.',
+            };
+            return JSON.stringify(refusal);
+        }
+        effectiveOutcomeId = resolved.id;
+        resolvedOutcomeName = resolved.name;
+    }
     const payload = {
         ticket_id: args.ticket_id,
         note: args.note,
     };
-    if (args.outcome_id !== undefined)
-        payload.outcome_id = args.outcome_id;
+    if (effectiveOutcomeId !== undefined)
+        payload.outcome_id = effectiveOutcomeId;
     if (args.email_reply !== undefined)
         payload.email_reply = args.email_reply;
     if (args.hiddenfromuser !== undefined)
         payload.hiddenfromuser = args.hiddenfromuser;
-    // Time-entry fields — passed verbatim using Halo's canonical field names.
-    // timetaken and chargehours are confirmed in the swagger Actions schema.
-    // nonchargeable, chargerate, start_datetime, end_datetime are part of the
-    // 508-property schema but not captured in the IPA swagger slice; they are
-    // accepted by empirical observation on live tenants.
+    // Time-entry fields. Caller-facing input names are mapped to Halo's documented
+    // Actions property names below. Verified 2026-05-12 against
+    // components.schemas.Actions in halopsa-swagger.json (508 properties):
+    //   timetaken      → timetaken         (in Actions schema, swagger-confirmed)
+    //   chargehours    → actionchargehours  (Actions uses `actionchargehours`,
+    //                                       NOT `chargehours`; `chargehours` is
+    //                                       on Faults/Faults_List (ticket-level
+    //                                       rollup) — NOT on Actions schema)
+    //   chargerate     → chargerate         (in Actions schema, int32 FK)
+    //   nonchargeable  → nonchargeable      (NOT in swagger; zero occurrences in
+    //                                       halopsa-swagger.json; accepted by
+    //                                       empirical observation on live tenants.
+    //                                       Documented Actions field is
+    //                                       actionnonchargehours: number (not
+    //                                       boolean). v1.8+ TODO: live-tenant
+    //                                       probe before renaming.)
+    //   start_datetime → start_datetime     (NOT in swagger; observation only)
+    //   end_datetime   → end_datetime       (NOT in swagger; observation only)
     if (args.timetaken !== undefined)
         payload.timetaken = args.timetaken;
+    // Map the caller-facing `chargehours` input to Halo's documented Actions
+    // property `actionchargehours`. `chargehours` is NOT declared on Actions —
+    // it is a ticket-level rollup field on components.schemas.Faults and
+    // components.schemas.Faults_List only. Sending `chargehours` on POST /Actions
+    // would be silently dropped by Halo's deserializer (unknown DataMember).
     if (args.chargehours !== undefined)
-        payload.chargehours = args.chargehours;
+        payload.actionchargehours = args.chargehours;
+    // nonchargeable: undocumented on Actions schema in halopsa-swagger.json. Tenant-accepted
+    // alias observed empirically. Documented field is actionnonchargehours: number (not boolean).
+    // v1.8+ TODO: live-tenant probe before renaming.
     if (args.nonchargeable !== undefined)
         payload.nonchargeable = args.nonchargeable;
     if (args.chargerate !== undefined)
@@ -215,9 +330,10 @@ export async function addTicketAction(client, args) {
         // When Halo returns 400 for a missing or invalid outcome_id, surface a
         // structured refusal with discovery info instead of re-throwing the raw
         // error.  This lets the caller retry with a valid outcome_id.
-        const haloMessage = error instanceof HaloPSAError ? error.message : String(error);
-        if (OUTCOME_ERROR_RE.test(haloMessage)) {
-            const refusal = await buildOutcomeDiscoveryRefusal(client, args.ticket_id, haloMessage);
+        const rawHaloMessage = error instanceof HaloPSAError ? error.message : String(error);
+        if (OUTCOME_ERROR_RE.test(rawHaloMessage)) {
+            const refusal = await buildOutcomeDiscoveryRefusal(client, args.ticket_id, rawHaloMessage);
+            // v1.7+ TODO: route through formatResponse() or apply scrubCredentials() before stringify. Low current risk: refusal fields are id+name+error_msg+remediation; CREDENTIAL_KEY_RE matches JSON keys, and Halo 400 messages on outcome failures empirically don't contain credential strings. Documented in 2026-05-12_review-protocol-validation.md.
             return JSON.stringify(refusal);
         }
         throw error;
@@ -225,8 +341,69 @@ export async function addTicketAction(client, args) {
     const created = Array.isArray(raw) ? raw[0] : raw;
     client.invalidateCache(`ticket-actions:${args.ticket_id}*`);
     client.invalidateCache(`ticket:${args.ticket_id}*`);
+    // Halo's POST /Actions response can be sparse — some tenants return only
+    // `{id: N}` (where `id` is the per-ticket sequence number, NOT a global ID).
+    // To keep the audit signal meaningful, synthesize a fallback object from the
+    // request payload and let real response fields override it. The resulting
+    // `id` (sequence-within-ticket) is preserved as the canonical id;
+    // `ticket_id` is also added so the response is self-describing.
+    //
+    // Phase 1.5 swagger: halopsa-swagger.json declares POST /Actions returns
+    // 201 with the full Actions schema (508 properties). Empirically tenants
+    // return a sparse body; this merge is the documented-vs-observed delta
+    // workaround. See tools/phase1-audit.sh item 1.5.
+    const note = args.note ?? '';
+    const synthesized = {
+        ticket_id: args.ticket_id,
+        note,
+    };
+    if (effectiveOutcomeId !== undefined)
+        synthesized.outcome_id = effectiveOutcomeId;
+    if (resolvedOutcomeName !== undefined)
+        synthesized.outcome = resolvedOutcomeName;
+    if (args.hiddenfromuser !== undefined)
+        synthesized.hiddenfromuser = args.hiddenfromuser;
+    if (args.timetaken !== undefined)
+        synthesized.timetaken = args.timetaken;
+    if (args.chargehours !== undefined)
+        synthesized.actionchargehours = args.chargehours;
+    if (args.chargerate !== undefined)
+        synthesized.chargerate = args.chargerate;
+    // R4 Finding 4.13: start_datetime / end_datetime are NOT declared in
+    // components.schemas.Actions in halopsa-swagger.json (verified 2026-05-12 via
+    // tools/phase1-audit.sh and `python3` swagger probe). Included in the
+    // synthesized object as request-payload echoes for audit-trail completeness —
+    // the caller sees back what they sent even if Halo's deserializer silently
+    // drops them. Empirically accepted by some tenants. If the API drops them,
+    // the merged response simply omits them rather than showing wrong data.
+    if (args.start_datetime !== undefined)
+        synthesized.start_datetime = args.start_datetime;
+    if (args.end_datetime !== undefined)
+        synthesized.end_datetime = args.end_datetime;
+    // Merge: request-side fallbacks first, then real response fields. Halo's `id`
+    // (sequence-within-ticket) is the only field guaranteed to be present.
+    //
+    // R1 Finding 1.5: drop `null`/`undefined`/`""` values from `created` before
+    // spreading so we never let Halo's response *erase* a synthesized fallback
+    // (e.g., resolvedOutcomeName) by overwriting it with null. Real values from
+    // Halo still win because non-empty values pass the filter.
+    const createdScrubbed = {};
+    for (const [k, v] of Object.entries(created)) {
+        if (v !== null && v !== undefined && v !== '')
+            createdScrubbed[k] = v;
+    }
+    const merged = {
+        ...synthesized,
+        ...createdScrubbed,
+    };
     const format = args.format_options?.format ?? 'compact';
-    return formatResponse(stripWriteResponse(created, format, 'action'), { format });
+    // Apply compactAction() on the compact path so note_preview is synthesized
+    // from the merged note text (so the response is meaningful even when Halo
+    // returned only {id: N}).  For non-compact formats, return the full merged
+    // object so callers see every field they sent plus everything Halo returned.
+    const compacted = format === 'compact' ? compactAction(merged) : merged;
+    const formatOpts = withCompactDefaults(args.format_options ?? { format: 'compact' }, ACTION_COMPACT_DEFAULTS);
+    return formatResponse(stripWriteResponse(compacted, format, 'action'), formatOpts);
 }
 export async function listTicketActions(client, args) {
     const params = { ticket_id: args.ticket_id };
@@ -234,7 +411,7 @@ export async function listTicketActions(client, args) {
         params.count = args.count;
     if (args.page_no !== undefined)
         params.page_no = args.page_no;
-    const formatOpts = args.format_options || { format: 'compact' };
+    const baseFormatOpts = args.format_options || { format: 'compact' };
     const response = await client.getCached('/Actions', params, {
         enabled: true,
         ttl: TTL.TICKET_ACTION_LIST,
@@ -243,9 +420,15 @@ export async function listTicketActions(client, args) {
     const { actions, record_count } = unwrapActionList(response);
     // Compact mode: substitute the preview-shaped objects so the response
     // never echoes back full HTML bodies on a journal listing.
-    const items = formatOpts.format === 'compact'
+    const items = baseFormatOpts.format === 'compact'
         ? actions.map(compactAction)
         : actions;
+    // Wire per-tool compact defaults so the compact projection guarantees
+    // {id, ticket_id, outcome_id, outcome, who, datetime, note_preview} even when
+    // some are null on the Halo response. Without this the legacy compactItem()
+    // heuristic would not recognize an action shape and could strip fields back
+    // to {id} on tenants that return sparse action records.
+    const formatOpts = withCompactDefaults(baseFormatOpts, ACTION_COMPACT_DEFAULTS);
     return formatResponse(items, formatOpts, { record_count });
 }
 // =============================================================================
@@ -276,6 +459,10 @@ export async function holdTicketSla(client, args) {
     client.invalidateCache(`ticket:${args.ticket_id}*`);
     client.invalidateCache('tickets:*');
     const note = args.reason ?? 'SLA hold — waiting on customer';
+    // v1.7+ TODO: route through formatResponse() or apply scrubCredentials() before stringify.
+    // Low current risk: SLA hold/release response object fields are held+ticket_id+reason+note (audit prose);
+    // CREDENTIAL_KEY_RE matches JSON keys, and Halo 200 responses on onhold updates empirically
+    // don't contain credential strings. Documented in 2026-05-12_review-protocol-validation.md.
     return JSON.stringify({
         held: true,
         ticket_id: args.ticket_id,
@@ -289,6 +476,10 @@ export async function releaseTicketSla(client, args) {
     await client.post('/Tickets', [payload]);
     client.invalidateCache(`ticket:${args.ticket_id}*`);
     client.invalidateCache('tickets:*');
+    // v1.7+ TODO: route through formatResponse() or apply scrubCredentials() before stringify.
+    // Low current risk: SLA hold/release response object fields are released+ticket_id+note (audit prose);
+    // CREDENTIAL_KEY_RE matches JSON keys, and Halo 200 responses on onhold updates empirically
+    // don't contain credential strings. Documented in 2026-05-12_review-protocol-validation.md.
     return JSON.stringify({
         released: true,
         ticket_id: args.ticket_id,
@@ -300,13 +491,13 @@ export async function releaseTicketSla(client, args) {
 // =============================================================================
 export const addTicketActionTool = {
     name: 'add_halopsa_ticket_action',
-    description: 'Append an action (note, email reply, status change journal entry, time entry) to a HaloPSA ticket. POST /Actions with array body wrapper. Supports time-entry billing fields: timetaken, chargehours, nonchargeable, chargerate, start_datetime, end_datetime. Invalidates ticket and action caches.',
+    description: 'Append an action (note, email reply, status change, time entry) to a HaloPSA ticket. Specify outcome by outcome_id OR outcome_name (case-insensitive, resolved via cached outcomes list). Supports billing fields: timetaken, chargehours, nonchargeable, chargerate, start_datetime, end_datetime. Note: `id` in the response is the per-ticket sequence number, NOT a global action ID.',
     schema: AddTicketActionArgsSchema,
     handler: addTicketAction,
 };
 export const listTicketActionsTool = {
     name: 'list_halopsa_ticket_actions',
-    description: 'List actions/journal entries on a HaloPSA ticket. Compact response includes a 200-char note_preview; pass format_options.format="detailed" for full notes. Cached 1min.',
+    description: 'List actions/journal entries on a HaloPSA ticket. Compact response guarantees {id, ticket_id, outcome_id, outcome, timetaken, actionchargehours, chargerate, who, datetime, note_preview (≤200 chars)} — null-filled when absent. Pass format_options.format="detailed" for full notes and all fields. Cached 1min.',
     schema: ListTicketActionsArgsSchema,
     handler: listTicketActions,
 };
@@ -318,7 +509,7 @@ export const holdTicketSlaTool = {
 };
 export const releaseTicketSlaTool = {
     name: 'release_halopsa_ticket_sla',
-    description: 'Release a HaloPSA ticket SLA hold (work resumed). Discovers the SLA-Release outcome at runtime via GET /Outcome name-match (/sla.{0,3}release/i) or HALO_MCP_SLA_RELEASE_OUTCOME_ID env var. Halo sets ticket.onhold=false server-side as a side-effect. Outcome is cached per-process after first resolution.',
+    description: 'Releases the SLA hold on a HaloPSA ticket. Performs read-before-write merge to set onhold=false on the ticket. Direct write — no outcome lookup, no env var. Invalidates ticket and ticket_actions caches.',
     schema: ReleaseTicketSlaArgsSchema,
     handler: releaseTicketSla,
 };