@tomtom-org/maps-sdk-plugin-agent-toolkit 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -23,6 +23,7 @@ import { Position } from 'geojson';
 import { PrepareStepFunction } from 'ai';
 import { ReachableRangeBudget } from '../../../../services/dist';
 import { Routes } from '../../../../core/dist';
+import { Routes as Routes_2 } from '../../../../../core/dist';
 import { RoutingModule } from '../../../../map/dist';
 import { TomTomMap } from '../../../../map/dist';
 import { TomTomMap as TomTomMap_2 } from '../../map/dist';
@@ -60,14 +61,167 @@ declare type AddBYODEntryOptions = {
     explicitId?: string;
 };
 
+/**
+ * Session-level registry of EVERY analysis — the single source of truth that replaces the per-entry
+ * `_analyses` stores. 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}. Held on `ToolState` as `state.analyses`.
+ *
+ * Pure storage + lifecycle. The one recurrence engine lives elsewhere: the standing sweep in
+ * `tools/state/analyses-runtime.ts` (reads {@link sweepCandidates}), which replays both `sandbox` and
+ * `deterministic` records. `_wired` is a one-shot guard the sweep reads so it subscribes to slice
+ * events once.
+ *
+ * @group Agent Toolkit
+ */
+declare class Analyses {
+    private readonly _records;
+    private _wired;
+    /** Subscribe to {@link AnalysesEvents} — fired whenever a result is attached or recomputed. */
+    readonly events: StateEvents<AnalysesEvents>;
+    /** True once the tools-layer sweep has subscribed to slice change events. Set via {@link markWired}. */
+    get wired(): boolean;
+    /** Mark the session as wired so {@link wired} guards a repeat subscription. */
+    markWired(): void;
+    /**
+     * Insert or replace a record's metadata + lifecycle (NOT its result — use {@link attachResult} for
+     * that). Re-registering an existing `analysisId` preserves its `enabled` flag and result history,
+     * UNLESS the sandbox `code` changed — in which case the history is dropped so the new recipe never
+     * inherits the old `previous`.
+     */
+    register(input: AnalysisRegistration): void;
+    /**
+     * Append a result to a record's timeline, evicting the oldest when the per-analysis cap is hit. A
+     * same-timestamp re-run (an id-stability re-read of an unchanged snapshot) overwrites the last entry
+     * rather than duplicating it. No-op (no emit) when the `analysisId` is unknown. Emits `analysis-change`.
+     */
+    attachResult(analysisId: string, result: EntryAnalysis): void;
+    /**
+     * Latest result of every analysis attached to `entryId`, in registration order. The on-demand
+     * replacement for the old per-entry `_analyses.results`. Linear scan over records — fine at session
+     * scale (one record per distinct analyseData name+sources, plus one per clustered incidents entry).
+     */
+    getAnalysesForEntry(entryId: string, type?: AnalysisType): readonly EntryAnalysis[];
+    /**
+     * Every analysis record, in registration order — the combined, cross-entry view. Pass a
+     * {@link AnalysisType} to restrict to one category (`'analysis'` for the operator-facing set,
+     * `'tracker-rule'` for tracker verdicts); omit it for every record. Read `record.history.at(-1)`
+     * for each one's latest result.
+     */
+    all(type?: AnalysisType): readonly AnalysisRecord[];
+    /** Full result timeline for one analysis, oldest first. Empty when unknown. */
+    history(analysisId: string): readonly EntryAnalysis[];
+    /** Latest result data threaded into the next replay as `previous`, or undefined. */
+    lastResult(analysisId: string): unknown;
+    get(analysisId: string): AnalysisRecord | undefined;
+    /** Flip an analysis on/off. Returns false when the id is unknown. */
+    setEnabled(analysisId: string, enabled: boolean): boolean;
+    /** Every enabled record, in registration order — the standing sweep's replay candidates. */
+    sweepCandidates(): AnalysisRecord[];
+    remove(analysisId: string): void;
+    /**
+     * Remove every record sharing a `name`, across all source entries. Mirrors the old per-entry
+     * `unregister(name)` which dropped a named analysis wherever it was attached.
+     */
+    removeByName(name: string): void;
+    /**
+     * Drop every record whose source entries are ALL gone — the single GC path now that entries no
+     * longer hold their analyses. The sweep wiring calls this on each `entries-change` with the live
+     * source-entry ids, so a removed entry's records are collected on the next change. A record over
+     * `[A, B]` survives while either is live (its `affectedEntryIds` keeps the dead id, which is
+     * harmless — nothing queries it).
+     */
+    pruneToLiveEntries(liveIds: ReadonlySet<string>): void;
+    /** Drop every record. Walked automatically by `destroyState` (duck-typed `reset`). */
+    reset(): void;
+}
+
+/** Events emitted by {@link Analyses}. One event for "an analysis result was attached or recomputed". */
+export declare 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)`.
+     */
+    'analysis-change': {
+        analysisId: string;
+        affectedEntryIds: readonly string[];
+    };
+};
+
+/**
+ * The metadata + lifecycle fields shared by {@link AnalysisRecord} and its {@link AnalysisRegistration}
+ * input — everything except `enabled` (defaulted on register) and the runtime-built `history`. The
+ * single source of truth for an analysis's declared shape, so the registry and its register input never
+ * drift.
+ *
+ * @group Agent Toolkit
+ */
+declare type AnalysisBase = {
+    /** Stable handle minted by {@link makeAnalysisId} (name + sorted source ids). */
+    analysisId: string;
+    name: string;
+    description?: string;
+    outputFormat: AnalysisOutputFormat;
+    /** What this record is for — `'analysis'` (default) or `'tracker-rule'`. See {@link AnalysisType}. */
+    type: AnalysisType;
+    /** Sandbox code replayed by the standing sweep. */
+    code?: string;
+    /** Original `analyseData` input descriptor (`MultiInputIds`); opaque here. */
+    inputs?: unknown;
+    /** Ids of every entry this analysis is attached to. The per-entry lookup key. */
+    affectedEntryIds: readonly string[];
+};
+
 declare type AnalysisOutputFormat = 'json' | 'chart';
 
+/**
+ * One analysis tracked by the session-level {@link Analyses} registry — the single home for every
+ * `analyseData` analysis, one-shot or monitored, across every entry kind. The shared {@link AnalysisBase}
+ * plus the registry-owned `enabled` flag and the runtime-built `history`. `affectedEntryIds` is the
+ * per-entry lookup key ({@link Analyses.getAnalysesForEntry}); `enabled` means "recomputes on source
+ * change". `history` is the bounded result timeline (replaces the old per-entry store); the latest is
+ * the current result and is threaded back into the sandbox code as `previous`.
+ *
+ * @group Agent Toolkit
+ */
+export declare type AnalysisRecord = AnalysisBase & {
+    /** Whether the standing sweep recomputes it when its source entry changes. */
+    enabled: boolean;
+    /** Bounded result timeline, oldest first (see {@link MAX_HISTORY_PER_ANALYSIS}). */
+    history: EntryAnalysis[];
+};
+
+/**
+ * {@link Analyses.register} input — the shared {@link AnalysisBase} plus an optional `enabled`
+ * (defaulted on register). No `history`; the registry builds that as results land.
+ *
+ * @group Agent Toolkit
+ */
+declare type AnalysisRegistration = Omit<AnalysisBase, 'type'> & {
+    type?: AnalysisType;
+    enabled?: boolean;
+};
+
+/**
+ * What an analysis record is FOR — its purpose, not its execution kind (every record is sandbox code).
+ * - `'analysis'`: an operator-facing `analyseData` result (the default), surfaced in the Analyses tab
+ *   and per-entry detail.
+ * - `'tracker-rule'`: a tracker rule's verdict. Recomputes, GC's, and reads by id exactly like an
+ *   analysis, but is its own enumerable category so the tracker can list its rules and operator views
+ *   can exclude them. Pass it to {@link Analyses.all} / {@link Analyses.getAnalysesForEntry} to filter.
+ *
+ * @group Agent Toolkit
+ */
+declare type AnalysisType = 'analysis' | 'tracker-rule';
+
 /**
  * The base system prompt that teaches the LLM how to use the agent toolkit tools.
  *
  * @remarks
- * Export this constant so consumers can reference or extend it when providing
- * a custom system prompt via `MapAgentOptions.systemPrompt`.
+ * Equivalent to `composeSystemPrompt()` with no overrides. Export this constant
+ * so consumers can reference or extend it when providing a custom system prompt
+ * via `MapAgentOptions.systemPrompt`. To replace just one section, prefer
+ * {@link composeSystemPrompt} instead of rebuilding the whole string.
  *
  * @example
  * ```typescript
@@ -81,7 +235,7 @@ declare type AnalysisOutputFormat = 'json' | 'chart';
  *
  * @group Agent Toolkit
  */
-export declare const BASE_SYSTEM_PROMPT = "You are a helpful map assistant with access to a TomTom interactive map and location services.\nIf a request is completely unrelated to geospatial topics, gracefully decline and steer the user back to map-related tasks you can help with.\n\nCOORDINATE ORDER:\n- All coordinates are [longitude, latitude] (GeoJSON standard)\n- All bounding boxes are [minLng, minLat, maxLng, maxLat]\n\nTOOL EXECUTION:\n- Call context-independent tools in the same step (parallel execution).\n- Many service tools have a show or showOnMap parameter \u2014 use it to display results on the map in one step instead of calling a separate show tool afterward.\n- Use standalone updatePlacesDisplay / updateRoutesDisplay / updateWaypointsDisplay only when displaying results already in context from a previous step.\n\nSESSION STATE & ENTRIES:\n- Seven append-only histories live in the session: `places`, `routes`, `ranges`, `customGeometries`, `trafficAreaAnalytics`, `trafficIncidents`, `byod`. Each tool call that produces results stores a new ENTRY (id like `places-3`, `routes-1`, `byod-0`) \u2014 these ids stay stable and are accepted by every show / recall / `processData` / `analyseData` tool via the matching `*EntryIDs` field.\n- Each slice has an `entryMode`: `multiple` (default \u2014 overlay several entries on the map) or `single` (only the latest entry stays; switching to it auto-drops every older entry from history). Inspect via `recallState` / `recallPlaces` / `recallRoutes` / `recallRanges` / `recallGeometries` / `recallByod` (traffic slices surface via `recallState`). Flip with `setEntryMode({ slice, mode })` when the user asks to \"only show one at a time\" or \"let me overlay multiple\".\n- Mode is sticky across turns \u2014 under `single`, calling another `discoverPlaces` automatically replaces the previous places entry.\n- Always check `recallX` (or `recallState`) before guessing entry ids; never invent them.\n\nLOCATION REFERENCE:\n- \"near me\" / \"my location\" / \"where I am\" \u2192 getCurrentLocation (user's physical GPS position, may prompt permission)\n- \"in this area\" / \"here on the map\" / \"near the map center\" \u2192 getViewport (map's current view)\n- If getCurrentLocation fails due to permission denial, fall back to getViewport as the reference point\n\nRESPONSE FORMATTING:\n- Use markdown in all responses\n- Show key information in bold\n- Use bullet lists when presenting multiple items or results\n- Keep responses concise \u2014 lead with the most relevant information\n\n";
+export declare const BASE_SYSTEM_PROMPT: string;
 
 /**
  * State for base map display: style, language, viewport, layers, and hillshade.
@@ -104,30 +258,20 @@ declare class BaseMapState implements StateSlice {
 
 /* Excluded from this release type: buildSystemPrompt */
 
+/* Excluded from this release type: BuildSystemPromptOptions */
+
 /**
- * A single analysis result attached to a BYOD entry. Produced by `analyseData`
- * when the entry is passed via `byodEntryIDs`; `data` is whatever the dynamic
- * code returned. Structurally identical to the other slices' analysis records
- * so the shared attach helper treats every slice uniformly.
+ * 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.
  *
  * @group Agent Toolkit
  */
-export declare type BYODAnalysis = {
-    /** Unique name within the parent entry (used as a key for the UI). */
-    name: string;
-    timestamp: number;
-    /** Optional human-readable description of what the analysis computed. */
-    description?: string;
-    /** How `data` should be interpreted — plain JSON or a Chart.js configuration. */
-    outputFormat: AnalysisOutputFormat;
-    /** Arbitrary analysis result returned by the dynamic code. */
-    data: unknown;
-};
+export declare type BYODAnalysis = EntryAnalysis;
 
 /**
  * Token-frugal description of a BYOD FeatureCollection's runtime shape: feature
  * count, the geometry types present, and a per-property profile. Stored on every
- * {@link BYODEntry} and surfaced through `addByodSource` / `recallByod`
+ * {@link BYODEntry} and surfaced through `addByodSource` / `recallState`
  * so the model never has to receive raw GeoJSON just to learn the schema.
  *
  * @group Agent Toolkit
@@ -177,11 +321,6 @@ export declare type BYODEntry = {
     _module?: CustomGeoJSONModule;
     /** True while this entry's `_module` is rendering on the map. */
     _shown?: boolean;
-    /**
-     * Analyses attached by `analyseData` (keyed by `name` — re-running an analysis with the
-     * same name replaces it). Empty / absent until the first analysis runs against this entry.
-     */
-    _analysis?: BYODAnalysis[];
 };
 
 /** Compact profile of one feature-`properties` key across the whole collection. */
@@ -215,6 +354,38 @@ export declare type BYODSource = {
     description?: string;
 };
 
+/**
+ * Verdict returned by a {@link ByodSourceUrlValidator}: explicitly allow the fetch with
+ * `{ valid: true }`, or block it with `{ valid: false, reason }` — the `reason` is surfaced
+ * to the model as the tool error.
+ *
+ * @group Agent Toolkit
+ */
+export declare type ByodSourceUrlValidation = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+
+/**
+ * App-supplied authorization hook for BYOD source URLs. Runs inside
+ * `addByodSource` AFTER the built-in scheme / size / timeout policy and BEFORE
+ * the network fetch. Return `{ valid: true }` to allow the fetch or
+ * `{ valid: false, reason }` to block it (see {@link ByodSourceUrlValidation}).
+ * May be sync or async — e.g. an allowlist lookup.
+ *
+ * The toolkit can't enforce SSRF guarantees the host itself can't, so it leaves
+ * the URL surface open by default; this hook lets a deployment add its own
+ * policy — refuse cloud-metadata endpoints (`169.254.169.254`), restrict to
+ * known hosts, etc. — without the SDK prescribing one for everyone. Configure
+ * via the `byod.validateSourceUrl` option on `createMapAgent`, or assign
+ * `state.byod.sourceUrlValidator` directly.
+ *
+ * @group Agent Toolkit
+ */
+export declare type ByodSourceUrlValidator = (url: URL) => ByodSourceUrlValidation | Promise<ByodSourceUrlValidation>;
+
 /**
  * State slice for BYOD (bring-your-own-data) GeoJSON layers — customer-owned
  * data that doesn't fit places / routes / ranges / custom-geometries. Each
@@ -232,6 +403,12 @@ declare class BYODState implements ShownEntriesSlice, StateSlice {
     private _entryMode;
     /** Subscribe to state changes — see {@link BYODStateEvents}. */
     readonly events: StateEvents<BYODStateEvents>;
+    /**
+     * Optional authorization hook for `addByodSource` URL fetches — see
+     * {@link ByodSourceUrlValidator}. Unset = no restriction beyond the built-in
+     * scheme / size / timeout policy.
+     */
+    sourceUrlValidator?: ByodSourceUrlValidator;
     constructor(_ttMap: TomTomMap);
     get entries(): readonly BYODEntry[];
     get latestEntry(): BYODEntry | undefined;
@@ -253,13 +430,6 @@ declare class BYODState implements ShownEntriesSlice, StateSlice {
      * specs are stored and the next {@link showEntry} picks them up. Throws on an unknown id.
      */
     setEntryLayers(entryId: string, layers: CustomGeoJSONLayerSpec[]): void;
-    /**
-     * Attach an analysis to an existing entry (replace if a result of the same name exists).
-     * Mirrors {@link CustomGeometriesState.addAnalysisToEntry} so the shared `analyseData`
-     * attach helper treats BYOD like every other analysable slice. No-op (returns `false`)
-     * when the entry is unknown.
-     */
-    addAnalysisToEntry(entryId: string, analysis: BYODAnalysis): boolean;
     /**
      * Lazy-init the entry's CustomGeoJSONModule. The module is created with a
      * single source named `data`, configured with this entry's `layers`. To swap
@@ -288,17 +458,19 @@ declare class BYODState implements ShownEntriesSlice, StateSlice {
  * @group Agent Toolkit
  */
 declare type BYODStateEvents = {
-    /** History changed — entry added, removed, or cleared via `reset()`. */
-    'entries-change': readonly BYODEntry[];
+    /**
+     * History changed — entry added, removed, or cleared via `reset()`. `entries` is the full
+     * snapshot after the change; `changedIds` lists the ids of the entries this specific change
+     * added, replaced in place, or removed.
+     */
+    'entries-change': {
+        entries: readonly BYODEntry[];
+        changedIds: readonly string[];
+    };
     /** Set of entries currently rendered on the map changed. */
     'shown-change': ReadonlySet<string>;
     /** Display policy switched between `single` and `multiple`. */
     'mode-change': EntryMode;
-    /** An analysis was attached to (or replaced on) an entry by `analyseData`. */
-    'analysis-added': {
-        entryId: string;
-        analysis: BYODAnalysis;
-    };
 };
 
 /**
@@ -381,6 +553,124 @@ export declare type ClassifierOptions = {
  */
 export declare const classifyUserIntent: (conversation: ConversationMessage[], options: ClassifierOptions) => Promise<ClassificationResult>;
 
+/** Output of {@link runClustering}. */
+export declare type ClusteringOutput = {
+    groups: ClusterResult[];
+};
+
+/** Tuneable parameters for {@link runClustering}. All optional with sensible defaults. */
+export declare type ClusteringParams = {
+    /** DBSCAN neighbourhood radius in km. Default: 0.5 */
+    eps?: number;
+    /** Minimum members to form a cluster. Default: 3 */
+    minMembers?: number;
+    /** Maximum clusters to return (top-N by total delay). Default: 6 */
+    maxClusters?: number;
+    /** Pre-filter rules applied before clustering. */
+    preFilter?: {
+        /** Categories to exclude entirely. Default: `['roadworks', 'road-closed']` */
+        excludeCategories?: string[];
+        /** Incidents with `delayInSeconds` below this are excluded (within excludeCategories). Default: 1 (i.e. exclude 0-delay) */
+        minDelaySeconds?: number;
+    };
+};
+
+/** A single cluster produced by {@link runClustering}. */
+export declare type ClusterResult = {
+    /** Stable identifier — reused across runs when member overlap >= 50%. */
+    id: string;
+    /** Geographic centre of the cluster `[lng, lat]`. */
+    centroid: [number, number];
+    /** Incident IDs belonging to this cluster. */
+    memberIds: string[];
+    /** Number of member incidents. */
+    size: number;
+    /** Sum of `delayInSeconds` across all members. */
+    totalDelaySeconds: number;
+    /** Maximum `delayInSeconds` among all members. */
+    peakDelaySeconds: number;
+    /** Diagonal of the cluster's bounding box in km. */
+    diameterKm: number;
+    /** Most-frequently referenced road numbers across members. */
+    primaryRoads: string[];
+    /** Most-frequent incident category across members (e.g. "jam"). */
+    primaryCategory: string;
+    /** Trend across recent snapshots — see {@link classifyTrend}. */
+    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.
+     */
+    delaySamples: number[];
+};
+
+/**
+ * Dedicated per-entry clustering state. Incident clustering is NOT a generic analysis — it is typed,
+ * first-class incidents state with its own home here. `output` is the latest {@link SandboxClusteringOutput}
+ * (the DBSCAN groups + the moment it was computed); `recipe` is how to recompute it (re-used by
+ * `tools/state/clusters-runtime.ts` to re-run on each monitor tick so clusters stay live). `recipe`
+ * is opaque here (a tools-layer `ClusterRecipe`) — the slice never interprets it, keeping the state layer
+ * tools-agnostic.
+ *
+ * @group Agent Toolkit
+ */
+declare type ClustersRecord = {
+    recipe: unknown;
+    output: SandboxClusteringOutput;
+};
+
+/** Direction a cluster's total delay is trending across recent snapshots. */
+export declare type ClusterTrend = 'growing' | 'fading' | 'steady' | 'new';
+
+/**
+ * Tunes `analyseData` / `processData` sandbox execution. **Where** the code runs is
+ * not configurable: it is chosen by environment — a sandboxed, opaque-origin
+ * iframe + Web Worker in the browser (no DOM/storage access, no network via CSP,
+ * terminable on timeout), and the main thread in Node / SSR (where that boundary
+ * has no equivalent). The options below only tune the isolated browser run.
+ *
+ * @group Agent Toolkit
+ */
+export declare type CodeExecutionConfig = {
+    /** Wall-clock budget per isolated (browser) run, in ms. Default: 5000. */
+    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).
+     */
+    loadWorkerLibrarySource?: () => string | Promise<string>;
+};
+
+/**
+ * Composes the base system prompt from {@link SYSTEM_PROMPT_SECTIONS}, applying
+ * any per-section overrides.
+ *
+ * @param overrides - Replacement **body** text keyed by section; omitted
+ * sections fall back to the default. The section heading is added automatically,
+ * so an override does not repeat it. Pass the result to
+ * `MapAgentOptions.systemPrompt`.
+ * @returns The composed system prompt string.
+ *
+ * @example
+ * ```typescript
+ * import { createMapAgent, composeSystemPrompt } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';
+ *
+ * const agent = createMapAgent(map, {
+ *   model: openai('gpt-4o'),
+ *   // No need to repeat "RESPONSE FORMATTING:" — it is prepended for you.
+ *   systemPrompt: composeSystemPrompt({
+ *     responseFormatting: 'Always respond in Spanish, and keep it terse.',
+ *   }),
+ * });
+ * ```
+ *
+ * @group Agent Toolkit
+ */
+export declare const composeSystemPrompt: (overrides?: SystemPromptSectionOverrides) => string;
+
 /**
  * A single turn in the conversation passed to {@link classifyUserIntent}.
  *
@@ -447,22 +737,13 @@ export declare const createDefaultClassifier: (options: {
 export declare const createMapAgent: <CS extends ToolState = ToolState>(map: TomTomMap_2, options: MapAgentOptions<CS>) => MapAgentInstance<CS>;
 
 /**
- * A single aggregation/analysis result attached to a custom-geometries entry.
- * Produced by `analyseData`; `data` is whatever the dynamic code returned.
+ * 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.
  *
  * @group Agent Toolkit
  */
-export declare type CustomGeometriesAnalysis = {
-    /** Unique name within the parent entry (used as a key for future UI). */
-    name: string;
-    timestamp: number;
-    /** Optional human-readable description of what the analysis computed. */
-    description?: string;
-    /** How `data` should be interpreted — plain JSON or a Chart.js configuration. */
-    outputFormat: AnalysisOutputFormat;
-    /** Arbitrary aggregation result returned by the dynamic code. */
-    data: unknown;
-};
+export declare type CustomGeometriesAnalysis = EntryAnalysis;
 
 /**
  * A single entry in the custom-geometries history — output of `processData`
@@ -479,8 +760,6 @@ export declare type CustomGeometriesEntry = {
     features: PolygonFeature[];
     /** Inputs and operation that produced this entry. */
     provenance: GeometryProvenance;
-    /** Accumulated analysis results linked to this entry. */
-    _analysis?: CustomGeometriesAnalysis[];
     /**
      * Per-entry GeometriesModule. Each entry owns its own module so display state
      * (theme, current features) lives on the entry instead of a shared slice-level
@@ -527,8 +806,6 @@ declare class CustomGeometriesState implements ShownEntriesSlice, StateSlice {
      * Returns the assigned id. Under `single` mode the new entry replaces every older one.
      */
     addEntry(features: PolygonFeature<CommonPlaceProps>[], provenance: CustomGeometriesEntry['provenance'], label: string, explicitId?: string): Promise<string>;
-    /** Attach an analysis to an existing entry (replace if a result of the same name exists). */
-    addAnalysisToEntry(entryId: string, analysis: CustomGeometriesAnalysis): boolean;
     /** Lazy-init the entry's GeometriesModule, applying / re-applying the requested theme. */
     getEntryGeometriesModule(entryId: string, theme?: GeometryTheme): Promise<GeometriesModule>;
     /**
@@ -563,15 +840,17 @@ declare class CustomGeometriesState implements ShownEntriesSlice, StateSlice {
  * @group Agent Toolkit
  */
 declare type CustomGeometriesStateEvents = {
-    /** History changed — entry added or cleared via `reset()`. */
-    'entries-change': readonly CustomGeometriesEntry[];
+    /**
+     * History changed — entry added or cleared via `reset()`. `entries` is the full snapshot after
+     * the change; `changedIds` lists the ids of the entries this specific change added, replaced in
+     * place, or removed.
+     */
+    'entries-change': {
+        entries: readonly CustomGeometriesEntry[];
+        changedIds: readonly string[];
+    };
     /** Set of entries currently rendered on the map changed. */
     'shown-change': ReadonlySet<string>;
-    /** A new analysis was attached to (or replaced on) an entry. */
-    'analysis-added': {
-        entryId: string;
-        analysis: CustomGeometriesAnalysis;
-    };
     /** Display policy switched between `single` and `multiple`. */
     'mode-change': EntryMode;
 };
@@ -650,25 +929,26 @@ export declare const DEFAULT_TOOLS: {
     getPOICategoryCodes: ToolDefinition;
     getTrafficIncidents: ToolDefinition;
     focusIncidents: ToolDefinition;
-    startTrafficIncidentsMonitor: ToolDefinition;
-    stopTrafficIncidentsMonitor: ToolDefinition;
+    clusterIncidents: ToolDefinition;
+    monitorAnalysis: ToolDefinition;
+    createTracker: ToolDefinition;
+    clearTracker: ToolDefinition;
+    getTrackerHistory: ToolDefinition;
+    getTrackers: ToolDefinition;
+    setTrafficIncidentsMonitor: ToolDefinition;
+    startRouteMonitor: ToolDefinition;
+    stopRouteMonitor: ToolDefinition;
     getTrafficAreaAnalytics: ToolDefinition;
-    queryTrafficAnalytics: ToolDefinition;
     updatePlacesDisplay: ToolDefinition;
     updateRoutesDisplay: ToolDefinition;
     updateTrafficAreaAnalyticsDisplay: ToolDefinition;
     updateWaypointsDisplay: ToolDefinition;
-    getShownTileIncidents: ToolDefinition;
     clearMap: ToolDefinition;
     flyTo: ToolDefinition;
     getViewport: ToolDefinition;
-    recallGeometries: ToolDefinition;
-    recallPlaces: ToolDefinition;
-    recallByod: ToolDefinition;
     addByodSource: ToolDefinition;
     setByodLayers: ToolDefinition;
     updateByodDisplay: ToolDefinition;
-    recallRoutes: ToolDefinition;
     getCurrentWaypoints: ToolDefinition;
     getStandardMapStyles: ToolDefinition;
     setMapStandardStyle: ToolDefinition;
@@ -684,12 +964,9 @@ export declare const DEFAULT_TOOLS: {
     zoomInOrOut: ToolDefinition;
     executeMaplibreCode: ToolDefinition;
     calculateBBox: ToolDefinition;
-    formatDistance: ToolDefinition;
-    formatDuration: ToolDefinition;
     getCurrentLocation: ToolDefinition;
     help: ToolDefinition;
     findReachableAreas: ToolDefinition;
-    recallRanges: ToolDefinition;
     recallState: ToolDefinition;
     resetState: ToolDefinition;
     setEntryMode: ToolDefinition;
@@ -704,6 +981,24 @@ export declare const DEFAULT_TOOLS: {
  */
 export declare const ENTRY_MODE_SLICE_NAMES: readonly EntryModeSliceName[];
 
+/**
+ * A single analysis result — the result of an `analyseData` run (one-shot or a `monitorAnalysis`
+ * standing replay). `data` is whatever the dynamic code returned. Identical across every entry kind.
+ *
+ * @group Agent Toolkit
+ */
+export declare type EntryAnalysis = {
+    /** Unique name within the parent entry — used as the key (re-attaching the same name replaces). */
+    name: string;
+    timestamp: number;
+    /** Optional human-readable description of what the analysis computed. */
+    description?: string;
+    /** How `data` should be interpreted — plain JSON or a Chart.js configuration. */
+    outputFormat: AnalysisOutputFormat;
+    /** Arbitrary aggregation result returned by the dynamic code. */
+    data: unknown;
+};
+
 /**
  * Tool-facing union of state slices that own analysable entries — the
  * vocabulary used by tools that read from multiple slices (`analyseData`,
@@ -919,9 +1214,14 @@ declare class IncidentMonitor {
     get isActive(): boolean;
     /**
      * Begin polling. Captures `deps` for the lifetime of the run, fires the first tick
-     * immediately, then schedules an interval. No-op when already running.
+     * immediately (unless `skipInitialTick`), then schedules an interval. No-op when already running.
+     *
+     * `skipInitialTick` is for the caller that JUST fetched the data itself (e.g. getTrafficIncidents
+     * arming monitoring on the entry it just loaded): the entry is already fresh, so an eager first
+     * tick would be a redundant duplicate fetch. Standalone callers leave it false so the monitor
+     * produces an initial snapshot without waiting a full interval.
      */
-    start(area: MonitoredArea, deps: IncidentMonitorDeps, intervalMs?: number): void;
+    start(area: MonitoredArea, deps: IncidentMonitorDeps, intervalMs?: number, skipInitialTick?: boolean): void;
     /** Stop polling and reset state. No-op when idle. */
     stop(): void;
     private _tick;
@@ -959,92 +1259,13 @@ declare type IncidentMonitorEvents = {
 };
 
 /**
- * Per-entry analysis registry: owns re-executing specs *and* the timeline of
- * their results. One thing, three parts — name, recipe (spec), output history —
- * kept together instead of split across sibling fields.
- *
- * Each named analysis keeps a bounded chronological history (see
- * {@link MAX_HISTORY_PER_ANALYSIS}) so consumers can trend results over time;
- * `getResult(name)` returns the most recent, `history(name)` the full timeline.
- *
- * Errors from individual specs are dropped silently — replay should never break
- * the monitor tick that triggered it.
+ * 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.
  *
  * @group Agent Toolkit
  */
-declare class IncidentsAnalyses {
-    private _specs;
-    private readonly _historyByName;
-    get specs(): readonly IncidentsAnalysisSpec[];
-    /**
-     * Latest result for each registered spec, in registration order. Specs whose
-     * history is empty (e.g. only failed runs) are skipped. UI layers that "render
-     * whatever analyses this entry has" should iterate this instead of poking at
-     * private history state.
-     */
-    get results(): readonly IncidentsAnalysis[];
-    /** Full timeline for a single named analysis, oldest first. Empty when unknown. */
-    history(name: string): readonly IncidentsAnalysis[];
-    /** Most recent result for a given analysis name, or undefined. */
-    getResult(name: string): IncidentsAnalysis | undefined;
-    /**
-     * Register a spec, or replace an existing one with the same name. When the new spec
-     * differs from the existing one (code, outputFormat, or description), drops history
-     * for that name — old results belong to a different analysis and must not leak into
-     * `getResult` / `results`, which describe the *current* spec. Identical re-registers
-     * are no-ops and preserve history (so trend continuity survives idempotent retries).
-     */
-    register(spec: IncidentsAnalysisSpec): void;
-    /** Drop a spec by name. No-op when unknown. Result history is preserved. */
-    unregister(name: string): void;
-    /**
-     * Append a result to the timeline for its name, evicting the oldest entry
-     * when the per-name cap is hit. Used by the slice for one-shot tool runs and
-     * by {@link replay} for each fresh tick.
-     */
-    attach(result: IncidentsAnalysis): void;
-    /**
-     * Re-run every registered spec against `data`, threading the previous result
-     * from the timeline. `sampledAt` is the canonical moment for this replay —
-     * shared with the entry data and the sandbox's `now`, so consumers can join
-     * across them safely. Each fresh result is appended before being returned.
-     * Failed specs are skipped.
-     */
-    replay(data: TrafficIncident[], sampledAt: number): Promise<IncidentsAnalysis[]>;
-}
-
-/**
- * A single aggregation/analysis result attached to a traffic-incidents entry.
- * Produced by `analyseData` (one-shot or `monitor`-rerun); `data` is whatever the dynamic code returned.
- *
- * @group Agent Toolkit
- */
-export declare type IncidentsAnalysis = {
-    /** Unique name within the parent entry (used as a key for future UI). */
-    name: string;
-    timestamp: number;
-    /** Optional human-readable description of what the analysis computed. */
-    description?: string;
-    /** How `data` should be interpreted — plain JSON or a Chart.js configuration. */
-    outputFormat: AnalysisOutputFormat;
-    /** Arbitrary aggregation result returned by the dynamic code. */
-    data: unknown;
-};
-
-/**
- * A registered, re-executing analysis. Produced by `analyseData` with `monitor: { entryId }`;
- * replayed by an entry's {@link IncidentsAnalyses} on every monitor-tick of its source.
- *
- * @group Agent Toolkit
- */
-declare type IncidentsAnalysisSpec = {
-    name: string;
-    description?: string;
-    outputFormat: AnalysisOutputFormat;
-    code: string;
-    /** Source entry id the spec reads from. */
-    source: string;
-};
+export declare type IncidentsAnalysis = EntryAnalysis;
 
 /**
  * A fresh batch of incidents from a single monitor tick, with the moment it was sampled.
@@ -1097,13 +1318,28 @@ export declare type MapAgentOptions<CS extends ToolState = ToolState> = {
     /** AI SDK language model instance. REQUIRED — no default provider. */
     model: LanguageModel;
     /**
-     * Complete system prompt that replaces the default.
-     * If provided, `systemPromptSuffix` is ignored.
+     * Either a full prompt string that replaces the default entirely, or a
+     * {@link SystemPromptSectionOverrides} map whose entries override individual
+     * sections of the built-in prompt (omitted sections keep their defaults).
+     *
+     * To extend a single section rather than replace it, read its default from
+     * the exported `SYSTEM_PROMPT_SECTIONS` map and override with a derived value
+     * (e.g. ``responseFormatting: `${SYSTEM_PROMPT_SECTIONS.responseFormatting}\n- Answer in Spanish.` ``).
+     *
+     * A full string ignores `systemPromptPrefix` and `systemPromptSuffix`;
+     * section overrides still honor both.
+     */
+    systemPrompt?: string | SystemPromptSectionOverrides;
+    /**
+     * Text prepended above the whole prompt as a preamble, separated by a blank
+     * line and carrying no heading. Applied on top of the base prompt or section
+     * overrides; ignored only when `systemPrompt` is a full replacement string.
      */
-    systemPrompt?: string;
+    systemPromptPrefix?: string;
     /**
-     * Additional text appended to the built-in prompt.
-     * Ignored if `systemPrompt` is provided.
+     * Additional text appended under an `ADDITIONAL INSTRUCTIONS` heading.
+     * Applied on top of the base prompt or section overrides; ignored only when
+     * `systemPrompt` is a full replacement string.
      */
     systemPromptSuffix?: string;
     /**
@@ -1161,13 +1397,48 @@ export declare type MapAgentOptions<CS extends ToolState = ToolState> = {
      *     dataEntries: {
      *         routes: { entryMode: 'single' },
      *         incidents: { entryMode: 'single' },
-     *         byod: { enabled: false }, // disables recallByod, addByodSource, setByodLayers, updateByodDisplay + byod scope on analyse/process
-     *         ranges: { enabled: false }, // disables findReachableAreas + recallRanges
+     *         byod: { enabled: false }, // disables recallState, addByodSource, setByodLayers, updateByodDisplay + byod scope on analyse/process
+     *         ranges: { enabled: false }, // disables findReachableAreas + recallState
      *     },
      * });
      * ```
      */
     dataEntries?: Partial<Record<DataEntryKind, DataEntryConfig>>;
+    /**
+     * BYOD (bring-your-own-data) options.
+     *
+     * @example
+     * ```typescript
+     * createMapAgent(map, {
+     *     model: openai('gpt-4o'),
+     *     byod: {
+     *         // Refuse cloud-metadata / private addresses; allow only known hosts.
+     *         validateSourceUrl: (url) =>
+     *             url.hostname === 'data.example.com'
+     *                 ? { valid: true }
+     *                 : { valid: false, reason: `Host "${url.hostname}" is not allowed.` },
+     *     },
+     * });
+     * ```
+     */
+    byod?: {
+        /**
+         * Authorize each `addByodSource` URL before it is fetched — see
+         * {@link ByodSourceUrlValidator}. Return `{ valid: true }` to allow or
+         * `{ valid: false, reason }` to block (sync or async). Runs in addition
+         * to the built-in scheme / size / timeout policy.
+         */
+        validateSourceUrl?: ByodSourceUrlValidator;
+    };
+    /**
+     * Tunes `analyseData` / `processData` sandbox execution — see {@link CodeExecutionConfig}.
+     * Where the code runs is chosen by environment (off-thread iframe-worker in the browser,
+     * main thread in Node/SSR), not configured here; these options only adjust the isolated
+     * browser run (`timeoutMs`, `loadWorkerLibrarySource`).
+     *
+     * @experimental
+     */
+    codeExecution?: CodeExecutionConfig;
     /**
      * Pluggable classifier for automatic tool selection.
      * - Omit to use the default LLM-based classifier (uses main model)
@@ -1254,6 +1525,18 @@ declare class MapPOIsState implements StateSlice {
     reset(): void;
 }
 
+/**
+ * The features within ONE source entry that matched the rule — the per-entry unit of a {@link Verdict}.
+ * `featureIds` is the matched SUBSET, not the whole entry: a rule selects features by arbitrary sandbox
+ * logic (proximity, threshold, filter), and that selection isn't recoverable from `entryId` alone (the
+ * entry holds every feature) without re-running the rule — so the verdict records exactly what matched.
+ * These are the features the UI highlights and the `summary` cites.
+ */
+export declare type MemberRef = {
+    entryId: string;
+    featureIds: string[];
+};
+
 /**
  * The geographic area a {@link TrafficIncidentsEntry} monitor is polling, captured at
  * monitor-start time and replayed on every tick.
@@ -1267,22 +1550,12 @@ export declare type MonitoredArea = {
 };
 
 /**
- * A single aggregation/analysis result attached to a places entry.
- * Produced by `analyseData`; `data` is whatever the dynamic code returned.
+ * 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.
  *
  * @group Agent Toolkit
  */
-export declare type PlacesAnalysis = {
-    /** Unique name within the parent entry (used as a key for future UI). */
-    name: string;
-    timestamp: number;
-    /** Optional human-readable description of what the analysis computed. */
-    description?: string;
-    /** How `data` should be interpreted — plain JSON or a Chart.js configuration. */
-    outputFormat: AnalysisOutputFormat;
-    /** Arbitrary aggregation result returned by the dynamic code. */
-    data: unknown;
-};
+export declare type PlacesAnalysis = EntryAnalysis;
 
 /**
  * A single entry in the place search history.
@@ -1303,8 +1576,6 @@ export declare type PlacesEntry = {
      * (`place.properties.dataSources.geometry.id`), matching the response shape of `geometryData`.
      */
     geometries?: PolygonFeature<CommonPlaceProps>[];
-    /** Accumulated analysis results linked to this entry. */
-    _analysis?: PlacesAnalysis[];
     /** Lazy place-id → Place index, built on first ID lookup through PlacesState.findPlaceById. */
     _byId?: Record<string, Place>;
     /** Lazy place-id → boundary polygon index, built on first lookup through PlacesState.getGeometryForPlace. */
@@ -1375,12 +1646,6 @@ declare class PlacesState implements StateSlice {
      */
     get latestPlace(): Place[] | undefined;
     addPlaceResult(place: Place | Places, label: string, explicitId?: string, connections?: PlaceConnectionDisplay[], geometries?: PolygonFeature<CommonPlaceProps>[]): Promise<string>;
-    /**
-     * Attach an analysis result to an existing entry. Analysis names are unique
-     * within a single entry — adding one with an existing name replaces it.
-     * Returns true on success, false if the entry doesn't exist.
-     */
-    addAnalysisToEntry(entryId: string, analysis: PlacesAnalysis): boolean;
     findPlaceById(placeId: string): {
         place: Place;
         entryId: string;
@@ -1475,15 +1740,18 @@ declare class PlacesState implements StateSlice {
  * @group Agent Toolkit
  */
 declare type PlacesStateEvents = {
-    /** History changed — entry added, replaced, or cleared via `reset()`. Payload: the full entries snapshot. */
-    'entries-change': readonly PlacesEntry[];
+    /**
+     * History changed — entry added, replaced, or cleared via `reset()`. `entries` is the full
+     * snapshot after the change; `changedIds` lists the ids of the entries this specific change
+     * added, replaced in place, or removed (the standing-analysis sweep matches these against each
+     * record's `affectedEntryIds`).
+     */
+    'entries-change': {
+        entries: readonly PlacesEntry[];
+        changedIds: readonly string[];
+    };
     /** Set of entries currently rendered on the map changed (or marker type swapped). */
     'shown-change': ReadonlySet<string>;
-    /** A new analysis was attached to (or replaced on) an entry. */
-    'analysis-added': {
-        entryId: string;
-        analysis: PlacesAnalysis;
-    };
     /** Boundary polygons were fetched and cached on an entry. */
     'geometries-change': {
         entryId: string;
@@ -1608,8 +1876,15 @@ declare class RangeState implements ShownEntriesSlice {
  * @group Agent Toolkit
  */
 declare type RangeStateEvents = {
-    /** Range history changed — entry added or cleared via `reset()`. */
-    'entries-change': readonly RangesEntry[];
+    /**
+     * Range history changed — entry added or cleared via `reset()`. `entries` is the full snapshot
+     * after the change; `changedIds` lists the ids of the entries this specific change added,
+     * replaced in place, or removed.
+     */
+    'entries-change': {
+        entries: readonly RangesEntry[];
+        changedIds: readonly string[];
+    };
     /** Set of ranges entries currently rendered on the map changed (multi-show under `multiple`). */
     'shown-change': ReadonlySet<string>;
     /** Display policy switched between `single` and `multiple`. */
@@ -1652,6 +1927,72 @@ export declare type ReachableRange = {
  */
 export declare const resolveTools: <S extends ToolState>(defaults: Record<string, ToolDefinition<S>>, overrides?: { [K in ToolNameHint]?: ToolEntry<S> | false | undefined; }) => Record<string, ToolDefinition<S>>;
 
+/**
+ * One-shot polling loop that recalculates a single route on an interval. Owns its timer, status, and
+ * error. Re-starting after `stop()` is allowed and resets all state.
+ *
+ * The monitor never knows about the entry that owns it — the `recalculate` closure captures the
+ * waypoints + params, and the caller decides what to do with each fresh snapshot. Mirrors
+ * `IncidentMonitor`; routes carry live traffic, so periodic recalculation keeps the entry fresh.
+ *
+ * @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;
+    /** True when the monitor is *currently* recalculating on its interval. */
+    get isRunning(): boolean;
+    /** True when the monitor has any activity (running or stopped-error). */
+    get isActive(): boolean;
+    /**
+     * Begin polling. Captures `deps` for the lifetime of the run, fires the first recalculation
+     * immediately (unless `skipInitialTick`), then schedules an interval. No-op when already running.
+     *
+     * `skipInitialTick` is for a caller that JUST calculated the route and only wants the recurring
+     * refresh — an eager first tick would be a redundant duplicate recalculation.
+     */
+    start(deps: RouteMonitorDeps, intervalMs?: number, skipInitialTick?: boolean): void;
+    /** Stop polling and reset state. No-op when idle. */
+    stop(): void;
+    private _tick;
+    private _failed;
+    private _releaseTimer;
+}
+
+/**
+ * Dependency injection for a {@link RouteMonitor}. Production code wires `recalculate` to a closure
+ * over `calculateRoute` + the entry's waypoints / params (so each tick re-runs the SAME route);
+ * tests pass a deterministic fake and override the timer.
+ *
+ * The recalculator returns just the routes — the monitor stamps `takenAt` itself so every consumer of
+ * one tick (entry data, derived analyses) agrees on the same canonical moment.
+ *
+ * @group Agent Toolkit
+ */
+declare type RouteMonitorDeps = {
+    recalculate: () => Promise<Routes_2>;
+    /** 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.
+ */
+declare type RouteMonitorEvents = {
+    /** A recalculation succeeded. Payload: the fresh snapshot. */
+    tick: RouteSnapshot;
+    /** A recalculation failed — the monitor has cleared its timer and moved to `stopped-error`. */
+    error: string;
+};
+
 /**
  * Route planning parameters stored in routing state.
  * Consumed by setRoute, addWaypointsToRoute, removeWaypointsFromRoute, and replaceWaypointInRoute.
@@ -1673,22 +2014,20 @@ export declare type RouteParams = {
 };
 
 /**
- * A single aggregation/analysis result attached to a routes entry.
- * Produced by `analyseData`; `data` is whatever the dynamic code returned.
+ * Lifecycle state of a per-entry route monitor. `stopped-error` indicates the last recalculation
+ * failed and the timer has been cleared — start the monitor again to retry.
  *
  * @group Agent Toolkit
  */
-export declare type RoutesAnalysis = {
-    /** Unique name within the parent entry (used as a key for future UI). */
-    name: string;
-    timestamp: number;
-    /** Optional human-readable description of what the analysis computed. */
-    description?: string;
-    /** How `data` should be interpreted — plain JSON or a Chart.js configuration. */
-    outputFormat: AnalysisOutputFormat;
-    /** Arbitrary aggregation result returned by the dynamic code. */
-    data: unknown;
-};
+declare type RoutePollingStatus = 'idle' | 'running' | 'stopped-error';
+
+/**
+ * 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.
+ *
+ * @group Agent Toolkit
+ */
+export declare type RoutesAnalysis = EntryAnalysis;
 
 /**
  * A single entry in the route calculation history.
@@ -1702,8 +2041,6 @@ export declare type RoutesEntry = {
     data: Routes;
     waypoints: WaypointLike[];
     params: RouteParams;
-    /** Accumulated analysis results linked to this entry. */
-    _analysis?: RoutesAnalysis[];
     /**
      * Per-entry RoutingModule. Each entry owns its own module so display state (which route
      * variant is selected, which waypoints are shown, layer theme) lives on the entry instead
@@ -1713,6 +2050,29 @@ export declare type RoutesEntry = {
     _module?: RoutingModule;
     /** True while this entry's `_module` is rendering routes/waypoints on the map. */
     _shown?: boolean;
+    /**
+     * Per-entry route monitor. Lazy-created on first {@link RoutingState.startMonitoring}; reused
+     * across stop/start cycles. Recalculates this route (same waypoints + params) on its interval so
+     * the entry stays fresh with live traffic.
+     */
+    _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.
+     */
+    _tick?: number;
+};
+
+/**
+ * A freshly recalculated route from a single monitor tick, with the moment it was sampled.
+ * Payload of {@link RoutingStateEvents.monitor-tick}.
+ *
+ * @group Agent Toolkit
+ */
+declare type RouteSnapshot = {
+    takenAt: number;
+    routes: Routes_2;
 };
 
 /**
@@ -1772,9 +2132,14 @@ declare class RoutingState implements ShownEntriesSlice {
      * layers don't pile up. Under `entryMode === 'multiple'` previously-shown entries stay
      * rendered, letting the caller overlay several routes at once.
      *
-     * Emits `shown-change` once the new entry is up.
-     */
-    showEntry(entryId: string): Promise<void>;
+     * Emits `shown-change` once the new entry is up. Pass `showWaypoints: false` to render the
+     * route lines without origin/stop/destination pins, and `showSummaryBubbles: false` to drop the
+     * per-route ETA bubbles (e.g. a monitored corridor backdrop).
+     */
+    showEntry(entryId: string, opts?: {
+        showWaypoints?: boolean;
+        showSummaryBubbles?: boolean;
+    }): Promise<void>;
     /** Slice-level main color persisted across entry swaps. Undefined when no theme has been set. */
     get mainColor(): string | undefined;
     /**
@@ -1807,14 +2172,29 @@ declare class RoutingState implements ShownEntriesSlice {
     get planningSlots(): PlanningWaypoint[];
     get params(): RouteParams;
     addRoutes(routes: Routes, waypoints: WaypointLike[], label: string): Promise<string>;
-    /**
-     * Attach an analysis result to an existing routes entry. Names are unique within a single
-     * entry — adding one with an existing name replaces it. Returns true on success, false if
-     * the entry doesn't exist.
-     */
-    addAnalysisToEntry(entryId: string, analysis: RoutesAnalysis): boolean;
     setWaypointAt(index: number, waypoint: WaypointLike): void;
     setParams(params: Partial<RouteParams>): void;
+    /**
+     * Replace a route entry's data in place (a monitor recalculated it). Bumps `_tick`, updates
+     * `data`/`timestamp`, emits `entries-change`, and re-renders the route on its module when shown.
+     * The `_tick` guard bails if a newer tick overwrote `data` while `showRoutes` awaited. No-op
+     * (returns false) when the entry is unknown. Mirrors `TrafficIncidentsState.replaceEntryData`.
+     */
+    replaceRouteData(entryId: string, routes: Routes, sampledAt: number): Promise<boolean>;
+    private _createMonitorForEntry;
+    /**
+     * Arm 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?: {
+        intervalMs?: number;
+        skipInitialTick?: boolean;
+    }): void;
+    /** Stop recalculating an entry; its last data stays. Emits `monitor-stop`. No-op when not running. */
+    stopMonitoring(entryId: string): void;
+    /** True when the entry is currently being recalculated on its interval. */
+    isMonitored(entryId: string): boolean;
     /**
      * Hide every route + waypoint set currently on the map. Map-only — history (`entries`)
      * stays intact. Implements {@link ClearableMapSlice}.
@@ -1829,21 +2209,77 @@ declare class RoutingState implements ShownEntriesSlice {
  * @group Agent Toolkit
  */
 declare type RoutingStateEvents = {
-    /** Route history changed — new calculation stored, analysis attached, or cleared via `reset()`. */
-    'entries-change': readonly RoutesEntry[];
+    /**
+     * Route history changed — new calculation stored, analysis attached, or cleared via `reset()`.
+     * `entries` is the full snapshot after the change; `changedIds` lists the ids of the entries
+     * this specific change added, replaced in place, or removed.
+     */
+    'entries-change': {
+        entries: readonly RoutesEntry[];
+        changedIds: readonly string[];
+    };
     /** Sparse waypoint planning slots changed (origin/stop/destination assignment). */
     'planning-change': readonly PlanningWaypoint[];
     /** Route parameters (alternatives, cost model, depart/arrive time) changed. */
     'params-change': RouteParams;
-    /** A new analysis was attached to (or replaced on) a routes entry. */
-    'analysis-added': {
-        entryId: string;
-        analysis: RoutesAnalysis;
-    };
     /** Set of routes entries currently rendered on the map changed (multi-show under `multiple`). */
     'shown-change': ReadonlySet<string>;
     /** Display policy switched between `single` and `multiple`. */
     'mode-change': EntryMode;
+    /** Monitoring began on an entry (idle → running). Skipped when already running. */
+    'monitor-start': {
+        entryId: string;
+    };
+    /**
+     * Monitoring halted on an entry. `reason: 'manual'` covers explicit `stopMonitoring` and entry
+     * teardown (remove / reset); `reason: 'error'` fires alongside `monitor-error`.
+     */
+    'monitor-stop': {
+        entryId: string;
+        reason: 'manual' | 'error';
+    };
+    /** A monitored route was recalculated (per-tick). The entry's data has been updated in place. */
+    'monitor-tick': {
+        entryId: string;
+        snap: RouteSnapshot;
+    };
+    /** A monitored route's recalculation failed — the monitor cleared its timer and stopped. */
+    'monitor-error': {
+        entryId: string;
+        error: string;
+    };
+};
+
+/**
+ * {@link runClustering} output plus the moment it was computed. The extra `sampledAt` lets the sandbox
+ * `cluster()` primitive thread the trend window forward without the caller juggling timestamps: it is
+ * stamped onto the result and read back off `previous` on the next call.
+ *
+ * @group Agent Toolkit
+ */
+declare type SandboxClusteringOutput = ClusteringOutput & {
+    sampledAt?: number;
+};
+
+/**
+ * Pluggable strategy for executing sandbox code. The default
+ * {@link mainThreadExecutor} compiles + runs in the host realm; an alternative
+ * executor (e.g. the iframe-worker one) can run the same code in a locked-down
+ * realm off the main thread while honouring this exact contract.
+ *
+ * `run` MUST resolve to `{ value }` or `{ error }` and never reject — execution
+ * failures are reported as `{ error }` via {@link formatSandboxExecutionError}.
+ *
+ * @group Agent Toolkit
+ */
+export declare type SandboxExecutor = {
+    run<Result = unknown>(code: string, paramNames: readonly string[], args: readonly unknown[], verb: string): Promise<{
+        value: Result;
+    } | {
+        error: string;
+    }>;
+    /** Release any held resources (iframe / worker). No-op for the main-thread executor. */
+    destroy?(): void;
 };
 
 /**
@@ -1940,7 +2376,7 @@ export declare type StateDigest = {
  *
  * Usage from outside the slice (subscribe-only):
  * ```ts
- * const unsub = state.places.events.on('entries-change', (entries) => render(entries));
+ * const unsub = state.places.events.on('entries-change', ({ entries }) => render(entries));
  * // ...
  * unsub();
  * ```
@@ -1973,6 +2409,90 @@ export declare interface StateSlice {
     reset(): void;
 }
 
+/**
+ * The default body text for each base-prompt section — heading excluded.
+ *
+ * @remarks
+ * Each value is the section's content only; the structural heading (e.g.
+ * `RESPONSE FORMATTING:`) is added by {@link composeSystemPrompt}. So an override
+ * passes just the body — `composeSystemPrompt({ responseFormatting: 'Reply in Spanish.' })`
+ * still renders under the `RESPONSE FORMATTING:` heading.
+ *
+ * The behavioral prose is split so each concern is overridable on its own:
+ * - `identity` — who the assistant is and its tone of voice; the natural hook to
+ *   rebrand or set a persona.
+ * - `capabilities` — the map environment plus a compact summary of what the
+ *   toolkit can do. Kept at the group level (not per-tool) so it does not drift
+ *   as tools change; the exact mechanics live in each tool's description and the
+ *   classifier prompt. It also gives `rejectionRules` something concrete to steer
+ *   the user back toward.
+ * - `rejectionRules` — how to handle in-scope / mixed / out-of-scope / illegal
+ *   requests, and the requirement to always explain a rejection.
+ * - `dataConfidence` — how to surface incomplete, partial, stale, or conflicting
+ *   data instead of presenting it as complete.
+ *
+ * Location-reference routing ("near me" → getCurrentLocation, "here" →
+ * getViewport) is intentionally NOT a section: it is a tool-selection rule
+ * already owned by the classifier prompt and the two tools' cross-referencing
+ * descriptions.
+ *
+ * This map is the canonical source of the default body text, exported so a
+ * consumer can read a default and override with a derived value (extend, prefix,
+ * or rewrite it) — see {@link SystemPromptSectionOverrides}.
+ *
+ * @group Agent Toolkit
+ */
+export declare const SYSTEM_PROMPT_SECTIONS: Record<SystemPromptSection, string>;
+
+/**
+ * @module agent-toolkit-system-prompt
+ *
+ * Behavioral contract: persona, tone, dual-response, cadence — lives here.
+ *
+ * Tool mechanics: call shape, return shape, error handling, when-to-use vs.
+ * which-tool-next — lives in the relevant tool's description string and Zod
+ * schema. Each tool re-explains its own role; the LLM sees those alongside
+ * this prompt. The intent classifier (see `utils/intent-classifier.ts`) also
+ * scopes tools per step, so a tool's description is only in context when that
+ * tool is active — keep cross-cutting safety rules here (always present), and
+ * leave per-tool mechanics to the tool itself.
+ *
+ * If you find yourself adding lines here to fix an LLM mistake, ask first
+ * whether the fix belongs in a tool description or a tool error message.
+ *
+ * The prompt is split into named {@link SYSTEM_PROMPT_SECTIONS} so consumers can
+ * override a single section via {@link composeSystemPrompt} without rebuilding
+ * the whole string.
+ */
+/**
+ * Named, individually-overridable sections of the base system prompt.
+ *
+ * @group Agent Toolkit
+ */
+export declare type SystemPromptSection = 'identity' | 'capabilities' | 'rejectionRules' | 'responseFormatting' | 'dataConfidence' | 'toolExecution' | 'sessionState';
+
+/**
+ * Per-section body overrides. Each key replaces that section's body; omitted
+ * sections fall back to {@link SYSTEM_PROMPT_SECTIONS}. Accepted by
+ * {@link composeSystemPrompt} and `MapAgentOptions.systemPrompt`.
+ *
+ * @remarks
+ * To *extend* rather than replace a section, read its current default from the
+ * exported {@link SYSTEM_PROMPT_SECTIONS} map and override with a derived string
+ * — e.g. append a rule, prepend a note, or hand the default to a coding agent to
+ * rewrite under some criteria:
+ *
+ * ```typescript
+ * composeSystemPrompt({
+ *   // Keep the default behaviour, add one extra line.
+ *   responseFormatting: `${SYSTEM_PROMPT_SECTIONS.responseFormatting}\n- Always answer in Spanish.`,
+ * });
+ * ```
+ *
+ * @group Agent Toolkit
+ */
+export declare type SystemPromptSectionOverrides = Partial<Record<SystemPromptSection, string>>;
+
 /**
  * All valid default tool names, derived from {@link DEFAULT_TOOLS}.
  *
@@ -2185,26 +2705,140 @@ export declare type ToolState = {
     customGeometries: CustomGeometriesState;
     /** Bring-your-own-data GeoJSON layers — customer-authored data the agent can read and render. */
     byod: BYODState;
+    /**
+     * Strategy used to run code-generation tools (`analyseData` / `processData`).
+     * Initialised to the main-thread executor by `createToolState`, and overridden
+     * by `createMapAgent` from {@link MapAgentOptions.codeExecution}. Tools read this
+     * to select where sandbox code runs.
+     */
+    codeExecution: SandboxExecutor;
+    /**
+     * Single session-level registry of every analysis (one-shot + recurring) across all entry kinds.
+     * Replaces the old per-entry `_analyses` stores: results live here, and per-entry views read them
+     * on demand via {@link Analyses.getAnalysesForEntry}. `analyseData` registers; `monitorAnalysis`
+     * toggles `enabled`.
+     */
+    analyses: Analyses;
+    /**
+     * Generic trackers — thin rising-edge reducers over `type: 'tracker-rule'` analyses. A tracker fires
+     * an alert/event when its rule's {@link Verdict} crosses an edge. Reacts to `analysis-change`; owns
+     * the durable {@link TrackerEvent} log.
+     */
+    trackers: TrackerState;
 };
 
 /**
- * A single aggregation/analysis result attached to a traffic-area-analytics entry.
- * Produced by `analyseData`; `data` is whatever the dynamic code returned.
+ * One tracker = one rule: an NL condition compiled to a `tracker-rule` analysis, plus its rising-edge
+ * state. Inputs are NOT stored — read `analyses.get(analysisId)?.affectedEntryIds` for the entries the
+ * rule watches, and a verdict's `members` for the ones that matched.
+ */
+export declare type Tracker = {
+    id: string;
+    name: string;
+    /** Natural-language condition (LLM-readable); the compiled code lives on the analysis record. */
+    rule: string;
+    /** The `type: 'tracker-rule'` analysis whose `data` is this tracker's {@link Verdict}. */
+    analysisId: string;
+    enabled: boolean;
+    /** The one bit of memory: was the verdict active at the last recompute (rising-edge detection). */
+    wasActive: boolean;
+    /** Rising-edge time of the current open episode, if active. */
+    openedAt?: number;
+};
+
+/** One thing that happened — a tracker crossing an edge. The durable record the feed + toasts render. */
+export declare type TrackerEvent = {
+    id: string;
+    /** Source-data sample time of the recompute that fired it (NOT wall-clock). */
+    at: number;
+    trackerId: string;
+    trackerName: string;
+    type: TrackerEventType;
+    kind: TrackerEventStatus;
+    summary: string;
+    members: MemberRef[];
+    /** Rising-edge time of the episode this closes — present on `resolved`. */
+    openedAt?: number;
+};
+
+/** Rising edge (`opened`) vs falling edge (`resolved`). The only two statuses in the rising-edge model. */
+export declare type TrackerEventStatus = 'opened' | 'resolved';
+
+/** Toast-worthy (`alert`) vs quietly-logged (`event`). One store; the type discriminates. */
+export declare type TrackerEventType = 'alert' | 'event';
+
+/**
+ * Generic tracker store + rising-edge reducer. Held on `ToolState` as `state.trackers`. Pure
+ * storage + reaction: tools register/unregister trackers and register their rule analyses in
+ * {@link Analyses}; this slice maps analysis → tracker and reacts to `analysis-change`.
  *
  * @group Agent Toolkit
  */
-export declare type TrafficAreaAnalyticsAnalysis = {
-    /** Unique name within the parent entry (used as a key for future UI). */
-    name: string;
-    timestamp: number;
-    /** Optional human-readable description of what the analysis computed. */
-    description?: string;
-    /** How `data` should be interpreted — plain JSON or a Chart.js configuration. */
-    outputFormat: AnalysisOutputFormat;
-    /** Arbitrary aggregation result returned by the dynamic code. */
-    data: unknown;
+declare class TrackerState implements StateSlice {
+    private readonly analyses;
+    private readonly _trackers;
+    private readonly _log;
+    /** analysisId → tracker id, so the reducer ignores non-tracker analyses in O(1). */
+    private readonly _trackerByAnalysis;
+    private _seq;
+    readonly events: StateEvents<TrackerStateEvents>;
+    /**
+     * Subscribe the rising-edge reducer to the analyses registry for the slice's lifetime. The
+     * subscription is never torn down (it no-ops without trackers); `reset()` only clears data.
+     */
+    constructor(analyses: Analyses);
+    /**
+     * Register a tracker and index its analysis. The caller (createTracker) registers it with the
+     * rising-edge bit clear (`wasActive: false`) and attaches the arm-time verdict AFTER this call, so a
+     * condition already live at creation crosses false→true through the reducer and fires one `opened`
+     * alert. Emits `trackers-change`.
+     */
+    register(tracker: Tracker): void;
+    /** Remove a tracker and drop its analysis index entry. Returns the analysis id it freed, if any. */
+    unregister(trackerId: string): string | undefined;
+    /** Pause/resume a tracker. A paused tracker never crosses edges. Emits `trackers-change`. */
+    setEnabled(trackerId: string, enabled: boolean): boolean;
+    /** Live trackers, as copies so external mutation can't corrupt the store. */
+    get trackers(): readonly Tracker[];
+    get(trackerId: string): Tracker | undefined;
+    /**
+     * Trackers whose rule reads `entryId` — e.g. every tracker watching a given incidents area. Derived
+     * from each rule's analysis `affectedEntryIds` (the inputs are NOT duplicated onto the tracker), so it
+     * stays correct if a rule's inputs change. Drives "show all trackers for this area" in the UI.
+     */
+    trackersForEntry(entryId: string): readonly Tracker[];
+    /**
+     * 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?: {
+        trackerId?: string;
+        sinceMs?: number;
+    }): readonly TrackerEvent[];
+    /** Clear all trackers + log. The analyses subscription persists (no-ops without trackers). */
+    reset(): void;
+    private onAnalysisChange;
+    private append;
+    private emitTrackers;
+}
+
+/** Events emitted by {@link TrackerState}. */
+export declare type TrackerStateEvents = {
+    /** The tracker set or a tracker's live state changed (create / clear / enable / edge crossed). */
+    'trackers-change': readonly Tracker[];
+    /** A tracker crossed an edge — the freshly-logged event (drives toasts + feed append). */
+    'tracker-event': TrackerEvent;
 };
 
+/**
+ * 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.
+ *
+ * @group Agent Toolkit
+ */
+export declare type TrafficAreaAnalyticsAnalysis = EntryAnalysis;
+
 /**
  * A single entry in the traffic-area-analytics history — output of one
  * `getTrafficAreaAnalytics` call. Mirrors the per-entry model used by
@@ -2232,8 +2866,6 @@ export declare type TrafficAreaAnalyticsEntry = {
     _configChangeUnsub?: () => void;
     /** True while `_module` is rendering on the map. */
     _shown?: boolean;
-    /** Accumulated analysis results linked to this entry. */
-    _analysis?: TrafficAreaAnalyticsAnalysis[];
 };
 
 /**
@@ -2274,12 +2906,6 @@ declare class TrafficAreaAnalyticsState implements ShownEntriesSlice, StateSlice
      * replaces every older one (hidden + dropped from history).
      */
     addEntry(data: TrafficAreaAnalytics, label: string, params: TrafficAreaAnalyticsParams, explicitId?: string): Promise<string>;
-    /**
-     * Attach an analysis to an existing entry. Replaces the prior result keyed by `analysis.name`
-     * on the same entry (mirrors PlacesState / CustomGeometriesState semantics). Returns `false`
-     * when the entry id is unknown.
-     */
-    addAnalysisToEntry(entryId: string, analysis: TrafficAreaAnalyticsAnalysis): boolean;
     /**
      * Lazy-init the entry's TrafficAreaAnalyticsModule, wiring per-entry config-change events.
      * Throws on unknown id.
@@ -2307,8 +2933,15 @@ declare class TrafficAreaAnalyticsState implements ShownEntriesSlice, StateSlice
  * @group Agent Toolkit
  */
 declare type TrafficAreaAnalyticsStateEvents = {
-    /** History changed — entry added, removed, or cleared via `reset()`. */
-    'entries-change': readonly TrafficAreaAnalyticsEntry[];
+    /**
+     * History changed — entry added, removed, or cleared via `reset()`. `entries` is the full
+     * snapshot after the change; `changedIds` lists the ids of the entries this specific change
+     * added, replaced in place, or removed.
+     */
+    'entries-change': {
+        entries: readonly TrafficAreaAnalyticsEntry[];
+        changedIds: readonly string[];
+    };
     /** Set of entries currently rendered on the map changed. */
     'shown-change': ReadonlySet<string>;
     /** Per-entry viz config changed (mode / metric / scaleMode / …). */
@@ -2316,18 +2949,15 @@ declare type TrafficAreaAnalyticsStateEvents = {
         entryId: string;
         config: TrafficAreaAnalyticsConfig | undefined;
     };
-    /** A new analysis was attached to (or replaced on) an entry. */
-    'analysis-added': {
-        entryId: string;
-        analysis: TrafficAreaAnalyticsAnalysis;
-    };
     /** Display policy switched between `single` and `multiple`. */
     'mode-change': EntryMode;
 };
 
 /**
  * A single traffic-incidents history entry: the captured query, its incidents, and the
- * per-entry rendering / monitoring / analysis state owned by {@link TrafficIncidentsState}.
+ * per-entry rendering / monitoring state owned by {@link TrafficIncidentsState}. `analyseData` analyses
+ * are NOT held here — they live in the session-level `state.analyses` registry. Clustering IS dedicated
+ * incidents state, kept in the slice's `clusters` map keyed by entry id (see {@link ClustersRecord}).
  *
  * @group Agent Toolkit
  */
@@ -2345,12 +2975,6 @@ export declare type TrafficIncidentsEntry = {
     params: TrafficIncidentDetailsByBBoxParams & {
         bbox: BBox;
     };
-    /**
-     * Per-entry analysis registry: owns re-executing specs *and* their results.
-     * Lazy-created on first {@link TrafficIncidentsState.setAnalysisSpec} or
-     * {@link TrafficIncidentsState.addAnalysisToEntry}.
-     */
-    _analyses?: IncidentsAnalyses;
     /**
      * Per-entry incident-details module. Each entry owns its own module so two areas can be
      * rendered on the map at the same time without sharing a single source. Lazy-initialised
@@ -2377,7 +3001,7 @@ export declare type TrafficIncidentsEntry = {
      * Monotonic counter incremented on every {@link TrafficIncidentsState.replaceEntryData}
      * call. Used to detect out-of-order ticks: if a slow `module.show()` from an earlier
      * tick resolves after a newer tick has already overwritten `data`, the late path bails
-     * before reapplying focus / replaying analyses.
+     * before reapplying focus.
      */
     _tick?: number;
 };
@@ -2396,6 +3020,7 @@ declare class TrafficIncidentsState implements StateSlice {
     private readonly _ttMap;
     private _entries;
     private _entryMode;
+    private readonly _clusters;
     /** Subscribe to state changes — see {@link TrafficIncidentsStateEvents}. */
     readonly events: StateEvents<TrafficIncidentsStateEvents>;
     constructor(_ttMap: TomTomMap);
@@ -2427,9 +3052,11 @@ declare class TrafficIncidentsState implements StateSlice {
      * Replace an entry's data in place and repaint its module without moving the camera.
      * Used by the per-entry monitor tick so incident geometries and any open detail
      * panel stay in sync with the freshest snapshot. `sampledAt` is the canonical moment
-     * for this update — propagated to the entry timestamp and to every analysis the
-     * registry replays, so all derived data shares one tick. Returns true on success,
-     * false when the entry is unknown.
+     * for this update — propagated to the entry timestamp before the `entries-change` emit.
+     * That emit is what drives analysis replay: the session-level standing sweep
+     * (`tools/state/analyses-runtime.ts`) re-runs every analysis bound to this entry off the
+     * change, ASYNCHRONOUSLY (a microtask later) — the slice itself owns no analysis logic.
+     * Returns true on success, false when the entry is unknown.
      */
     replaceEntryData(entryId: TrafficIncidentsEntry['id'], data: TrafficIncident[], sampledAt: number): Promise<boolean>;
     /**
@@ -2456,19 +3083,17 @@ declare class TrafficIncidentsState implements StateSlice {
      */
     removeEntry(entryId: TrafficIncidentsEntry['id']): Promise<void>;
     /**
-     * Attach an analysis result to an existing entry. Names are unique within a single
-     * entry — adding one with an existing name replaces it. Returns true on success, false
-     * if the entry doesn't exist. Lazy-creates the entry's {@link IncidentsAnalyses}.
-     */
-    addAnalysisToEntry(entryId: TrafficIncidentsEntry['id'], analysis: IncidentsAnalysis): boolean;
-    /**
-     * Register (or replace) a re-executing analysis spec on its source entry. Names are unique
-     * per entry — adding one with an existing name replaces it. Lazy-creates the entry's
-     * {@link IncidentsAnalyses} on first call.
-     */
-    setAnalysisSpec(spec: IncidentsAnalysisSpec): void;
-    /** Remove a spec by name from every entry that carries it. */
-    removeAnalysisSpec(name: string): void;
+     * Store (or replace) an entry's clustering record and emit `clusters-change`. No-op when the entry is
+     * unknown — clusters are entry-scoped, so an orphan record is meaningless. Called by `clusterIncidents`
+     * and its monitor-tick re-run (`tools/state/clusters-runtime.ts`).
+     */
+    setClusters(entryId: TrafficIncidentsEntry['id'], record: ClustersRecord): void;
+    /** Latest clustering output for an entry, or undefined when none has been computed. */
+    getClusters(entryId: TrafficIncidentsEntry['id']): SandboxClusteringOutput | undefined;
+    /** Full clustering record (recipe + output) for an entry — the re-run reads this back. */
+    getClustersRecord(entryId: TrafficIncidentsEntry['id']): ClustersRecord | undefined;
+    /** Drop an entry's clustering. Emits `clusters-change` with `null`. No-op when nothing is stored. */
+    clearClusters(entryId: TrafficIncidentsEntry['id']): void;
     /** Snapshot of an entry's focus subset, or null when no focus is active or the entry is unknown. */
     getFocus(entryId: TrafficIncidentsEntry['id']): IncidentFocus | null;
     /**
@@ -2505,6 +3130,7 @@ declare class TrafficIncidentsState implements StateSlice {
      */
     startMonitoring(entryId: TrafficIncidentsEntry['id'], area: MonitoredArea, deps: IncidentMonitorDeps, opts?: {
         intervalMs?: number;
+        skipInitialTick?: boolean;
     }): void;
     /** Stop polling. No-op when idle or unknown. */
     stopMonitoring(entryId: TrafficIncidentsEntry['id']): void;
@@ -2517,7 +3143,6 @@ declare class TrafficIncidentsState implements StateSlice {
     isMonitored(entryId: TrafficIncidentsEntry['id']): boolean;
     private _createMonitorForEntry;
     private _requireEntry;
-    private _rerunRegisteredSpecs;
     private _teardownEntry;
     /**
      * Hide every traffic-incidents entry currently on the map. Map-only — history is kept.
@@ -2534,20 +3159,18 @@ declare class TrafficIncidentsState implements StateSlice {
  * @group Agent Toolkit
  */
 declare type TrafficIncidentsStateEvents = {
-    /** History changed — entry added, replaced, removed, or cleared via `reset()`. Payload: full entries snapshot. */
-    'entries-change': readonly TrafficIncidentsEntry[];
-    /** Set of entries currently rendered on the map changed. */
-    'shown-change': ReadonlySet<TrafficIncidentsEntry['id']>;
     /**
-     * A fresh analysis result landed on an entry. Fires when a spec is first
-     * registered, when it is replaced under the same name, AND on every monitor-tick
-     * replay — the event is intentionally agnostic about whether the spec is new
-     * or recomputed; subscribers re-render off the latest result either way.
+     * History changed — entry added, replaced, removed, or cleared via `reset()`. `entries` is the
+     * full snapshot after the change; `changedIds` lists the ids of the entries this specific change
+     * added, replaced in place, or removed. The standing-analysis sweep and the clustering re-run
+     * match these against the entries they depend on.
      */
-    'analysis-change': {
-        entryId: TrafficIncidentsEntry['id'];
-        analysis: IncidentsAnalysis;
+    'entries-change': {
+        entries: readonly TrafficIncidentsEntry[];
+        changedIds: readonly string[];
     };
+    /** Set of entries currently rendered on the map changed. */
+    'shown-change': ReadonlySet<TrafficIncidentsEntry['id']>;
     /** Focus subset for an entry changed (or cleared, when `focus === null`). */
     'focus-change': {
         entryId: TrafficIncidentsEntry['id'];
@@ -2582,6 +3205,15 @@ declare type TrafficIncidentsStateEvents = {
         entryId: TrafficIncidentsEntry['id'];
         reason: 'manual' | 'error';
     };
+    /**
+     * An entry's clustering result changed — set, recomputed on a tick, or cleared (`clusters === null`).
+     * UI that renders cluster pins re-derives off this (not `entries-change`): the clustering re-run is
+     * async to the monitor tick, so the fresh result lands here a step later.
+     */
+    'clusters-change': {
+        entryId: TrafficIncidentsEntry['id'];
+        clusters: SandboxClusteringOutput | null;
+    };
 };
 
 /**
@@ -2604,4 +3236,26 @@ declare class TrafficTilesState implements StateSlice {
     reset(): void;
 }
 
+/**
+ * What a tracker's sandboxed `evaluateCode` returns — stored verbatim as the rule analysis's `data`
+ * and read back by the reducer. `members` groups matches by source entry so a verdict can span
+ * multiple entry kinds (e.g. "an incident within 100m of a hospital" returns a hospitals group and an
+ * incidents group). `summary` is a grounded headline the code produces deterministically.
+ */
+export declare type Verdict = {
+    active: boolean;
+    members: MemberRef[];
+    summary: string;
+};
+
 export { }
+
+
+
+// Build-time virtual module (see the `sandbox-sdk-utils` plugin in
+// `vite-sandbox-build.ts`): the bundled SDK worker-utilities IIFE (`routeUtils`, …),
+// inlined as a string into the worker source. Declared here so `tsc` treats it as a
+// string module.
+declare module 'virtual:sandbox-sdk-utils' {
+    export const source: string;
+}