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

package/LICENSE.txt

@@ -14,7 +14,7 @@ You may not use the SDK or accept this Agreement if you are barred from receivin
 
 3.1. You agree to use the SDK only for purposes permitted by (a) this Agreement and (b) any applicable law, regulation or generally accepted practice or guideline in the relevant jurisdictions (including any laws regarding the export of data or software to and from the United States or other relevant countries).
 
-3.2. Other than as permitted by applicable legislation, you are prohibited from copying (except for backup purposes), modifying, adapting, (re)distributing, renting, lending, publicly presenting, decompiling, reverse engineering, disassembling or creating derivative works of the SDK or any part of it. Notwithstanding the foregoing, you may inspect the SDK as distributed to you, including any source code embedded in its source maps, solely for the purpose of debugging your Permitted Application, provided that it is not shared or redistributed. The readability of the SDK’s source code in its distribution does not constitute “Open-Source” licensing and grants you no rights under any Open Source Initiative (OSI) approved license, nor shall it be construed as a grant of rights to modify, fork or redistribute the SDK beyond those expressly granted in Clause 1 and this Clause 3.2.
+3.2. Except as permitted by applicable law or this Clause 3.2, you may not copy (except for backup purposes), modify, adapt, distribute, rent, lend, publicly present, decompile, reverse engineer, disassemble or create derivative works of the SDK. Solely for your Permitted Applications and subject to Clauses 3.3 to 3.5, you may: (a) inspect the SDK, including source code in its source maps, for debugging; (b) copy the SDK as reasonably necessary to develop, build, test and deploy them, including in internal repositories, mirrors and offline build environments used only by you, your Affiliates and your contractors; (c) modify the SDK to fix errors or security vulnerabilities, to maintain compatibility, or to prepare a Contribution under Clause 11.5, but you may not alter, circumvent or disable any functionality for authentication, metering, billing, the notices in Clause 5.2 or the data collection in Clause 4; and (d) distribute the SDK only as a bundled part of a Permitted Application, and not on a standalone basis or as a library. Modified versions remain part of the SDK, and TomTom need not support them. On termination, you must delete all copies held under (b), except copies already distributed under (d). The readability of the SDK's source code does not make it open source and grants no rights beyond those in Clause 1 and this Clause 3.2.
 
 3.3. You may not use the SDK in connection with any illegal, fraudulent, dishonest or unethical activity or behaviour, and in particular not to create or develop, or help others create or develop, a product, service or library that competes, directly or indirectly, with the SDK or the TomTom APIs.
 
@@ -22,7 +22,7 @@ You may not use the SDK or accept this Agreement if you are barred from receivin
 
 3.5. The SDK may include data or software that TomTom licenses from third parties, including open-source software. Such components are made available to you under the terms and conditions of their applicable licenses, and you shall comply with all requirements and restrictions that those third parties may require TomTom to impose on you (as may be updated and amended by TomTom from time to time). It is your responsibility to check, review and comply with those terms as they apply to the SDK licensed to you under this Agreement. The applicable third party and open-source notices are set out in the accompanying THIRD_PARTY.txt file. In the event of a conflict between this Agreement and an open-source license governing a specific dependency, that open-source license shall prevail solely with respect to that dependency.
 
-4. PRIVACY: In order to improve the TomTom Developer Portal and the SDK, TomTom may collect certain usage related information from the software, including but not limited to general SDK and product identifiers, version numbers, and information on which tools and/or services in the SDK are used and how you use them. In addition, TomTom may collect your unique identifier and associated IP address for legitimate business reasons (such as, without limitation, the processing of invoices). This data is retained for a maximum period of 120 days and is maintained in accordance with our Privacy Policy.
+4. PRIVACY: In order to improve the TomTom Developer Portal and the SDK, TomTom may collect certain usage related information from the software, including but not limited to general SDK and product identifiers, version numbers, and information on which tools and/or services in the SDK are used and how you use them. In addition, TomTom may collect your unique identifier and associated IP address for legitimate business reasons (such as, without limitation, the processing of invoices). This data is retained for a maximum period of 120 days and is maintained in accordance with our Privacy Policy (https://www.tomtom.com/privacy/).
 
 5. INTELLECTUAL PROPERTY RIGHTS AND COPYRIGHT NOTICES:
 

package/README.md

@@ -1,33 +1,35 @@
-# 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/).
+This plugin is 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. It's built on [Vercel AI SDK v6](https://ai-sdk.dev/).
 
-No UI is included — bring your own chat interface. No LLM provider is bundled — supply any AI SDK-compatible model.
+The plugin has no UI, so you bring your own chat interface. It bundles no LLM provider, so you supply any AI SDK-compatible model.
 
-> **Full documentation** — guides, architecture diagrams, and tutorials are available at [docs.tomtom.com](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/overview).
+> **Full documentation**, with guides, architecture diagrams and tutorials, lives at [docs.tomtom.com](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/overview).
 
 ## Design principles
 
-1. **Client-side only** — uses AI SDK's `DirectChatTransport` + `ToolLoopAgent`. The consumer provides the model; no server infrastructure is required.
-2. **No bundled LLM provider** — supply any AI SDK-compatible `LanguageModel`. Keeps the package provider-agnostic.
-3. **Token-efficient** — all service responses are summarized before reaching the LLM. Full GeoJSON stays in `ToolState`.
-4. **Lazy module initialization** — map modules are instantiated on first use and cached in state.
-5. **Coordinate convention** — always `[longitude, latitude]` per GeoJSON standard, enforced throughout.
-6. **Task-oriented tools** — tool boundaries follow user tasks, not SDK API surface, so a single prompt maps to a single tool call.
+1. **Client-side only** — the agent runs on AI SDK's `DirectChatTransport` and `ToolLoopAgent`. You provide the model and need no server infrastructure.
+2. **No bundled LLM provider** — you supply any AI SDK-compatible `LanguageModel`, which keeps the package provider-agnostic.
+3. **Token-efficient** — the plugin summarizes every service response before it reaches the LLM. The full GeoJSON stays in `ToolState`.
+4. **Lazy module initialization** — the plugin creates each map module on first use and caches it in state.
+5. **Coordinate convention** — the plugin always uses and enforces `[longitude, latitude]`, the GeoJSON standard's order.
+6. **Task-oriented tools** — tool boundaries follow user tasks, not the SDK's API surface, so one prompt maps to one tool call.
 
 ## 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,11 +81,11 @@ function ChatPanel() {
 }
 ```
 
-See [`examples/map-traffic-agent-react`](../../examples/map-traffic-agent-react) for a full working example.
+For a full working app, see the [traffic agent example](https://docs.tomtom.com/maps-sdk-js/examples/map-traffic-agent-react).
 
 ## Tools reference
 
-The plugin ships a `DEFAULT_TOOLS` registry covering search, routing, traffic, reachable areas, BYOD GeoJSON, base-map control, MapLibre access, and code-generated analysis. All tools are included by default and can be individually removed or replaced via the [`tools` option](#composing-tool-sets). The full per-tool reference lives in the [Agent Toolkit guide](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/tools).
+The plugin ships a `DEFAULT_TOOLS` registry that covers search, routing, traffic, reachable areas, BYOD GeoJSON, base-map control, MapLibre access and code-generated analysis. The agent gets every tool by default, and you can remove or replace each one through the [`tools` option](#composing-tool-sets). The [Agent Toolkit guide](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/tools) has the full per-tool reference.
 
 ### Location & search
 
@@ -94,30 +96,31 @@ The plugin ships a `DEFAULT_TOOLS` registry covering search, routing, traffic, r
 | `discoverPlaces` | Search for places by text query or POI category within an area |
 | `getPOICategoryCodes` | Look up TomTom POI category codes from natural-language names |
 | `getCurrentLocation` | Get the user's physical GPS location from the browser |
-| `getViewport` | Get current map center, zoom, and bounding box |
+| `getViewport` | Get the current map center, zoom and bounding box |
 
 ### Routing & reachable areas
 
 | Tool | Description |
 |---|---|
-| `setRoute` | Calculate or recalculate a route — provide `locations` (waypoints), `parameters` (route options), or both |
+| `setRoute` | Calculate or recalculate a route — provide `locations` (waypoints), `parameters` (route options) or both |
 | `addWaypointsToRoute` | Extend the current route — prepend a new origin, append a new destination, and/or insert intermediate stops |
 | `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 |
+| `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) |
+| `stopRouteMonitor` | Stop recalculating a route. The entry keeps its last data |
+| `findReachableAreas` | Calculate isochrone/isodistance polygons from one or more origins (in private preview, so 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); the entry keeps refreshing by default |
+| `getTrafficIncidents` | Fetch traffic incidents within an area (viewport, named place, route corridor, polygon, IDs). By default, the entry keeps refreshing |
 | `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 |
+
 ### Trackers
 
 | Tool | Description |
@@ -125,30 +128,30 @@ The plugin ships a `DEFAULT_TOOLS` registry covering search, routing, traffic, r
 | `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 |
+| `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` |
-| `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 |
+| `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 with `setByodLayers` |
+| `setByodLayers` | Restyle a BYOD entry by replacing its MapLibre layers (type and data-driven paint), using the entry's data `profile` |
+| `updateByodDisplay` | Show, hide or clear BYOD layers on the map |
 
-> See the [Bring your own data](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/byod) guide for ingestion patterns, visibility lifecycle, and how BYOD entries feed into `analyseData` / `processData`.
+> See the [Bring your own data](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/byod) guide for ingestion patterns, the visibility lifecycle and how BYOD entries feed into `analyseData` / `processData`.
 
 ### Unified data tools — scope-aware code generation
 
 | Tool | Description |
 |---|---|
-| `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 |
+| `analyseData` | Aggregate or chart entries (`places`, `routes`, `incidents`, `geometries`, `trafficAreaAnalytics`, `byod`) with dynamic JS. The scope the classifier emits narrows the schema each turn |
+| `processData` | Transform entries, with dynamic JS, into new `places`, `placeConnections`, `geometries`, `byod` or a `fitOnMap` camera move |
 | `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 |
+| `executeMaplibreCode` | Run arbitrary MapLibre JS against the live `Map` instance, an escape hatch for custom layers, animations and 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.
+> 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.
 
-`analyseData`, `processData`, `createTracker` and `clusterIncidents` code is **always isolated in the browser** — a Web Worker in a sandboxed, opaque-origin iframe (no DOM/network; terminable on timeout), zero-config (the SDK lazily loads its own bundled turf/h3 for the worker). Where the code runs is chosen by environment, not configured: the browser always isolates; Node / SSR always run on the main thread (where that boundary has no equivalent — defense-in-depth only). The optional `codeExecution` only tunes the isolated browser run:
+`analyseData`, `processData`, `createTracker` and `clusterIncidents` code is **always isolated in the browser**. It runs in a Web Worker inside a sandboxed, opaque-origin iframe with no DOM or network access, terminable on timeout. It needs no configuration, since the SDK lazily loads its own bundled turf and h3 for the worker. The environment, not a setting, decides where the code runs. The browser always isolates it, while Node and SSR always run it on the main thread. That boundary has no equivalent there, so the protection is defense-in-depth only. The optional `codeExecution` only tunes the isolated browser run:
 
 ```typescript
 const agent = createMapAgent(map, {
@@ -157,17 +160,17 @@ const agent = createMapAgent(map, {
 });
 ```
 
-> **Experimental** — the isolation boundary is verified by the `e2e-tests/` suite (CSP egress-block, worker termination, opaque-origin isolation), which runs in CI as a dedicated job; if the iframe can't initialise it falls back to the main thread (with a warning). `turf` / `h3` / `routeUtils` are all bundled into the worker, so that code (route-slicing included) runs fully in the browser. See the [code-generation guide](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/code-generation#data-tool-execution-isolation-experimental).
+> **Experimental.** The `e2e-tests/` suite verifies the isolation boundary (CSP egress-block, worker termination, opaque-origin isolation) and runs in CI as a dedicated job. If the iframe can't initialise, the code falls back to the main thread with a warning. The worker bundles `turf`, `h3` and `routeUtils`, so that code, route slicing included, runs fully in the browser. See the [code-generation guide](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/code-generation#data-tool-execution-isolation-experimental).
 
 ### Map display
 
 | 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) |
+| `updatePlacesDisplay` | Show, hide or restyle place entries on the map |
+| `updateRoutesDisplay` | Show, hide or swap route entries, switch the highlighted alternative or fit the camera |
 | `updateWaypointsDisplay` | Show staged waypoint markers without the route line |
-| `updateTrafficAreaAnalyticsDisplay` | Visualize traffic-area-analytics as hexgrid, heatmap, or tiles |
-| `clearMap` | Remove displayed places, routes, BYOD layers, or all features |
+| `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, by knob id, what the base map shows and how it looks. That covers 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. It also sets 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
 
@@ -208,7 +210,7 @@ const agent = createMapAgent(map, {
 
 ## Customization
 
-> See [Customizing tools](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/customizing-tools) for the full walkthrough — registry resolution, removing or replacing defaults, adding scopable custom tools, and starting from a blank slate.
+> See [Customizing tools](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/customizing-tools) for the full walkthrough. It covers registry resolution, removing or replacing defaults, adding scopable custom tools and starting from a blank slate.
 
 ### `createMapAgent` options
 
@@ -275,7 +277,7 @@ const agent = createMapAgent<MyState>(map, {
 
 ### Composing tool sets
 
-The `tools` option is merged with the built-in defaults. Use `false` to exclude a tool.
+The plugin merges the `tools` option with the built-in defaults. To exclude a tool, set it to `false`.
 
 ```typescript
 import { createMapAgent } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
@@ -305,7 +307,7 @@ createMapAgent(map, { model, includeDefaultTools: false, tools: { myTool } });
 
 ### Defining custom tools
 
-Use `satisfies` for type-safe custom tool definitions:
+To define custom tools type-safely, use `satisfies`:
 
 ```typescript
 import { type ToolEntry, createMapAgent } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
@@ -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,14 +350,20 @@ 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
 };
 ```
 
 ## State management
 
-> See the [State](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/state) guide for a per-slice deep dive, `entryMode` semantics (`multiple` vs `single`), inspecting state from your application, and adding custom slices.
+> See the [State](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/state) guide for a per-slice deep dive, `entryMode` semantics (`multiple` vs `single`), inspecting state from your application and adding custom slices.
 
-`ToolState` is organized by feature area. Each slice manages lazy-initialized map modules and an append-only history of results produced during the session. Built-in slices:
+`ToolState` holds one slice per feature area. Each slice manages lazily initialized map modules and an append-only history of the results the session produces. The built-in slices are:
 
 - `PlacesState` — place / geometry entry history
 - `RoutingState` — route history, planning waypoint slots, route parameters
@@ -362,12 +371,12 @@ type ToolEntry<S extends ToolState = ToolState> = {
 - `CustomGeometriesState` — derived polygon entries produced by `processData` (union, difference, h3-coverage, …)
 - `BYODState` — bring-your-own-data GeoJSON layer entries
 - `BaseMapState` — viewport, style, language, raw `mapLibreMap`
-- `TrafficTilesState` — real-time traffic flow + incident tile-overlay visibility
+- `TrafficTilesState` — visibility of the real-time traffic flow and incident tile overlays
 - `TrafficAreaAnalyticsState` — historical traffic-area-analytics entries and per-entry visualisation
-- `TrafficIncidentsState` — fetched incident entries, registered analyses, focused subsets, and the optional polling monitor
+- `TrafficIncidentsState` — fetched incident entries, registered analyses, focused subsets and the optional polling monitor
 - `MapPOIsState` — POI category visibility and filters
 
-Built-in slices are constructed automatically by `createMapAgent`. To add custom slices, define an interface extending `ToolState` and pass the type parameter — only the custom fields need to be provided:
+`createMapAgent` constructs the built-in slices. To add custom slices, define an interface that extends `ToolState` and pass it as the type parameter. You provide only the custom fields:
 
 ```typescript
 interface MyState extends ToolState {
@@ -387,14 +396,14 @@ agent.state.places;  // PlacesState — append-only history of place entries
 
 > See the [What the agent sends, and where](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/what-the-agent-sends) guide for the full list.
 
-- **What reaches your model provider**: every message and the system prompt; the classifier's copy (by default up to 8 earlier messages, 300 characters each; `classifier: false` turns it off); and tool results, including addresses, coordinates, the viewport, the device location, `analyseData` and `processData` output over your BYOD data, and up to 200 events per tracker.
+- **What reaches your model provider**: every message and the system prompt, plus the classifier's copy of earlier messages. By default, that copy holds up to eight messages of 300 characters each, and `classifier: false` turns it off. Tool results go too, including addresses, coordinates, the viewport, the device location, `analyseData` and `processData` output over your BYOD data, and up to 200 events per tracker.
 - **The provider is your processor**: sign a DPA with it and pick an EEA region where it offers one.
-- **What stays in memory**: `agent.state`, until the `resetState` tool or `agent.destroy()`. Nothing goes to browser storage. Chat history is yours, so erasing a user's data means clearing it and calling `agent.destroy()`.
-- **To send less**: remove tools (`getCurrentLocation: false`), turn off the classifier, or replace a tool with one that returns less.
+- **What stays in memory**: `agent.state`, until the `resetState` tool or `agent.destroy()` clears it. Nothing goes to browser storage. Chat history is yours, so erasing a user's data means clearing it and calling `agent.destroy()`.
+- **To send less**: remove tools (`getCurrentLocation: false`), turn off the classifier or replace a tool with one that returns less.
 
 ## Intent classifier
 
-The intent classifier is an optional per-turn optimization that selects which tools the LLM sees, reducing noise and improving accuracy. See the [How it works](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/how-it-works) guide for the full two-phase pipeline (classification → tool loop), prompt assembly, and observability hooks.
+The intent classifier is an optional per-turn optimization. It picks which tools the LLM sees, which cuts noise and improves accuracy. The [How it works](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/how-it-works) guide covers the full two-phase pipeline (classification, then the tool loop), prompt assembly and observability hooks.
 
 ```typescript
 import { createMapAgent, createDefaultClassifier } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
@@ -415,13 +424,13 @@ const agent = createMapAgent(map, {
 });
 ```
 
-The classifier prompt is built dynamically from each tool's `classificationPrompt` and `relatedTools` metadata, so it stays in sync automatically when tools are added or renamed.
+The plugin builds the classifier prompt on the fly from each tool's `classificationPrompt` and `relatedTools` metadata, so the prompt stays in sync when you add or rename tools.
 
 ## System prompt
 
-The built-in `BASE_SYSTEM_PROMPT` covers identity, a capability summary, scope/rejection rules, response formatting, data-confidence rules, tool-execution guidance, and session-state conventions. Per-tool mechanics (coordinate order, location-reference routing, etc.) live in the tool descriptions and the classifier prompt, not here.
+The built-in `BASE_SYSTEM_PROMPT` covers identity, a capability summary, scope/rejection rules, response formatting, data-confidence rules, tool-execution guidance and session-state conventions. Per-tool mechanics (coordinate order, location-reference routing, etc.) live in the tool descriptions and the classifier prompt, not here.
 
-`systemPrompt` accepts **either** a full replacement string **or** a section-overrides object (`Partial<Record<SystemPromptSection, string>>`) — omitted sections keep their defaults, and you supply only the section body (the heading is added for you):
+`systemPrompt` accepts **either** a full replacement string **or** a section-overrides object (`Partial<Record<SystemPromptSection, string>>`). Sections you omit keep their defaults. For a section you override, you supply only its body, and the plugin adds the heading:
 
 ```typescript
 import {
@@ -473,7 +482,7 @@ const agent = createMapAgent(map, {
 
 ### Wrapping default tools
 
-Add logging, analytics, or custom behavior around existing tools:
+To add logging, analytics or custom behavior around an existing tool, wrap it:
 
 ```typescript
 import { DEFAULT_TOOLS, createMapAgent } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
@@ -516,8 +525,7 @@ const agent = createMapAgent(map, {
     tools: {
         setMapStandardStyle: false,
         setLanguage: false,
-        setLayoutProperties: false,
-        setPaintProperties: false,
+        setLayerProperties: false,
         setMapStyling: false,
     },
 });
@@ -536,15 +544,16 @@ agent.destroy(); // Reset all state slices (call on unmount)
 
 ## Public API exports
 
-The main entry point is `createMapAgent`; `DEFAULT_TOOLS` and `BASE_SYSTEM_PROMPT` cover the most common customizations (see the examples above).
+The main entry point is `createMapAgent`. `DEFAULT_TOOLS` and `BASE_SYSTEM_PROMPT` cover the most common customizations, as the examples above show.
 
-For the complete, always-current list of exports — factories, tool-registry helpers, state introspection, the classifier, and all types — see the [API reference](https://docs.tomtom.com/maps-sdk-js/reference).
+For the complete, always-current list of exports, including factories, tool-registry helpers, state introspection, the classifier and all types, see the [API reference](https://docs.tomtom.com/maps-sdk-js/reference).
 
 ## Dependencies
 
 | 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 |
@@ -558,13 +567,13 @@ For the complete, always-current list of exports — factories, tool-registry he
     - [How it works](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/how-it-works) — two-phase pipeline (classifier + tool loop), prompt assembly, observability
     - [Tools](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/tools) — per-tool reference
     - [State](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/state) — per-slice reference, entry modes, custom slices
-    - [Customizing tools](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/customizing-tools) — add, replace, remove, or start from a blank slate
+    - [Customizing tools](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/customizing-tools) — add, replace, remove or start from a blank slate
     - [Code generation](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/code-generation) — `analyseData` / `processData` / `createTracker` / `clusterIncidents` / `executeMaplibreCode` (threat model included)
     - [Scope-aware data tools](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/scope-aware-data-tools) — per-turn scope mechanism
     - [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/THIRD_PARTY.txt

@@ -49,7 +49,7 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ---
 
 Name: ai
-Version: 6.0.300
+Version: 6.0.302
 License: Apache-2.0
 Bundled: false (peer dependency)
 Description: AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.
@@ -334,7 +334,7 @@ limitations under the License.
 ---
 
 Name: maplibre-gl
-Version: 6.12.0
+Version: 6.13.0
 License: BSD-3-Clause
 Bundled: false (peer dependency)
 Description: BSD licensed community fork of mapbox-gl, a WebGL interactive maps library

package/dist/THIRD_PARTY.txt

@@ -39,7 +39,7 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ---
 
 Name: ai
-Version: 6.0.300
+Version: 6.0.302
 License: Apache-2.0
 Bundled: false (peer dependency)
 Description: AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.
@@ -324,7 +324,7 @@ limitations under the License.
 ---
 
 Name: maplibre-gl
-Version: 6.12.0
+Version: 6.13.0
 License: BSD-3-Clause
 Bundled: false (peer dependency)
 Description: BSD licensed community fork of mapbox-gl, a WebGL interactive maps library

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;