fix(ai-tools): structured VALIDATION_ERROR for manage_* billing-domain tools (#2362)

[ToddHebebrand]

Summary

manage_quotes (observed live in an MCP dogfood session) surfaced every malformed call as a bare HTTP 500 {"error":"Internal Server Error"}. Root causes:

• The flat tool input schema marks every id/payload optional (required-ness depends on action), so a missing quoteId sailed past validation, got coerced by String(undefined) into the literal string "undefined", and died downstream as an opaque uuid/DB error.
• Payload casts (input.line as QuoteLineInput) skipped Zod entirely, so schema violations either threw raw ZodErrors (escaping as 500s) or passed garbage into the services.
• add_manual_line's real schema (quoteLineInputSchema) requires sourceType and taxable — neither was mentioned in the tool description, so the "obvious" payload always 500'd.
• add_catalog_line ran String(input.catalogItemId) unconditionally, so a partNumber-only call 500'd; partNumber read like a lookup key but is only a stored override.

Changes

• New shared apps/api/src/services/aiToolValidation.ts — per-action required-param presence checks (run BEFORE any coercion) and ZodError → structured {"error": "<message with path>", "code": "VALIDATION_ERROR"} mapping, matching the existing service-error shape (e.g. QUOTE_NOT_FOUND).
• manage_quotes: presence-checks each action's required params, then parses input/patch/block/line payloads with the same shared Zod schemas the HTTP quote routes use (one source of truth). ZodError paths are self-describing (line.sourceType: ...).
• Descriptions: the tool description now enumerates required params per action; input/line/block document required + optional fields the way the deposit patch param already did; catalogItemId is marked REQUIRED for add_catalog_line and partNumber is explicitly documented as a stored override, NOT a lookup key (kept as-is rather than promoted to a lookup key — smallest safe change; a SKU-search lookup can be a follow-up).
• Sweep: the same missing-param guard + ZodError mapping applied to the sibling billing-domain multiplexers manage_invoices, manage_contracts, manage_catalog.

Tests

• aiToolsQuotes.test.ts: missing quoteId/patch/input, missing line.sourceType/line.taxable (asserts both field paths in the error), partNumber-only add_catalog_line, non-uuid catalogItemId, mismatched block content, missing lineId — each asserts the structured error and that the service was NOT called.
• Sweep tests in aiToolsBilling.manageInvoices.test.ts, aiToolsContracts.manageContracts.test.ts, aiToolsCatalog.manageCatalog.test.ts.
• All 4 affected suites green (52 tests); tsc --noEmit --project apps/api/tsconfig.json clean.

Closes #2362

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying breeze with    Cloudflare Pages

Latest commit:	e79feae
Status:	🚫  Build failed.

View logs

[ToddHebebrand]

Review run: /code-review (high effort, inline finder angles: line-by-line diff scan, removed-behavior audit, cross-file caller trace, reuse/simplification, CLAUDE.md conventions) over the full stacked diff.
Findings: 0 on this PR's diff (1 minor message-clarity finding surfaced in the stacked #2373 diff, fixed there in 3a449f7). Verified every REQUIRED_PARAMS map matches its switch cases and action enum 1:1 across all four manage_* tools, and that the outer validateToolInput layer already safeParses (so handler checks are defense-in-depth, not the only guard).
Tests: 4 affected suites green (aiToolsQuotes, aiToolsBilling.manageInvoices, aiToolsContracts.manageContracts, aiToolsCatalog.manageCatalog — 52 tests); tsc --noEmit --project apps/api/tsconfig.json clean.
Status: review-clean, awaiting maintainer merge. Merge before #2373 (its base is this branch).