[Plugin] Harden error handling, null guards, and type validation in omi-usgs-earthquake-app

Problem Description

In plugins/omi-usgs-earthquake-app/, several edge cases, missing defensive guards, and unhandled type/overflow exceptions cause runtime crashes across chat tool endpoints:

1. Timestamp Overflow and Year Out of Range Crashes in _timestamp_to_utc:

   • Extreme, negative, or malformed millisecond timestamps (e.g. 1e16 or -1e16) passed to datetime.fromtimestamp() crash with ValueError: year is out of range or OverflowError instead of returning None safely.
   • Non-finite float values (NaN, Infinity) crash or format unpredictably.

2. Null & Non-Dict Crashes in _summarize_feature:

   • _summarize_feature crashes with AttributeError: 'NoneType' object has no attribute 'get' when feature is non-dict (None, scalar, or string).
   • geometry.get("coordinates") crashes with AttributeError if geometry is non-dict or malformed.
   • Indexing coordinates[0] crashes or produces invalid values if coordinates is non-list or contains non-numeric strings/nulls.

3. NaN / Inf Coordinate & Bounds Bypass:

   • _parse_float and _safe_float lack math.isfinite() validation, permitting NaN and Infinity to bypass coordinate range checks and propagate into query parameters sent to the USGS FDSN API.

4. USGS Event URL Passing in tool_earthquake_details:

   • Users or LLMs frequently pass complete USGS URLs (e.g. https://earthquake.usgs.gov/earthquakes/eventpage/us7000m8v4 or with query strings/hash prefixes). tool_earthquake_details passes the raw URL directly to eventid=..., causing HTTP 400 Client Error from the USGS API.

5. Ephemeral HTTP Client Churn & Missing Lifespan Pooling:

   • _usgs_get spins up a brand-new httpx.AsyncClient on every single invocation without persistent connection pooling.
   • Unhandled httpx.TimeoutException or HTTP status errors lack explicit friendly envelopes.

6. Missing Typed Models, Request Validation, and Status Observability:

   • Missing typed request models and standard RequestValidationError envelope handler.
   • Missing /status endpoint with runtime configuration and observability metadata.

---

Proposed Fixes

1. Add defensive null and non-dict guards across _summarize_feature, safely handling missing or malformed properties, geometry, and coordinates.
2. Guard _timestamp_to_utc against ValueError, OverflowError, and OSError, validating finite bounds before conversion.
3. Validate finite floats in _parse_float and _safe_float, rejecting NaN and Infinity.
4. Implement _clean_event_id supporting clean USGS IDs, eventpage URLs, query parameters, and stripping #/whitespace.
5. Implement pooled httpx.AsyncClient lifecycle via FastAPI lifespan with graceful fallback for isolated testing.
6. Add typed Pydantic request models (RecentEarthquakesRequest, NearbyEarthquakesRequest, EarthquakeDetailsRequest) and RequestValidationError handler.
7. Expose /status endpoint reporting configuration, timeout, and health status.
8. Expand test suite in plugins/omi-usgs-earthquake-app/test_main.py from 5 to 29 hermetic tests running in <0.05s under pure Python stdlib (python3 -S).

Proposed bounty: 0.00 USD PayPal: [email protected]