fix: route plan_route stops by resolved waypoints and add text-search fallback

[weikhang95]

Summary

PlacesSearcher.planRoute resolved every stop twice, with two different resolvers, then zipped the results by array index. geocoded[] came from the Geocoding API and supplied only the display labels; the raw strings went separately to computeRoutes, where toWaypoint turned any non-lat,lng string into { address: rawString } — a second, independent geocode. Google's Specify locations for a route says an address string "must first be geocoded by the Routes API" and that the result may differ from the Geocoding API.

So labels and distances could describe different places while the tool returned success: true. On main (v0.0.55):

plan_route(["Tokyo Tower", "SAWA Hotel"])
  → success: true, label: SAWA Hotel (488 Rue de Verdun, Douala, Cameroon), distance: 12158.8 km
distance_matrix(["35.6585805,139.7454329"] → ["4.0340411,9.6839268"])   # Tokyo Tower → that label
  → 20251.4 km

12158.8 ≠ 20251.4 — Routes had resolved SAWA Hotel to a third place, so the agent sees success and reports a route nobody measured.

plan_route and explore_area also threw on free text Geocoding cannot resolve, even when Text Search finds it:

plan_route(["河口湖駅", "精進湖 他根浜"])  →  Failed to geocode: 精進湖 他根浜
search_places("精進湖 他根浜")             →  Tatego-Hama Beach, ChIJ13ziPsznG2ARIqd4uJcjN0s

The class is narrow: text that is neither an address nor an indexed landmark. Tokyo Tower geocodes fine and explore_area("Tokyo Tower") works on main.

Fix

PlacesSearcher.resolveLocation(input) resolves a string once — lat,lng parsed and range-checked locally, otherwise Geocoding, then Places Text Search, throwing if neither resolves. It throws rather than returning { success: false } because planRoute.ts and exploreArea.ts JSON.stringify(result.data) without checking the flag.

The result reaches computeRoutes as a place ID waypoint, so label and route cannot disagree. Google recommends place IDs "instead of latitude/longitude coordinates or address strings", because a coordinate is "snapped to the road nearest to those coordinates".

Changes

File	Change
src/services/RoutesService.ts	Export COORDINATE_STRING_PATTERN; add RouteWaypoint / WaypointInput so origin / destination / intermediates accept structured waypoints; add describeWaypoint; optional originLabel / destinationLabel so no-route errors still name the caller's stop
src/services/PlacesSearcher.ts	Add ResolvedLocation, toRouteWaypoint, resolveLocation; planRoute and exploreArea resolve each input once
tests/locationResolution.unit.test.ts	New — 9 tests over resolution, fallback, coordinate handling and the label/route guard
tests/routesWaypoints.unit.test.ts	New — 5 tests over waypoint conversion, the matrix path and error text

No tool schema, description or registration changed, so the 9-file tool checklist in CLAUDE.md does not apply. computeRouteMatrix is untouched and still takes strings.

Impact

• Distances shift slightly for name-based stops — place IDs route to a place's own access points, not the nearest road. The three-stop Tokyo route went 130.3 → 128.5 km. Anyone snapshot-testing distances will see a diff.
• Geocoding's answer now always wins. Label and route are consistent, but a name the Routes geocoder happened to resolve better can get worse. SAWA Hotel still lands in Cameroon — now consistently rather than divergently.
• Coordinate stops keep the caller's exact point and no longer depend on Geocoding. Out-of-range coordinates fail locally in plan_route / explore_area; toWaypoint is unchanged, so get_directions and distance_matrix behave as today.
• Error text: Failed to geocode: X → Failed to resolve location: X (geocoding: …; places text search: …).
• One extra API call, only when Geocoding returns nothing — and on any geocoding failure, not just zero results, since geocode flattens every error into { success: false } with no status code. Text Search is the pricier call ($32.00 vs $5.00 per 1000 at the first paid tier).
• Not from this PR: 3 stops with the default optimize: true fails with Cannot read properties of undefined (reading 'originalName') on this branch and on main alike — the bug fix: require at least 2 intermediates for waypoint optimization #86 fixes, in the same index-zip code the divergence above came from.

Test plan

• npm run build succeeds
• npm run lint — 0 errors (175 pre-existing warnings, plus 22 no-explicit-any on the new tests' stubs)
• npm test — 198 passed, 0 failed
• npm run test:unit — 16 passed, 0 failed, with tests/exploreArea.unit.test.ts unedited
• Reverting only src/ to main and keeping the new tests: 5 pass, 11 fail — the 11 are exactly the new assertions
• Manual verification against the live API

Verification

	before	after
plan_route(["Tokyo Tower","SAWA Hotel"])	12158.8 km, label ≠ route	20206.0 km, label and route share one place_id
plan_route(["河口湖駅","精進湖 他根浜"])	Failed to geocode	success, 18.3 km
explore_area("精進湖 他根浜")	Failed to geocode address	success, 35.4906841 / 138.6046066
plan_route([2 coordinate strings])	12.3 km	12.3 km, unchanged

Follow-ups (not in this PR)

• Location biasing would fix the wrong-continent match itself, but it changes which place an input resolves to — your call as maintainer.
• get_directions, search_along_route and distance_matrix still pass raw strings to Routes, with the same divergence exposure.
• npm run test:unit is not in CI. I left ci.yml alone deliberately; say the word and I will send the one-line PR.

Changelog entry

- fix: route plan_route stops by resolved waypoints and add text-search fallback (#87)

[cablate]

Thanks for the exceptionally detailed report and verification — especially the concrete label/route divergence example, the fallback cost note, and the follow-up scope.

I’ve updated this branch as maintainer to integrate #86 while preserving both contributors’ commits. The PR now also:

• skips waypoint optimization for fewer than two intermediates;
• includes the fix: require at least 2 intermediates for waypoint optimization #86 unit and live regression coverage;
• tests the optimization threshold at the RoutesService boundary;
• runs npm run test:unit in CI; and
• skips the live place-photo smoke test when fork PRs cannot access GOOGLE_MAPS_API_KEY.

CI is now green. I intentionally left location biasing and the related raw-string paths in get_directions, search_along_route, and distance_matrix for focused follow-up work, since those change resolution semantics beyond this PR.