@tomtom-org/maps-sdk-plugin-agent-toolkit 0.14.0 → 0.15.0

package/README.md

@@ -1,4 +1,4 @@
-# TomTom Maps SDK - Agent Toolkit Plugin
+# Agent Toolkit Plugin
 
 A headless conversational agent that gives Large Language Models tool-based control over a [TomTom Map](https://docs.tomtom.com/maps-sdk-js/guides/map/tomtom-map) and TomTom location services, powered by [Vercel AI SDK v6](https://ai-sdk.dev/).
 
@@ -18,16 +18,18 @@ No UI is included — bring your own chat interface. No LLM provider is bundled
 ## Installation
 
 ```bash
-pnpm add @tomtom-org/maps-sdk @tomtom-org/maps-sdk-plugin-agent-toolkit ai zod maplibre-gl @turf/turf chart.js h3-js
+pnpm add @tomtom-org/maps-sdk @tomtom-org/maps-sdk-plugin-agent-toolkit @tomtom-org/maps-sdk-plugin-map-theme ai zod maplibre-gl @turf/turf chart.js h3-js
 ```
 
-Install at least one AI SDK provider:
+Install at least one AI SDK provider, plus `@ai-sdk/react` for the `useChat` example below:
 
 ```bash
 # Pick one (or more)
 pnpm add @ai-sdk/openai
 pnpm add @ai-sdk/anthropic
 pnpm add @ai-sdk/azure
+
+pnpm add @ai-sdk/react
 ```
 
 ## Quick start
@@ -79,7 +81,7 @@ function ChatPanel() {
 }
 ```
 
-See [`examples/map-traffic-agent-react`](../../examples/map-traffic-agent-react) for a full working example.
+See the [traffic agent example](https://docs.tomtom.com/maps-sdk-js/examples/map-traffic-agent-react) for a full working example.
 
 ## Tools reference
 
@@ -118,6 +120,7 @@ The plugin ships a `DEFAULT_TOOLS` registry covering search, routing, traffic, r
 | `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 |
+
 ### Trackers
 
 | Tool | Description |
@@ -164,9 +167,9 @@ const agent = createMapAgent(map, {
 | Tool | Description |
 |---|---|
 | `updatePlacesDisplay` | Show, hide, or restyle place entries on the map |
-| `updateRoutesDisplay` | Show, hide, or restyle route entries (line color, waypoint icons, fit camera) |
+| `updateRoutesDisplay` | Show, hide, or swap route entries, switch the highlighted alternative, fit the camera |
 | `updateWaypointsDisplay` | Show staged waypoint markers without the route line |
-| `updateTrafficAreaAnalyticsDisplay` | Visualize traffic-area-analytics as hexgrid, heatmap, or tiles |
+| `updateTrafficAreaAnalyticsDisplay` | Show, hide, or swap traffic-area-analytics entries |
 | `clearMap` | Remove displayed places, routes, BYOD layers, or all features |
 
 ### Map control
@@ -180,15 +183,14 @@ const agent = createMapAgent(map, {
 | `setMapStandardStyle` | Switch map style (light, dark, satellite, driving, etc.) |
 | `setLanguage` | Change the language for map labels and API responses |
 | `setGeopoliticalView` | Show disputed borders and territory names from a country's view, for the map and later searches |
-| `setMapStyling` | Set or reset what the base map shows and how it looks, by knob id — layer groups such as 3D buildings, the built-in POI icons and their categories, the live traffic overlays and their filters, the hillshade and 3D terrain, sizes, colours, map presets, or a whole theme from a few colours or an image |
+| `setMapStyling` | Set or reset what the base map shows and how it looks, by knob id — layer groups such as 3D buildings, the built-in POI icons and their categories, the live traffic overlays and their filters, the hillshade and 3D terrain, sizes, colours, map presets, or a whole theme from a few colours or an image — and the look of every layer the agent drew: places, routes and their sections, polygons, reachable areas, area analytics and fetched incidents; the classifier scope lists only the knob families a turn touches |
 
 ### MapLibre direct access
 
 | Tool | Description |
 |---|---|
 | `getMapStyleLayers` | List MapLibre layer IDs with their paint/layout properties |
-| `setLayoutProperties` | Set MapLibre layout properties on named layers |
-| `setPaintProperties` | Set MapLibre paint properties (colors, widths, opacity) on named layers |
+| `setLayerProperties` | Set MapLibre paint (colors, widths, opacity) and layout (visibility, text, sizes) properties on named layers |
 
 ### State & recall
 
@@ -334,11 +336,12 @@ createMapAgent(map, { model, tools: fleetTools });
 Every tool (built-in or custom) follows the `ToolEntry` interface:
 
 ```typescript
-type ToolEntry<S extends ToolState = ToolState> = {
+type ToolEntry<S extends ToolState = ToolState, Scope = unknown> = {
     description: string;            // Operational contract for the LLM
     inputSchema: z.ZodType;         // Zod schema for input validation
     outputSchema?: z.ZodType;       // Optional structured output schema
-    execute: (input, state: S) => Promise<any>;
+    // options.signal is the turn's AbortSignal: forward it to the services calls the tool makes
+    execute: (input, state: S, options?: ToolExecuteOptions) => Promise<any>;
 
     // Classifier metadata (optional)
     classificationPrompt?: string;  // One-liner for the intent classifier
@@ -347,6 +350,12 @@ type ToolEntry<S extends ToolState = ToolState> = {
     examplePrompts?: string[];      // Natural language prompt examples
     relatedTools?: string[];        // Tools often used together
     dependsOn?: string[];           // Tools that must run before this one
+    scopeSchema?: z.ZodType<Scope>; // Per-turn scope the classifier may emit to narrow the tool
+    scopePrompt?: string;           // Classifier hint on when and how to scope the tool
+
+    // Loop control (optional)
+    alwaysActive?: boolean;         // Visible on every step, whatever the classifier picks
+    endsTurnOnCall?: boolean;       // Stop the loop on the step that calls this tool
 };
 ```
 
@@ -516,8 +525,7 @@ const agent = createMapAgent(map, {
     tools: {
         setMapStandardStyle: false,
         setLanguage: false,
-        setLayoutProperties: false,
-        setPaintProperties: false,
+        setLayerProperties: false,
         setMapStyling: false,
     },
 });
@@ -544,7 +552,8 @@ For the complete, always-current list of exports — factories, tool-registry he
 
 | Type | Package | Purpose |
 |---|---|---|
-| Peer | `@tomtom-org/maps-sdk` | TomTom Maps SDK (types, services, map modules) |
+| Peer | `@tomtom-org/maps-sdk@>=1.0.0-rc.0 <1.0.0` | TomTom Maps SDK (types, services, map modules) — its 1.0.0 release candidates |
+| Peer | `@tomtom-org/maps-sdk-plugin-map-theme@>=0.3.0` | Theming the map from a few colours or an image in `setMapStyling` |
 | Peer | `ai@^6` | Vercel AI SDK (ToolLoopAgent, tool types) |
 | Peer | `zod@^4` | Schema validation |
 | Peer | `maplibre-gl@^6` | Map rendering engine |
@@ -564,7 +573,7 @@ For the complete, always-current list of exports — factories, tool-registry he
     - [Bring your own data](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/byod) — ingest customer GeoJSON layers
 - [AI SDK v6 documentation](https://ai-sdk.dev/)
 - [TomTom Maps SDK documentation](https://docs.tomtom.com/maps-sdk-js)
-- [Example application](../../examples/map-traffic-agent-react) — full chat interface implementation
+- [Example application](https://docs.tomtom.com/maps-sdk-js/examples/map-traffic-agent-react) — full chat interface implementation
 
 ## License
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { BaseMapModule, CustomGeoJSONLayerSpec, CustomGeoJSONModule, GeometriesModule, GeometryFillStyle, POIsModule, PlaceConnectionDisplay, PlacesModule, PlanningWaypoint, ReachableRangesModule, RoutingModule, StylingFoundationsModule, TerrainModule, TomTomMap, TrafficAreaAnalyticsModule, TrafficAreaAnalyticsModuleConfig, TrafficFlowModule, TrafficIncidentDetailsModule, TrafficIncidentsModule } from "@tomtom-org/maps-sdk/map";
+import { BaseMapModule, CustomGeoJSONLayerSpec, CustomGeoJSONModule, GeometriesModule, GeometryFillStyle, KnobEntry, KnobTarget, POIsModule, PlaceConnectionDisplay, PlacesModule, PlanningWaypoint, ReachableRangesModule, RoutingModule, StylingFoundationsModule, TerrainModule, 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";
@@ -719,6 +719,38 @@ declare class BaseMapState implements StateSlice {
   reset(): void;
 }
 //#endregion
+//#region src/state/slice-knobs.d.ts
+/**
+ * The knobs set on every module of one kind a slice holds: the modules it holds now, and each one
+ * it creates later through {@link SliceKnobs.applyTo}. `setMapStyling` sets the knobs of the
+ * places, routes, geometries, ranges and traffic modules the agent drew through it.
+ *
+ * @group Agent Toolkit
+ */
+declare class SliceKnobs {
+  readonly catalogue: readonly KnobEntry<string>[];
+  private readonly modules;
+  private readonly _values;
+  /**
+   * @param catalogue - The catalogue of the module kind, e.g. `routingKnobCatalogue`.
+   * @param modules - The modules of that kind the slice holds now.
+   */
+  constructor(catalogue: readonly KnobEntry<string>[], modules: () => Iterable<KnobTarget<unknown>>);
+  /** Every knob set, by its id in the catalogue. */
+  get values(): Readonly<Record<string, unknown>>;
+  /** Sets the knob on every module, and remembers it for those created later. Throws on an invalid value. */
+  set(id: string, value: unknown): void;
+  /** Resets the knob on every module to its default, and forgets it. */
+  reset(id: string): void;
+  /** Resets every knob set. */
+  resetAll(): void;
+  /** Forgets every knob set without touching the modules, for a slice dropping them. */
+  clear(): void;
+  /** Sets every knob remembered on a module the slice just created, and returns it. */
+  applyTo<MODULE extends KnobTarget<unknown>>(module: MODULE): MODULE;
+  private _knob;
+}
+//#endregion
 //#region src/tools/shared/agent-headers.d.ts
 /**
  * @module agent-toolkit-tools
@@ -1193,6 +1225,10 @@ declare class PlacesState implements StateSlice {
   private _entryMode;
   /** The state change events, listed in {@link PlacesStateEvents}. */
   readonly events: StateEvents<PlacesStateEvents>;
+  /** The knobs set on every entry's PlacesModule, such as `color` and `label.size`. Cleared on `reset`. */
+  readonly knobs: SliceKnobs;
+  /** The knobs set on every entry's boundary GeometriesModule. Cleared on `reset`. */
+  readonly geometriesKnobs: SliceKnobs;
   constructor(_ttMap: TomTomMap);
   /**
    * The display policy. `multiple` (default) keeps every history entry available to render
@@ -1214,8 +1250,8 @@ declare class PlacesState implements StateSlice {
   getEntryPlacesModule(entryId: string, markerType: PlacesMarkerType): Promise<PlacesModule>;
   /**
    * Returns the entry's place-geometries module for POI footprints and municipality outlines,
-   * created on first call. Re-applies the config when the fill style changes. Throws on an
-   * unknown entry id.
+   * created on first call. Updates only the fill style when it changes, keeping the styling
+   * applied since. Throws on an unknown entry id.
    */
   getEntryGeometriesModule(entryId: string, fillStyle?: GeometryFillStyle): Promise<GeometriesModule>;
   private _requireEntry;
@@ -1430,6 +1466,12 @@ declare class RangeState implements ShownEntriesSlice {
   private _entryMode;
   /** The state change events, listed in {@link RangeStateEvents}. */
   readonly events: StateEvents<RangeStateEvents>;
+  /** The knobs set on every entry's ReachableRangesModule, such as `fill.opacity`. Cleared on `reset`. */
+  readonly knobs: SliceKnobs;
+  /** The knobs set on every entry's GeometriesModule, the one drawing in a style of your own. Cleared on `reset`. */
+  readonly geometriesKnobs: SliceKnobs;
+  /** The knobs set on every entry's origin-pin PlacesModule. Cleared on `reset`. */
+  readonly placesKnobs: SliceKnobs;
   constructor(_ttMap: TomTomMap);
   /** Set of ranges-entry ids currently rendered on the map. */
   get shownEntryIds(): ReadonlySet<string>;
@@ -1705,12 +1747,8 @@ declare class RoutingState implements ShownEntriesSlice {
   private _planningSlots;
   private _params;
   private _entryMode;
-  /**
-   * Slice-level route colour applied to every RoutingModule on first show / re-show. Sticky
-   * across entry swaps so the rendered route always uses the most recently requested color.
-   * Set via {@link setColor}; persists for the lifetime of the slice (cleared on `reset`).
-   */
-  private _color?;
+  /** The knobs set on every entry's RoutingModule, `color` and `widthFactor` among them. Cleared on `reset`. */
+  readonly knobs: SliceKnobs;
   /**
    * The most recently `.showEntry`-ed id. Tracks "who was last brought up" so tools that
    * operate on the focused module have a single pointer to read; the authoritative shown
@@ -1754,15 +1792,6 @@ declare class RoutingState implements ShownEntriesSlice {
     showWaypoints?: boolean;
     showSummaryBubbles?: boolean;
   }): Promise<void>;
-  /** The slice-level route colour, persisted across entry swaps. Undefined if none was set. */
-  get color(): string | undefined;
-  /**
-   * Sets the slice-level route colour. It applies immediately to every shown entry's
-   * RoutingModule, and later {@link showEntry} calls apply it automatically. Pass `undefined` to
-   * clear the sticky colour. Shown modules then keep their last paint until they're re-shown,
-   * and MapLibre style restore handles the full revert.
-   */
-  setColor(color: string | undefined): void;
   /**
    * Hides the entry's routes and waypoints by clearing its module, which stays cached.
    * Does nothing if the entry is unknown or already hidden.
@@ -2046,6 +2075,12 @@ declare class TrafficAreaAnalyticsState implements ShownEntriesSlice, StateSlice
   private _entryMode;
   /** The state change events, listed in {@link TrafficAreaAnalyticsStateEvents}. */
   readonly events: StateEvents<TrafficAreaAnalyticsStateEvents>;
+  /**
+   * The knobs set on every entry's TrafficAreaAnalyticsModule, such as `displayMode` and
+   * `metrics.congestionLevel.palette`. An entry that did not fetch the `activeMetric` set shows
+   * the first metric it fetched. Cleared on `reset`.
+   */
+  readonly knobs: SliceKnobs;
   constructor(_ttMap: TomTomMap);
   get entries(): readonly TrafficAreaAnalyticsEntry[];
   get latestEntry(): TrafficAreaAnalyticsEntry | undefined;
@@ -2414,6 +2449,8 @@ declare class TrafficIncidentsState implements StateSlice {
   private readonly _clusters;
   /** The state change events, listed in {@link TrafficIncidentsStateEvents}. */
   readonly events: StateEvents<TrafficIncidentsStateEvents>;
+  /** The knobs set on every entry's TrafficIncidentDetailsModule. Cleared on `reset`. */
+  readonly knobs: SliceKnobs;
   constructor(_ttMap: TomTomMap);
   get entries(): readonly TrafficIncidentsEntry[];
   /**
@@ -3408,8 +3445,6 @@ type CustomGeometriesEntry = BaseEntry<PolygonFeature[]> & {
    * module. Lazy-initialised via CustomGeometriesState helpers.
    */
   _module?: GeometriesModule;
-  /** Fill style that the geometries module is currently configured with. */
-  _shownFillStyle?: GeometryFillStyle;
   /** True while this entry's `_module` is rendering on the map. */
   _shown?: boolean;
 };
@@ -3452,6 +3487,8 @@ declare class CustomGeometriesState implements ShownEntriesSlice, StateSlice {
   private _entryMode;
   /** The state change events, listed in {@link CustomGeometriesStateEvents}. */
   readonly events: StateEvents<CustomGeometriesStateEvents>;
+  /** The knobs set on every entry's GeometriesModule, such as `line.width`. Cleared on `reset`. */
+  readonly knobs: SliceKnobs;
   constructor(_ttMap: TomTomMap);
   get entries(): readonly CustomGeometriesEntry[];
   get latestEntry(): CustomGeometriesEntry | undefined;
@@ -3470,7 +3507,10 @@ declare class CustomGeometriesState implements ShownEntriesSlice, StateSlice {
    * suffix (`-2`, `-3`, ...). In `single` mode the new entry replaces every older one.
    */
   addEntry(features: PolygonFeature<CommonPlaceProps>[], provenance: CustomGeometriesEntry['provenance'], label: string, explicitId?: string): Promise<string>;
-  /** Initialises the entry's GeometriesModule lazily and applies the requested fill style. */
+  /**
+   * Initialises the entry's GeometriesModule lazily. Updates only the fill style when it changes,
+   * keeping the styling applied since.
+   */
   getEntryGeometriesModule(entryId: string, fillStyle?: GeometryFillStyle): Promise<GeometriesModule>;
   /**
    * Renders the entry's polygons. `mode` applies to this entry's own layer only:
@@ -3961,8 +4001,7 @@ export declare const DEFAULT_TOOLS: {
   setGeopoliticalView: ToolDefinition;
   setMapStyling: ToolDefinition;
   getMapStyleLayers: ToolDefinition;
-  setLayoutProperties: ToolDefinition;
-  setPaintProperties: ToolDefinition;
+  setLayerProperties: ToolDefinition;
   setPitchBearing: ToolDefinition;
   zoomInOrOut: ToolDefinition;
   executeMaplibreCode: ToolDefinition;