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

package/LICENSE.txt

@@ -1,8 +1,8 @@
 TOMTOM MAPS SDK FOR JAVASCRIPT LICENSE AGREEMENT (“AGREEMENT”)
 
-Last update: September 2026
+Last update: October 2026
 
-By downloading or accessing the “TomTom Maps SDK for JavaScript” (the “SDK”), you are entering into a binding agreement with TomTom Global Content B.V. (“TomTom”). The SDK comprises all software, binaries and source code made available by TomTom for it, whether through the TomTom Developer Portal or public code repositories (e.g. GitHub). This Agreement with TomTom consists of the terms and conditions below together with the Data Processing Schedule. You should not use the SDK if you cannot agree to both.
+By downloading or accessing the “TomTom Maps SDK for JavaScript” (the “SDK”), you are entering into a binding agreement with TomTom Global Content B.V. (“TomTom”). The SDK comprises all software, binaries and source code made available by TomTom for it, whether through the TomTom Developer Portal, package registries (e.g. npm) or otherwise. The example applications that TomTom publishes in public code repositories (e.g. GitHub) are not part of the SDK: they are licensed separately, under the license distributed with them. This Agreement with TomTom consists of the terms and conditions below together with the Data Processing Schedule. You should not use the SDK if you cannot agree to both.
 
 You may not use the SDK or accept this Agreement if you are barred from receiving it under the laws of the European Union or of any other country, including the country in which you are resident or from which you use the SDK. If you accept this Agreement on behalf of your employer or another entity, you represent and warrant that you have full legal authority to bind that employer or entity. If you do not have that authority, you may not accept this Agreement or use the SDK on their behalf.
 
@@ -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, where the SDK is hosted on a public repository (e.g. GitHub, which allows forking under its terms of service), you may: (i) fork the repository solely for the purpose of submitting a pull request to TomTom, provided that such fork remains hosted within the platform and is not used as a basis for a separate or competing product or service; and (ii) download a local copy of the source code solely for the purpose of debugging your Permitted Application, provided that such copy is not shared or redistributed. The availability of the source code in a public repository does not constitute “Open-Source” licensing and grants you no rights under any Open Source Initiative (OSI) approved license. Neither that availability, nor any rights granted by the platform’s terms of service with respect to viewing or forking within the platform, shall 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. 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.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.
 
@@ -78,7 +78,7 @@ You may not use the SDK or accept this Agreement if you are barred from receivin
 
 11.4. The TomTom APIs and the SDK are provided as “Commercial Computer Software” or “restricted computer software”. Use, duplication or disclosure by the U.S. Government or a U.S. Government subcontractor is subject to the restrictions set forth in 48 C.F.R. Section 12.212 or 48 C.F.R. 227.2702, as applicable, or successor provisions. In respect of the Map API and Search API, the manufacturer is TomTom Global Content B.V.
 
-11.5. By submitting any suggestion, bug fix or code contribution (“Contribution”) to TomTom (e.g. via a GitHub Pull Request), you grant TomTom a perpetual, irrevocable, worldwide, royalty-free and non-exclusive license to use, reproduce, modify and distribute the Contribution as part of the SDK. You represent that you have the legal right to grant this license and that the Contribution does not infringe any third-party intellectual property rights.
+11.5. By submitting any suggestion, bug fix or code contribution (“Contribution”) to TomTom (e.g. via a GitHub issue or discussion), you grant TomTom a perpetual, irrevocable, worldwide, royalty-free and non-exclusive license to use, reproduce, modify and distribute the Contribution as part of the SDK. You represent that you have the legal right to grant this license and that the Contribution does not infringe any third-party intellectual property rights.
 
 THIRD PARTY SOFTWARE NOTICES
 

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,9 +120,6 @@ 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 |
-| `toggleTilesTrafficFlow` | Toggle the real-time traffic-flow tile overlay |
-| `toggleTilesTrafficIncidents` | Toggle the real-time traffic-incidents tile overlay |
-| `setMapStyling` | Set or reset how the map looks — label/icon/road sizes, exit numbers and road arrows, POI and hillshade looks, congestion colours, map colours, map presets, or a whole theme from a few colours or an image |
 
 ### Trackers
 
@@ -152,25 +151,25 @@ The plugin ships a `DEFAULT_TOOLS` registry covering search, routing, traffic, r
 
 > 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` 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** — 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:
 
 ```typescript
 const agent = createMapAgent(map, {
     model,
-    codeExecution: { timeoutMs: 5000 }, // wall-clock budget per isolated run (default 5000)
+    codeExecution: { timeoutMs: 5000 }, // wall-clock budget per isolated run (default 10000)
 });
 ```
 
-> **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 `analyseData` and `processData` (including route-slicing) run 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 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).
 
 ### 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) |
+| `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
@@ -183,15 +182,15 @@ const agent = createMapAgent(map, {
 | `getStandardMapStyles` | List available standard map style presets |
 | `setMapStandardStyle` | Switch map style (light, dark, satellite, driving, etc.) |
 | `setLanguage` | Change the language for map labels and API responses |
-| `toggleTilesPOIs` | Show/hide built-in map POI icons with optional category filtering |
+| `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 — 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
 
@@ -337,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
@@ -350,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
 };
 ```
 
@@ -386,6 +392,15 @@ agent.state.fleet;   // FleetState — custom slice
 agent.state.places;  // PlacesState — append-only history of place entries
 ```
 
+## Privacy
+
+> 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.
+- **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.
+
 ## 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.
@@ -510,9 +525,8 @@ const agent = createMapAgent(map, {
     tools: {
         setMapStandardStyle: false,
         setLanguage: false,
-        setLayoutProperties: false,
-        setPaintProperties: false,
-        toggleTilesPOIs: false,
+        setLayerProperties: false,
+        setMapStyling: false,
     },
 });
 ```
@@ -538,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 |
@@ -553,12 +568,12 @@ For the complete, always-current list of exports — factories, tool-registry he
     - [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
-    - [Code generation](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/code-generation) — `analyseData` / `processData` / `executeMaplibreCode` (threat model included)
+    - [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

@@ -334,7 +334,7 @@ limitations under the License.
 ---
 
 Name: maplibre-gl
-Version: 6.11.2
+Version: 6.12.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

@@ -324,7 +324,7 @@ limitations under the License.
 ---
 
 Name: maplibre-gl
-Version: 6.11.2
+Version: 6.12.0
 License: BSD-3-Clause
 Bundled: false (peer dependency)
 Description: BSD licensed community fork of mapbox-gl, a WebGL interactive maps library