@tomtom-org/maps-sdk-plugin-agent-toolkit 0.16.0 → 0.17.0

package/README.md

@@ -1,6 +1,8 @@
 # Agent Toolkit Plugin
 
-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/).
+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 v7](https://ai-sdk.dev/).
+
+> **Public preview.** This plugin is in [Public Preview](https://docs.tomtom.com/legal/public-preview) until its 1.0.0 release.
 
 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.
 
@@ -85,7 +87,7 @@ For a full working app, see the [traffic agent example](https://docs.tomtom.com/
 
 ## Tools reference
 
-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.
+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 in it 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
 
@@ -147,11 +149,12 @@ The plugin ships a `DEFAULT_TOOLS` registry that covers search, routing, traffic
 | `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` | Run arbitrary MapLibre JS against the live `Map` instance, an escape hatch for custom layers, animations and raster overlays |
+
+`executeMaplibreCode` runs arbitrary MapLibre JS against the live `Map` instance, an escape hatch for custom layers, animations and raster overlays. Its code runs in your page with no sandbox, so it's not in `DEFAULT_TOOLS`. Add it with `tools: { executeMaplibreCode: createExecuteMaplibreCodeTool() }` only where you trust the model.
 
 > 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**. 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:
+`analyseData`, `processData`, `createTracker` and `clusterIncidents` code is **isolated in the browser, or not run**, unless you opt into `codeExecution.allowMainThreadFallback`. It runs in a Web Worker inside a sandboxed, opaque-origin iframe with no DOM or network access, terminable on timeout. The SDK lazily loads its own bundled turf and h3 for the worker, so a page without a Content Security Policy needs no configuration. A page with one must allow what the sandbox needs, which the code-generation guide lists. The environment decides where the code runs. The browser 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` tunes the browser run:
 
 ```typescript
 const agent = createMapAgent(map, {
@@ -160,7 +163,7 @@ const agent = createMapAgent(map, {
 });
 ```
 
-> **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).
+> **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 start, the code doesn't run. The tool returns an error to the model, and a call 30 seconds or more later tries again. `agent.getCodeExecutionMode()` reports where the code runs, and `codeExecution.allowMainThreadFallback: true` runs it in the page, not isolated, and does not retry the iframe. 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
 
@@ -533,13 +536,14 @@ const agent = createMapAgent(map, {
 
 ### The `MapAgentInstance`
 
-`createMapAgent` returns a `ToolLoopAgent` (usable directly with `DirectChatTransport`) with two extra properties:
+`createMapAgent` returns a `ToolLoopAgent` (usable directly with `DirectChatTransport`) with three extra properties:
 
 ```typescript
 const agent = createMapAgent(map, { model });
 
-agent.state;     // Live state — typed as CS when custom state is provided, ToolState otherwise
-agent.destroy(); // Reset all state slices (call on unmount)
+agent.state;                  // Live state — typed as CS when custom state is provided, ToolState otherwise
+agent.getCodeExecutionMode(); // Where the code-generation tools run: not-started, iframe-worker, unavailable or main-thread
+agent.destroy();              // Reset all state slices (call on unmount)
 ```
 
 ## Public API exports
@@ -552,11 +556,11 @@ For the complete, always-current list of exports, including factories, tool-regi
 
 | Type | Package | Purpose |
 |---|---|---|
-| 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@^1.0.0-rc.4` | TomTom Maps SDK (types, services, map modules), from 1.0.0-rc.4 through every 1.x release |
 | 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 |
+| Peer | `ai@^7.0.143` | Vercel AI SDK (ToolLoopAgent, tool types) |
+| Peer | `zod@^4.6.7` | Schema validation |
+| Peer | `maplibre-gl@^6.15.0` | Map rendering engine |
 | Peer | `@turf/turf@^7` | Geospatial math (distance, bbox, bearing) used by the data tools |
 | Peer | `chart.js@^4` | Chart rendering for `analyseData` outputs |
 | Peer | `h3-js@^4` | H3 hexagonal grid for `processData` coverage / hexgrid visualizations |
@@ -571,10 +575,14 @@ For the complete, always-current list of exports, including factories, tool-regi
     - [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/)
+- [AI SDK v7 documentation](https://ai-sdk.dev/)
 - [TomTom Maps SDK documentation](https://docs.tomtom.com/maps-sdk-js)
 - [Example application](https://docs.tomtom.com/maps-sdk-js/examples/map-traffic-agent-react) — full chat interface implementation
 
 ## License
 
 See `LICENSE.txt`.
+
+## Security
+
+To report a security vulnerability, follow [SECURITY.md](https://github.com/tomtom-international/maps-sdk-js/blob/main/SECURITY.md), which keeps it private.

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.302
+Version: 7.0.143
 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.13.0
+Version: 6.15.0
 License: BSD-3-Clause
 Bundled: false (peer dependency)
 Description: BSD licensed community fork of mapbox-gl, a WebGL interactive maps library
@@ -464,7 +464,7 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ---
 
 Name: zod
-Version: 4.6.5
+Version: 4.6.7
 License: MIT
 Bundled: false (peer dependency)
 Description: TypeScript-first schema declaration and validation library with static type inference

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.302
+Version: 7.0.143
 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.13.0
+Version: 6.15.0
 License: BSD-3-Clause
 Bundled: false (peer dependency)
 Description: BSD licensed community fork of mapbox-gl, a WebGL interactive maps library
@@ -454,7 +454,7 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ---
 
 Name: zod
-Version: 4.6.5
+Version: 4.6.7
 License: MIT
 Bundled: false (peer dependency)
 Description: TypeScript-first schema declaration and validation library with static type inference

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { ChartConfiguration } from "chart.js";
 import { Map as Map$1 } from "maplibre-gl";
 import { z } from "zod";
 import { GeoBias, TrafficIncidentDetailsByBBoxParams } from "@tomtom-org/maps-sdk/services";
-import { LanguageModel, ModelMessage, PrepareStepFunction, ToolLoopAgent } from "ai";
+import { LanguageModel, ModelMessage, PrepareStepFunction, ToolLoopAgent, ToolSet } from "ai";
 //#region src/engine/engine.d.ts
 /** What {@link JobEngine.register} needs to mint a {@link Job}. `run` and `onOrphaned` are owner closures. */
 type JobSpec = {
@@ -156,7 +156,7 @@ export type SandboxExecutor = {
   destroy?(): void;
 };
 /**
- * Default executor for Node/SSR (and the in-browser fallback): compiles + runs the
+ * Default executor for Node/SSR (and the browser's opt-in `allowMainThreadFallback`): compiles + runs the
  * code synchronously in the host realm. Deep-copies data inputs (see
  * {@link cloneDataArg}) so the body can't mutate live state, but provides no isolation
  * beyond the global shadowing — see {@link SHADOWED_GLOBALS}.
@@ -802,10 +802,10 @@ export declare const buildEntryKindScopeSchema: (enabled: readonly EntryDataKind
   kinds: z.ZodArray<z.ZodEnum<{
     places: "places";
     routes: "routes";
-    incidents: "incidents";
-    customGeometries: "customGeometries";
     trafficAreaAnalytics: "trafficAreaAnalytics";
+    customGeometries: "customGeometries";
     byod: "byod";
+    incidents: "incidents";
   }>>;
 }, z.core.$strip>;
 /**
@@ -1670,6 +1670,10 @@ type RoutesEntry = BaseEntry<Routes> & {
   _module?: RoutingModule;
   /** True while this entry's `_module` is rendering routes/waypoints on the map. */
   _shown?: boolean;
+  /** False once its waypoint pins are hidden, which every later show keeps until they are shown again. */
+  _waypointsShown?: boolean;
+  /** Finds the ids of the sections to ring on a route, so a monitor tick rings them on the recalculated one. */
+  _sectionFocus?: (route: Route) => readonly string[];
   /**
    * Per-entry route monitor. Lazy-created on first {@link RoutingState.startMonitoring}; reused
    * across stop/start cycles. Recalculates this route (same waypoints + params) on its interval so
@@ -1784,14 +1788,21 @@ declare class RoutingState implements ShownEntriesSlice {
    * layers don't pile up. With `entryMode === 'multiple'`, previously-shown entries stay
    * rendered, so the caller can overlay several routes at once.
    *
-   * Emits `shown-change` once the new entry is up. Pass `showWaypoints: false` to render the
-   * route lines without origin/stop/destination pins, and `showSummaryBubbles: false` to drop the
-   * per-route ETA bubbles (e.g. a monitored corridor backdrop).
+   * Emits `shown-change` once the new entry is up. Pass `showWaypoints` to show or hide the
+   * origin/stop/destination pins for this show only, over the entry's {@link setWaypointsShown}
+   * choice, and `showSummaryBubbles: false` to drop the per-route ETA bubbles (e.g. a monitored
+   * corridor backdrop).
    */
   showEntry(entryId: string, opts?: {
     showWaypoints?: boolean;
     showSummaryBubbles?: boolean;
   }): Promise<void>;
+  /**
+   * Shows or hides the origin/stop/destination pins of an entry's routes, and keeps that choice
+   * for every later {@link showEntry}. An entry not on the map only records it.
+   */
+  setWaypointsShown(entryId: string, shown: boolean): Promise<void>;
+  private _renderWaypoints;
   /**
    * Hides the entry's routes and waypoints by clearing its module, which stays cached.
    * Does nothing if the entry is unknown or already hidden.
@@ -3330,11 +3341,15 @@ export declare const isResolveError: (r: unknown) => r is ResolveError;
  */
 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 compareRoutes: (route: import("@tomtom-org/maps-sdk/core").Route, reference: import("@tomtom-org/maps-sdk/core").Route, { types }?: import("@tomtom-org/maps-sdk/core").CompareRoutesOptions) => import("@tomtom-org/maps-sdk/core").RouteComparison;
   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 getImportantRoads: (route: import("@tomtom-org/maps-sdk/core").Route, { within, minLengthInMeters }?: import("@tomtom-org/maps-sdk/core").ImportantRoadsOptions) => import("@tomtom-org/maps-sdk/core").ImportantRoad[];
   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").RouteSpan) => 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").RouteSpan) => import("@tomtom-org/maps-sdk/core").OptionalBBox;
+  readonly getSectionsWithin: (route: import("@tomtom-org/maps-sdk/core").Route, { within, types }?: import("@tomtom-org/maps-sdk/core").SectionsWithinOptions) => import("@tomtom-org/maps-sdk/core").SectionsWithin;
+  readonly isHairpin: (curve: Pick<import("@tomtom-org/maps-sdk/core").CurveSectionProps, "headingChangeInDegrees" | "radiusInMeters" | "maneuver">) => boolean;
 };
 //#endregion
 //#region src/tools/shared/routes-schema-doc.d.ts
@@ -3702,16 +3717,15 @@ type ByodSourceUrlValidation = {
   reason: string;
 };
 /**
- * An app-supplied authorization hook for BYOD source URLs. `addByodSource` runs it
- * after the built-in scheme, size and timeout policy and before the network fetch.
- * Return `{ valid: true }` to allow the fetch or `{ valid: false, reason }` to
- * block it (see {@link ByodSourceUrlValidation}). It may be sync or async, such as
- * an allowlist lookup.
+ * An app-supplied authorization hook for BYOD source URLs. `addByodSource` runs it on
+ * every `http:` or `https:` URL, before the network fetch. Return `{ valid: true }` to
+ * allow the fetch or `{ valid: false, reason }` to block it (see
+ * {@link ByodSourceUrlValidation}). It may be sync or async, such as an allowlist lookup.
  *
- * The toolkit can't enforce SSRF guarantees the host itself can't, so by default it
- * leaves the URL surface open. This hook lets a deployment add its own policy, such
- * as refusing cloud-metadata endpoints (`169.254.169.254`) or allowing only known
- * hosts, without the SDK prescribing one for everyone. Set it via the
+ * It **replaces** the built-in policy, which allows only public `https:` URLs: no
+ * `http:`, no page origin, no `localhost`-style hostname and no loopback, private,
+ * link-local or other non-public IP address. The size cap, the timeout, the omitted
+ * credentials and the refused redirects apply either way. Set it via the
  * `byod.validateSourceUrl` option on `createMapAgent`, or assign
  * `state.byod.sourceUrlValidator` directly.
  *
@@ -3737,8 +3751,8 @@ declare class BYODState implements ShownEntriesSlice, StateSlice {
   readonly events: StateEvents<BYODStateEvents>;
   /**
    * The optional authorization hook for `addByodSource` URL fetches (see
-   * {@link ByodSourceUrlValidator}). If unset, only the built-in scheme, size
-   * and timeout policy applies.
+   * {@link ByodSourceUrlValidator}). If unset, the built-in policy allows only
+   * public `https:` URLs.
    */
   sourceUrlValidator?: ByodSourceUrlValidator;
   constructor(_ttMap: TomTomMap);
@@ -3958,6 +3972,8 @@ export declare const buildSystemPrompt: ({ customPrompt, prefix, suffix }?: Buil
  *
  * createMapAgent includes it automatically unless includeDefaultTools is false.
  * For manual composition outside createMapAgent, use resolveTools().
+ * It leaves out executeMaplibreCode, which runs model-written code in your page.
+ * createExecuteMaplibreCodeTool() adds it.
  *
  * @group Agent Toolkit
  */
@@ -4004,7 +4020,6 @@ export declare const DEFAULT_TOOLS: {
   setLayerProperties: ToolDefinition;
   setPitchBearing: ToolDefinition;
   zoomInOrOut: ToolDefinition;
-  executeMaplibreCode: ToolDefinition;
   calculateBBox: ToolDefinition;
   getCurrentLocation: ToolDefinition;
   clarifyIntent: ToolDefinition;
@@ -4050,6 +4065,17 @@ export declare const TOOLS_BY_DATA_ENTRY_KIND: Record<DataEntryKind, readonly To
  */
 export declare const getDefaultToolPrompts: () => Record<ToolName, readonly string[]>;
 //#endregion
+//#region src/tools/shared/sandbox/iframe-worker-executor.d.ts
+/**
+ * A {@link SandboxExecutor} that reports where its code currently runs, for
+ * `MapAgentInstance.getCodeExecutionMode`.
+ *
+ * @ignore
+ */
+type ResolvedSandboxExecutor = SandboxExecutor & {
+  getMode(): CodeExecutionMode;
+};
+//#endregion
 //#region src/utils/types/intent-classifier.d.ts
 /**
  * Result returned by {@link classifyUserIntent}.
@@ -4219,7 +4245,7 @@ export type ToolState = {
    * `createMapAgent` re-resolves it with {@link MapAgentOptions.codeExecution}. Tools read this
    * to select where sandbox code runs.
    */
-  codeExecution: SandboxExecutor;
+  codeExecution: ResolvedSandboxExecutor;
   /**
    * The single recurrence engine. Owners (`analyses`, `trackers`) register entry-anchored jobs and keep
    * the returned handles. The engine re-runs each active job when its source entries change. It is generic
@@ -4242,11 +4268,10 @@ export type ToolState = {
 };
 /**
  * Tunes the sandbox execution of `analyseData`, `processData`, `createTracker` and
- * `clusterIncidents` code. **Where** the code runs is
- * not configurable, since the environment decides. In the browser, it is a
- * sandboxed, opaque-origin iframe + Web Worker (no DOM/storage access, no network
+ * `clusterIncidents` code. The environment decides where the code runs. In the browser,
+ * it is a sandboxed, opaque-origin iframe + Web Worker (no DOM/storage access, no network
  * via CSP, terminable on timeout). In Node / SSR, where that boundary has no
- * equivalent, it is the main thread. The options below only tune the isolated browser run.
+ * equivalent, it is the main thread. The options below only apply in the browser.
  *
  * @group Agent Toolkit
  */
@@ -4260,7 +4285,26 @@ export type CodeExecutionConfig = {
    * `self.turf` and `self.h3` (string or Promise of one).
    */
   loadWorkerLibrarySource?: () => string | Promise<string>;
+  /**
+   * Whether code runs on the page's main thread, NOT isolated, when the iframe can't start.
+   * Defaults to `false`: the code-running tools then return an error to the model, and a
+   * call 30 seconds or more later tries the iframe again. When `true`, the failure is final
+   * and later runs stay on the main thread. {@link MapAgentInstance.getCodeExecutionMode} reports which happened.
+   */
+  allowMainThreadFallback?: boolean;
 };
+/**
+ * Where `analyseData`, `processData`, `createTracker` and `clusterIncidents` code runs now:
+ * - `not-started` - Browser. The iframe starts on the first code run.
+ * - `iframe-worker` - Browser, isolated in the iframe's Web Worker.
+ * - `unavailable` - Browser. The last start failed, so code-running tools return an error.
+ *   A call 30 seconds or more later tries again.
+ * - `main-thread` - In the page, NOT isolated: Node / SSR, or a browser where the start failed with
+ *   {@link CodeExecutionConfig.allowMainThreadFallback} set. That failure does not retry the iframe.
+ *
+ * @group Agent Toolkit
+ */
+export type CodeExecutionMode = 'not-started' | 'iframe-worker' | 'unavailable' | 'main-thread';
 /**
  * Per-call options handed to a tool's `execute`, separate from its parsed input.
  *
@@ -4614,9 +4658,9 @@ export type MapAgentOptions<CS extends ToolState = ToolState> = {
    * createMapAgent(map, {
    *     model: openai('gpt-4o'),
    *     byod: {
-   *         // Refuse cloud-metadata / private addresses; allow only known hosts.
+   *         // Allow only known hosts.
    *         validateSourceUrl: (url) =>
-   *             url.hostname === 'data.example.com'
+   *             url.protocol === 'https:' && url.hostname === 'data.example.com'
    *                 ? { valid: true }
    *                 : { valid: false, reason: `Host "${url.hostname}" is not allowed.` },
    *     },
@@ -4627,16 +4671,16 @@ export type MapAgentOptions<CS extends ToolState = ToolState> = {
     /**
      * Authorises each `addByodSource` URL before it is fetched (see
      * {@link ByodSourceUrlValidator}). Return `{ valid: true }` to allow or
-     * `{ valid: false, reason }` to block (sync or async). It runs in addition
-     * to the built-in scheme / size / timeout policy.
+     * `{ valid: false, reason }` to block (sync or async). It replaces the
+     * built-in policy, which allows only public `https:` URLs.
      */
     validateSourceUrl?: ByodSourceUrlValidator;
   };
   /**
    * Tunes the data tools' sandbox execution (see {@link CodeExecutionConfig}).
-   * The environment, not this option, chooses where the code runs (off-thread iframe-worker
-   * in the browser, main thread in Node/SSR). These options only adjust the isolated
-   * browser run (`timeoutMs`, `loadWorkerLibrarySource`).
+   * The environment chooses where the code runs (off-thread iframe-worker in the browser,
+   * main thread in Node/SSR). These options adjust the browser run (`timeoutMs`,
+   * `loadWorkerLibrarySource`, `allowMainThreadFallback`).
    *
    * @experimental
    */
@@ -4662,8 +4706,11 @@ export type MapAgentOptions<CS extends ToolState = ToolState> = {
   /**
    * Custom prepareStep hook, composed with internal classification step.
    * Your `activeTools` are intersected with the classifier's selection.
+   * An `instructions` or `messages` override carries over to the later steps of the turn: build
+   * `instructions` from `initialInstructions`, and `messages` from
+   * `[...initialMessages, ...responseMessages]`, so the earlier steps' tool calls and results stay in.
    */
-  prepareStep?: PrepareStepFunction;
+  prepareStep?: PrepareStepFunction<ToolSet>;
   /**
    * Whether to include output schemas on tools.
    * Defaults to `true`. Set to `false` for providers that don't support structured tool outputs.
@@ -4725,6 +4772,11 @@ export type MapAgentOptions<CS extends ToolState = ToolState> = {
 export type MapAgentInstance<CS extends ToolState = ToolState> = ToolLoopAgent & {
   /** Live agent state (built-in + custom slices). */
   readonly state: CS;
+  /**
+   * Where the data tools' generated code runs now. In a browser, `unavailable` (code fails) and
+   * `main-thread` (code runs unisolated) both mean the iframe sandbox couldn't start.
+   */
+  getCodeExecutionMode(): CodeExecutionMode;
   /** Tears down by resetting all state slices that have a reset() method. */
   destroy(): void;
 };
@@ -4737,6 +4789,9 @@ export type MapAgentInstance<CS extends ToolState = ToolState> = ToolLoopAgent &
  * `state` and `destroy` attached. Classification runs transparently inside
  * `prepareStep`, so you need no wrapper type.
  *
+ * @remarks
+ * **[Public Preview](https://docs.tomtom.com/legal/public-preview)** until the plugin's 1.0.0 release.
+ *
  * @param map - The map to control.
  * @returns A ToolLoopAgent with state access and cleanup.
  *
@@ -4789,6 +4844,23 @@ export declare const createMapAgent: <CS extends ToolState = ToolState>(map: Tom
  */
 export declare const resolveTools: <S extends ToolState>(defaults: Record<string, ToolDefinition<S>>, overrides?: MapAgentOptions<S>["tools"]) => Record<string, ToolDefinition<S>>;
 //#endregion
+//#region src/tools/maplibre/execute-maplibre-code.d.ts
+/**
+ * Builds the executeMaplibreCode {@link ToolEntry}, which runs model-written JavaScript in your page
+ * against the live MapLibre map, with no sandbox. It is not in `DEFAULT_TOOLS`: add it through
+ * `createMapAgent`'s `tools` option only where you trust the model and every prompt and tool result it reads.
+ *
+ * ```typescript
+ * createMapAgent(map, {
+ *     model,
+ *     tools: { executeMaplibreCode: createExecuteMaplibreCodeTool() },
+ * });
+ * ```
+ *
+ * @group Agent Toolkit
+ */
+export declare const createExecuteMaplibreCodeTool: () => ToolEntry;
+//#endregion
 //#region src/tools/utilities/clarify-user-intent.d.ts
 /** A single clarification question shown to the user. Exported so a host can type its form state. */
 export declare const questionSchema: z.ZodObject<{