Add saved routes and scheduled traffic updates

[QueryPlanner]

Summary

Add user-scoped saved routes and scheduled traffic summaries on top of the
read-only Google Maps Routes tools delivered by PR 1.

Users should be able to save a common trip such as "home to office", request a
fresh traffic-aware estimate by name, and receive a current route summary at a
recurring local time. Scheduled updates must reuse Blacki's existing reminder
scheduler and ADK execution path instead of introducing a second scheduler.

Priority

P1 / High — This is the product layer that turns one-off route estimates
into a useful daily commute workflow.

Level of Effort

Large (5–8 engineering days) — Includes persistent user-scoped storage,
mutation tools, reminder integration, privacy controls, automated tests, and
agent behavior evaluation.

User scenarios

• "Save my home-to-office route."
• "How long will my commute take right now?"
• "Check my office commute every weekday at 8:00 AM."
• "List my saved routes."
• "Change my gym route to avoid tolls."
• "Delete my old office route."
• A scheduled event fetches a new Routes API response and reports the current
  ETA, baseline duration, and traffic delay.

Proposed behavior

Saved route definition

Persist only the route definition:

• Stable route ID
• Owning user ID
• User-provided route name
• Origin and destination place IDs
• Safe display labels
• Travel mode
• Route modifiers such as avoid tolls, highways, or ferries
• Created and updated timestamps

Resolve address inputs to canonical place IDs before persistence. If an input
cannot be resolved safely or is ambiguous, return a non-mutating response that
asks the user for a more precise location.

Do not persist raw Routes API responses, polylines, traffic intervals,
historical ETAs, or traffic snapshots. Google Maps policies restrict caching
and storage of most Routes content, while place IDs may be stored.

Agent tools

Add tools with clear JSON-serializable result contracts:

• save_common_route
• list_common_routes
• check_common_route
• update_common_route
• delete_common_route

All mutation tools must require an explicit user request. Route names must be
unique per user using normalized, case-insensitive matching. Reads and writes
must always be scoped to the current authenticated user.

Scheduled traffic summaries

Reuse the existing recurring-reminder system:

1. Schedule a self-contained reminder that identifies the saved route by ID.
2. At execution time, run the reminder through the existing ADK runtime.
3. Call check_common_route to obtain a fresh traffic-aware Routes response.
4. Send a concise summary containing distance, current ETA, static duration,
   traffic delay, requested departure time, and Google Maps attribution.

The first version should always send the scheduled summary. Conditional
"notify only when delay exceeds N minutes" behavior is out of scope until the
scheduled-event delivery path can intentionally suppress a response.

If the referenced route has been deleted, the scheduled run must return a
safe, actionable message and must not use another user's route.

Architecture

• Add a dedicated asynchronous SQLite storage component rather than encoding
  route records in general user preferences.
• Initialize and close the component through Blacki's dependency container.
• Reuse the PR 1 Routes client; do not create a separate HTTP client.
• Reuse the existing reminder scheduler and delivery callback.
• Add route-domain instructions to the agent prompt:
  • Use a fresh lookup for current traffic questions.
  • Never imply that scheduled polling is continuous live tracking.
  • Ask one focused question when a route name or endpoint is missing.
  • Require explicit intent before saving, updating, or deleting.
• Redact exact locations and place IDs from logs and telemetry.
• Enforce a configurable per-user saved-route limit.

Non-goals

• Continuous GPS tracking or provider-pushed traffic subscriptions
• Long-term traffic history, commute analytics, or cached ETA trends
• Route Matrix support
• Traffic-colored polyline rendering
• Places autocomplete UI
• Toll price, eco-route, or fuel-consumption comparisons
• A second scheduling service

Failure behavior

• Missing or deleted route: return not_found without mutation.
• Duplicate route name: return a conflict and identify the existing route.
• Routes API unavailable: preserve the saved definition and disclose that the
  live estimate could not be refreshed.
• Reminder creation failure: do not claim the update was scheduled.
• Unauthorized route ID: behave as not found and do not disclose ownership.
• Unsupported route mode or modifier: reject before persistence.

Definition of done

• Saved-route records are isolated by user ID at the storage query level.
• Place IDs and route definitions are persisted, while raw route responses
  and traffic snapshots are not.
• Save, list, check, update, and delete tools have stable typed contracts.
• Persistent mutations occur only after explicit user intent.
• Route-name normalization and per-user uniqueness are enforced.
• Recurring updates use the existing reminder scheduler and timezone
  configuration.
• Every scheduled execution performs a fresh Routes API lookup.
• Scheduled summaries include ETA, static duration, calculated traffic
  delay, lookup time, and Google Maps attribution.
• Deleted or inaccessible routes fail safely without cross-user leakage.
• External Maps and model boundaries are mocked with strict autospecs;
  internal storage, tools, scheduler, and ADK integration use real code.
• Tests cover happy paths, duplicates, missing routes, API failures,
  ownership isolation, deletion, recurring execution, and restart
  persistence.
• Route-domain eval cases cover saving, checking, scheduling, ambiguity,
  deletion, missing configuration, and attempts to access another user.
• uv run ruff format --check, uv run ruff check,
  uv run mypy ., and uv run pytest --cov=src pass with 100% coverage.
• Targeted ADK route evaluations pass using the repository's evaluation
  configuration.

Sources

Google documentation

• Routes API location inputs and place IDs
• Understand Routes API responses and geocoding results
• Traffic-aware routing preferences
• Routes API policies, storage, and attribution
• Routes API usage, quotas, and billing

Blacki implementation references

• Reminder tools
• Reminder scheduler
• Scheduled Telegram delivery
• Dependency container
• Tool registry