@tomtom-org/maps-sdk-plugin-agent-toolkit 0.10.1 → 0.11.0

package/README.md

@@ -57,8 +57,8 @@ console.log(result.text);
 
 ### With React (`useChat`)
 
-```typescript
-import { DirectChatTransport } from 'ai';
+```tsx
+import { DirectChatTransport, isTextUIPart } from 'ai';
 import { useChat } from '@ai-sdk/react';
 
 const agent = createMapAgent(map, { model: openai('gpt-4o') });
@@ -70,10 +70,10 @@ function ChatPanel() {
 
     return (
         <div>
-            {messages.map((m) => (
-                <div key={m.id}>{m.content}</div>
+            {messages.map((message) => (
+                <div key={message.id}>{message.parts.filter(isTextUIPart).map((part) => part.text).join('')}</div>
             ))}
-            <input onKeyDown={(e) => e.key === 'Enter' && sendMessage(e.target.value)} />
+            <input onKeyDown={(event) => event.key === 'Enter' && sendMessage({ text: event.currentTarget.value })} />
         </div>
     );
 }
@@ -105,29 +105,37 @@ The plugin ships a `DEFAULT_TOOLS` registry covering search, routing, traffic, r
 | `removeWaypointsFromRoute` | Remove one or more waypoints by index from the current route |
 | `replaceWaypointInRoute` | Overwrite a single waypoint of the current route in place — origin, destination, or by index |
 | `getCurrentWaypoints` | Get the staged waypoint slots (origin, stops, destination) |
+| `startRouteMonitor` | Recalculate an already-calculated route on a cadence (default 60 s) so its live-traffic delays stay current |
+| `stopRouteMonitor` | Stop recalculating a route; the entry keeps its last data |
 | `findReachableAreas` | Calculate isochrone/isodistance polygons from one or more origins (private preview: the API key needs Calculate Reachable Range access) |
 
 ### Traffic
 
 | Tool | Description |
 |---|---|
-| `getTrafficIncidents` | Fetch traffic incidents within an area (viewport, named place, route corridor, polygon, IDs) |
-| `startTrafficIncidentsMonitor` | Start a live monitor that refreshes incident state on a configurable cadence |
-| `stopTrafficIncidentsMonitor` | Stop the live incident monitor |
+| `getTrafficIncidents` | Fetch traffic incidents within an area (viewport, named place, route corridor, polygon, IDs); the entry keeps refreshing by default |
+| `setTrafficIncidentsMonitor` | Turn background refreshing of an already-loaded incidents entry on or off |
+| `clusterIncidents` | Group loaded incidents into hotspots (DBSCAN) with road and category labels, delay totals and trends |
 | `focusIncidents` | Highlight a subset of incidents (by id / category / severity) on the map and dim the rest |
 | `getTrafficAreaAnalytics` | Fetch historical traffic analytics (speed, congestion, travel time) for an area |
-| `queryTrafficAnalytics` | Query cached analytics data or check what is currently displayed |
 | `toggleTilesTrafficFlow` | Toggle the real-time traffic-flow tile overlay |
 | `toggleTilesTrafficIncidents` | Toggle the real-time traffic-incidents tile overlay |
 | `setMapStyling` | Set or reset base-map styling knobs — label/icon/road sizes, exit numbers, shields, 3D buildings, congestion colours, map colours, presets, or a whole theme from a few colours or an image |
-| `getShownTileIncidents` | List real-time incidents visible in the current viewport |
+
+### Trackers
+
+| Tool | Description |
+|---|---|
+| `createTracker` | Watch loaded entries with generated code and log an alert when its condition turns true (e.g. an incident near a hospital) |
+| `getTrackers` | List the active trackers and whether each is firing |
+| `getTrackerHistory` | Read the alerts and events trackers have logged, for one tracker or since a time |
+| `clearTracker` | Stop a tracker; the entries it watched stay |
 
 ### Bring-your-own-data (BYOD)
 
 | Tool | Description |
 |---|---|
 | `addByodSource` | Ingest a customer-authored GeoJSON source (URL or inline `FeatureCollection`) and profile its shape; the entry has no layers and renders nothing until the agent sets them via `setByodLayers` |
-| `recallByod` | List BYOD entries, or retrieve a single entry's full `FeatureCollection` by id |
 | `setByodLayers` | Restyle a BYOD entry — replace its MapLibre layers (type + data-driven paint) using the entry's data `profile` |
 | `updateByodDisplay` | Show, hide, or clear BYOD layers on the map |
 
@@ -139,6 +147,7 @@ The plugin ships a `DEFAULT_TOOLS` registry covering search, routing, traffic, r
 |---|---|
 | `analyseData` | Aggregate / chart entries (`places`, `routes`, `incidents`, `geometries`, `trafficAreaAnalytics`, `byod`) via dynamic JS; classifier-emitted scope narrows the schema per turn |
 | `processData` | Transform entries into new `places`, `placeConnections`, `geometries`, `byod`, or a `fitOnMap` camera move via dynamic JS |
+| `monitorAnalysis` | Start or stop recomputing an `analyseData` analysis whenever its source entries change |
 | `executeMaplibreCode` | Execute arbitrary MapLibre JS against the live `Map` instance — escape hatch for custom layers, animations, raster overlays |
 
 > See [Code generation](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/code-generation) for the injected identifiers, output contracts, and threat model, and [Scope-aware data tools](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/scope-aware-data-tools) for how the per-turn classifier scope keeps the prompt small.
@@ -188,12 +197,7 @@ const agent = createMapAgent(map, {
 
 | Tool | Description |
 |---|---|
-| `recallPlaces` | Retrieve the history of place lookups from this session |
-| `recallRoutes` | Retrieve previously calculated routes from this session |
-| `recallRanges` | Retrieve stored reachable-range results |
-| `recallGeometries` | Look up polygon sources by `{ kind, id }` across place footprints, isochrones, and `customGeometries` entries |
-| `recallByod` | Retrieve BYOD entries (see [BYOD](#bring-your-own-data-byod)) |
-| `recallState` | Summarize the current contents of every state slice |
+| `recallState` | Read session state: a snapshot of every slice, one kind's entries (`places`, `routes`, `ranges`, `geometries`, `byod`, …), or one entry by `{ kind, id }` |
 | `setEntryMode` | Switch a slice between `multiple` (default) and `single` entry modes |
 | `resetState` | Reset one or all state slices |
 
@@ -202,8 +206,7 @@ const agent = createMapAgent(map, {
 | Tool | Description |
 |---|---|
 | `calculateBBox` | Compute a bounding box from GeoJSON features or tool results |
-| `formatDistance` | Format meters into a human-readable string (e.g. "2.5 km") |
-| `formatDuration` | Format seconds into a human-readable string (e.g. "1 h 30 min") |
+| `clarifyIntent` | Ask the user to resolve a genuinely ambiguous or missing input, as a few numbered choices plus a free answer |
 | `help` | List available capabilities in summary or searchable detail mode |
 
 ## Customization

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { BaseMapModule, CustomGeoJSONLayerSpec, CustomGeoJSONModule, GeometriesModule, GeometryFillStyle, POIsModule, PlaceConnectionDisplay, PlacesModule, PlanningWaypoint, RoutingModule, StylingModule, TomTomMap, TrafficAreaAnalyticsModule, TrafficAreaAnalyticsModuleConfig, TrafficFlowModule, TrafficIncidentOverlayModule, TrafficIncidentsModule } from "@tomtom-org/maps-sdk/map";
-import { BBox, CommonPlaceProps, GeographyType, Place, Places, PolygonFeature, PolygonFeatures, Route, Routes, TrafficAreaAnalytics, TrafficIncident, WaypointLike } from "@tomtom-org/maps-sdk/core";
+import { BaseMapModule, CustomGeoJSONLayerSpec, CustomGeoJSONModule, GeometriesModule, GeometryFillStyle, POIsModule, PlaceConnectionDisplay, PlacesModule, PlanningWaypoint, ReachableRangesModule, RoutingModule, StylingModule, TomTomMap, TrafficAreaAnalyticsModule, TrafficAreaAnalyticsModuleConfig, TrafficFlowModule, TrafficIncidentDetailsModule, TrafficIncidentsModule } from "@tomtom-org/maps-sdk/map";
+import { BBox, CommonPlaceProps, GeographyType, Place, Places, PolygonFeature, PolygonFeatures, ReachableRangeBudget, Route, Routes, TrafficAreaAnalytics, TrafficIncident, WaypointLike } from "@tomtom-org/maps-sdk/core";
 import { ChartConfiguration } from "chart.js";
 import { Map as Map$1 } from "maplibre-gl";
 import { z } from "zod";
-import { GeoBias, ReachableRangeBudget, TrafficIncidentDetailsByBBoxParams } from "@tomtom-org/maps-sdk/services";
+import { GeoBias, TrafficIncidentDetailsByBBoxParams } from "@tomtom-org/maps-sdk/services";
 import { LanguageModel, ModelMessage, PrepareStepFunction, ToolLoopAgent } from "ai";
 //#region src/engine/engine.d.ts
 /** What {@link JobEngine.register} needs to mint a {@link Job}. `run` and `onOrphaned` are owner closures. */
@@ -1177,7 +1177,7 @@ type PlacesStateEvents = {
  * State for the places layer: an append-only history of place results plus per-entry display
  * modules.
  *
- * Each entry owns a single PlacesModule (switched in place via `applyMarkerType` when the marker
+ * Each entry owns a single PlacesModule (switched in place via `updateConfig` when the marker
  * type changes — an entry only renders under one marker type at a time) and a dedicated
  * GeometriesModule, lazy-initialised on first show. Display state lives on the entry, so two
  * entries can be rendered side by side under different marker types without sharing a single source.
@@ -1206,7 +1206,7 @@ declare class PlacesState implements StateSlice {
   /**
    * Lazy-init and return the entry's PlacesModule, switched to `markerType`. An entry only
    * ever renders under one marker type at a time, so the same module is reused — flipping marker
-   * types calls `applyMarkerType` in place. Throws when the entry id is unknown.
+   * types calls `updateConfig` in place. Throws when the entry id is unknown.
    */
   getEntryPlacesModule(entryId: string, markerType: PlacesMarkerType): Promise<PlacesModule>;
   /**
@@ -1335,7 +1335,7 @@ type PlacesEntry = BaseEntry<Place[]> & {
   _geometryByPlaceId?: Record<string, PolygonFeature<CommonPlaceProps>>;
   /**
    * Per-entry display modules. An entry is rendered under at most one marker type at a time,
-   * so a single PlacesModule covers all of them — `_showEntryAs` switches it via `applyMarkerType`.
+   * so a single PlacesModule covers all of them — `_showEntryAs` switches it via `updateConfig({ markerType })`.
    * A dedicated GeometriesModule renders the entry's boundary polygons.
    * Lazy-initialised via PlacesState helpers — undefined until first show.
    */
@@ -1377,17 +1377,17 @@ type ReachableRange = {
  */
 type RangesEntry = BaseEntry<ReachableRange[]> & {
   /**
-   * Per-entry display modules. Each entry owns a dedicated GeometriesModule (for the
-   * isochrone polygons) and PlacesModule (for the origin pin(s)), so display state lives
+   * Per-entry display modules. Each entry owns a dedicated ReachableRangesModule (for the
+   * isochrone polygons, and their fill style), a GeometriesModule (for the same polygons in a
+   * consumer's own style) and a PlacesModule (for the origin pin(s)), so display state lives
    * on the entry instead of a shared slice-level module. Lazy-initialised via RangeState
    * helpers — undefined until first show.
    */
   _modules?: {
+    ranges?: ReachableRangesModule;
     geometries?: GeometriesModule;
     places?: PlacesModule;
   };
-  /** Fill style that the geometries module is currently configured with. */
-  _shownFillStyle?: GeometryFillStyle;
   /** True while any of this entry's modules are rendering on the map. */
   _shown?: boolean;
 };
@@ -1418,7 +1418,7 @@ type RangeStateEvents = {
  *
  * Stores semantic summaries of calculated ranges (origin, budgets).
  * Also retains raw polygon geometry internally for use in geometry searches
- * (e.g. discoverPlaces withinRange). Displayed on the map via GeometriesModule.
+ * (e.g. discoverPlaces withinRange). Displayed on the map via ReachableRangesModule.
  *
  * @group Agent Toolkit
  */
@@ -1444,9 +1444,16 @@ declare class RangeState implements ShownEntriesSlice {
    */
   setEntryMode(mode: EntryMode): Promise<void>;
   /**
-   * Lazy-init the entry's GeometriesModule (for the isochrone/isodistance polygons),
+   * Lazy-init the entry's ReachableRangesModule (for the isochrone/isodistance polygons),
    * applying the requested fill style. Throws on unknown id.
    */
+  getEntryRangesModule(entryId: string, fillStyle?: GeometryFillStyle): Promise<ReachableRangesModule>;
+  /**
+   * Lazy-init the entry's plain GeometriesModule, for drawing the entry's polygons in a style of
+   * your own (per-feature colours, border widths) rather than as reachable-range bands.
+   * Updates only the fill style when it changes, keeping the styling applied since. Throws on
+   * unknown id.
+   */
   getEntryGeometriesModule(entryId: string, fillStyle?: GeometryFillStyle): Promise<GeometriesModule>;
   /**
    * Lazy-init the entry's origin-pin PlacesModule. Each entry maintains its own pin module
@@ -1466,7 +1473,7 @@ declare class RangeState implements ShownEntriesSlice {
   /** Hide every module on the entry (clear). No-op when the entry is unknown. */
   hideEntry(entryId: string): Promise<void>;
   /**
-   * Drop a single entry from history. Hides it from the map first (clears its geometries +
+   * Drop a single entry from history. Hides it from the map first (clears its ranges +
    * origin-pin modules) then removes it from `_entries`. Emits `entries-change`. No-op when
    * the id is unknown.
    */
@@ -2292,7 +2299,7 @@ type TrafficIncidentsEntry = BaseEntry<TrafficIncident[]> & {
    * via `TrafficIncidentsState.getEntryModule` — undefined until first show. Subscribe to
    * clicks via `module.events.on('click', ...)` once retrieved.
    */
-  _module?: TrafficIncidentOverlayModule;
+  _module?: TrafficIncidentDetailsModule;
   /** True while this entry is currently rendered on the map. */
   _shown?: boolean;
   /**
@@ -2390,7 +2397,7 @@ type TrafficIncidentsStateEvents = {
 };
 /**
  * State for traffic incidents: entry history and map rendering via per-entry
- * TrafficIncidentOverlayModule. Each entry can be a separate area; under the default
+ * TrafficIncidentDetailsModule. Each entry can be a separate area; under the default
  * `multiple` mode several entries can render at once.
  *
  * Each entry owns its own module (lazy-init on first show) plus an optional per-entry
@@ -2442,11 +2449,11 @@ declare class TrafficIncidentsState implements StateSlice {
    */
   replaceEntryData(entryId: TrafficIncidentsEntry['id'], data: TrafficIncident[], sampledAt: number): Promise<boolean>;
   /**
-   * Lazy-init and return the entry's TrafficIncidentOverlayModule. Consumers subscribe to
+   * Lazy-init and return the entry's TrafficIncidentDetailsModule. Consumers subscribe to
    * clicks directly on the returned module via `module.events.on('click', ...)`;
    * Throws on unknown entry id.
    */
-  getEntryModule(entryId: TrafficIncidentsEntry['id']): Promise<TrafficIncidentOverlayModule>;
+  getEntryModule(entryId: TrafficIncidentsEntry['id']): Promise<TrafficIncidentDetailsModule>;
   /**
    * Render an entry on the map. Lazy-inits its module, pushes the entry's incidents, and
    * (when `fitBounds` is true) fits the camera to the entry's bbox. Emits `shown-change`
@@ -2824,17 +2831,6 @@ export declare const prepareMultiInputs: (ids: MultiInputIds, state: ToolState)
  * @ignore
  */
 export declare const BY_ENTRY_VIEWS_DOC: string;
-/**
- * @ignore
- */
-export declare const routeUtils: {
-  readonly calculateProgressAtRoutePoint: (route: Route, pathIndex: number) => import("@tomtom-org/maps-sdk/core").RouteProgressAtPoint | undefined;
-  readonly getCoordinateAtRouteProgress: (route: Route, query: import("@tomtom-org/maps-sdk/core").RouteProgressQuery) => import("@tomtom-org/maps-sdk/core").RouteCoordinateAtProgress | undefined;
-  readonly getProgressAtNearestRoutePoint: (route: Route, point: import("@tomtom-org/maps-sdk/core").HasLngLat) => import("@tomtom-org/maps-sdk/core").RouteCoordinateAtProgress | undefined;
-  readonly getRouteProgressBetween: (route: Route, startPathIndex: number, endPathIndex: number) => import("@tomtom-org/maps-sdk/core").RouteSegmentProgress | undefined;
-  readonly getRouteProgressForSection: (route: Route, section: import("@tomtom-org/maps-sdk/core").SectionProps) => import("@tomtom-org/maps-sdk/core").RouteSegmentProgress | undefined;
-  readonly getSectionBBox: (route: Route, section: import("@tomtom-org/maps-sdk/core").SectionProps) => import("@tomtom-org/maps-sdk/core").OptionalBBox;
-};
 /**
  * Names injected into the sandbox by analyseData / processData, in fixed order.
  *
@@ -3279,6 +3275,30 @@ export type ResolvedAreaDisclosure = {
 };
 export declare const isResolveError: (r: unknown) => r is ResolveError;
 //#endregion
+//#region src/tools/shared/route-utils.d.ts
+/**
+ * @module agent-toolkit-tools
+ *
+ * The `routeUtils` namespace injected into sandboxed model-authored code, so a routes input can be
+ * sliced and measured without re-implementing it. Its own module because the worker entry
+ * (`sandbox/sdk-utils-worker-entry.ts`) is bundled standalone at SDK build time, so importing it
+ * from `multi-input.ts` would pull that module's prompt text into the worker bundle.
+ *
+ * Every function here depends only on `@turf/turf` — available in the worker as `self.turf` — and
+ * pure local helpers, which is what makes the set portable into the sandbox.
+ */
+/**
+ * @ignore
+ */
+export declare const routeUtils: {
+  readonly calculateProgressAtRoutePoint: (route: import("@tomtom-org/maps-sdk/core").Route, pathIndex: number) => import("@tomtom-org/maps-sdk/core").RouteProgressAtPoint | undefined;
+  readonly getCoordinateAtRouteProgress: (route: import("@tomtom-org/maps-sdk/core").Route, query: import("@tomtom-org/maps-sdk/core").RouteProgressQuery) => import("@tomtom-org/maps-sdk/core").RouteCoordinateAtProgress | undefined;
+  readonly getProgressAtNearestRoutePoint: (route: import("@tomtom-org/maps-sdk/core").Route, point: import("@tomtom-org/maps-sdk/core").HasLngLat) => import("@tomtom-org/maps-sdk/core").RouteCoordinateAtProgress | undefined;
+  readonly getRouteProgressBetween: (route: import("@tomtom-org/maps-sdk/core").Route, startPathIndex: number, endPathIndex: number) => import("@tomtom-org/maps-sdk/core").RouteSegmentProgress | undefined;
+  readonly getRouteProgressForSection: (route: import("@tomtom-org/maps-sdk/core").Route, section: import("@tomtom-org/maps-sdk/core").SectionProps) => import("@tomtom-org/maps-sdk/core").RouteSegmentProgress | undefined;
+  readonly getSectionBBox: (route: import("@tomtom-org/maps-sdk/core").Route, section: import("@tomtom-org/maps-sdk/core").SectionProps) => import("@tomtom-org/maps-sdk/core").OptionalBBox;
+};
+//#endregion
 //#region src/tools/shared/routes-schema-doc.d.ts
 /**
  * @module agent-toolkit-tools
@@ -4683,7 +4703,8 @@ export type MapAgentInstance<CS extends ToolState = ToolState> = ToolLoopAgent &
  * ```typescript
  * import { createMapAgent } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
  * import { openai } from '@ai-sdk/openai';
- * import { DirectChatTransport } from 'ai/react';
+ * import { useChat } from '@ai-sdk/react';
+ * import { DirectChatTransport } from 'ai';
  *
  * const agent = createMapAgent(map, { model: openai('gpt-4o') });
  *
@@ -4810,4 +4831,26 @@ type ClarifyIntentToolOptions = {
  */
 export declare const createClarifyIntentTool: (options?: ClarifyIntentToolOptions) => ToolEntry;
 //#endregion
-export type { AnalysesEvents, AnalysisRecord, BYODAnalysis, BYODDataProfile, BYODEntry, BYODPropertyProfile, BYODSource, ByodSourceUrlValidation, ByodSourceUrlValidator, ClarifyIntentQuestion, ClarifyIntentToolOptions, ClassificationResult, ClassifierOptions, ClusterResult, ClusterTrend, ClusteringOutput, ClusteringParams, CustomGeometriesAnalysis, CustomGeometriesEntry, DataEntryConfig, DataEntryKind, EntryAnalysis, EntryMode, EntryModeSlice, EntryModeSliceName, GeometryProvenance, IncidentSnapshot, IncidentsAnalysis, MemberRef, MonitoredArea, PlacesAnalysis, PlacesEntry, PollingStatus, RangesEntry, ReachableRange, RouteParams, RoutesAnalysis, RoutesEntry, StateDigest, SystemPromptSection, SystemPromptSectionOverrides, ToolName, Tracker, TrackerEvent, TrackerEventStatus, TrackerEventType, TrackerStateEvents, TrafficAreaAnalyticsAnalysis, TrafficAreaAnalyticsEntry, TrafficAreaAnalyticsParams, TrafficIncidentsEntry, Verdict };
+//#region src/tools/utilities/get-current-location.d.ts
+type GetCurrentLocationToolOptions = {
+  /**
+   * Send the exact position, the device's accuracy and the fix's timestamp to the model, from a
+   * fresh high-accuracy fix. Defaults to `false`: the position is rounded to 3 decimals (about
+   * 100 m) from a fix up to a minute old, with no timestamp.
+   */
+  fullPrecision?: boolean;
+};
+/**
+ * Build a getCurrentLocation {@link ToolEntry}. Pass the result to `createMapAgent`'s `tools` option
+ * to replace the built-in default, for example to send the exact position:
+ *
+ * ```typescript
+ * createMapAgent(map, {
+ *     model,
+ *     tools: { getCurrentLocation: createGetCurrentLocationTool({ fullPrecision: true }) },
+ * });
+ * ```
+ */
+export declare const createGetCurrentLocationTool: (options?: GetCurrentLocationToolOptions) => ToolEntry;
+//#endregion
+export type { AnalysesEvents, AnalysisRecord, BYODAnalysis, BYODDataProfile, BYODEntry, BYODPropertyProfile, BYODSource, ByodSourceUrlValidation, ByodSourceUrlValidator, ClarifyIntentQuestion, ClarifyIntentToolOptions, ClassificationResult, ClassifierOptions, ClusterResult, ClusterTrend, ClusteringOutput, ClusteringParams, CustomGeometriesAnalysis, CustomGeometriesEntry, DataEntryConfig, DataEntryKind, EntryAnalysis, EntryMode, EntryModeSlice, EntryModeSliceName, GeometryProvenance, GetCurrentLocationToolOptions, IncidentSnapshot, IncidentsAnalysis, MemberRef, MonitoredArea, PlacesAnalysis, PlacesEntry, PollingStatus, RangesEntry, ReachableRange, RouteParams, RoutesAnalysis, RoutesEntry, StateDigest, SystemPromptSection, SystemPromptSectionOverrides, ToolName, Tracker, TrackerEvent, TrackerEventStatus, TrackerEventType, TrackerStateEvents, TrafficAreaAnalyticsAnalysis, TrafficAreaAnalyticsEntry, TrafficAreaAnalyticsParams, TrafficIncidentsEntry, Verdict };