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

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 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";
 import { z } from "zod";
+import { Map as Map$1 } from "maplibre-gl";
 import { GeoBias, TrafficIncidentDetailsByBBoxParams } from "@tomtom-org/maps-sdk/services";
 import { LanguageModel, ModelMessage, PrepareStepFunction, ToolLoopAgent, ToolSet } from "ai";
 //#region src/engine/engine.d.ts
@@ -10,7 +10,7 @@ import { LanguageModel, ModelMessage, PrepareStepFunction, ToolLoopAgent, ToolSe
 type JobSpec = {
   /** Ids of every entry this job reads. The engine re-runs the job when any of them changes. */
   affectedEntryIds: readonly string[];
-  /** The recipe, opaque to the engine and the single home of the code, compared on re-arm to detect change. */
+  /** The recipe, opaque to the engine and the single home of the code. */
   code: string;
   /** Whether the engine scans this job. A paused job (`false`) is retained but never run. */
   active: boolean;
@@ -23,7 +23,7 @@ type JobSpec = {
 interface Job {
   /** Ids of every entry this job reads (immutable, as a re-arm with different sources is a different job). */
   readonly affectedEntryIds: readonly string[];
-  /** The recipe behind this job, which a re-arm compares to decide whether to drop stale history. */
+  /** The recipe behind this job. */
   readonly code: string;
   /** Whether the engine currently scans this job. */
   readonly active: boolean;
@@ -45,6 +45,7 @@ declare class JobEngine {
   private scanning;
   private scheduled;
   private pending;
+  private generation;
   /** Registers a job and returns its handle, which the owner stores as its reference to the recurrence. */
   register(spec: JobSpec): Job;
   /** @internal — called by {@link JobHandle.unregister}. */
@@ -78,6 +79,7 @@ declare class JobHandle implements Job {
 }
 //#endregion
 //#region src/tools/shared/sandbox-code.d.ts
+/** @ignore */
 export type AnalysisOutputFormat = 'json' | 'chart';
 /**
  * Compact sandbox-code blurb shared by every code-generation tool, through
@@ -104,7 +106,11 @@ export declare const isChartConfiguration: (value: unknown) => value is ChartCon
 export declare const isPolygonFeature: <P = unknown>(value: unknown) => value is PolygonFeature<P>;
 /** @ignore */
 export declare const isPolygonFeatureArray: <P = unknown>(value: unknown) => value is PolygonFeature<P>[];
-/** Shared `describe()` text for the analyse-* `outputFormat` enum field. */
+/**
+ * Shared `describe()` text for the analyse-* `outputFormat` enum field.
+ *
+ * @ignore
+ */
 export declare const ANALYSE_OUTPUT_FORMAT_DESCRIPTION: string;
 /**
  * Builds the shared "return value" blurb for the analyse-* tools' `code` field.
@@ -115,6 +121,8 @@ export declare const ANALYSE_OUTPUT_FORMAT_DESCRIPTION: string;
  *   for the specific tool (e.g. "counts, groupings, hex bins, centroids").
  * @param chartLabelExample Optional inline code snippet illustrating a
  *   multi-line `string[]` label using the tool's domain. Omitted when empty.
+ *
+ * @ignore
  */
 export declare const buildAnalyseReturnPrompt: (jsonExamples: string, chartLabelExample?: string) => string;
 /**
@@ -136,10 +144,9 @@ export declare const sandboxedGlobalShadows: readonly ["fetch", "XMLHttpRequest"
 /** @ignore */
 export declare const WORKER_PROVIDED_PARAMS: readonly ["turf", "h3", "routeUtils", "log", "cluster"];
 /**
- * Pluggable strategy for executing sandbox code. The default
- * {@link mainThreadExecutor} compiles and runs in the host realm. An alternative
- * executor, such as the iframe-worker one, can run the same code in a locked-down
- * realm off the main thread while honouring this exact contract.
+ * Pluggable strategy for executing sandbox code, chosen by environment: in a browser
+ * the default runs the code in a locked-down iframe worker, off the main thread, and
+ * without a DOM it runs in the host realm. Every executor honours this exact contract.
  *
  * `run` MUST resolve to `{ value }` or `{ error }` and never reject. Execution
  * failures are reported as `{ error }` via {@link formatSandboxExecutionError}.
@@ -199,8 +206,9 @@ export declare const stripInjectedRedeclarations: (code: string, identifiers: re
  * Appends a `Hint:` suffix when the error matches a common pattern so the
  * model can self-correct on retry. `verb` is the human-readable action used
  * in the prefix (e.g. `"Analysis"`, `"Process"`).
+ *
+ * @ignore
  */
-/** @ignore */
 export declare const formatSandboxExecutionError: (verb: string, error: unknown) => string;
 //#endregion
 //#region src/state/events.d.ts
@@ -210,7 +218,8 @@ export declare const formatSandboxExecutionError: (verb: string, error: unknown)
  * A tiny typed event emitter that every state slice (PlacesState, RoutingState, ...) uses to notify
  * subscribers when its internals change. Its shape mirrors the SDK's `ModuleEvents` API
  * (`on(type, handler) => unsubscribe`, `off(type)`), so consumers see one consistent pattern across
- * the SDK and the agent toolkit. It plugs straight into React's `useSyncExternalStore`.
+ * the SDK and the agent toolkit. To drive React's `useSyncExternalStore`, copy what an event reports into
+ * a new snapshot: a slice can still change its `entries` array, and the entries in it, in place.
  *
  * @group Agent Toolkit
  */
@@ -243,7 +252,7 @@ declare class StateEvents<EventMap extends Record<string, unknown>> {
    * @internal
    */
   emit<K extends keyof EventMap>(type: K, payload: EventMap[K]): void;
-  /** Removes every handler for every type. A slice's `reset()` calls it to detach lingering listeners. */
+  /** Removes every handler for every type. */
   clear(): void;
 }
 //#endregion
@@ -257,7 +266,7 @@ declare class StateEvents<EventMap extends Record<string, unknown>> {
  * @ignore
  */
 type EntryAnalysis = {
-  /** Unique name within the parent entry — used as the key (re-attaching the same name replaces). */
+  /** The analysis name. With its sorted source ids it forms the analysis id (see {@link makeAnalysisId}). */
   name: string;
   timestamp: number;
   /** Optional human-readable description of what the analysis computed. */
@@ -280,8 +289,11 @@ type EntryAnalysis = {
 type AnalysisRecord = {
   /** Stable handle minted by {@link makeAnalysisId} (name + sorted source ids). */
   analysisId: string;
+  /** The analysis name. With its sorted source ids it forms `analysisId`. */
   name: string;
+  /** Optional human-readable description of what the analysis computes. */
   description?: string;
+  /** How each result's `data` should be interpreted — plain JSON or a Chart.js configuration. */
   outputFormat: AnalysisOutputFormat;
   /** Ids of every entry this analysis is attached to. The per-entry lookup key. */
   affectedEntryIds: readonly string[];
@@ -296,14 +308,16 @@ type AnalysisRecord = {
  */
 type AnalysisRegistration = Omit<AnalysisRecord, 'history'>;
 /**
- * Events emitted by {@link Analyses}. One event for "an analysis result was attached or recomputed".
+ * Events emitted by {@link Analyses}. One event for "an analysis result was attached or recomputed, or the
+ * analysis was removed".
  *
  * @ignore
  */
 type AnalysesEvents = {
   /**
-   * An analysis result landed (one-shot attach or a recompute). Carries the `analysisId` and the ids
-   * of every entry it touches — a per-entry consumer filters with `affectedEntryIds.includes(id)`.
+   * An analysis result landed (one-shot attach or a recompute), or the analysis was removed. Carries the
+   * `analysisId` and the ids of every entry it touches — a per-entry consumer filters with
+   * `affectedEntryIds.includes(id)`.
    */
   'analysis-change': {
     analysisId: string;
@@ -311,15 +325,15 @@ type AnalysesEvents = {
   };
 };
 /**
- * The session-level registry of EVERY analysis, the single source of truth that replaces the per-entry
- * `_analyses` stores. It holds one {@link AnalysisRecord} per analysis (keyed by `analysisId`), each
- * with its own bounded result history. Entries carry no analysis state. Per-entry views call
+ * The session-level registry of EVERY analysis, the single source of truth for analysis state. It
+ * holds one {@link AnalysisRecord} per analysis (keyed by `analysisId`), each with its own bounded
+ * result history. Entries carry no analysis state. Per-entry views call
  * {@link getAnalysesForEntry}. `ToolState` holds it as `state.analyses`.
  *
  * It is a pure sink of metadata and result history. The recurrence lives on the {@link JobEngine}.
- * This registry keeps each monitored analysis's {@link Job} handle in `_jobs` (keyed by `analysisId`)
- * so it can pause or resume it ({@link job}) or compare its `code` on re-arm. A one-shot analysis keeps
- * a paused job for later promotion.
+ * This registry keeps each monitored analysis's {@link Job} handle in `_jobs` (keyed by `analysisId`),
+ * so the tools layer can pause or resume it ({@link job}), or keep or retire it on re-arm. A one-shot
+ * analysis keeps a paused job for later promotion.
  *
  * @group Agent Toolkit
  */
@@ -327,7 +341,7 @@ declare class Analyses {
   private readonly _records;
   /** analysisId → the {@link Job} backing it (one-shot = paused). The reference linking record to engine. */
   private readonly _jobs;
-  /** The {@link AnalysesEvents} emitter, fired whenever a result is attached or recomputed. */
+  /** The {@link AnalysesEvents} emitter, fired whenever a result is attached or recomputed, or a record removed. */
   readonly events: StateEvents<AnalysesEvents>;
   /**
    * Inserts or replaces a record's metadata, NOT its result (use {@link attachResult}) or its recipe,
@@ -349,9 +363,8 @@ declare class Analyses {
    */
   attachResult(analysisId: string, result: EntryAnalysis): void;
   /**
-   * Returns the latest result of every analysis attached to `entryId`, in registration order,
-   * replacing the old per-entry `_analyses.results`. It scans records linearly, fine at session scale
-   * (one record per distinct analyseData name+sources, plus one per clustered incidents entry).
+   * Returns the latest result of every analysis attached to `entryId`, in registration order. It scans
+   * records linearly, fine at session scale (one record per distinct analyseData name+sources).
    */
   getAnalysesForEntry(entryId: string): readonly EntryAnalysis[];
   /**
@@ -367,21 +380,24 @@ declare class Analyses {
   get(analysisId: string): AnalysisRecord | undefined;
   /** Whether the analysis is currently recomputed on source change (its job exists and is active). */
   isMonitored(analysisId: string): boolean;
-  /** Removes an analysis, tearing down its job and dropping the record and handle. */
+  /** Removes an analysis, tearing down its job and dropping the record and handle. Emits `analysis-change`. */
   remove(analysisId: string): void;
   /**
-   * Removes every record sharing a `name`, across all source entries, as the old per-entry
-   * `unregister(name)` dropped a named analysis wherever it was attached.
+   * Removes every record sharing a `name`, across all source entries, so a named analysis is dropped
+   * wherever it is attached.
    */
   removeByName(name: string): void;
-  /** Drops every record and job handle. `destroyState` calls it automatically (duck-typed `reset`). */
+  /**
+   * Drops every record and job handle, emitting `analysis-change` for each dropped record.
+   * `destroyState` calls it automatically (duck-typed `reset`).
+   */
   reset(): void;
 }
 //#endregion
 //#region src/state/byod/analysis.d.ts
 /**
  * A single analysis result attached to a BYOD entry. Alias of the shared {@link EntryAnalysis} —
- * every entry kind uses the same result shape; kept as a named export for back-compat.
+ * every entry kind uses the same result shape.
  *
  * @group Agent Toolkit
  *
@@ -696,169 +712,379 @@ type BYODEntry = BaseEntry<FeatureCollection$1> & {
   _shown?: boolean;
 };
 //#endregion
-//#region src/state/base-map/state.d.ts
+//#region src/state/state.d.ts
 /**
- * State for base map display: style, language, viewport and layers.
- *
- * It exposes the TomTomMap and MapLibre instances directly, alongside
- * lazy-initialized BaseMapModule, StylingFoundationsModule and TerrainModule.
+ * The per-slice display policy. With `multiple` (default), several history entries can be on the
+ * map at once. With `single`, only the most recent one stays. Switching from `multiple` to
+ * `single` automatically drops every entry except the latest and clears their modules, so
+ * the map matches the new policy immediately.
  *
  * @group Agent Toolkit
  */
-declare class BaseMapState implements StateSlice {
-  readonly ttMap: TomTomMap;
-  private _baseMapModule?;
-  private _stylingFoundationsModule?;
-  private _terrainModule?;
-  constructor(ttMap: TomTomMap);
-  get mapLibreMap(): Map$1;
-  getBaseMapModule(): Promise<BaseMapModule>;
-  getStylingFoundationsModule(): Promise<StylingFoundationsModule>;
-  getTerrainModule(): Promise<TerrainModule>;
-  get terrainModule(): TerrainModule | undefined;
-  reset(): void;
-}
-//#endregion
-//#region src/state/slice-knobs.d.ts
+type EntryMode = 'single' | 'multiple';
 /**
- * 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.
+ * A state slice that owns a history of entries and can be set to `single` or `multiple`
+ * mode. Every {@link ToolState} slice with `setEntryMode` implements this shape, which lets
+ * callers (the `setEntryMode` tool, `createMapAgent`'s `dataEntries` option, …) handle the
+ * whole family uniformly without listing slice names.
  *
  * @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;
+interface EntryModeSlice {
+  readonly entryMode: EntryMode;
+  readonly entries: readonly {
+    readonly id: string;
+  }[];
+  setEntryMode(mode: EntryMode): Promise<void>;
 }
-//#endregion
-//#region src/tools/shared/agent-headers.d.ts
 /**
- * @module agent-toolkit-tools
+ * The data-entry kind names that `dataEntries` on `createMapAgent` uses. They extend the
+ * analyse/process input kinds (`EntryDataKind`) with `ranges`, which has its own
+ * entry-mode-supporting slice but is not a top-level input kind for those tools.
+ *
+ * The kind names are LLM-facing (`routes`, `incidents`) instead of slice names (`routing`,
+ * `trafficIncidents`). The slice mapping is internal (see {@link DATA_ENTRY_KIND_TO_SLICE}).
+ *
+ * @group Agent Toolkit
  */
-export declare const AGENT_TOOLKIT_ID = "AgentToolkit";
+type DataEntryKind = EntryDataKind | 'ranges';
 /**
- * The `tomtom-user-agent` value identifying agent-toolkit traffic. Shared by both paths that carry
- * it — {@link withAgentToolkitHeaders} on service calls, `createMapAgent` on the map — so the two
- * cannot drift into separate analytics rows.
+ * Per-kind configuration accepted by `createMapAgent`'s `dataEntries` option.
  *
- * @ignore
+ * @group Agent Toolkit
  */
-export declare const AGENT_TOOLKIT_USER_AGENT: string;
+type DataEntryConfig = {
+  /**
+   * When `false`, the kind is removed from the agent's data tools:
+   * - The kind disappears from the `analyseData` and `processData` scope and input fields.
+   * - Its display and fetch tools are dropped from the registry (see {@link TOOLS_BY_DATA_ENTRY_KIND}).
+   *   Tools spanning kinds, such as `recallState` and `setMapStyling`, stay.
+   *
+   * Defaults to `true`.
+   */
+  enabled?: boolean;
+  /**
+   * The initial entry-display policy for the underlying slice. `single` keeps only the latest
+   * entry on the map and hides the others. `multiple` (default) lets several coexist.
+   */
+  entryMode?: EntryMode;
+};
 /**
- * Tags an SDK service call as coming from agent-toolkit, via the SDK's own supported per-call
- * `tomtom-user-agent` override (see `generateTomTomHeaders`, `core/src/util/headers.ts`) — reuses
- * an existing, already-allow-listed header rather than adding a new one.
+ * Maps each {@link DataEntryKind} (LLM-facing name) to the {@link ToolState} slice key that
+ * owns its entries. `createMapAgent` uses it to apply `entryMode` from
+ * `dataEntries[kind].entryMode` to the right slice.
  *
- * @ignore
+ * @group Agent Toolkit
  */
-export declare const withAgentToolkitHeaders: <P extends object>(params: P) => P;
-//#endregion
-//#region src/tools/shared/entry-kinds.d.ts
+export declare const DATA_ENTRY_KIND_TO_SLICE: {
+  readonly places: "places";
+  readonly routes: "routing";
+  readonly incidents: "trafficIncidents";
+  readonly customGeometries: "customGeometries";
+  readonly trafficAreaAnalytics: "trafficAreaAnalytics";
+  readonly byod: "byod";
+  readonly ranges: "ranges";
+};
 /**
- * Canonical ordering for {@link EntryDataKind}. Used wherever per-kind doc fragments or
- * field lists are concatenated — keeps the layout stable regardless of the order kinds
- * appear in a scope or enabled-kinds list.
+ * The compile-time union of {@link ToolState} keys whose slice supports {@link EntryMode}.
+ * Names match the {@link ToolState} keys exactly, such as `routing` (not `routes`) and
+ * `customGeometries` (not `geometries`), so the slice name in the tool API never drifts
+ * from the property on `state`.
  *
- * @ignore
+ * When a new slice implements `setEntryMode`, the union picks up its key, and the runtime
+ * list {@link ENTRY_MODE_SLICE_NAMES} fails to type-check until the key is added there too.
+ *
+ * @group Agent Toolkit
  */
-export declare const ALL_ENTRY_DATA_KINDS: readonly ["places", "routes", "incidents", "customGeometries", "trafficAreaAnalytics", "byod"];
+type EntryModeSliceName = { [K in keyof ToolState]: ToolState[K] extends EntryModeSlice ? K : never; }[keyof ToolState];
 /**
- * Per-kind scope envelope. The classifier emits one of these in `toolScopes.<toolName>`
- * to narrow which kinds the tool's per-turn input schema and code-doc mention.
+ * The runtime list of slice names that support entry mode. Its `satisfies` clause makes
+ * drift a compile error. When a new {@link ToolState} slice gains `setEntryMode`, the
+ * package won't build until this constant is updated.
  *
- * @ignore
+ * @group Agent Toolkit
  */
-export type EntryKindScope = {
-  kinds: readonly EntryDataKind[];
-};
+export declare const ENTRY_MODE_SLICE_NAMES: readonly EntryModeSliceName[];
 /**
- * Build a zod scope schema that only accepts kinds within the supplied enabled set.
- * Mirrors the per-tool scope guard so a classifier picking a disabled kind fails-open
- * (the malformed scope is dropped, full surface stays in place).
+ * A state slice that owns a set of "entries", each of which can be hidden individually by id, and
+ * exposes the shown set. Helpers that hide previously-shown entries before rendering a new one
+ * consume it (see `hidePreviousShownEntries`).
  *
- * @ignore
+ * {@link PlacesState} doesn't implement it, because it uses a wider per-entry marker-type
+ * model (`removeShownEntries(ids)` instead of `hideEntry(id)`).
+ *
+ * @group Agent Toolkit
  */
-export declare const buildEntryKindScopeSchema: (enabled: readonly EntryDataKind[]) => z.ZodObject<{
-  kinds: z.ZodArray<z.ZodEnum<{
-    places: "places";
-    routes: "routes";
-    trafficAreaAnalytics: "trafficAreaAnalytics";
-    customGeometries: "customGeometries";
-    byod: "byod";
-    incidents: "incidents";
-  }>>;
-}, z.core.$strip>;
+interface ShownEntriesSlice extends StateSlice {
+  readonly entryMode: EntryMode;
+  readonly shownEntryIds: ReadonlySet<string>;
+  hideEntry(entryId: string): Promise<void>;
+}
+//#endregion
+//#region src/state/byod/state.d.ts
 /**
- * `extra` fragment supplied by the tool — appended to each generated input-field
- * description so callers see tool-specific hints alongside the shared metadata.
+ * Events fired by {@link BYODState}. Subscribe via `state.byod.events.on(type, handler)`.
  *
- * @ignore
+ * @group Agent Toolkit
  */
-type FieldBuildOptions = {
-  verb: 'analyse' | 'process';
-  requiredHint: string;
+type BYODStateEvents = {
+  /**
+   * An entry was added or removed, its layers were replaced, entries were dropped by `single` mode, or
+   * `reset()` cleared the history. `entries` is the full snapshot after the change, and `changedIds`
+   * lists the ids of the entries this change added, changed in place, or removed.
+   */
+  'entries-change': {
+    entries: readonly BYODEntry[];
+    changedIds: readonly string[];
+  };
+  /** The set of entries rendered on the map changed. */
+  'shown-change': ReadonlySet<string>;
+  /** The display policy switched between `single` and `multiple`. */
+  'mode-change': EntryMode;
 };
 /**
- * Per-kind metadata. One row per {@link EntryDataKind}. Owns:
- * - field name + label used in schemas and "at least one of" messages;
- * - the factory that produces the `*EntryIDs` zod field for a given tool verb;
- * - the one-line sandbox-doc fragment ("• `placesByEntry` — object keyed by entry id …");
- * - the deep schema-doc fragment (only included when scope commits to this kind);
- * - which recall tool the LLM should call to list available ids.
+ * Options accepted by {@link BYODState.addEntry}.
  *
- * @ignore
+ * @group Agent Toolkit
  */
-export type EntryKindMeta = {
-  fieldName: string;
-  fieldLabel: string;
-  buildField: (options: FieldBuildOptions) => z.ZodTypeAny;
-  sandboxDoc: string;
-  schemaDoc: string;
-  recallTool: string;
+type AddBYODEntryOptions = {
+  /**
+   * Explicit MapLibre layer specs, never derived automatically. You pass them here,
+   * or the agent sets them via `setByodLayers`. Until then the entry renders nothing.
+   * Either way they are only stored, and {@link BYODState.showEntry} renders them.
+   */
+  layers?: CustomGeoJSONLayerSpec[];
+  /** Provenance for the data. Defaults to `{ kind: 'integrator' }`. */
+  source?: BYODSource;
+  /**
+   * Semantic entry id. Auto-suffixed (`-2`, `-3`, …) on collision. Defaults
+   * to `byod-N`.
+   */
+  explicitId?: string;
 };
 /**
- * Single source of truth for the per-kind input vocabulary. Both `analyseData` and
- * `processData` read this map to assemble their input schemas and doc fragments.
+ * The verdict a {@link ByodSourceUrlValidator} returns. `{ valid: true }` explicitly allows
+ * the fetch, and `{ valid: false, reason }` blocks it and surfaces the `reason` to the model
+ * as the tool error.
  *
- * @ignore
+ * @group Agent Toolkit
  */
-export declare const ENTRY_KIND_META: Record<EntryDataKind, EntryKindMeta>;
+type ByodSourceUrlValidation = {
+  valid: true;
+} | {
+  valid: false;
+  reason: string;
+};
 /**
- * Resolve the set of kinds active for a single per-turn build: the intersection of
- * the agent's enabled kinds and the classifier's per-turn scope. `scope === undefined`
- * means "no per-turn narrowing — every enabled kind stays in scope".
+ * 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.
  *
- * @ignore
- */
-export declare const resolveActiveKinds: (enabled: readonly EntryDataKind[], scope: EntryKindScope | undefined) => readonly EntryDataKind[];
-/**
- * Predicate form of {@link resolveActiveKinds} for a single kind. Used when generating
- * tool-specific fields (e.g. analyseData's `monitor`) that should only appear when
- * `incidents` is in the active set.
+ * 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.
  *
- * @ignore
+ * @group Agent Toolkit
  */
-export declare const isKindActive: (enabled: readonly EntryDataKind[], scope: EntryKindScope | undefined, kind: EntryDataKind) => boolean;
+type ByodSourceUrlValidator = (url: URL) => ByodSourceUrlValidation | Promise<ByodSourceUrlValidation>;
+/**
+ * The state slice for BYOD (bring-your-own-data) GeoJSON layers, the customer-owned
+ * data that doesn't fit places, routes, ranges or custom geometries. Each entry
+ * wraps a {@link CustomGeoJSONModule} so the agent can render, query, and pipe it
+ * through analyseData or processData.
+ *
+ * As in {@link CustomGeometriesState}, every entry owns its own module, initialised
+ * lazily on first show.
+ *
+ * @group Agent Toolkit
+ */
+declare class BYODState implements ShownEntriesSlice {
+  private readonly _ttMap;
+  private _entries;
+  private readonly _history;
+  private _entryMode;
+  private _addedCount;
+  private readonly _creatingModules;
+  /** The state change events, listed in {@link BYODStateEvents}. */
+  readonly events: StateEvents<BYODStateEvents>;
+  /**
+   * The optional authorization hook for `addByodSource` URL fetches (see
+   * {@link ByodSourceUrlValidator}). If unset, the built-in policy allows only
+   * public `https:` URLs.
+   */
+  sourceUrlValidator?: ByodSourceUrlValidator;
+  constructor(_ttMap: TomTomMap);
+  get entries(): readonly BYODEntry[];
+  get latestEntry(): BYODEntry | undefined;
+  /** Set of BYOD entry ids currently rendered on the map. */
+  get shownEntryIds(): ReadonlySet<string>;
+  get entryMode(): EntryMode;
+  setEntryMode(mode: EntryMode): Promise<void>;
+  findById(entryId: string): BYODEntry | undefined;
+  /**
+   * Appends a new BYOD entry and returns its assigned id. In `single` mode the new entry
+   * replaces every older one. It hides and drops them before pushing the new entry, so the
+   * caller never sees it rendered on top of a still-visible old one.
+   */
+  addEntry(data: FeatureCollection$1, label: string, options?: AddBYODEntryOptions): Promise<string>;
+  /**
+   * Replaces the MapLibre layer specs an entry renders under. If the entry already owns a
+   * module because it was shown at least once, the module's `applyConfig` runtime layer diff
+   * pushes the new specs live, without tear-down or flicker. Otherwise the specs are stored
+   * and the next {@link showEntry} picks them up. Throws on an unknown id, and keeps the previous
+   * specs when the module rejects the new ones.
+   */
+  setEntryLayers(entryId: string, layers: CustomGeoJSONLayerSpec[]): void;
+  /**
+   * Initialises the entry's CustomGeoJSONModule lazily. The module has a single
+   * source named `data`, configured with this entry's `layers`. To swap layers
+   * afterwards, call {@link setEntryLayers}, which pushes the new specs into this
+   * module via `applyConfig` instead of recreating it. Rejects for an entry with no layers yet, such as
+   * one `addByodSource` just added, since the module needs at least one.
+   */
+  getEntryModule(entryId: string): Promise<CustomGeoJSONModule>;
+  private _entryModule;
+  /** Renders the entry on the map. */
+  showEntry(entryId: string): Promise<void>;
+  private _hideOthersUnderSingleMode;
+  hideEntry(entryId: string): Promise<void>;
+  private _hideEntry;
+  /** Drops an entry from history and clears its module. Does nothing for an unknown id. */
+  removeEntry(entryId: string): Promise<void>;
+  private _requireEntry;
+  /**
+   * Hides every BYOD layer on the map but keeps the history. Implements
+   * {@link ClearableMapSlice}.
+   */
+  clearShown(): Promise<void>;
+  reset(): void;
+}
+//#endregion
+//#region src/state/custom-geometries/analysis.d.ts
+/**
+ * A single analysis result attached to a custom-geometries entry. Alias of the shared
+ * {@link EntryAnalysis} — every entry kind uses the same result shape.
+ *
+ * @group Agent Toolkit
+ *
+ * @ignore
+ */
+type CustomGeometriesAnalysis = EntryAnalysis;
+//#endregion
+//#region src/tools/shared/agent-headers.d.ts
+/**
+ * @module agent-toolkit-tools
+ */
+/** @ignore */
+export declare const AGENT_TOOLKIT_ID = "AgentToolkit";
+/**
+ * The `tomtom-user-agent` value identifying agent-toolkit traffic. Shared by both paths that carry
+ * it — {@link withAgentToolkitHeaders} on service calls, `createMapAgent` on the map — so the two
+ * cannot drift into separate analytics rows.
+ *
+ * @ignore
+ */
+export declare const AGENT_TOOLKIT_USER_AGENT: string;
+/**
+ * Tags an SDK service call as coming from agent-toolkit, via the SDK's own supported per-call
+ * `tomtom-user-agent` override (see `generateTomTomHeaders`, `core/src/util/headers.ts`) — reuses
+ * an existing, already-allow-listed header rather than adding a new one.
+ *
+ * @ignore
+ */
+export declare const withAgentToolkitHeaders: <P extends object>(parameters: P) => P;
+//#endregion
+//#region src/tools/shared/entry-kinds.d.ts
+/**
+ * Canonical ordering for {@link EntryDataKind}. Used wherever per-kind doc fragments or
+ * field lists are concatenated — keeps the layout stable regardless of the order kinds
+ * appear in a scope or enabled-kinds list.
+ *
+ * @ignore
+ */
+export declare const ALL_ENTRY_DATA_KINDS: readonly ["places", "routes", "incidents", "customGeometries", "trafficAreaAnalytics", "byod"];
+/**
+ * Per-kind scope envelope. The classifier emits one of these in `toolScopes.<toolName>`
+ * to narrow which kinds the tool's per-turn input schema and code-doc mention.
+ *
+ * @ignore
+ */
+export type EntryKindScope = {
+  kinds: readonly EntryDataKind[];
+};
+/**
+ * Build a zod scope schema that only accepts kinds within the supplied enabled set.
+ * Mirrors the per-tool scope guard so a classifier picking a disabled kind fails-open
+ * (the malformed scope is dropped, full surface stays in place).
+ *
+ * @ignore
+ */
+export declare const buildEntryKindScopeSchema: (enabled: readonly EntryDataKind[]) => z.ZodObject<{
+  kinds: z.ZodArray<z.ZodEnum<{
+    places: "places";
+    routes: "routes";
+    trafficAreaAnalytics: "trafficAreaAnalytics";
+    customGeometries: "customGeometries";
+    byod: "byod";
+    incidents: "incidents";
+  }>>;
+}, z.core.$strip>;
+/**
+ * What the calling tool supplies to word each generated input-field description: its verb and
+ * its "at least one of" hint.
+ *
+ * @ignore
+ */
+type FieldBuildOptions = {
+  verb: 'analyse' | 'process';
+  requiredHint: string;
+};
+/**
+ * Per-kind metadata. One row per {@link EntryDataKind}. Owns:
+ * - field name + label used in schemas and "at least one of" messages;
+ * - the factory that produces the `*EntryIDs` zod field for a given tool verb;
+ * - the one-line sandbox-doc fragment ("• `placesByEntry` — object keyed by entry id …");
+ * - the deep schema-doc fragment (only included when scope commits to this kind);
+ * - which recall tool the LLM should call to list available ids, and the kind's name in a missing-id error.
+ *
+ * @ignore
+ */
+export type EntryKindMeta = {
+  fieldName: string;
+  fieldLabel: string;
+  buildField: (options: FieldBuildOptions) => z.ZodTypeAny;
+  sandboxDoc: string;
+  schemaDoc: string;
+  recallTool: string;
+  entryLabel: string;
+};
+/**
+ * Single source of truth for the per-kind input vocabulary. Both `analyseData` and
+ * `processData` read this map to assemble their input schemas and doc fragments.
+ *
+ * @ignore
+ */
+export declare const ENTRY_KIND_META: Record<EntryDataKind, EntryKindMeta>;
+/**
+ * Resolve the set of kinds active for a single per-turn build: the intersection of
+ * the agent's enabled kinds and the classifier's per-turn scope. `scope === undefined`
+ * means "no per-turn narrowing — every enabled kind stays in scope".
+ *
+ * @ignore
+ */
+export declare const resolveActiveKinds: (enabled: readonly EntryDataKind[], scope: EntryKindScope | undefined) => readonly EntryDataKind[];
+/**
+ * Predicate form of {@link resolveActiveKinds} for a single kind. Used when generating
+ * tool-specific fields (e.g. analyseData's `monitor`) that should only appear when
+ * `incidents` is in the active set.
+ *
+ * @ignore
+ */
+export declare const isKindActive: (enabled: readonly EntryDataKind[], scope: EntryKindScope | undefined, kind: EntryDataKind) => boolean;
 /**
  * Slash-joined list of scoped `*EntryIDs` field labels — used in "At least one of `A` / `B`
  * must be set." messages and in per-field hints. Order follows {@link ALL_ENTRY_DATA_KINDS}.
@@ -875,8 +1101,7 @@ export declare const buildEntryFieldList: (active: readonly EntryDataKind[]) =>
 export declare const buildEntryKindSandboxDocs: (active: readonly EntryDataKind[]) => string;
 /**
  * Join the per-kind deep schema-doc fragments in canonical order for the supplied active
- * set. Empty when no active kind has a schema doc (only places / routes / customGeometries
- * carry one today).
+ * set. Empty when no active kind has a schema doc (`byod` carries none).
  *
  * @ignore
  */
@@ -895,8 +1120,7 @@ export declare const buildEntryIdFields: (active: readonly EntryDataKind[], opti
  * "at least one of …" refine so both tools agree on what counts as "input present".
  *
  * `geometriesEntryIDs` carries `GeometriesId[]`; the rest carry `string[]`. We treat
- * either as "present" when the array has length, which is what the existing inline
- * refines did.
+ * either as "present" when the array has length.
  *
  * @ignore
  */
@@ -947,6 +1171,8 @@ export declare const applyFitOnMap: (state: ToolState, fit: FitOnMapInput) => z.
  * from drowning the area. Without it, "De Pijp" and "Westminster" geocode to Streets at rank 0.
  * Excludes `Country` (too coarse) and `PostalCodeArea` (homonym noise, such as "A10" matching a
  * Kazakh postcode).
+ *
+ * @ignore
  */
 export declare const AREA_GEOGRAPHY_TYPES: GeographyType[];
 /**
@@ -954,11 +1180,13 @@ export declare const AREA_GEOGRAPHY_TYPES: GeographyType[];
  * `bias` (the map centre). Because `geographyTypes` filters to areas, every result carries a
  * `boundingBox`. Callers choose among the candidates, for example the one nearest the current view.
  * A centre bias is used rather than a hard viewport-bbox filter, so out-of-view areas still resolve.
+ *
+ * @ignore
  */
-export declare const geocodeAreas: (query: string, opts?: {
+export declare const geocodeAreas: (query: string, options?: {
   bias?: Position;
   limit?: number;
-}, execOptions?: ToolExecuteOptions) => Promise<Place[]>;
+}, executeOptions?: ToolExecuteOptions) => Promise<Place[]>;
 //#endregion
 //#region src/tools/shared/geometries-id.d.ts
 /**
@@ -966,7 +1194,7 @@ export declare const geocodeAreas: (query: string, opts?: {
  *
  * @group Agent Toolkit
  */
-export type GeometriesIdKind = 'place' | 'places' | 'ranges' | 'customGeometries';
+export type GeometriesIdKind = GeometriesId['kind'];
 /**
  * Tagged geometries id. The Zod schema is exposed so tools can plug it
  * straight into their input shape (`z.array(geometriesIdSchema).min(1)`),
@@ -1047,39 +1275,174 @@ export declare const GEOMETRIES_SOURCE_IDS_DESC = "Tagged input ids that contrib
 /** @ignore */
 export declare const GEOMETRIES_SCHEMA_DOC: string;
 //#endregion
-//#region src/state/custom-geometries/analysis.d.ts
+//#region src/state/base-map/state.d.ts
 /**
- * A single analysis result attached to a custom-geometries entry. Alias of the shared
- * {@link EntryAnalysis} — every entry kind uses the same result shape; kept as a named export for
- * back-compat.
+ * State for the base map.
+ *
+ * It exposes the TomTomMap and MapLibre instances directly, alongside
+ * lazy-initialized BaseMapModule, StylingFoundationsModule and TerrainModule.
  *
  * @group Agent Toolkit
+ */
+declare class BaseMapState implements StateSlice {
+  readonly ttMap: TomTomMap;
+  private _terrainModule?;
+  constructor(ttMap: TomTomMap);
+  get mapLibreMap(): Map$1;
+  getBaseMapModule(): Promise<BaseMapModule>;
+  getStylingFoundationsModule(): Promise<StylingFoundationsModule>;
+  getTerrainModule(): Promise<TerrainModule>;
+  get terrainModule(): TerrainModule | undefined;
+  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.
  *
- * @ignore
+ * @group Agent Toolkit
  */
-type CustomGeometriesAnalysis = EntryAnalysis;
+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;
+}
 //#endregion
-//#region src/state/digest.d.ts
+//#region src/state/custom-geometries/state.d.ts
 /**
- * A compact, diffable snapshot of the user-visible parts of `ToolState`. Every field serialises to
- * JSON and stays stable for `===` comparison while the underlying state is unchanged.
+ * Events fired by {@link CustomGeometriesState}. Subscribe via
+ * `state.customGeometries.events.on(type, handler)`.
  *
  * @group Agent Toolkit
  */
-type StateDigest = {
-  places: {
-    /** Entry ids currently rendered as individual pins, sorted ascending. */
-    shownAsPin: string[];
-    /** Entry ids currently rendered as base-map POIs, sorted ascending. */
-    shownAsBaseMap: string[];
-    /** The slice's display policy, `multiple` (default) or `single`. */
-    entryMode: EntryMode;
+type CustomGeometriesStateEvents = {
+  /**
+   * An entry was added or removed, entries were dropped by `single` mode, or `reset()` cleared the
+   * history. `entries` is the full snapshot after the change, and `changedIds` lists the ids of the
+   * entries this change added or removed.
+   */
+  'entries-change': {
+    entries: readonly CustomGeometriesEntry[];
+    changedIds: readonly string[];
   };
-  routes: {
-    /** Routes-entry ids currently drawn on the map, sorted ascending. */
-    shown: string[];
-    /** The slice's display policy, `multiple` (default) or `single`. */
-    entryMode: EntryMode;
+  /** The set of entries rendered on the map changed. */
+  'shown-change': ReadonlySet<string>;
+  /** The display policy switched between `single` and `multiple`. */
+  'mode-change': EntryMode;
+};
+/**
+ * The state for derived or custom geometries, the output of `processData` and any future
+ * polygon-producing tool whose result doesn't belong to a place or a reachable-range entry.
+ *
+ * As in {@link RangeState}, each entry owns a dedicated GeometriesModule, initialised lazily
+ * on first show. Provenance metadata captures the input sources (tagged ids) and the
+ * operation that produced the polygons.
+ *
+ * @group Agent Toolkit
+ */
+declare class CustomGeometriesState implements ShownEntriesSlice {
+  private readonly _ttMap;
+  private _entries;
+  private readonly _history;
+  private _entryMode;
+  private _addedCount;
+  private readonly _creatingModules;
+  /** 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;
+  /** Set of custom-geometries entry ids currently rendered on the map. */
+  get shownEntryIds(): ReadonlySet<string>;
+  /**
+   * The display policy. `multiple` (default) lets several derived-geometry entries render
+   * side by side. `single` allows at most one entry on the map, and switching to it hides
+   * older entries.
+   */
+  get entryMode(): EntryMode;
+  setEntryMode(mode: EntryMode): Promise<void>;
+  findById(entryId: string): CustomGeometriesEntry | undefined;
+  /**
+   * Appends a new entry and returns its assigned id. If `explicitId` collides, the slice adds a
+   * 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, in `fillStyle` or as an outline. After that, a
+   * passed `fillStyle` updates only the fill style, keeping the styling applied since.
+   */
+  getEntryGeometriesModule(entryId: string, fillStyle?: GeometryFillStyle): Promise<GeometriesModule>;
+  private _geometriesModule;
+  /**
+   * Renders the entry's polygons. `mode` applies to this entry's own layer only:
+   * - `'replace'` (default) shows exactly `entry.data` and clears whatever the
+   *   entry's module rendered before.
+   * - `'add'` merges `entry.data` with the polygons shown on this entry's layer,
+   *   deduped by feature id. It matters mostly when re-showing the same entry.
+   *
+   * `fillStyle` restyles the entry's module; omit it to keep its current style, an outline at first.
+   *
+   * Other entries are handled separately. With `entryMode === 'single'`, other shown
+   * entries are hidden first. Otherwise the caller uses `hideEntry` or the tools'
+   * `hidePreviousEntries` option.
+   */
+  showEntry(entryId: string, fillStyle?: GeometryFillStyle, mode?: 'add' | 'replace'): Promise<void>;
+  private _hideOthersUnderSingleMode;
+  hideEntry(entryId: string): Promise<void>;
+  private _hideEntry;
+  /** Drops an entry from history and clears its module. Does nothing for an unknown id. */
+  removeEntry(entryId: string): Promise<void>;
+  private _requireEntry;
+  /**
+   * Hides every custom-geometries entry on the map but keeps the history. Implements
+   * {@link ClearableMapSlice}.
+   */
+  clearShown(): Promise<void>;
+  reset(): void;
+}
+//#endregion
+//#region src/state/digest.d.ts
+/**
+ * A compact, diffable snapshot of the user-visible parts of `ToolState`. Every field serialises to
+ * JSON. Each call builds new arrays, so compare two digests with {@link formatStateDigestDiff}, not `===`.
+ *
+ * @group Agent Toolkit
+ */
+type StateDigest = {
+  places: {
+    /** Entry ids currently rendered as individual pins, sorted ascending. */
+    shownAsPin: string[];
+    /** Entry ids currently rendered as base-map POIs, sorted ascending. */
+    shownAsBaseMap: string[];
+    /** The slice's display policy, `multiple` (default) or `single`. */
+    entryMode: EntryMode;
+  };
+  routes: {
+    /** Routes-entry ids currently drawn on the map, sorted ascending. */
+    shown: string[];
+    /** The slice's display policy, `multiple` (default) or `single`. */
+    entryMode: EntryMode;
   };
   ranges: {
     /** Range-entry ids currently drawn on the map, sorted ascending. */
@@ -1134,15 +1497,15 @@ export declare const getStateDigest: (state: ToolState) => StateDigest;
  *
  * @example
  * ```ts
- * const prev = getStateDigest(state);
+ * const previous = getStateDigest(state);
  * // ... user clicks around in the UI ...
- * const diff = formatStateDigestDiff(prev, getStateDigest(state));
- * // → '[map state changed since last response: places shown as pins: "amsterdam-cinemas"; route now "routes-2"]'
+ * const diff = formatStateDigestDiff(previous, getStateDigest(state));
+ * // → '[map state changed since last response: places shown as pins: "amsterdam-cinemas"; routes shown: "routes-2"]'
  * ```
  *
  * @group Agent Toolkit
  */
-export declare const formatStateDigestDiff: (prev: StateDigest, next: StateDigest) => string | null;
+export declare const formatStateDigestDiff: (previous: StateDigest, next: StateDigest) => string | null;
 //#endregion
 //#region src/state/map-pois/state.d.ts
 /**
@@ -1165,7 +1528,7 @@ declare class MapPOIsState implements StateSlice {
 //#region src/state/places/analysis.d.ts
 /**
  * A single analysis result attached to a places entry. Alias of the shared {@link EntryAnalysis} —
- * every entry kind uses the same result shape; kept as a named export for back-compat.
+ * every entry kind uses the same result shape.
  *
  * @group Agent Toolkit
  *
@@ -1189,9 +1552,9 @@ type PlacesMarkerType = (typeof placesMarkerTypes)[number];
  */
 type PlacesStateEvents = {
   /**
-   * An entry was added or replaced, or `reset()` cleared the history. `entries` is the full
-   * snapshot after the change, and `changedIds` lists the ids of the entries this change added,
-   * replaced in place, or removed. The {@link JobEngine} matches these against each job's
+   * An entry was added or removed, entries were dropped by `single` mode, or `reset()` cleared the
+   * history. `entries` is the full snapshot after the change, and `changedIds` lists the ids of the
+   * entries this change added or removed. The {@link JobEngine} matches these against each job's
    * `affectedEntryIds`.
    */
   'entries-change': {
@@ -1200,7 +1563,10 @@ type PlacesStateEvents = {
   };
   /** The set of entries rendered on the map, or a marker type, changed. */
   'shown-change': ReadonlySet<string>;
-  /** Boundary polygons were fetched and cached on an entry. */
+  /**
+   * Boundary polygons were fetched and cached on an entry, `count` being the cached total, or
+   * its shown polygons were cleared, with `count: 0` while the cache stays.
+   */
   'geometries-change': {
     entryId: string;
     count: number;
@@ -1222,7 +1588,11 @@ type PlacesStateEvents = {
 declare class PlacesState implements StateSlice {
   private readonly _ttMap;
   private _entries;
+  private readonly _history;
   private _entryMode;
+  private _addedCount;
+  private readonly _creatingPlacesModules;
+  private readonly _creatingGeometriesModules;
   /** 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`. */
@@ -1250,8 +1620,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. Updates only the fill style when it changes, keeping the styling
-   * applied since. Throws on an unknown entry id.
+   * created on first call in `fillStyle` or as an outline. After that, a passed `fillStyle` updates
+   * only the fill style, keeping the styling applied since. Throws on an unknown entry id.
    */
   getEntryGeometriesModule(entryId: string, fillStyle?: GeometryFillStyle): Promise<GeometriesModule>;
   private _requireEntry;
@@ -1278,6 +1648,8 @@ declare class PlacesState implements StateSlice {
    * is unknown or has no geometry data source.
    */
   fetchPlaceGeometry(placeId: string, options?: ToolExecuteOptions): Promise<PolygonFeature | undefined>;
+  private _storeGeometries;
+  private _placesNeedingGeometry;
   /**
    * Batch-fetches boundary polygons for every place in an entry that has a geometry data source
    * but is not yet cached. Issues one Geometry Data request per chunk of {@link GEOMETRY_DATA_BATCH_SIZE}
@@ -1295,6 +1667,8 @@ declare class PlacesState implements StateSlice {
    * - `mode: 'add'` merges the new features with the polygons shown on this entry's layer,
    *   deduped by `feature.id`, and re-renders the union. An empty array does nothing.
    *
+   * `fillStyle` restyles the entry's module; omit it to keep its current style, an outline at first.
+   *
    * `entryId` defaults to the latest entry that owns geometries, which suits callers that only
    * render the most recently produced footprints. Pass an explicit id to target an older one.
    */
@@ -1339,13 +1713,13 @@ declare class PlacesState implements StateSlice {
   clearShown(): Promise<void>;
   clearShownGeometries(ids?: readonly string[]): Promise<void>;
   /**
-   * Drops a single entry from history. It first hides the entry by clearing every module it
-   * owns, then removes it from `_entries`. Emits `entries-change`, plus `shown-change` if the
-   * entry was shown. Does nothing if the id is unknown.
+   * Drops a single entry from history and clears every module it owns. Emits `entries-change`, plus
+   * `shown-change` if the entry was shown. Does nothing if the id is unknown.
    */
   removeEntry(id: string): Promise<void>;
   private _showEntryAs;
   private _hideEntry;
+  private _dropEntry;
   reset(): void;
 }
 //#endregion
@@ -1438,9 +1812,9 @@ type RangesEntry = BaseEntry<ReachableRange[]> & {
  */
 type RangeStateEvents = {
   /**
-   * An entry was added, or `reset()` cleared the range history. `entries` is the full snapshot
-   * after the change, and `changedIds` lists the ids of the entries this change added, replaced
-   * in place, or removed.
+   * An entry was added or removed, entries were dropped by `single` mode, or `reset()` cleared the
+   * range history. `entries` is the full snapshot after the change, and `changedIds` lists the ids
+   * of the entries this change added or removed.
    */
   'entries-change': {
     entries: readonly RangesEntry[];
@@ -1463,7 +1837,14 @@ type RangeStateEvents = {
 declare class RangeState implements ShownEntriesSlice {
   private readonly _ttMap;
   private _entries;
+  private readonly _history;
   private _entryMode;
+  private _addedCount;
+  private readonly _creatingRangesModules;
+  private readonly _creatingGeometriesModules;
+  private readonly _creatingPlacesModules;
+  private readonly _drawing;
+  private readonly _droppedWhileDrawn;
   /** 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`. */
@@ -1489,14 +1870,15 @@ declare class RangeState implements ShownEntriesSlice {
   setEntryMode(mode: EntryMode): Promise<void>;
   /**
    * Initialises the entry's ReachableRangesModule for the isochrone/isodistance polygons
-   * lazily and applies the requested fill style. Throws on unknown id.
+   * lazily, in `fillStyle` or as an outline. After that, a passed `fillStyle` updates only the
+   * fill style. Throws on unknown id.
    */
   getEntryRangesModule(entryId: string, fillStyle?: GeometryFillStyle): Promise<ReachableRangesModule>;
   /**
    * Initialises the entry's plain GeometriesModule lazily for drawing the entry's polygons in a
-   * style of your own (per-feature colours, border widths) instead of as reachable-range bands.
-   * Updates only the fill style when it changes, keeping the styling applied since. Throws on
-   * unknown id.
+   * style of your own (per-feature colours, border widths) instead of as reachable-range bands,
+   * in `fillStyle` or as an outline. After that, a passed `fillStyle` updates only the fill style,
+   * keeping the styling applied since. Throws on unknown id.
    */
   getEntryGeometriesModule(entryId: string, fillStyle?: GeometryFillStyle): Promise<GeometriesModule>;
   /**
@@ -1510,18 +1892,22 @@ declare class RangeState implements ShownEntriesSlice {
    * flag in sync with what the user sees.
    *
    * With `entryMode === 'single'`, any other shown entry is hidden first so two range
-   * layers don't overlap.
+   * layers don't overlap. An entry dropped since its modules were asked for has its modules
+   * cleared instead.
    */
   markEntryShown(entryId: string): Promise<void>;
-  /** Clears every module on the entry. Does nothing if the entry is unknown. */
+  /** Clears the entry's ranges, geometries and origin-pin modules. Does nothing if the entry is unknown or hidden. */
   hideEntry(entryId: string): Promise<void>;
+  private _hideEntry;
+  private _clearModules;
+  private _dropEntry;
   /**
-   * Drops a single entry from history. It clears the entry's ranges and origin-pin modules to
-   * hide it, then removes it from `_entries`. Emits `entries-change`. Does nothing if the id is
-   * unknown.
+   * Drops a single entry from history and hides it as {@link hideEntry} does. Emits `entries-change`.
+   * Does nothing if the id is unknown.
    */
   removeEntry(entryId: string): Promise<void>;
   private _requireEntry;
+  private _requireDrawnEntry;
   get entries(): readonly RangesEntry[];
   get latestEntry(): RangesEntry | undefined;
   addEntry(entry: Omit<RangesEntry, 'id' | 'timestamp'>): Promise<string>;
@@ -1536,7 +1922,7 @@ declare class RangeState implements ShownEntriesSlice {
 //#region src/state/routing/analysis.d.ts
 /**
  * A single analysis result attached to a routes entry. Alias of the shared {@link EntryAnalysis} —
- * every entry kind uses the same result shape; kept as a named export for back-compat.
+ * every entry kind uses the same result shape.
  *
  * @group Agent Toolkit
  *
@@ -1544,6 +1930,75 @@ declare class RangeState implements ShownEntriesSlice {
  */
 type RoutesAnalysis = EntryAnalysis;
 //#endregion
+//#region src/state/polling-monitor.d.ts
+/**
+ * The lifecycle state of a per-entry route or incidents monitor. `stopped-error` means the last
+ * poll failed and the timer was cleared. To retry, start the monitor again.
+ *
+ * @group Agent Toolkit
+ */
+type PollingStatus = 'idle' | 'running' | 'stopped-error';
+/** The timers a polling monitor schedules on. */
+type PollingTimers = {
+  /** Override for tests. Defaults to the global `setInterval`. */
+  setInterval?: (fn: () => void, ms: number) => unknown;
+  clearInterval?: (handle: unknown) => void;
+};
+/**
+ * Events fired by a {@link PollingMonitor}. The owning slice subscribes once and re-emits translated
+ * copies (`monitor-tick`, `monitor-error`) keyed by entry id.
+ */
+type PollingMonitorEvents<SNAPSHOT> = {
+  /** A poll succeeded. The payload is the fresh snapshot. */
+  tick: SNAPSHOT;
+  /** A poll failed, so the monitor cleared its timer and moved to `stopped-error`. */
+  error: string;
+};
+/**
+ * A one-shot polling loop. It owns its timer, status and error, and restarting it after `stop()`
+ * resets all state. It never knows about the entry that owns it: the fetch it is started with
+ * captures what to poll, and the caller decides what to do with each snapshot.
+ *
+ * Each snapshot is stamped with `takenAt` after its fetch resolves, so every consumer of one tick
+ * (entry data, derived analyses, sandbox `now`) agrees on the same canonical moment.
+ */
+declare abstract class PollingMonitor<VALUE, SNAPSHOT> {
+  private readonly _subject;
+  readonly events: StateEvents<PollingMonitorEvents<SNAPSHOT>>;
+  private _status;
+  private _error?;
+  private _intervalHandle?;
+  private _clearInterval?;
+  private _fetch?;
+  private _run;
+  private _tickInFlightRun?;
+  /** @param _subject The monitor as its console warnings name it, e.g. `a route monitor`. */
+  protected constructor(_subject: string);
+  get status(): PollingStatus;
+  get error(): string | undefined;
+  /**
+   * Whether the monitor is *currently* polling. Unlike {@link isActive}, it excludes
+   * `stopped-error`, a state where the timer is gone but the monitor still carries an
+   * unacknowledged error. Use this to ask "is the entry being polled right now", and
+   * `isActive` to ask "is there anything to clean up".
+   */
+  get isRunning(): boolean;
+  /** Whether the monitor has any polling activity (running or stopped-error). */
+  get isActive(): boolean;
+  /** Stops polling and resets state. Does nothing when idle. */
+  stop(): void;
+  /** The snapshot one successful fetch makes. */
+  protected abstract _snapshot(value: VALUE, takenAt: number): SNAPSHOT;
+  /**
+   * Starts polling `fetch`: fires the first tick immediately unless `skipInitialTick` is set, then
+   * schedules an interval. Does nothing if already running.
+   */
+  protected _startPolling(fetch: () => Promise<VALUE>, timers: PollingTimers, intervalMs: number, skipInitialTick: boolean): void;
+  private _tick;
+  private _failed;
+  private _releaseTimer;
+}
+//#endregion
 //#region src/state/routing/monitor/types.d.ts
 /**
  * A freshly recalculated route from a single monitor tick, with the moment it was sampled.
@@ -1555,13 +2010,6 @@ type RouteSnapshot = {
   takenAt: number;
   routes: Routes;
 };
-/**
- * The lifecycle state of a per-entry route monitor. `stopped-error` means the last recalculation
- * failed and the timer was cleared. To retry, start the monitor again.
- *
- * @group Agent Toolkit
- */
-type RoutePollingStatus = 'idle' | 'running' | 'stopped-error';
 //#endregion
 //#region src/state/routing/monitor/monitor.d.ts
 /**
@@ -1574,45 +2022,17 @@ type RoutePollingStatus = 'idle' | 'running' | 'stopped-error';
  *
  * @group Agent Toolkit
  */
-type RouteMonitorDeps = {
+type RouteMonitorDeps = PollingTimers & {
   recalculate: () => Promise<Routes>;
-  /** Override for tests. Defaults to the global `setInterval`. */
-  setInterval?: (fn: () => void, ms: number) => unknown;
-  clearInterval?: (handle: unknown) => void;
-};
-/**
- * Events fired by {@link RouteMonitor}. The slice subscribes once and re-emits translated copies
- * (`monitor-tick`, `monitor-error`) keyed by entry id.
- */
-type RouteMonitorEvents = {
-  /** A recalculation succeeded. The payload is the fresh snapshot. */
-  tick: RouteSnapshot;
-  /** A recalculation failed, so the monitor cleared its timer and moved to `stopped-error`. */
-  error: string;
 };
 /**
- * A one-shot polling loop that recalculates a single route on an interval. It owns its timer, status,
- * and error. Restarting it after `stop()` resets all state.
- *
- * The monitor never knows about the entry that owns it. The `recalculate` closure captures the
- * waypoints and params, and the caller decides what to do with each fresh snapshot. It mirrors
- * `IncidentMonitor`. Routes carry live traffic, so periodic recalculation keeps the entry fresh.
+ * A one-shot polling loop that recalculates a single route on an interval. Routes carry live traffic,
+ * so periodic recalculation keeps the entry fresh. It mirrors `IncidentMonitor`.
  *
  * @group Agent Toolkit
  */
-declare class RouteMonitor {
-  readonly events: StateEvents<RouteMonitorEvents>;
-  private _status;
-  private _error?;
-  private _intervalHandle?;
-  private _clearInterval?;
-  private _recalculate?;
-  get status(): RoutePollingStatus;
-  get error(): string | undefined;
-  /** Whether the monitor is *currently* recalculating on its interval. */
-  get isRunning(): boolean;
-  /** Whether the monitor has any activity (running or stopped-error). */
-  get isActive(): boolean;
+declare class RouteMonitor extends PollingMonitor<Routes, RouteSnapshot> {
+  constructor();
   /**
    * Starts polling. It captures `deps` for the lifetime of the run, fires the first recalculation
    * immediately unless `skipInitialTick` is set, then schedules an interval. Does nothing if
@@ -1622,11 +2042,7 @@ declare class RouteMonitor {
    * since an eager first tick would duplicate that recalculation.
    */
   start(deps: RouteMonitorDeps, intervalMs?: number, skipInitialTick?: boolean): void;
-  /** Stops polling and resets state. Does nothing when idle. */
-  stop(): void;
-  private _tick;
-  private _failed;
-  private _releaseTimer;
+  protected _snapshot(routes: Routes, takenAt: number): RouteSnapshot;
 }
 //#endregion
 //#region src/state/routing/entry.d.ts
@@ -1681,9 +2097,9 @@ type RoutesEntry = BaseEntry<Routes> & {
    */
   _monitor?: RouteMonitor;
   /**
-   * Monotonic counter bumped on every {@link RoutingState.replaceRouteData}. Guards against an
-   * out-of-order render: a slow `showRoutes` from an earlier tick that resolves after a newer tick
-   * has already overwritten `data` bails before touching the map.
+   * Monotonic counter bumped on every {@link RoutingState.replaceRouteData}. Guards the section
+   * focus against an out-of-order render: a slow `showRoutes` from an earlier tick that resolves
+   * after a newer tick has already overwritten `data` skips re-applying the focus.
    */
   _tick?: number;
 };
@@ -1696,9 +2112,10 @@ type RoutesEntry = BaseEntry<Routes> & {
  */
 type RoutingStateEvents = {
   /**
-   * A calculation was stored, an analysis attached, or `reset()` cleared the history.
-   * `entries` is the full snapshot after the change, and `changedIds` lists the ids of the
-   * entries this change added, replaced in place, or removed.
+   * A calculation was stored, a monitor tick replaced an entry's routes, entries were removed or
+   * dropped by `single` mode, or `reset()` cleared the history. `entries` is the full snapshot after
+   * the change, and `changedIds` lists the ids of the entries this change added, replaced in place,
+   * or removed.
    */
   'entries-change': {
     entries: readonly RoutesEntry[];
@@ -1748,9 +2165,12 @@ type RoutingStateEvents = {
 declare class RoutingState implements ShownEntriesSlice {
   private readonly _ttMap;
   private _entries;
+  private readonly _history;
   private _planningSlots;
   private _params;
   private _entryMode;
+  private _addedCount;
+  private readonly _creatingModules;
   /** The knobs set on every entry's RoutingModule, `color` and `widthFactor` among them. Cleared on `reset`. */
   readonly knobs: SliceKnobs;
   /**
@@ -1793,7 +2213,7 @@ declare class RoutingState implements ShownEntriesSlice {
    * choice, and `showSummaryBubbles: false` to drop the per-route ETA bubbles (e.g. a monitored
    * corridor backdrop).
    */
-  showEntry(entryId: string, opts?: {
+  showEntry(entryId: string, options?: {
     showWaypoints?: boolean;
     showSummaryBubbles?: boolean;
   }): Promise<void>;
@@ -1808,11 +2228,13 @@ declare class RoutingState implements ShownEntriesSlice {
    * Does nothing if the entry is unknown or already hidden.
    */
   hideEntry(entryId: string): Promise<void>;
+  private _hideEntry;
   /**
-   * Drops a single entry from history. It clears the entry's routing module to hide it, then
-   * removes it from `_entries`. Emits `entries-change`. Does nothing if the id is unknown.
+   * Drops a single entry from history, stops its monitor and clears its routing module. Emits
+   * `entries-change`. Does nothing if the id is unknown.
    */
   removeEntry(entryId: string): Promise<void>;
+  private _dropEntry;
   private _requireEntry;
   /**
    * The RoutingModule of the most recently shown entry, or undefined if no entry is shown.
@@ -1834,18 +2256,20 @@ declare class RoutingState implements ShownEntriesSlice {
    * false if the entry is unknown. Mirrors `TrafficIncidentsState.replaceEntryData`.
    */
   replaceRouteData(entryId: string, routes: Routes, sampledAt: number): Promise<boolean>;
+  private _showRoutesKeepingSelection;
   private _createMonitorForEntry;
   /**
    * Arms background recalculation on an entry. Lazy-creates its monitor, then starts polling with
    * the caller-supplied `recalculate` closure. Emits `monitor-start` on the idle → running
    * transition. Throws on unknown id.
    */
-  startMonitoring(entryId: string, deps: RouteMonitorDeps, opts?: {
+  startMonitoring(entryId: string, deps: RouteMonitorDeps, options?: {
     intervalMs?: number;
     skipInitialTick?: boolean;
   }): void;
   /** Stops recalculating an entry but keeps its last data. Emits `monitor-stop`. Does nothing if not running. */
   stopMonitoring(entryId: string): void;
+  private _stopMonitor;
   /** Whether the entry is being recalculated on its interval. */
   isMonitored(entryId: string): boolean;
   /**
@@ -1858,8 +2282,8 @@ declare class RoutingState implements ShownEntriesSlice {
 //#endregion
 //#region src/types/state.d.ts
 /**
- * Common interface for state slices. Implement `reset()` to participate
- * in cleanup when `destroy()` is called on the agent.
+ * Common interface for state slices. Implement `reset()` to participate in cleanup: `destroy()` on
+ * the agent calls it, and so does the `resetState` tool when the user asks to start over.
  *
  * All built-in state classes implement this. Custom slices can optionally
  * implement it to get automatic cleanup.
@@ -1877,6 +2301,8 @@ export interface StateSlice {
  * logic (proximity, threshold, filter). The entry holds every feature, so without re-running the rule
  * that selection can't be recovered from `entryId` alone, and the verdict records exactly what matched.
  * These are the features the UI highlights and the `summary` cites.
+ *
+ * @group Agent Toolkit
  */
 type MemberRef = {
   entryId: string;
@@ -1887,17 +2313,31 @@ type MemberRef = {
  * and read back by the reducer. `members` groups matches by source entry, so a verdict can span
  * several entry kinds. For example, "an incident within 100m of a hospital" returns a hospitals group
  * and an incidents group. `summary` is a grounded headline the code produces deterministically.
+ *
+ * @group Agent Toolkit
  */
 type Verdict = {
   active: boolean;
   members: MemberRef[];
   summary: string;
 };
-/** Toast-worthy (`alert`) or quietly-logged (`event`), discriminating events in one store. */
+/**
+ * Toast-worthy (`alert`) or quietly-logged (`event`), discriminating events in one store.
+ *
+ * @group Agent Toolkit
+ */
 type TrackerEventType = 'alert' | 'event';
-/** Rising edge (`opened`) or falling edge (`resolved`), the only two statuses in the rising-edge model. */
+/**
+ * Rising edge (`opened`) or falling edge (`resolved`), the only two statuses in the rising-edge model.
+ *
+ * @group Agent Toolkit
+ */
 type TrackerEventStatus = 'opened' | 'resolved';
-/** A tracker crossing an edge, kept as the durable record the feed and toasts render. */
+/**
+ * A tracker crossing an edge, kept as the durable record the feed and toasts render.
+ *
+ * @group Agent Toolkit
+ */
 type TrackerEvent = {
   id: string;
   /** Source-data sample time of the recompute that fired it, **not** wall-clock. */
@@ -1915,6 +2355,8 @@ type TrackerEvent = {
  * A tracker is one rule, a natural-language condition plus its rising-edge state. The compiled code
  * lives on the tracker's {@link Job}, not here. `affectedEntryIds` are the entries the rule watches,
  * and a verdict's `members` are the ones that matched.
+ *
+ * @group Agent Toolkit
  */
 type Tracker = {
   id: string;
@@ -1929,7 +2371,11 @@ type Tracker = {
   /** Rising-edge time of the current open episode, if active. */
   openedAt?: number;
 };
-/** Events emitted by {@link EventsState}. */
+/**
+ * Events emitted by {@link EventsState}.
+ *
+ * @group Agent Toolkit
+ */
 type TrackerStateEvents = {
   /** The tracker set or a tracker's live state changed (create, clear, enable, edge crossed). */
   'trackers-change': readonly Tracker[];
@@ -1976,7 +2422,7 @@ declare class EventsState implements StateSlice {
    * The event log, newest last. Pass `sinceMs` to filter and `trackerId` to scope. Returns deep copies
    * so a caller can't mutate a logged event (or its `members`) and corrupt the store.
    */
-  log(opts?: {
+  log(options?: {
     trackerId?: string;
     sinceMs?: number;
   }): readonly TrackerEvent[];
@@ -1997,8 +2443,7 @@ declare class EventsState implements StateSlice {
 //#region src/state/traffic-area-analytics/analysis.d.ts
 /**
  * A single analysis result attached to a traffic-area-analytics entry. Alias of the shared
- * {@link EntryAnalysis} — every entry kind uses the same result shape; kept as a named export for
- * back-compat.
+ * {@link EntryAnalysis} — every entry kind uses the same result shape.
  *
  * @group Agent Toolkit
  *
@@ -2010,8 +2455,7 @@ type TrafficAreaAnalyticsAnalysis = EntryAnalysis;
 /**
  * Compact provenance metadata for a traffic-area-analytics entry — the request
  * parameters that produced the result. Kept opaque (`Record<string, unknown>`)
- * because the SDK call accepts a wide param shape and we just want to surface
- * enough context for `recall` / `digest` tools.
+ * because the SDK call accepts a wide param shape.
  *
  * @group Agent Toolkit
  *
@@ -2038,7 +2482,7 @@ type TrafficAreaAnalyticsEntry = BaseEntry<TrafficAreaAnalytics> & {
   _module?: TrafficAreaAnalyticsModule;
   /** Latest viz config reflected from the module (mode / metric / scaleMode / …). */
   _config?: TrafficAreaAnalyticsModuleConfig;
-  /** Unsubscribe from this entry's module config-change wiring. Cleared on hide / remove. */
+  /** Unsubscribe from this entry's module config-change wiring. Released when the entry is dropped or reset. */
   _configChangeUnsub?: () => void;
   /** True while `_module` is rendering on the map. */
   _shown?: boolean;
@@ -2053,9 +2497,9 @@ type TrafficAreaAnalyticsEntry = BaseEntry<TrafficAreaAnalytics> & {
  */
 type TrafficAreaAnalyticsStateEvents = {
   /**
-   * An entry was added or removed, or `reset()` cleared the history. `entries` is the full
-   * snapshot after the change, and `changedIds` lists the ids of the entries this change added,
-   * replaced in place, or removed.
+   * An entry was added or removed, entries were dropped by `single` mode, or `reset()` cleared the
+   * history. `entries` is the full snapshot after the change, and `changedIds` lists the ids of the
+   * entries this change added or removed.
    */
   'entries-change': {
     entries: readonly TrafficAreaAnalyticsEntry[];
@@ -2080,10 +2524,13 @@ type TrafficAreaAnalyticsStateEvents = {
  *
  * @group Agent Toolkit
  */
-declare class TrafficAreaAnalyticsState implements ShownEntriesSlice, StateSlice {
+declare class TrafficAreaAnalyticsState implements ShownEntriesSlice {
   private readonly _ttMap;
   private _entries;
+  private readonly _history;
   private _entryMode;
+  private _addedCount;
+  private readonly _creatingModules;
   /** The state change events, listed in {@link TrafficAreaAnalyticsStateEvents}. */
   readonly events: StateEvents<TrafficAreaAnalyticsStateEvents>;
   /**
@@ -2113,8 +2560,10 @@ declare class TrafficAreaAnalyticsState implements ShownEntriesSlice, StateSlice
   showEntry(entryId: string): Promise<void>;
   /** Hides the entry's analytics on its module. Does nothing if unknown or already hidden. */
   hideEntry(entryId: string): Promise<void>;
-  /** Hides a single entry, then drops it from history and emits `entries-change`. Does nothing for an unknown id. */
+  private _hideEntry;
+  /** Drops a single entry from history, hides it and emits `entries-change`. Does nothing for an unknown id. */
   removeEntry(entryId: string): Promise<void>;
+  private _dropEntry;
   private _requireEntry;
   /**
    * Hides every traffic-area-analytics entry on the map but keeps the history. Implements
@@ -2127,8 +2576,7 @@ declare class TrafficAreaAnalyticsState implements ShownEntriesSlice, StateSlice
 //#region src/state/traffic-incidents/analysis.d.ts
 /**
  * A single analysis result attached to a traffic-incidents entry. Alias of the shared
- * {@link EntryAnalysis} — every entry kind uses the same result shape; kept as a named export for
- * back-compat.
+ * {@link EntryAnalysis} — every entry kind uses the same result shape.
  *
  * @group Agent Toolkit
  *
@@ -2137,9 +2585,18 @@ declare class TrafficAreaAnalyticsState implements ShownEntriesSlice, StateSlice
 type IncidentsAnalysis = EntryAnalysis;
 //#endregion
 //#region src/state/traffic-incidents/clustering.d.ts
-/** Direction a cluster's total delay is trending across recent snapshots. */
+/**
+ * Direction a cluster's total delay is trending across recent snapshots.
+ *
+ * @group Agent Toolkit
+ */
 type ClusterTrend = 'growing' | 'fading' | 'steady' | 'new';
-/** Tuneable parameters for {@link runClustering}, all optional with sensible defaults. */
+/**
+ * Tuneable parameters for clustering traffic incidents, through the `clusterIncidents` tool or the sandbox's
+ * `cluster(incidents, params)`, all optional with sensible defaults.
+ *
+ * @group Agent Toolkit
+ */
 type ClusteringParams = {
   /** DBSCAN neighbourhood radius in km. Default: 0.5 */
   eps?: number;
@@ -2149,13 +2606,17 @@ type ClusteringParams = {
   maxClusters?: number;
   /** Pre-filter rules applied before clustering. */
   preFilter?: {
-    /** Categories to exclude entirely. Default: `['roadworks', 'road-closed']` */
+    /** Categories whose incidents are dropped when below `minDelaySeconds`. Default: `['roadworks', 'road-closed']` */
     excludeCategories?: string[];
     /** Incidents in excludeCategories with `delayInSeconds` below this are excluded. Default: 1 (excludes 0-delay) */
     minDelaySeconds?: number;
   };
 };
-/** A single cluster produced by {@link runClustering}. */
+/**
+ * A single cluster of traffic incidents, as `clusterIncidents` and the sandbox's `cluster(...)` produce it.
+ *
+ * @group Agent Toolkit
+ */
 type ClusterResult = {
   /** A stable identifier, reused across runs when member overlap >= 50%. */
   id: string;
@@ -2175,16 +2636,19 @@ type ClusterResult = {
   primaryRoads: string[];
   /** Most-frequent incident category across members (e.g. "jam"). */
   primaryCategory: string;
-  /** Trend across recent snapshots (see {@link classifyTrend}). */
+  /** Trend across the last 3 snapshots: `new` on a first sighting, `steady` until there are 3. */
   trend: ClusterTrend;
   /**
-   * Rolling window of `totalDelaySeconds` across recent matched snapshots,
-   * bounded to {@link TREND_WINDOW}. Internal trend state threaded forward
-   * via the previous run, not display data.
+   * Rolling window of `totalDelaySeconds` across the last 3 matched snapshots.
+   * Internal trend state threaded forward via the previous run, not display data.
    */
   delaySamples: number[];
 };
-/** Output of {@link runClustering}. */
+/**
+ * Output of clustering traffic incidents: the clusters, ranked by total delay.
+ *
+ * @group Agent Toolkit
+ */
 type ClusteringOutput = {
   groups: ClusterResult[];
 };
@@ -2201,7 +2665,7 @@ type SandboxClusteringOutput = ClusteringOutput & {
 //#endregion
 //#region src/state/traffic-incidents/monitor/types.d.ts
 /**
- * The geographic area a {@link TrafficIncidentsEntry} monitor is polling, captured at
+ * The geographic area a traffic incidents entry's monitor is polling, captured at
  * monitor-start time and replayed on every tick.
  *
  * @group Agent Toolkit
@@ -2212,8 +2676,8 @@ type MonitoredArea = {
   label?: string;
 };
 /**
- * A fresh batch of incidents from a single monitor tick, with the moment it was sampled.
- * Payload of {@link TrafficIncidentsStateEvents.monitor-tick}.
+ * A fresh batch of incidents from a single monitor tick, with the moment it was sampled: the `snap`
+ * field of the traffic incidents slice's `monitor-tick` event.
  *
  * @group Agent Toolkit
  */
@@ -2221,13 +2685,6 @@ type IncidentSnapshot = {
   takenAt: number;
   incidents: TrafficIncident[];
 };
-/**
- * The lifecycle state of a per-entry incidents monitor. `stopped-error` means the last
- * poll failed and the timer was cleared. To retry, start the monitor again.
- *
- * @group Agent Toolkit
- */
-type PollingStatus = 'idle' | 'running' | 'stopped-error';
 //#endregion
 //#region src/state/traffic-incidents/monitor/monitor.d.ts
 /**
@@ -2241,53 +2698,20 @@ type PollingStatus = 'idle' | 'running' | 'stopped-error';
  *
  * @group Agent Toolkit
  */
-type IncidentMonitorDeps = {
+type IncidentMonitorDeps = PollingTimers & {
   fetchIncidents: (bbox: BBox) => Promise<TrafficIncident[]>;
-  /** Override for tests. Defaults to the global `setInterval`. */
-  setInterval?: (fn: () => void, ms: number) => unknown;
-  clearInterval?: (handle: unknown) => void;
 };
 /**
- * Events fired by {@link IncidentMonitor}. The slice subscribes once and re-emits
- * translated copies (`monitor-tick`, `monitor-error`) keyed by entry id.
- */
-type IncidentMonitorEvents = {
-  /** A poll succeeded. Payload: the fresh snapshot. */
-  tick: IncidentSnapshot;
-  /** A poll failed, so the monitor cleared its timer and moved to `stopped-error`. */
-  error: string;
-};
-/**
- * A one-shot polling loop scoped to a single bbox. It owns its timer, status, error,
- * and captured area. Restarting it after `stop()` resets all state.
- *
- * The monitor never knows about the entry that owns it. It surfaces ticks and errors
- * through `events`, and the caller decides what to do with the snapshot.
+ * A one-shot polling loop scoped to a single bbox. Besides the polling state, it owns the area
+ * captured at start.
  *
  * @group Agent Toolkit
  */
-declare class IncidentMonitor {
+declare class IncidentMonitor extends PollingMonitor<TrafficIncident[], IncidentSnapshot> {
   private readonly _bbox;
-  readonly events: StateEvents<IncidentMonitorEvents>;
-  private _status;
   private _area?;
-  private _error?;
-  private _intervalHandle?;
-  private _clearInterval?;
-  private _fetchIncidents?;
   constructor(_bbox: BBox);
-  get status(): PollingStatus;
   get monitoredArea(): MonitoredArea | undefined;
-  get error(): string | undefined;
-  /**
-   * Whether the monitor is *currently* polling. Unlike {@link isActive}, it excludes
-   * `stopped-error`, a state where the timer is gone but the monitor still carries an
-   * unacknowledged error. Use this to ask "is the entry being polled right now", and
-   * `isActive` to ask "is there anything to clean up".
-   */
-  get isRunning(): boolean;
-  /** Whether the monitor has any polling activity (running or stopped-error). */
-  get isActive(): boolean;
   /**
    * Starts polling. It captures `deps` for the lifetime of the run, fires the first tick
    * immediately unless `skipInitialTick` is set, then schedules an interval. Does nothing if
@@ -2299,11 +2723,8 @@ declare class IncidentMonitor {
    * produces an initial snapshot without waiting a full interval.
    */
   start(area: MonitoredArea, deps: IncidentMonitorDeps, intervalMs?: number, skipInitialTick?: boolean): void;
-  /** Stops polling and resets state. Does nothing when idle. */
   stop(): void;
-  private _tick;
-  private _failed;
-  private _releaseTimer;
+  protected _snapshot(incidents: TrafficIncident[], takenAt: number): IncidentSnapshot;
 }
 //#endregion
 //#region src/state/traffic-incidents/state.d.ts
@@ -2354,10 +2775,7 @@ type TrafficIncidentsEntry = BaseEntry<TrafficIncident[]> & {
    * Focused subset on this entry — the agent's `focusIds` write-side. Drives the dim/highlight
    * affordance on `_module` and feeds `focusedFeatures(entryId)` for stepping through.
    */
-  _focus?: {
-    ids: Set<string>;
-    reason?: string;
-  };
+  _focus?: IncidentFocus;
   /**
    * Per-entry polling loop. Lazy-created on first {@link TrafficIncidentsState.startMonitoring}
    * call; reused across stop/start cycles. Owns timer, status, error, captured area.
@@ -2453,10 +2871,13 @@ type TrafficIncidentsStateEvents = {
  *
  * @group Agent Toolkit
  */
-declare class TrafficIncidentsState implements StateSlice {
+declare class TrafficIncidentsState implements ShownEntriesSlice {
   private readonly _ttMap;
   private _entries;
+  private readonly _history;
   private _entryMode;
+  private _addedCount;
+  private readonly _creatingModules;
   private readonly _clusters;
   /** The state change events, listed in {@link TrafficIncidentsStateEvents}. */
   readonly events: StateEvents<TrafficIncidentsStateEvents>;
@@ -2567,12 +2988,13 @@ declare class TrafficIncidentsState implements StateSlice {
    * once, then delegates to {@link IncidentMonitor.start}. Does nothing if polling is already
    * running. Throws on unknown entry id.
    */
-  startMonitoring(entryId: TrafficIncidentsEntry['id'], area: MonitoredArea, deps: IncidentMonitorDeps, opts?: {
+  startMonitoring(entryId: TrafficIncidentsEntry['id'], area: MonitoredArea, deps: IncidentMonitorDeps, options?: {
     intervalMs?: number;
     skipInitialTick?: boolean;
   }): void;
   /** Stops polling. Does nothing if idle or unknown. */
   stopMonitoring(entryId: TrafficIncidentsEntry['id']): void;
+  private _stopMonitor;
   /**
    * Whether the entry is *currently* being polled. A monitor stuck in
    * `stopped-error` returns false here, so the start tool can report a truthful
@@ -2634,17 +3056,19 @@ export type QueryAs = 'poi' | 'place';
 /**
  * Resolves a query string to up to `limit` Places, using POI search when `queryAs === 'poi'`,
  * otherwise geocoding. The optional `bias` narrows the search to a region.
+ *
+ * @ignore
  */
 export declare const locatePlaces: (query: string, queryAs: QueryAs, options: {
   limit: number;
   bias?: GeoBias;
-}, execOptions?: ToolExecuteOptions) => Promise<Place[]>;
+}, executeOptions?: ToolExecuteOptions) => Promise<Place[]>;
 /**
  * Finds the best match for a query as the `locatePlace` tool does, for a custom tool that needs one place.
  * A failed or cancelled request rejects, so catch it in `execute`.
  *
  * @param bias - Favours results near a position, such as the map centre from {@link getViewportBias}.
- * @param execOptions - The `execute` options, whose `signal` cancels the request with the turn.
+ * @param executeOptions - The `execute` options, whose `signal` cancels the request with the turn.
  * @returns The first match, or `null` when nothing matches.
  *
  * @example
@@ -2658,7 +3082,7 @@ export declare const locatePlaces: (query: string, queryAs: QueryAs, options: {
  *
  * @group Agent Toolkit
  */
-export declare const locatePlace: (query: string, queryAs: QueryAs, bias?: GeoBias, execOptions?: ToolExecuteOptions) => Promise<Place | null>;
+export declare const locatePlace: (query: string, queryAs: QueryAs, bias?: GeoBias, executeOptions?: ToolExecuteOptions) => Promise<Place | null>;
 //#endregion
 //#region src/tools/shared/location-input.d.ts
 /** @ignore */
@@ -2735,19 +3159,22 @@ export type CollectedGeometries = {
  * `PolygonFeature[]`. The id's `kind` tells the helper which slice to
  * consult: `place` and `places` go through the per-place fetch pipeline
  * (Geometry Data service for footprints, lazy cached on the places-entry);
- * `ranges` flattens isochrone polygons already in memory; `custom` reads a
+ * `ranges` flattens isochrone polygons already in memory; `customGeometries` reads a
  * derived entry produced by a previous `processData`.
  *
  * Validates the input precondition (at least one id) and the output
  * postcondition (at least one polygon collected). Returns `affectedEntries`
  * — the entries that should carry analyses computed from these geometries
- * (places-entries from `place`/`places` inputs, custom-entries from
- * `custom` inputs; ranges entries don't carry analyses, so they're not
+ * (places-entries from `place`/`places` inputs, custom-geometries entries from
+ * `customGeometries` inputs; ranges entries don't carry analyses, so they're not
  * included here).
  *
+ * Pass the turn's `options` so cancelling it cancels the Geometry Data requests too; a monitor
+ * re-run leaves them out.
+ *
  * @ignore
  */
-export declare const collectInputGeometries: (sources: readonly GeometriesId[], state: ToolState) => Promise<{
+export declare const collectInputGeometries: (inputSources: readonly GeometriesId[], state: ToolState, options?: ToolExecuteOptions) => Promise<{
   value: CollectedGeometries;
 } | {
   error: string;
@@ -2756,7 +3183,6 @@ export declare const collectInputGeometries: (sources: readonly GeometriesId[],
  * Resolves `placesEntryIDs` into a `Record<entryId, Places>` map for
  * sandbox cross-referencing. Returns `{ value: undefined }` when no IDs
  * are supplied so callers can pass the result straight into the sandbox.
- * Mirrors the resolution used by analyse-routes and process-routes.
  *
  * @ignore
  */
@@ -2796,8 +3222,12 @@ export type ResolvedEntries = {
   trafficAreaAnalytics: TrafficAreaAnalyticsEntry[];
   byod: BYODEntry[];
 };
-/** Newest `timestamp` across every resolved source entry, or undefined when none carry one, as
- * the canonical `sampledAt` for a recurring sandbox run over these inputs. */
+/**
+ * Newest `timestamp` across every resolved source entry, or undefined when none carry one, as
+ * the canonical `sampledAt` for a recurring sandbox run over these inputs.
+ *
+ * @ignore
+ */
 export declare const latestTimestamp: (resolved: ResolvedEntries) => number | undefined;
 /**
  * Sandbox-facing inputs. Each kind is exposed as a single `<kind>ByEntry` record keyed by the entry id
@@ -2863,11 +3293,12 @@ export type PreparedInputs = {
 /**
  * Resolve every requested input kind, build the sandbox views, and surface the resolved entries to the
  * caller. The caller (analyseData / processData) enforces "at least one input must be set" via the zod
- * schema; this helper enforces it again as a safety net.
+ * schema; this helper enforces it again as a safety net. Pass the turn's `options` from a tool call,
+ * and none from a monitor re-run (see {@link collectInputGeometries}).
  *
  * @ignore
  */
-export declare const prepareMultiInputs: (ids: MultiInputIds, state: ToolState) => Promise<{
+export declare const prepareMultiInputs: (ids: MultiInputIds, state: ToolState, options?: ToolExecuteOptions) => Promise<{
   value: PreparedInputs;
 } | {
   error: string;
@@ -2904,7 +3335,7 @@ export declare const buildSandboxToolsDoc: (active: readonly EntryDataKind[], sc
  * Pack `prepared.sandbox` into the positional argument array expected by
  * `runSandboxedFn`, in the same order as {@link MULTI_INPUT_SANDBOX_PARAMS}.
  *
- * The merged / per-entry views are shallow — their feature objects are the SAME
+ * The `<kind>ByEntry` records are shallow — their feature objects are the SAME
  * references held in the entry slices — so sandbox code must not mutate them in
  * place or it would corrupt live app state. We do NOT deep-copy here: the copy is
  * the executor's job, done exactly once and only where needed — the main-thread
@@ -2913,7 +3344,7 @@ export declare const buildSandboxToolsDoc: (active: readonly EntryDataKind[], sc
  * boundary. Cloning here too would be redundant double-work. Trailing `h3` / `turf` /
  * `routeUtils` / `cluster` are read-only function references, passed through untouched —
  * `routeUtils` is the shared {@link routeUtils} set and `cluster` is the
- * {@link clusterIncidents} primitive; both are injected into both tools. (In the
+ * {@link clusterIncidents} primitive; both reach every code-generation tool. (In the
  * iframe-worker path these positions are dropped and refilled from the worker's own
  * globals — see {@link WORKER_PROVIDED_PARAMS} — so they must stay function references here.)
  *
@@ -2926,26 +3357,23 @@ export declare const packSandboxArgs: (sandbox: SandboxInputs, libs: {
 //#endregion
 //#region src/tools/shared/places-schema-doc.d.ts
 /**
- * Build the Place properties schema doc embedded in tool descriptions for
- * sandboxed code. `Places` is a FeatureCollection of Point Features; only the
- * `properties` shape (the TomTom-specific bit) is documented here.
- *
- * @remarks
- * Takes {@link FeatureFlags} so a future flag can vary the doc; no flag
- * currently does, so every caller gets the same text.
+ * The Place properties schema doc embedded in tool descriptions for sandboxed code. `Places` is a
+ * FeatureCollection of Point Features; only the `properties` shape (the TomTom-specific bit) is
+ * documented here.
  *
  * @ignore
  */
-export declare const buildPlacesSchemaDoc: (_flags: FeatureFlags) => string;
+export declare const PLACES_SCHEMA_DOC: string;
 /**
- * Places schema doc — preserved as a named constant so non-flag-aware tools
- * keep working.
+ * The {@link PLACES_SCHEMA_DOC} for a set of {@link FeatureFlags}, which a future flag can vary; no flag
+ * currently does, so every caller gets the same text.
  *
  * @ignore
  */
-export declare const PLACES_SCHEMA_DOC: string;
+export declare const buildPlacesSchemaDoc: (_flags: FeatureFlags) => string;
 //#endregion
 //#region src/tools/shared/resolve-range.d.ts
+/** @ignore */
 export declare const getRangePolygons: (state: ToolState, rangeId: string) => {
   polygons: (Polygon | MultiPolygon)[];
 } | {
@@ -3074,9 +3502,8 @@ export declare const geometryDisplayConfigSchema: z.ZodObject<{
   }>>;
 }, z.core.$strip>;
 /**
- * Shared marker-type enum. Used as a required field in `showPlacesSchema` (the
- * nested `show` object for discover/filter/search tools) and as an optional
- * top-level field in `showPlaces` itself.
+ * Shared marker-type enum, a required field in `showPlacesSchema` (the nested `show` object of the
+ * place-searching tools).
  *
  * @ignore
  */
@@ -3294,9 +3721,9 @@ export type ResolveAreasOptions = {
 };
 export type ResolveKind = 'within' | 'nearby' | 'global';
 export type AreaSource = 'viewport' | 'boundingBox' | 'query' | 'placeId' | 'geometries' | 'route';
-export declare function resolveWhere(opts: ResolveAreasOptions, where?: AreaWhere, ctx?: WhereContext): Promise<ResolveError | ResolvedArea[]> | ResolvedBias | Promise<ResolvedBias>;
-export declare const resolveWithin: (where: AreaWhere, ctx: WhereContext) => Promise<ResolvedArea[] | ResolveError>;
-export declare const resolveNearby: (where: AreaWhere, ctx: WhereContext) => Promise<ResolvedBias>;
+export declare function resolveWhere(options: ResolveAreasOptions, where?: AreaWhere, context?: WhereContext): Promise<ResolveError | ResolvedArea[]> | ResolvedBias | Promise<ResolvedBias>;
+export declare const resolveWithin: (where: AreaWhere, context: WhereContext) => Promise<ResolvedArea[] | ResolveError>;
+export declare const resolveNearby: (where: AreaWhere, context: WhereContext) => Promise<ResolvedBias>;
 export declare const resolveGlobal: () => ResolvedBias;
 export type ResolvedArea = {
   bbox: BBox;
@@ -3322,7 +3749,7 @@ export type ResolvedAreaDisclosure = {
   query?: string;
   matched: string;
 };
-export declare const isResolveError: (r: unknown) => r is ResolveError;
+export declare const isResolveError: (value: unknown) => value is ResolveError;
 //#endregion
 //#region src/tools/shared/route-utils.d.ts
 /**
@@ -3344,459 +3771,137 @@ export declare const routeUtils: {
   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
-/**
- * @module agent-toolkit-tools
- *
- * Compact schema documentation for the `Route` properties shape, reused by
- * every tool whose LLM-authored code reads a Routes FeatureCollection
- * (`analyseData`, `processData`), injected per entry as `routesByEntry[id]`.
- * Only the non-GeoJSON-standard bits are spelled out, since `Route` is a LineString Feature.
- */
-/** @ignore */
-export declare const ROUTES_SCHEMA_DOC: string;
-//#endregion
-//#region src/tools/shared/show-byod-on-map.d.ts
-/**
- * Render a BYOD entry on the map per the tool's `show` options: hide
- * previously-shown entries (per `hidePreviousEntries`), show the new entry, then
- * optionally fit the camera to every shown BYOD entry. Sequential by design —
- * map mutations must not race (see ENGINEERING-GUIDELINES §6).
- *
- * @ignore
- */
-export declare const showByodOnMap: (state: ToolState, byodEntryId: string, show: z.infer<typeof showByodSchema>) => Promise<z.infer<typeof shownByodSchema>>;
-//#endregion
-//#region src/tools/shared/show-entry-geometries.d.ts
-/** @ignore */
-export type ShowEntryGeometriesResult = {
-  fetched: number;
-  shown: boolean;
-};
-/**
- * Fetch boundary polygons for every place in an entry that has a geometry data source,
- * cache them on the entry, and optionally render them via the entry's GeometriesModule.
- *
- * Shared by tools that produce a single places entry (discoverPlaces, locatePlace) — they
- * differ only in how they shape the result into their output schemas.
- *
- * @ignore
- */
-export declare const showEntryGeometries: (state: ToolState, placesEntryId: string, config: NonNullable<z.infer<typeof showPlaceGeometriesSchema>>, options?: ToolExecuteOptions) => Promise<ShowEntryGeometriesResult>;
-//#endregion
-//#region src/tools/shared/show-places-on-map.d.ts
-/** @ignore */
-export declare const showResultsOnMap: (state: ToolState, placesEntryIds: readonly string[], show: z.infer<typeof showPlacesSchema>) => Promise<z.infer<typeof shownSchema>>;
-//#endregion
-//#region src/tools/shared/tool-state-where-context.d.ts
-/** Adapts the live `ToolState` to the narrow `WhereContext` the resolver depends on. Keeping this
- * mapping in one place lets resolveAreas stay testable without a ToolState. */
-export declare const toolStateToWhereContext: (state: ToolState, options?: ToolExecuteOptions) => WhereContext;
-//#endregion
-//#region src/tools/shared/viewport-bias.d.ts
-/**
- * Lowest zoom at which {@link getViewportBias} returns the map centre.
- *
- * @group Agent Toolkit
- */
-export declare const MIN_VIEWPORT_BIAS_ZOOM = 6;
-/**
- * Returns the map centre, to favour search results in view. Pass it as `{ position }` to a service's `geoBias`
- * or to {@link locatePlace}'s `bias`. Below `minZoom`, the view is too wide to say where the user means.
- *
- * @param map - The agent's base-map slice, `state.baseMap` in a tool's `execute`.
- * @returns The centre as `[longitude, latitude]`, or `undefined` below `minZoom`.
- *
- * @group Agent Toolkit
- */
-export declare const getViewportBias: (map: BaseMapState, minZoom?: number) => Position | undefined;
-/** @ignore */
-export declare const getViewportBoundingBox: (map: BaseMapState) => BBox;
-//#endregion
-//#region src/state/custom-geometries/entry.d.ts
-/**
- * Provenance metadata for a custom-geometries entry — captures every input
- * source that fed the polygon-producing operation. `sourceIds` holds tagged
- * ids in the same form `geometriesEntryIDs` accepts: `{ kind: 'place' }` for
- * a single place footprint, `{ kind: 'places' }` for every footprint in a
- * places entry, `{ kind: 'ranges' }` for an isochrone entry,
- * `{ kind: 'customGeometries' }` for a derived entry. `operation` is a short label for
- * the kind of computation that produced the entry (e.g. `'union'`, `'buffer'`,
- * `'h3-coverage'`).
- *
- * @group Agent Toolkit
- *
- * @ignore
- */
-type GeometryProvenance = {
-  /** Short label for the operation that produced this entry (free-form). */
-  operation?: string;
-  /** Tagged source ids that fed the producing operation. */
-  sourceIds: readonly GeometriesId[];
-};
-/**
- * A single entry in the custom-geometries history — output of `processData`
- * (and any future polygon-producing tool that doesn't naturally belong to
- * places or ranges).
- *
- * @group Agent Toolkit
- *
- * @ignore
- */
-type CustomGeometriesEntry = BaseEntry<PolygonFeature[]> & {
-  /** Inputs and operation that produced this entry. */
-  provenance: GeometryProvenance;
-  /**
-   * Per-entry GeometriesModule. Each entry owns its own module so display state
-   * (fill style, current features) lives on the entry instead of a shared slice-level
-   * module. Lazy-initialised via CustomGeometriesState helpers.
-   */
-  _module?: GeometriesModule;
-  /** True while this entry's `_module` is rendering on the map. */
-  _shown?: boolean;
-};
-//#endregion
-//#region src/state/custom-geometries/state.d.ts
-/**
- * Events fired by {@link CustomGeometriesState}. Subscribe via
- * `state.customGeometries.events.on(type, handler)`.
- *
- * @group Agent Toolkit
- */
-type CustomGeometriesStateEvents = {
-  /**
-   * An entry was added, or `reset()` cleared the history. `entries` is the full snapshot after
-   * the change, and `changedIds` lists the ids of the entries this change added, replaced in
-   * place, or removed.
-   */
-  'entries-change': {
-    entries: readonly CustomGeometriesEntry[];
-    changedIds: readonly string[];
-  };
-  /** The set of entries rendered on the map changed. */
-  'shown-change': ReadonlySet<string>;
-  /** The display policy switched between `single` and `multiple`. */
-  'mode-change': EntryMode;
-};
-/**
- * The state for derived or custom geometries, the output of `processData` and any future
- * polygon-producing tool whose result doesn't belong to a place or a reachable-range entry.
- *
- * As in {@link RangeState}, each entry owns a dedicated GeometriesModule, initialised lazily
- * on first show. Provenance metadata captures the input sources (tagged ids) and the
- * operation that produced the polygons.
- *
- * @group Agent Toolkit
- */
-declare class CustomGeometriesState implements ShownEntriesSlice, StateSlice {
-  private readonly _ttMap;
-  private _entries;
-  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;
-  /** Set of custom-geometries entry ids currently rendered on the map. */
-  get shownEntryIds(): ReadonlySet<string>;
-  /**
-   * The display policy. `multiple` (default) lets several derived-geometry entries render
-   * side by side. `single` allows at most one entry on the map, and switching to it hides
-   * older entries.
-   */
-  get entryMode(): EntryMode;
-  setEntryMode(mode: EntryMode): Promise<void>;
-  findById(entryId: string): CustomGeometriesEntry | undefined;
-  /**
-   * Appends a new entry and returns its assigned id. If `explicitId` collides, the slice adds a
-   * 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. 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:
-   * - `'replace'` (default) shows exactly `entry.data` and clears whatever the
-   *   entry's module rendered before.
-   * - `'add'` merges `entry.data` with the polygons shown on this entry's layer,
-   *   deduped by feature id. It matters mostly when re-showing the same entry.
-   *
-   * Other entries are handled separately. With `entryMode === 'single'`, other shown
-   * entries are hidden first. Otherwise the caller uses `hideEntry` or the tools'
-   * `hidePreviousEntries` option.
-   */
-  showEntry(entryId: string, fillStyle?: GeometryFillStyle, mode?: 'add' | 'replace'): Promise<void>;
-  private _hideOthersUnderSingleMode;
-  hideEntry(entryId: string): Promise<void>;
-  /** Clears an entry's module, then drops the entry from history. Does nothing for an unknown id. */
-  removeEntry(entryId: string): Promise<void>;
-  private _requireEntry;
-  /**
-   * Hides every custom-geometries entry on the map but keeps the history. Implements
-   * {@link ClearableMapSlice}.
-   */
-  clearShown(): Promise<void>;
-  reset(): void;
-}
-//#endregion
-//#region src/state/state.d.ts
-/**
- * The per-slice display policy. With `multiple` (default), several history entries can be on the
- * map at once. With `single`, only the most recent one stays. Switching from `multiple` to
- * `single` automatically drops every entry except the latest and clears their modules, so
- * the map matches the new policy immediately.
- *
- * @group Agent Toolkit
- */
-type EntryMode = 'single' | 'multiple';
-/**
- * A state slice that owns a history of entries and can be set to `single` or `multiple`
- * mode. Every {@link ToolState} slice with `setEntryMode` implements this shape, which lets
- * callers (the `setEntryMode` tool, `createMapAgent`'s `dataEntries` option, …) handle the
- * whole family uniformly without listing slice names.
- *
- * @group Agent Toolkit
- */
-interface EntryModeSlice {
-  readonly entryMode: EntryMode;
-  readonly entries: readonly {
-    readonly id: string;
-  }[];
-  setEntryMode(mode: EntryMode): Promise<void>;
-}
-/**
- * The data-entry kind names that `dataEntries` on `createMapAgent` uses. They extend the
- * analyse/process input kinds (`EntryDataKind`) with `ranges`, which has its own
- * entry-mode-supporting slice but is not a top-level input kind for those tools.
- *
- * The kind names are LLM-facing (`routes`, `incidents`) instead of slice names (`routing`,
- * `trafficIncidents`). The slice mapping is internal (see {@link DATA_ENTRY_KIND_TO_SLICE}).
- *
- * @group Agent Toolkit
- */
-type DataEntryKind = 'places' | 'routes' | 'incidents' | 'customGeometries' | 'trafficAreaAnalytics' | 'byod' | 'ranges';
-/**
- * Per-kind configuration accepted by `createMapAgent`'s `dataEntries` option.
- *
- * @group Agent Toolkit
- */
-type DataEntryConfig = {
-  /**
-   * When `false`, the kind is removed from the agent's tool surface entirely:
-   * - The kind disappears from the `analyseData` and `processData` scope and input fields.
-   * - Related recall, display and fetch tools are dropped from the registry
-   *   (see {@link TOOLS_BY_DATA_ENTRY_KIND}).
-   *
-   * Defaults to `true`.
-   */
-  enabled?: boolean;
-  /**
-   * The initial entry-display policy for the underlying slice. `single` keeps only the latest
-   * entry on the map and hides the others. `multiple` (default) lets several coexist.
-   */
-  entryMode?: EntryMode;
-};
-/**
- * Maps each {@link DataEntryKind} (LLM-facing name) to the {@link ToolState} slice key that
- * owns its entries. `createMapAgent` uses it to apply `entryMode` from
- * `dataEntries[kind].entryMode` to the right slice.
- *
- * @group Agent Toolkit
- */
-export declare const DATA_ENTRY_KIND_TO_SLICE: {
-  readonly places: "places";
-  readonly routes: "routing";
-  readonly incidents: "trafficIncidents";
-  readonly customGeometries: "customGeometries";
-  readonly trafficAreaAnalytics: "trafficAreaAnalytics";
-  readonly byod: "byod";
-  readonly ranges: "ranges";
+  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
 /**
- * The compile-time union of {@link ToolState} keys whose slice supports {@link EntryMode}.
- * Names match the {@link ToolState} keys exactly, such as `routing` (not `routes`) and
- * `customGeometries` (not `geometries`), so the slice name in the tool API never drifts
- * from the property on `state`.
+ * @module agent-toolkit-tools
  *
- * When a new slice implements `setEntryMode`, the union picks up its key, and the runtime
- * list {@link ENTRY_MODE_SLICE_NAMES} fails to type-check until the key is added there too.
+ * Compact schema documentation for the `Route` properties shape, reused by
+ * every tool whose LLM-authored code reads a Routes FeatureCollection
+ * (`analyseData`, `processData`), injected per entry as `routesByEntry[id]`.
+ * Only the non-GeoJSON-standard bits are spelled out, since `Route` is a LineString Feature.
+ */
+/** @ignore */
+export declare const ROUTES_SCHEMA_DOC: string;
+//#endregion
+//#region src/tools/shared/show-byod-on-map.d.ts
+/**
+ * Render a BYOD entry on the map per the tool's `show` options: hide
+ * previously-shown entries (per `hidePreviousEntries`), show the new entry, then
+ * optionally fit the camera to every shown BYOD entry. Sequential by design —
+ * map mutations must not race (see ENGINEERING-GUIDELINES §6).
  *
- * @group Agent Toolkit
+ * @ignore
  */
-type EntryModeSliceName = { [K in keyof ToolState]: ToolState[K] extends EntryModeSlice ? K : never; }[keyof ToolState];
+export declare const showByodOnMap: (state: ToolState, byodEntryId: string, show: z.infer<typeof showByodSchema>) => Promise<z.infer<typeof shownByodSchema>>;
+//#endregion
+//#region src/tools/shared/show-entry-geometries.d.ts
 /**
- * The runtime list of slice names that support entry mode. Its `satisfies` clause makes
- * drift a compile error. When a new {@link ToolState} slice gains `setEntryMode`, the
- * package won't build until this constant is updated.
+ * `error` is set when a Geometry Data request failed, so a failed fetch doesn't read as a place
+ * without a boundary.
  *
- * @group Agent Toolkit
+ * @ignore
  */
-export declare const ENTRY_MODE_SLICE_NAMES: readonly EntryModeSliceName[];
+export type ShowEntryGeometriesResult = {
+  fetched: number;
+  shown: boolean;
+  error?: string;
+};
 /**
- * A state slice that owns a set of "entries" (routes, ranges), each of which can be hidden
- * individually by id, and exposes the shown set. {@link RoutingState} and {@link RangeState}
- * implement it. Helpers that hide previously-shown entries before rendering a new one
- * consume it (see `hidePreviousShownEntries`).
+ * Fetch boundary polygons for every place in an entry that has a geometry data source,
+ * cache them on the entry, and optionally render them via the entry's GeometriesModule.
  *
- * {@link PlacesState} doesn't implement it, because it uses a wider per-entry marker-type
- * model (`removeShownEntries(ids)` instead of `hideEntry(id)`).
+ * Shared by tools that produce a single places entry (discoverPlaces, locatePlace) — they
+ * differ only in how they shape the result into their output schemas.
  *
- * @group Agent Toolkit
+ * @ignore
  */
-interface ShownEntriesSlice extends StateSlice {
-  readonly entryMode: EntryMode;
-  readonly shownEntryIds: ReadonlySet<string>;
-  hideEntry(entryId: string): Promise<void>;
-}
+export declare const showEntryGeometries: (state: ToolState, placesEntryId: string, config: NonNullable<z.infer<typeof showPlaceGeometriesSchema>>, options?: ToolExecuteOptions) => Promise<ShowEntryGeometriesResult>;
 //#endregion
-//#region src/state/byod/state.d.ts
+//#region src/tools/shared/show-places-on-map.d.ts
+/** @ignore */
+export declare const showResultsOnMap: (state: ToolState, placesEntryIds: readonly string[], show: z.infer<typeof showPlacesSchema>) => Promise<z.infer<typeof shownSchema>>;
+//#endregion
+//#region src/tools/shared/tool-state-where-context.d.ts
+/** Adapts the live `ToolState` to the narrow `WhereContext` the resolver depends on. Keeping this
+ * mapping in one place lets resolveWithin stay testable without a ToolState. */
+export declare const toolStateToWhereContext: (state: ToolState, options?: ToolExecuteOptions) => WhereContext;
+//#endregion
+//#region src/tools/shared/viewport-bias.d.ts
 /**
- * Events fired by {@link BYODState}. Subscribe via `state.byod.events.on(type, handler)`.
+ * Lowest zoom at which {@link getViewportBias} returns the map centre.
  *
  * @group Agent Toolkit
  */
-type BYODStateEvents = {
-  /**
-   * An entry was added or removed, or `reset()` cleared the history. `entries` is the full
-   * snapshot after the change, and `changedIds` lists the ids of the entries this change added,
-   * replaced in place, or removed.
-   */
-  'entries-change': {
-    entries: readonly BYODEntry[];
-    changedIds: readonly string[];
-  };
-  /** The set of entries rendered on the map changed. */
-  'shown-change': ReadonlySet<string>;
-  /** The display policy switched between `single` and `multiple`. */
-  'mode-change': EntryMode;
-};
+export declare const MIN_VIEWPORT_BIAS_ZOOM = 6;
 /**
- * Options accepted by {@link BYODState.addEntry}.
+ * Returns the map centre, to favour search results in view. Pass it as `{ position }` to a service's `geoBias`
+ * or to {@link locatePlace}'s `bias`. Below `minZoom`, the view is too wide to say where the user means.
+ *
+ * @param map - The agent's base-map slice, `state.baseMap` in a tool's `execute`.
+ * @returns The centre as `[longitude, latitude]`, or `undefined` below `minZoom`.
  *
  * @group Agent Toolkit
  */
-type AddBYODEntryOptions = {
-  /**
-   * Explicit MapLibre layer specs, never derived automatically. You pass them here,
-   * or the agent sets them via `setByodLayers`. Until then the entry renders nothing.
-   * Either way they are only stored, and {@link BYODState.showEntry} renders them.
-   */
-  layers?: CustomGeoJSONLayerSpec[];
-  /** Provenance for the data. Defaults to `{ kind: 'integrator' }`. */
-  source?: BYODSource;
-  /**
-   * Semantic entry id. Auto-suffixed (`-2`, `-3`, …) on collision. Defaults
-   * to `byod-N`.
-   */
-  explicitId?: string;
-};
+export declare const getViewportBias: (map: BaseMapState, minZoom?: number) => Position | undefined;
 /**
- * The verdict a {@link ByodSourceUrlValidator} returns. `{ valid: true }` explicitly allows
- * the fetch, and `{ valid: false, reason }` blocks it and surfaces the `reason` to the model
- * as the tool error.
+ * MapLibre reports a view across the antimeridian with an edge past ±180, and a view wider than the
+ * world with a span of 360 or more. The returned box wraps the edges, `west > east` across the
+ * antimeridian, and spans the whole world once the view does.
  *
- * @group Agent Toolkit
+ * @ignore
  */
-type ByodSourceUrlValidation = {
-  valid: true;
-} | {
-  valid: false;
-  reason: string;
-};
+export declare const getViewportBoundingBox: (map: BaseMapState) => BBox;
+//#endregion
+//#region src/state/custom-geometries/entry.d.ts
 /**
- * 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.
- *
- * 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.
+ * Provenance metadata for a custom-geometries entry — captures every input
+ * source that fed the polygon-producing operation. `sourceIds` holds tagged
+ * ids in the same form `geometriesEntryIDs` accepts: `{ kind: 'place' }` for
+ * a single place footprint, `{ kind: 'places' }` for every footprint in a
+ * places entry, `{ kind: 'ranges' }` for an isochrone entry,
+ * `{ kind: 'customGeometries' }` for a derived entry. `operation` is a short label for
+ * the kind of computation that produced the entry (e.g. `'union'`, `'buffer'`,
+ * `'h3-coverage'`).
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
-type ByodSourceUrlValidator = (url: URL) => ByodSourceUrlValidation | Promise<ByodSourceUrlValidation>;
+type GeometryProvenance = {
+  /** Short label for the operation that produced this entry (free-form). */
+  operation?: string;
+  /** Tagged source ids that fed the producing operation. */
+  sourceIds: readonly GeometriesId[];
+};
 /**
- * The state slice for BYOD (bring-your-own-data) GeoJSON layers, the customer-owned
- * data that doesn't fit places, routes, ranges or custom geometries. Each entry
- * wraps a {@link CustomGeoJSONModule} so the agent can render, query, and pipe it
- * through analyseData or processData.
- *
- * As in {@link CustomGeometriesState}, every entry owns its own module, initialised
- * lazily on first show.
+ * A single entry in the custom-geometries history — output of `processData`
+ * (and any future polygon-producing tool that doesn't naturally belong to
+ * places or ranges).
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
-declare class BYODState implements ShownEntriesSlice, StateSlice {
-  private readonly _ttMap;
-  private _entries;
-  private _entryMode;
-  /** The state change events, listed in {@link BYODStateEvents}. */
-  readonly events: StateEvents<BYODStateEvents>;
-  /**
-   * The optional authorization hook for `addByodSource` URL fetches (see
-   * {@link ByodSourceUrlValidator}). If unset, the built-in policy allows only
-   * public `https:` URLs.
-   */
-  sourceUrlValidator?: ByodSourceUrlValidator;
-  constructor(_ttMap: TomTomMap);
-  get entries(): readonly BYODEntry[];
-  get latestEntry(): BYODEntry | undefined;
-  /** Set of BYOD entry ids currently rendered on the map. */
-  get shownEntryIds(): ReadonlySet<string>;
-  get entryMode(): EntryMode;
-  setEntryMode(mode: EntryMode): Promise<void>;
-  findById(entryId: string): BYODEntry | undefined;
-  /**
-   * Appends a new BYOD entry and returns its assigned id. In `single` mode the new entry
-   * replaces every older one. It hides and drops them before pushing the new entry, so the
-   * caller never sees it rendered on top of a still-visible old one.
-   */
-  addEntry(data: FeatureCollection$1, label: string, options?: AddBYODEntryOptions): Promise<string>;
-  /**
-   * Replaces the MapLibre layer specs an entry renders under. If the entry already owns a
-   * module because it was shown at least once, the module's `applyConfig` runtime layer diff
-   * pushes the new specs live, without tear-down or flicker. Otherwise the specs are stored
-   * and the next {@link showEntry} picks them up. Throws on an unknown id.
-   */
-  setEntryLayers(entryId: string, layers: CustomGeoJSONLayerSpec[]): void;
-  /**
-   * Initialises the entry's CustomGeoJSONModule lazily. The module has a single
-   * source named `data`, configured with this entry's `layers`. To swap layers
-   * afterwards, call {@link setEntryLayers}, which pushes the new specs into this
-   * module via `applyConfig` instead of recreating it.
-   */
-  getEntryModule(entryId: string): Promise<CustomGeoJSONModule>;
-  /** Renders the entry on the map. */
-  showEntry(entryId: string): Promise<void>;
-  private _hideOthersUnderSingleMode;
-  hideEntry(entryId: string): Promise<void>;
-  /** Clears an entry's module, then drops the entry from history. Does nothing for an unknown id. */
-  removeEntry(entryId: string): Promise<void>;
-  private _requireEntry;
+type CustomGeometriesEntry = BaseEntry<PolygonFeature[]> & {
+  /** Inputs and operation that produced this entry. */
+  provenance: GeometryProvenance;
   /**
-   * Hides every BYOD layer on the map but keeps the history. Implements
-   * {@link ClearableMapSlice}.
+   * Per-entry GeometriesModule. Each entry owns its own module so display state
+   * (fill style, current features) lives on the entry instead of a shared slice-level
+   * module. Lazy-initialised via CustomGeometriesState helpers.
    */
-  clearShown(): Promise<void>;
-  reset(): void;
-}
+  _module?: GeometriesModule;
+  /** True while this entry's `_module` is rendering on the map. */
+  _shown?: boolean;
+};
 //#endregion
 //#region src/system-prompt.d.ts
 /**
@@ -3971,7 +4076,8 @@ export declare const buildSystemPrompt: ({ customPrompt, prefix, suffix }?: Buil
  * {@link ToolBuildOptions} (e.g. feature flags) at agent-creation time.
  *
  * createMapAgent includes it automatically unless includeDefaultTools is false.
- * For manual composition outside createMapAgent, use resolveTools().
+ * resolveTools() merges your additions, replacements and removals into it; createMapAgent then
+ * builds the builder entries and binds `help`.
  * It leaves out executeMaplibreCode, which runs model-written code in your page.
  * createExecuteMaplibreCodeTool() adds it.
  *
@@ -4058,8 +4164,9 @@ export declare const TOOLS_BY_DATA_ENTRY_KIND: Record<DataEntryKind, readonly To
  * materialised with empty {@link ToolBuildOptions} so the prompts reflect the
  * tool's default (full-surface) shape. Tools without prompts map to `[]`.
  *
- * Surface these in chat UIs to keep starter suggestions in sync with what the
- * tools can actually do. The registry stays the single source of truth.
+ * It covers the full default registry, whatever an agent's `dataEntries` or `tools`
+ * options drop, so filter the result to the agent's resolved tools before surfacing
+ * these as starter suggestions in a chat UI.
  *
  * @group Agent Toolkit
  */
@@ -4160,7 +4267,7 @@ export declare const extractLastUserText: (messages: ReadonlyArray<ModelMessage>
  * message with structured generation.
  *
  * @param options.model - Language model for classification (ideally fast/cheap like gpt-4o-mini)
- * @param options.maxHistoryMessages - Max prior turns for context. Default: 8
+ * @param options.maxHistoryMessages - Max prior messages, user and assistant alike, for context. Default: 8
  * @param options.maxHistoryMessageLength - Max chars per history message. Default: 300
  *
  * @group Agent Toolkit
@@ -4280,9 +4387,10 @@ export type CodeExecutionConfig = {
   timeoutMs?: number;
   /**
    * Optional override of the worker's library source. By default, the SDK loads its own
-   * inlined turf/h3 UMD (a separate lazy chunk), so this is rarely needed. Supply it only
-   * to pin a specific build or add libraries. Return UMD/IIFE JavaScript that defines
-   * `self.turf` and `self.h3` (string or Promise of one).
+   * inlined turf/h3 UMD and worker utilities (a separate lazy chunk), so this is rarely needed.
+   * Supply it only to pin a specific build. The returned source replaces the bundled one whole:
+   * return UMD/IIFE JavaScript (string or Promise of one) that defines `self.turf` and `self.h3`,
+   * plus `self.routeUtils` and `self.cluster` if generated code uses them.
    */
   loadWorkerLibrarySource?: () => string | Promise<string>;
   /**
@@ -4342,15 +4450,7 @@ export type ToolEntry<S extends ToolState = ToolState, Scope = unknown> = {
   inputSchema: z.ZodType;
   /** Optional Zod schema describing the tool's structured output. */
   outputSchema?: z.ZodType;
-  /**
-   * Function that executes the tool. It receives the parsed input and the agent's state.
-   *
-   * If this calls a `@tomtom-org/maps-sdk/services` function directly, wrap its params with
-   * `withAgentToolkitHeaders` (`tools/shared/agent-headers.ts`) before passing them in, for example
-   * `const requestParams = withAgentToolkitHeaders({ position }); await reverseGeocode(requestParams);`.
-   * This tags the request so TomTom's traffic analytics attribute it to agent-toolkit. The guard
-   * test in `tools/shared/tests/agent-headers.test.ts` picks up an untagged call.
-   */
+  /** Function that executes the tool. It receives the parsed input and the agent's state. */
   execute: (input: any, state: S, options?: ToolExecuteOptions) => Promise<any>;
   /** Compact one-liner for the intent classifier prompt. */
   classificationPrompt?: string;
@@ -4368,7 +4468,8 @@ export type ToolEntry<S extends ToolState = ToolState, Scope = unknown> = {
    * Whether this tool stays active on every step regardless of the classifier's selection. Its name is
    * unioned into the per-turn `activeTools` set, so the model can always reach it. Use it sparingly,
    * for tools that may be needed to set up *any* request (e.g. asking the user to clarify intent).
-   * It has no effect on the fail-open path (when classification is skipped, every tool is active).
+   * A host `prepareStep` can't narrow it away either. It has no effect on the fail-open path (when
+   * classification is skipped, every tool is active).
    */
   alwaysActive?: boolean;
   /**
@@ -4404,7 +4505,7 @@ export type ToolEntry<S extends ToolState = ToolState, Scope = unknown> = {
 export type ToolMetadata = {
   /** Tool identifier, derived from the config key. */
   name: string;
-  /** Description of the tool's purpose, used by the SDK's system prompt. */
+  /** Description of the tool's purpose, which the model reads and the help tool's detail mode shows. */
   description: string;
   /** Compact one-liner for the intent classifier prompt. */
   classificationPrompt?: string;
@@ -4516,7 +4617,7 @@ export type ToolEntryBuilder<S extends ToolState = ToolState, Scope = unknown> =
  *
  * @typeParam S - The ToolState shape this tool requires. Default: base `ToolState`.
  * @typeParam Scope - Optional per-tool scope shape (only relevant for builder
- *   form). Defaults to `never` for non-scopable tools.
+ *   form). Defaults to `any`, so builders with any scope type fit.
  *
  * @group Agent Toolkit
  */
@@ -4527,7 +4628,7 @@ export type ToolDefinition<S extends ToolState = ToolState, Scope = any> = ToolE
  * @group Agent Toolkit
  */
 export type ToolExecutionInfo = {
-  /** Registered tool name (the `defaultTools` key). */
+  /** The name the tool is registered under: its `DEFAULT_TOOLS` or `MapAgentOptions.tools` key. */
   toolName: string;
   /** Wall-clock duration of `execute`, in milliseconds (includes any network/IO). */
   durationMs: number;
@@ -4599,7 +4700,7 @@ export type MapAgentOptions<CS extends ToolState = ToolState> = {
    * Tool overrides merged with default tools.
    * - {@link ToolDefinition} values (a `ToolEntry`, a builder, or a `DEFAULT_TOOLS` value) add a new
    *   tool or replace a default.
-   * - `false` values exclude a default tool.
+   * - `false` and `undefined` values exclude a default tool.
    *
    * When omitted, all default tools are used as-is.
    *
@@ -4628,13 +4729,13 @@ export type MapAgentOptions<CS extends ToolState = ToolState> = {
   /**
    * Per-kind data-entry configuration. Each {@link DataEntryKind} accepts
    * `{ enabled?, entryMode? }`. Setting `enabled: false` removes the kind from the
-   * agent's tool surface entirely. It disappears from `analyseData` / `processData`
+   * agent's data tools. It disappears from `analyseData` / `processData`
    * scope and input fields, and its slice-specific display / fetch tools
-   * ({@link TOOLS_BY_DATA_ENTRY_KIND}) are dropped from the registry. `recallState` stays.
+   * ({@link TOOLS_BY_DATA_ENTRY_KIND}) are dropped from the registry. `recallState` and `setMapStyling` stay.
    * `entryMode` is applied to the underlying slice right after the agent state is built, before any tool runs.
    *
    * Keys are LLM-facing kind names (`routes`, `incidents`), not slice names
-   * (`routing`, `trafficIncidents`). The slice mapping is internal.
+   * (`routing`, `trafficIncidents`). {@link DATA_ENTRY_KIND_TO_SLICE} maps one to the other.
    *
    * @example
    * ```typescript
@@ -4705,7 +4806,8 @@ export type MapAgentOptions<CS extends ToolState = ToolState> = {
   onToolExecute?: OnToolExecute;
   /**
    * Custom prepareStep hook, composed with internal classification step.
-   * Your `activeTools` are intersected with the classifier's selection.
+   * Your `activeTools` are intersected with the classifier's selection, and every `alwaysActive`
+   * tool is added back.
    * 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.
@@ -4777,7 +4879,10 @@ export type MapAgentInstance<CS extends ToolState = ToolState> = ToolLoopAgent &
    * `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. */
+  /**
+   * Tears down by resetting all state slices that have a reset() method and destroying the code
+   * sandbox. The map keeps the agent-toolkit request tag `createMapAgent` set on it.
+   */
   destroy(): void;
 };
 //#endregion
@@ -4785,15 +4890,15 @@ export type MapAgentInstance<CS extends ToolState = ToolState> = ToolLoopAgent &
 /**
  * Creates a conversational agent toolkit that gives an LLM control over a TomTom map.
  *
- * It returns a ToolLoopAgent instance (compatible with DirectChatTransport) with
- * `state` and `destroy` attached. Classification runs transparently inside
- * `prepareStep`, so you need no wrapper type.
+ * It returns a ToolLoopAgent instance (compatible with DirectChatTransport) with `state`, `destroy`
+ * and `getCodeExecutionMode` attached ({@link MapAgentInstance}). 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.
+ * @returns A ToolLoopAgent with state access, cleanup and the code-execution mode.
  *
  * @example Basic usage
  * ```typescript
@@ -4829,7 +4934,7 @@ export declare const createMapAgent: <CS extends ToolState = ToolState>(map: Tom
  * Merges default tools with user overrides.
  *
  * - `ToolEntry` (or builder) values add or replace tools in `defaults`.
- * - `false` values remove tools from `defaults`.
+ * - `false` and `undefined` values remove tools from `defaults`.
  * - It returns a new object and never mutates `defaults`.
  *
  * Default entries may be {@link ToolEntryBuilder builders} that produce
@@ -4862,17 +4967,27 @@ export declare const resolveTools: <S extends ToolState>(defaults: Record<string
 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. */
+/**
+ * A single clarification question shown to the user. Exported so a host can type its form state.
+ *
+ * @group Agent Toolkit
+ */
 export declare const questionSchema: z.ZodObject<{
   id: z.ZodString;
   question: z.ZodString;
   options: z.ZodArray<z.ZodString>;
   multiSelect: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
-/** One clarification question, the unit a host UI renders. */
+/**
+ * One clarification question, the unit a host UI renders.
+ *
+ * @group Agent Toolkit
+ */
 type ClarifyIntentQuestion = z.infer<typeof questionSchema>;
 /**
- * Input schema for {@link executeClarifyIntent}.
+ * Input schema for the clarifyIntent tool.
+ *
+ * @group Agent Toolkit
  */
 export declare const clarifyIntentSchema: z.ZodObject<{
   intro: z.ZodOptional<z.ZodString>;
@@ -4884,11 +4999,9 @@ export declare const clarifyIntentSchema: z.ZodObject<{
   }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
- * Output schema for {@link executeClarifyIntent}. The tool resolves immediately, echoing back the
- * `intro` + `questions` (so a host can render the whole form) plus an `awaiting_user_response` status.
- * No "stop and wait" directive is echoed, because the description-level usage contract already carries
- * it. CLARIFY_FORM_PROMPT and CLARIFY_PROSE_PROMPT both tell the agent to STOP and wait, so repeating it
- * in the result would be redundant.
+ * Output schema for the clarifyIntent tool: the `intro` and `questions` echoed back, for a host to render.
+ *
+ * @group Agent Toolkit
  */
 export declare const clarifyIntentOutputSchema: z.ZodObject<{
   status: z.ZodLiteral<"awaiting_user_response">;
@@ -4900,11 +5013,23 @@ export declare const clarifyIntentOutputSchema: z.ZodObject<{
     multiSelect: z.ZodDefault<z.ZodBoolean>;
   }, z.core.$strip>>;
 }, z.core.$strip>;
-/** Usage contract appended to the description when the host renders the form: silent turn, questions not restated in prose. */
+/**
+ * Usage contract appended to the description when the host renders the form: silent turn, questions not restated in prose.
+ *
+ * @group Agent Toolkit
+ */
 export declare const CLARIFY_FORM_PROMPT: string;
-/** Usage contract appended to the description when there is no form. The model also writes the questions as prose so any UI shows them. */
+/**
+ * Usage contract appended to the description when there is no form. The model also writes the questions as prose so any UI shows them.
+ *
+ * @group Agent Toolkit
+ */
 export declare const CLARIFY_PROSE_PROMPT: string;
-/** Per-call overrides accepted by {@link createClarifyIntentTool}. */
+/**
+ * Per-call overrides accepted by {@link createClarifyIntentTool}.
+ *
+ * @group Agent Toolkit
+ */
 type ClarifyIntentToolOptions = {
   /** Replace the default tool description (e.g. add domain-specific guidance). */
   description?: string;
@@ -4941,10 +5066,17 @@ type ClarifyIntentToolOptions = {
  *     },
  * });
  * ```
+ *
+ * @group Agent Toolkit
  */
 export declare const createClarifyIntentTool: (options?: ClarifyIntentToolOptions) => ToolEntry;
 //#endregion
 //#region src/tools/utilities/get-current-location.d.ts
+/**
+ * Options of {@link createGetCurrentLocationTool}.
+ *
+ * @group Agent Toolkit
+ */
 type GetCurrentLocationToolOptions = {
   /**
    * Whether the model gets the exact position, the device's accuracy and the fix's timestamp, from a
@@ -4963,6 +5095,8 @@ type GetCurrentLocationToolOptions = {
  *     tools: { getCurrentLocation: createGetCurrentLocationTool({ fullPrecision: true }) },
  * });
  * ```
+ *
+ * @group Agent Toolkit
  */
 export declare const createGetCurrentLocationTool: (options?: GetCurrentLocationToolOptions) => ToolEntry;
 //#endregion