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

package/dist/index.d.ts

@@ -1,30 +1,44 @@
 import { BaseMapModule } from '../../../../map/dist';
 import { BBox } from '../../../../core/dist';
 import { BBox as BBox_2 } from '../../../../../core/dist';
+import { ChartConfiguration } from 'chart.js';
 import { CommonPlaceProps } from '../../../../core/dist';
 import { CustomGeoJSONLayerSpec } from '../../../../map/dist';
 import { CustomGeoJSONModule } from '../../../../map/dist';
+import { Feature } from 'geojson';
 import { FeatureCollection } from 'geojson';
+import { GeographyType } from '../../../../core/dist';
 import { GeometriesModule } from '../../../../map/dist';
 import { GeometryTheme } from '../../../../map/dist';
+import { HasLngLat } from '../../../../core/dist';
 import { HillshadeModule } from '../../../../map/dist';
 import { LanguageModel } from 'ai';
 import { Map as Map_2 } from 'maplibre-gl';
 import { ModelMessage } from 'ai';
+import { MultiPolygon } from 'geojson';
+import { OptionalBBox } from '../../../../core/dist';
 import { Place } from '../../../../core/dist';
 import { PlaceConnectionDisplay } from '../../../../map/dist';
 import { Places } from '../../../../core/dist';
 import { PlacesModule } from '../../../../map/dist';
 import { PlanningWaypoint } from '../../../../map/dist';
+import { POICategory } from '../../../../core/dist';
 import { POIsModule } from '../../../../map/dist';
+import { Polygon } from 'geojson';
 import { PolygonFeature } from '../../../../core/dist';
 import { PolygonFeatures } from '../../../../core/dist';
 import { Position } from 'geojson';
 import { PrepareStepFunction } from 'ai';
 import { ReachableRangeBudget } from '../../../../services/dist';
+import { Route } from '../../../../core/dist';
+import { RouteCoordinateAtProgress } from '../../../../core/dist';
+import { RouteProgressAtPoint } from '../../../../core/dist';
+import { RouteProgressQuery } from '../../../../core/dist';
 import { Routes } from '../../../../core/dist';
 import { Routes as Routes_2 } from '../../../../../core/dist';
+import { RouteSegmentProgress } from '../../../../core/dist';
 import { RoutingModule } from '../../../../map/dist';
+import { SectionProps } from '../../../../core/dist';
 import { TomTomMap } from '../../../../map/dist';
 import { TomTomMap as TomTomMap_2 } from '../../map/dist';
 import { ToolLoopAgent } from 'ai';
@@ -61,35 +75,57 @@ declare type AddBYODEntryOptions = {
     explicitId?: string;
 };
 
+/** @ignore */
+export declare type AffectedEntry = {
+    /** Unqualified entry id within the owning slice. */
+    id: string;
+    /** Which slice the entry lives in (only kinds that carry analyses are tracked). */
+    kind: 'places' | 'customGeometries';
+};
+
+/**
+ * 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"];
+
+/** Shared `describe()` text for the analyse-* `outputFormat` enum field. */
+export declare const ANALYSE_OUTPUT_FORMAT_DESCRIPTION: 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.
+ * Pure sink: metadata + result history only. 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/resume it ({@link job}) or compare its `code` on re-arm. A one-shot analysis keeps a paused
+ * job for later promotion.
  *
  * @group Agent Toolkit
  */
 declare class Analyses {
     private readonly _records;
-    private _wired;
+    /** analysisId → the {@link Job} backing it (one-shot = paused). The reference linking record to engine. */
+    private readonly _jobs;
     /** 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`.
+     * Insert or replace a record's metadata (NOT its result — use {@link attachResult}; nor its recipe —
+     * that lives on the {@link Job}). Re-registering an existing `analysisId` preserves its result
+     * history; callers drop stale history explicitly via {@link resetHistory} when the recipe changes.
      */
     register(input: AnalysisRegistration): void;
+    /** Store the {@link Job} backing an analysis — the reference linking this record to the engine. */
+    setJob(analysisId: string, job: Job): void;
+    /** The {@link Job} backing an analysis, if monitored or a retained one-shot. */
+    job(analysisId: string): Job | undefined;
+    /** Drop an analysis's result history — called on re-arm when the recipe changed (stale `previous`). */
+    resetHistory(analysisId: string): 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
@@ -101,42 +137,36 @@ declare class Analyses {
      * 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[];
+    getAnalysesForEntry(entryId: string): 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.
+     * Every analysis record, in registration order — the combined, cross-entry view. Read
+     * `record.history.at(-1)` for each one's latest result. (Tracker verdicts are no longer analyses, so
+     * every record here is operator-facing.)
      */
-    all(type?: AnalysisType): readonly AnalysisRecord[];
+    all(): 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[];
+    /** Whether the analysis is currently recomputed on source change (its job exists and is active). */
+    isMonitored(analysisId: string): boolean;
+    /** Remove an analysis: tear down its job and drop the record + handle. */
     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`). */
+    /** Drop every record + job handle. Walked automatically by `destroyState` (duck-typed `reset`). */
     reset(): void;
 }
 
-/** 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".
+ *
+ * @ignore
+ */
 export declare type AnalysesEvents = {
     /**
      * An analysis result landed (one-shot attach or a recompute). Carries the `analysisId` and the ids
@@ -148,71 +178,92 @@ export declare type AnalysesEvents = {
     };
 };
 
+export declare type AnalysisOutputFormat = 'json' | 'chart';
+
 /**
- * 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.
+ * 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. Pure sink state: metadata plus
+ * the bounded result `history`. The recipe (`code` / `inputs`) and recurrence are NOT here — they live on
+ * the analysis's {@link Job} (see `_jobs`). `affectedEntryIds` is the per-entry lookup key
+ * ({@link Analyses.getAnalysesForEntry}); `history` is the result timeline (oldest first), whose latest
+ * is the current result and is threaded back into the sandbox code as `previous`.
  *
  * @group Agent Toolkit
  */
-declare type AnalysisBase = {
+export declare type AnalysisRecord = {
     /** 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[];
+    /** Bounded result timeline, oldest first (see {@link MAX_HISTORY_PER_ANALYSIS}). */
+    history: EntryAnalysis[];
 };
 
-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`.
+ * {@link Analyses.register} input — the record's metadata. No `history` (the registry builds that as
+ * results land) and no recipe (that lives on the {@link Job}).
  *
  * @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[];
-};
+declare type AnalysisRegistration = Omit<AnalysisRecord, 'history'>;
 
 /**
- * {@link Analyses.register} input — the shared {@link AnalysisBase} plus an optional `enabled`
- * (defaulted on register). No `history`; the registry builds that as results land.
+ * Apply a sandbox-returned `fitOnMap` directive: move the camera to the bbox
+ * with the requested padding/animation, and return a normalized record for
+ * the tool's output payload.
  *
- * @group Agent Toolkit
+ * @ignore
  */
-declare type AnalysisRegistration = Omit<AnalysisBase, 'type'> & {
-    type?: AnalysisType;
-    enabled?: boolean;
-};
+export declare const applyFitOnMap: (state: ToolState, fit: FitOnMapInput) => z.infer<typeof fittedReportSchema>;
 
 /**
- * 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
+ * Administrative-AREA geography types accepted when resolving a query to a *containing area*
+ * (`within` mode). Restricting the geocode to these (via `entityTypeSet`) is what stops streets and
+ * POIs from drowning the area — e.g. "De Pijp" / "Westminster" geocode to Streets at rank 0 without
+ * it. Excludes `Country` (too coarse) and `PostalCodeArea` (homonym noise — "A10" → a Kazakh
+ * postcode).
+ */
+export declare const AREA_GEOGRAPHY_TYPES: GeographyType[];
+
+export declare type AreaSource = 'viewport' | 'boundingBox' | 'query' | 'placeId' | 'geometries' | 'route';
+
+/** The `where` fields this module resolves. `range` is deliberately excluded — callers resolve it
+ * themselves because the downstream endpoints differ (traffic bbox vs. searchInRange id).
+ * Inferred from `areaWhereSchema` so the LLM-facing tool schemas and the resolver can't drift. */
+export declare type AreaWhere = z.infer<typeof areaWhereSchema>;
+
+/**
+ * The resolver's input: the area-producing `where` fields. `z.infer` of this is `AreaWhere` in
+ * resolve-where.ts, so the LLM-facing tool schemas and the resolver input share one definition.
+ * No `range` — that maps to stored isochrones and is resolved caller-side.
+ * @ignore
  */
-declare type AnalysisType = 'analysis' | 'tracker-rule';
+export declare const areaWhereSchema: z.ZodObject<{
+    viewport: z.ZodOptional<z.ZodBoolean>;
+    boundingBox: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodNumber>]>>;
+    queries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        query: z.ZodString;
+        queryAs: z.ZodOptional<z.ZodEnum<{
+            place: "place";
+            poi: "poi";
+        }>>;
+    }, z.core.$strip>>>;
+    placeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    geometries: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodLiteral<"Polygon">;
+        coordinates: z.ZodArray<z.ZodArray<z.ZodArray<z.ZodNumber>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"MultiPolygon">;
+        coordinates: z.ZodArray<z.ZodArray<z.ZodArray<z.ZodArray<z.ZodNumber>>>>;
+    }, z.core.$strip>]>>>;
+    route: z.ZodOptional<z.ZodObject<{
+        routeId: z.ZodOptional<z.ZodString>;
+        widthMeters: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 
 /**
  * The base system prompt that teaches the LLM how to use the agent toolkit tools.
@@ -237,6 +288,45 @@ declare type AnalysisType = 'analysis' | 'tracker-rule';
  */
 export declare const BASE_SYSTEM_PROMPT: string;
 
+/**
+ * @module agent-toolkit-state
+ *
+ * Shared base shape for the per-slice history entries (places / routes / ranges / byod /
+ * custom-geometries / traffic-area-analytics / traffic-incidents). Every slice keeps an append-only
+ * history of entries, and they all share the same four fields — an `id`, a `timestamp`, a `label`,
+ * and a single `data` payload. Those live here so each slice's entry type can be written as
+ * `BaseEntry<TPayload> & { … }` plus only the fields unique to that slice (its per-entry display and
+ * runtime state).
+ *
+ * @group Agent Toolkit
+ */
+/**
+ * The fields shared by every history entry across the toolkit's state slices: identity
+ * (`id`), provenance (`timestamp`, `label`), and the slice's payload (`data`). Each slice intersects
+ * this with its own per-entry display state — e.g. `type RoutesEntry = BaseEntry<Routes> & { … }`.
+ *
+ * @typeParam TData - the entry's payload type (e.g. `Routes`, `Place[]`, `FeatureCollection`,
+ * `TrafficIncident[]`). It is the single result the entry was created to hold.
+ *
+ * @group Agent Toolkit
+ */
+declare type BaseEntry<TData> = {
+    /**
+     * Stable, slice-unique entry id (e.g. `places-0`, or a caller-supplied id deduped against
+     * existing entries on collision). Used to address the entry from tools and recall surfaces.
+     */
+    id: string;
+    /**
+     * Creation / last-refresh time, in milliseconds since the epoch. Set when the entry is added and
+     * bumped on each in-place replace (a monitored re-run stamps the source sample time).
+     */
+    timestamp: number;
+    /** Short, human-readable label for the entry — shown in recall / recents surfaces. */
+    label: string;
+    /** The entry's payload — the single result this entry was created to hold. */
+    data: TData;
+};
+
 /**
  * State for base map display: style, language, viewport, layers, and hillshade.
  *
@@ -256,15 +346,148 @@ declare class BaseMapState implements StateSlice {
     reset(): void;
 }
 
+export declare const biasDisclosure: (bias: ResolvedBias) => ResolvedAreaDisclosure[];
+
+/** The point-bias `where` fields (`nearby` mode). Exactly one is set by the schema. */
+export declare type BiasWhere = {
+    viewport?: boolean;
+    position?: Position;
+    query?: {
+        query: string;
+        queryAs?: QueryAs;
+    };
+};
+
+/**
+ * Builds the shared "return value" blurb for the analyse-* tools' `code` field.
+ * Encodes the JSON-only contract, the Chart.js config shape, and the
+ * `string[]`-label workaround for tooltip-callback use cases.
+ *
+ * @param jsonExamples Comma-separated examples of typical `json`-shape outputs
+ *   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.
+ */
+export declare const buildAnalyseReturnPrompt: (jsonExamples: string, chartLabelExample?: string) => string;
+
+/**
+ * Message used by the shared "at least one of …" refine. Lists the active kinds'
+ * field labels and the slash-joined recall-tool hints for the same set.
+ *
+ * @ignore
+ */
+export declare const buildAtLeastOneEntryIdMessage: (active: readonly EntryDataKind[]) => string;
+
+/**
+ * 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}.
+ *
+ * @ignore
+ */
+export declare const buildEntryFieldList: (active: readonly EntryDataKind[]) => string;
+
+/**
+ * Build the input-shape Record passed into `z.object({...})`. Both tools share this
+ * shape — each kind in the active set contributes its `*EntryIDs` field via
+ * {@link EntryKindMeta.buildField}. Tools layer their own per-tool fields onto the
+ * resulting record before calling `z.object`.
+ *
+ * @ignore
+ */
+export declare const buildEntryIdFields: (active: readonly EntryDataKind[], options: FieldBuildOptions) => Record<string, z.ZodTypeAny>;
+
+/**
+ * Join the per-kind sandbox-doc fragments in canonical order for the supplied active set.
+ * Returns the multi-line "Each input is …" block.
+ *
+ * @ignore
+ */
+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).
+ *
+ * @ignore
+ */
+export declare const buildEntryKindSchemaDocs: (active: readonly EntryDataKind[]) => string;
+
+/**
+ * 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";
+        customGeometries: "customGeometries";
+        routes: "routes";
+        incidents: "incidents";
+        trafficAreaAnalytics: "trafficAreaAnalytics";
+        byod: "byod";
+    }>>;
+}, z.core.$strip>;
+
+/**
+ * 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.
+ *
+ * @ignore
+ */
+export declare const buildPlacesSchemaDoc: (flags: FeatureFlags) => string;
+
+/**
+ * Compact sandbox-code blurb shared by `process-places`, `process-geometries`,
+ * `analyse-places`, `analyse-geometries`, and `analyse-routes`. Keeps the
+ * "what's in scope / what's forbidden" rules short and consistent across all
+ * code-generation tools so the LLM is prompted the same way each time. Pass
+ * the names of the injected identifiers (the params the AsyncFunction body
+ * receives) so the rule reads naturally for each tool.
+ *
+ * @ignore
+ */
+export declare const buildSandboxCodePrompt: (injected: readonly string[]) => string;
+
+/**
+ * Common "tools available in the sandbox" prompt section, shared verbatim by
+ * analyseData and processData so the injected-library docs live in ONE place and the
+ * two tools never drift. It documents the three function namespaces handed to every
+ * sandbox body — `turf` / `h3` (base usage rules via {@link buildSandboxCodePrompt}),
+ * the cross-kind turf cheat-sheet ({@link CROSS_KIND_OPS_DOC}), and `routeUtils`
+ * ({@link ROUTE_UTILS_DOC}) — in a fixed order. The two scope-gated docs are appended
+ * only when relevant: cross-kind when scope commits to more than one kind, routeUtils
+ * when `routes` is in scope (matching the conditional `routeUtils` usefulness). Returns
+ * a block ending in a blank line, ready to drop straight into either tool's `code` doc.
+ *
+ * @ignore
+ */
+export declare const buildSandboxToolsDoc: (active: readonly EntryDataKind[], scoped: boolean) => string;
+
 /* Excluded from this release type: buildSystemPrompt */
 
 /* Excluded from this release type: BuildSystemPromptOptions */
 
+/**
+ * Describes the per-entry input shape, surfaced by {@link buildSandboxToolsDoc} for every sandbox tool.
+ * Each requested kind is a single `<kind>ByEntry` record keyed by entry id — there is no flat/merged
+ * companion, so the model must access one entry by id or merge across entries explicitly. Spelling out
+ * the merge idioms keeps the model from assuming a bare `places`/`routes` array exists (it doesn't).
+ *
+ * @ignore
+ */
+export declare const BY_ENTRY_VIEWS_DOC: string;
+
 /**
  * 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
+ *
+ * @ignore
  */
 export declare type BYODAnalysis = EntryAnalysis;
 
@@ -275,6 +498,8 @@ export declare type BYODAnalysis = EntryAnalysis;
  * so the model never has to receive raw GeoJSON just to learn the schema.
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
 export declare type BYODDataProfile = {
     featureCount: number;
@@ -292,12 +517,10 @@ export declare type BYODDataProfile = {
  * through analyseData / processData.
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
-export declare type BYODEntry = {
-    id: string;
-    timestamp: number;
-    label: string;
-    data: FeatureCollection;
+export declare type BYODEntry = BaseEntry<FeatureCollection> & {
     /** Provenance for the data — used by recall tools and the UI. */
     source: BYODSource;
     /**
@@ -323,7 +546,11 @@ export declare type BYODEntry = {
     _shown?: boolean;
 };
 
-/** Compact profile of one feature-`properties` key across the whole collection. */
+/**
+ * Compact profile of one feature-`properties` key across the whole collection.
+ *
+ * @ignore
+ */
 export declare type BYODPropertyProfile = {
     /** Property key as it appears in `feature.properties`. */
     name: string;
@@ -342,6 +569,8 @@ export declare type BYODPropertyProfile = {
  * - `inline`: passed as inline GeoJSON via `addByodSource`.
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
 export declare type BYODSource = {
     kind: 'integrator';
@@ -473,6 +702,71 @@ declare type BYODStateEvents = {
     'mode-change': EntryMode;
 };
 
+/** Chart.js chart types accepted by the analyse-* tools when `outputFormat: "chart"`. */
+export declare const CHART_TYPES: Set<string>;
+
+/** Usage contract appended to the description when the host renders the form: silent turn, questions not restated in prose. */
+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. */
+export declare const CLARIFY_PROSE_PROMPT: string;
+
+/**
+ * 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 here: 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.
+ */
+export declare const clarifyIntentOutputSchema: z.ZodObject<{
+    status: z.ZodLiteral<"awaiting_user_response">;
+    intro: z.ZodOptional<z.ZodString>;
+    questions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodString>;
+        multiSelect: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+
+/** One clarification question — the unit a host UI renders. */
+export declare type ClarifyIntentQuestion = z.infer<typeof questionSchema>;
+
+/**
+ * Input schema for {@link executeClarifyIntent}.
+ */
+export declare const clarifyIntentSchema: z.ZodObject<{
+    intro: z.ZodOptional<z.ZodString>;
+    questions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodString>;
+        multiSelect: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+
+/** Per-call overrides accepted by {@link createClarifyIntentTool}. */
+export declare type ClarifyIntentToolOptions = {
+    /** Replace the default tool description (e.g. add domain-specific guidance). */
+    description?: string;
+    /** Replace the default classifier hint. */
+    classificationPrompt?: string;
+    /** Replace the default usage examples. */
+    examples?: string[];
+    /** Replace the default natural-language example prompts. */
+    examplePrompts?: string[];
+    /**
+     * Keep the tool active on every step regardless of the classifier (so the agent can always ask
+     * to clarify, even mid-task). Defaults to `true`; set `false` to leave activation to the classifier.
+     */
+    alwaysActive?: boolean;
+    /**
+     * Does your host render the clarifyIntent form? `true` → silent form contract; `false` (default) →
+     * the agent narrates the questions as prose so they reach a form-less UI.
+     */
+    rendersForm?: boolean;
+};
+
 /**
  * Result returned by {@link classifyUserIntent}.
  *
@@ -644,6 +938,41 @@ export declare type CodeExecutionConfig = {
     loadWorkerLibrarySource?: () => string | Promise<string>;
 };
 
+/** @ignore */
+export declare type CollectedGeometries = {
+    geometries: PolygonFeature[];
+    /** Place objects whose footprints contributed (used to seed processGeometries provenance). */
+    sourcePlaces: Place[];
+    /** Entries that should receive analyses (places + customGeometries; ranges don't carry analyses). */
+    affectedEntries: AffectedEntry[];
+    skipped: SkippedSource[];
+    /** Tagged ids that contributed at least one polygon, in input order. */
+    contributingSourceIds: GeometriesId[];
+};
+
+/**
+ * Resolves a heterogeneous list of tagged geometry ids into a single
+ * `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
+ * derived entry produced by a previous `processGeometries`.
+ *
+ * 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
+ * included here).
+ *
+ * @ignore
+ */
+export declare const collectInputGeometries: (sources: readonly GeometriesId[], state: ToolState) => Promise<{
+    value: CollectedGeometries;
+} | {
+    error: string;
+}>;
+
 /**
  * Composes the base system prompt from {@link SYSTEM_PROMPT_SECTIONS}, applying
  * any per-section overrides.
@@ -681,6 +1010,25 @@ declare type ConversationMessage = {
     content: string;
 };
 
+/**
+ * Build a clarifyIntent {@link ToolEntry}, optionally overriding its description and examples for a
+ * specific domain. The schema and `execute` are fixed; only the classifier-facing metadata is
+ * customizable. Pass the result to `createMapAgent`'s `tools` option to replace the built-in default:
+ *
+ * ```typescript
+ * createMapAgent(map, {
+ *     model,
+ *     tools: {
+ *         clarifyIntent: createClarifyIntentTool({
+ *             description: 'Ask before running a site analysis — surface demand anchors, competitors, scoring weights…',
+ *             examplePrompts: ['Profile this site for me', 'Rank these addresses'],
+ *         }),
+ *     },
+ * });
+ * ```
+ */
+export declare const createClarifyIntentTool: (options?: ClarifyIntentToolOptions) => ToolEntry;
+
 /**
  * Creates the default LLM-based classifier. Uses structured generation to select
  * the minimal tool set for each user message.
@@ -742,6 +1090,8 @@ export declare const createMapAgent: <CS extends ToolState = ToolState>(map: Tom
  * back-compat.
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
 export declare type CustomGeometriesAnalysis = EntryAnalysis;
 
@@ -751,13 +1101,10 @@ export declare type CustomGeometriesAnalysis = EntryAnalysis;
  * places or ranges).
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
-export declare type CustomGeometriesEntry = {
-    id: string;
-    timestamp: number;
-    label: string;
-    /** The polygons stored on this entry (Polygon / MultiPolygon GeoJSON Features). */
-    features: PolygonFeature[];
+export declare type CustomGeometriesEntry = BaseEntry<PolygonFeature[]> & {
     /** Inputs and operation that produced this entry. */
     provenance: GeometryProvenance;
     /**
@@ -810,9 +1157,9 @@ declare class CustomGeometriesState implements ShownEntriesSlice, StateSlice {
     getEntryGeometriesModule(entryId: string, theme?: GeometryTheme): Promise<GeometriesModule>;
     /**
      * Render this entry's polygons. `mode` is scoped to this entry's own layer:
-     * - `'replace'` (default) — show exactly `entry.features`, clearing whatever the
+     * - `'replace'` (default) — show exactly `entry.data`, clearing whatever the
      *   entry's module had rendered before.
-     * - `'add'` — merge `entry.features` with the polygons currently shown on this entry's
+     * - `'add'` — merge `entry.data` with the polygons currently shown on this entry's
      *   layer (deduped by feature id). Mostly only meaningful when re-showing the same entry.
      *
      * Cross-entry visibility is handled separately: under `entryMode === 'single'` other
@@ -965,6 +1312,7 @@ export declare const DEFAULT_TOOLS: {
     executeMaplibreCode: ToolDefinition;
     calculateBBox: ToolDefinition;
     getCurrentLocation: ToolDefinition;
+    clarifyIntent: ToolDefinition;
     help: ToolDefinition;
     findReachableAreas: ToolDefinition;
     recallState: ToolDefinition;
@@ -972,6 +1320,14 @@ export declare const DEFAULT_TOOLS: {
     setEntryMode: ToolDefinition;
 };
 
+/**
+ * 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>;
+
 /**
  * Runtime enumeration of slice names that support entry mode. The `satisfies` clause
  * makes drift a compile error: when a new {@link ToolState} slice gains `setEntryMode`,
@@ -986,6 +1342,8 @@ export declare const ENTRY_MODE_SLICE_NAMES: readonly EntryModeSliceName[];
  * standing replay). `data` is whatever the dynamic code returned. Identical across every entry kind.
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
 export declare type EntryAnalysis = {
     /** Unique name within the parent entry — used as the key (re-attaching the same name replaces). */
@@ -1015,6 +1373,35 @@ export declare type EntryAnalysis = {
  */
 export declare type EntryDataKind = 'places' | 'routes' | 'incidents' | 'customGeometries' | 'trafficAreaAnalytics' | 'byod';
 
+/**
+ * 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.
+ *
+ * @ignore
+ */
+export declare type EntryKindMeta = {
+    fieldName: string;
+    fieldLabel: string;
+    buildField: (options: FieldBuildOptions) => z.ZodTypeAny;
+    sandboxDoc: string;
+    schemaDoc: string;
+    recallTool: string;
+};
+
+/**
+ * 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 declare type EntryKindScope = {
+    kinds: readonly EntryDataKind[];
+};
+
 /**
  * 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
@@ -1057,6 +1444,63 @@ export declare type EntryModeSliceName = {
     [K in keyof ToolState]: ToolState[K] extends EntryModeSlice ? K : never;
 }[keyof ToolState];
 
+/**
+ * Generic tracker store + rising-edge reducer. Held on `ToolState` as `state.trackers`. Pure
+ * storage + reaction: tools register/unregister trackers and register their rule jobs on the
+ * {@link JobEngine}; each job's `run` feeds verdicts here via {@link ingestVerdict}. Keeps the
+ * {@link Job} handle backing each tracker (`_jobs`) so pausing a tracker pauses its job.
+ *
+ * @group Agent Toolkit
+ */
+declare class EventsState implements StateSlice {
+    private readonly _trackers;
+    private readonly _log;
+    /** trackerId → the {@link Job} backing it. The reference linking tracker to engine. */
+    private readonly _jobs;
+    private _seq;
+    readonly events: StateEvents<TrackerStateEvents>;
+    /**
+     * Register a tracker. The caller (createTracker) registers it with the rising-edge bit clear
+     * (`wasActive: false`) and feeds the arm-time verdict via {@link ingestVerdict} AFTER this call, so a
+     * condition already live at creation crosses false→true and fires one `opened` alert. Emits
+     * `trackers-change`.
+     */
+    register(tracker: Tracker): void;
+    /** Store the {@link Job} backing a tracker — the reference linking it to the engine. */
+    setJob(trackerId: string, job: Job): void;
+    /** Remove a tracker and tear down its job. */
+    unregister(trackerId: string): void;
+    /** Pause/resume a tracker AND its job (a paused job never recomputes, so never crosses edges). */
+    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. 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 + job handles. Walked automatically by `destroyState`. */
+    reset(): void;
+    /**
+     * Feed a freshly-computed verdict through the rising-edge reducer — called by the tracker's job `run`
+     * on each recompute (and once at arm time). Bails fast unless the tracker is live + enabled. A verdict
+     * flipping false→true logs `opened` (alert); true→false logs `resolved` (event). No change on
+     * active→active / inactive→inactive. `at` is the source-data sample time of the recompute.
+     */
+    ingestVerdict(trackerId: string, verdict: Verdict, at: number): void;
+    private append;
+    private emitTrackers;
+}
+
 /**
  * Extracts the text content of the last user message in a message array.
  * Returns null if no user message is found or if content has no text.
@@ -1065,6 +1509,11 @@ export declare type EntryModeSliceName = {
  */
 export declare const extractLastUserText: (messages: ReadonlyArray<ModelMessage>) => string | null;
 
+declare type FeatureCollection_2<F> = {
+    type: 'FeatureCollection';
+    features: F[];
+};
+
 /**
  * Feature-flag bag for {@link createMapAgent}. Toggles in-flight or
  * opt-in agent-toolkit behaviour. Individual flags vary in stability —
@@ -1080,6 +1529,57 @@ export declare type FeatureFlags = {
     /* Excluded from this release type: experimentalSearch */
 };
 
+/**
+ * `extra` fragment supplied by the tool — appended to each generated input-field
+ * description so callers see tool-specific hints alongside the shared metadata.
+ *
+ * @ignore
+ */
+declare type FieldBuildOptions = {
+    verb: 'analyse' | 'process';
+    requiredHint: string;
+};
+
+/**
+ * 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
+ */
+export declare const findPlacesByEntry: (placesEntryIDs: readonly string[] | undefined, state: ToolState) => {
+    value: Record<string, Places> | undefined;
+} | {
+    error: string;
+};
+
+/** Doc blurb to inline in sandboxed-code descriptions. @ignore */
+export declare const FIT_ON_MAP_DOC: string;
+
+/** @ignore */
+export declare type FitOnMapInput = BBox | {
+    bbox: BBox;
+    padding?: number;
+    animate?: boolean;
+};
+
+/** @ignore */
+export declare const fitOnMapInputSchema: z.ZodUnion<readonly [z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodObject<{
+    bbox: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+    padding: z.ZodOptional<z.ZodNumber>;
+    animate: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>]>;
+
+/** @ignore */
+export declare const fittedReportSchema: z.ZodObject<{
+    bbox: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+    padding: z.ZodNumber;
+}, z.core.$strip>;
+
+/** @ignore */
+export declare const formatSandboxExecutionError: (verb: string, error: unknown) => string;
+
 /**
  * Produce a compact, LLM-readable summary of the differences between two digests, or `null` when
  * nothing changed. The output is short enough to prepend to a user prompt without bloating the
@@ -1097,6 +1597,67 @@ export declare type FeatureFlags = {
  */
 export declare const formatStateDigestDiff: (prev: StateDigest, next: StateDigest) => string | null;
 
+/**
+ * Geocodes `query` restricted to administrative AREA geographies (not streets/POIs), biased toward
+ * `bias` (the map centre). Because `geographyTypes` filters to areas, every result carries a
+ * `boundingBox`. Callers choose among the candidates (e.g. 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.
+ */
+export declare const geocodeAreas: (query: string, opts?: {
+    bias?: Position;
+    limit?: number;
+}) => Promise<Place[]>;
+
+/** @ignore */
+export declare const geoJsonBBoxSchema: z.ZodUnion<readonly [z.ZodArray<z.ZodNumber>]>;
+
+/**
+ * One-liner describing the per-source variability of `geometry.properties`.
+ * Shared between `processGeometries` and `analyseGeometries` `code` prompts.
+ *
+ * @ignore
+ */
+export declare const GEOMETRIES_PROPS_DOC: string;
+
+/** @ignore */
+export declare const GEOMETRIES_SCHEMA_DOC: string;
+
+/**
+ * Shared description for `skipped` arrays in tool outputs.
+ *
+ * @ignore
+ */
+export declare const GEOMETRIES_SKIPPED_DESC = "Source ids that could not contribute (unknown id, no geometry data source, fetch failure, or empty entry).";
+
+/**
+ * Shared description for `sourceIds` arrays in tool outputs.
+ *
+ * @ignore
+ */
+export declare const GEOMETRIES_SOURCE_IDS_DESC = "Tagged input ids that contributed at least one polygon to the run, in input order.";
+
+/**
+ * Shared `geometriesEntryIDs` input schema for tools that read polygons from
+ * session state (`processGeometries`, `analyseGeometries`). One canonical
+ * description so the two tools stay aligned and the model sees the same
+ * contract everywhere.
+ *
+ * @ignore
+ */
+export declare const geometriesEntryIDsSchema: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"place">;
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"places">;
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"ranges">;
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"customGeometries">;
+    id: z.ZodString;
+}, z.core.$strip>], "kind">>;
+
 /**
  * Tagged id for any polygon source in session state.
  *
@@ -1132,6 +1693,47 @@ export declare const geometriesIdSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodString;
 }, z.core.$strip>], "kind">;
 
+/**
+ * Geometries metadata — only populated when `geometriesEntryIDs` was passed.
+ *
+ * @ignore
+ */
+export declare type GeometriesMeta = {
+    affectedEntries: AffectedEntry[];
+    sourceIds: GeometriesId[];
+    skipped: SkippedSource[];
+};
+
+/**
+ * Schema for the geometry-rendering option on the places display tool
+ * (`updatePlacesDisplay`). Presence of this object means "render boundaries";
+ * there is no `show: boolean` toggle — that is reserved for the search-time
+ * variant ({@link showPlaceGeometriesSchema}).
+ *
+ * @ignore
+ */
+export declare const geometryDisplayConfigSchema: z.ZodObject<{
+    theme: z.ZodOptional<z.ZodEnum<{
+        filled: "filled";
+        outline: "outline";
+        inverted: "inverted";
+    }>>;
+    placeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        add: "add";
+        replace: "replace";
+    }>>;
+}, z.core.$strip>;
+
+/** @ignore */
+export declare const geometryInputSchema: z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodLiteral<"Polygon">;
+    coordinates: z.ZodArray<z.ZodArray<z.ZodArray<z.ZodNumber>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"MultiPolygon">;
+    coordinates: z.ZodArray<z.ZodArray<z.ZodArray<z.ZodArray<z.ZodNumber>>>>;
+}, z.core.$strip>]>;
+
 /**
  * Provenance metadata for a custom-geometries entry — captures every input
  * source that fed the polygon-producing operation. `sourceIds` holds tagged
@@ -1143,6 +1745,8 @@ export declare const geometriesIdSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
  * `'h3-coverage'`).
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
 export declare type GeometryProvenance = {
     /** Short label for the operation that produced this entry (free-form). */
@@ -1163,6 +1767,12 @@ export declare type GeometryProvenance = {
  */
 export declare const getDefaultToolPrompts: () => Record<ToolName, readonly string[]>;
 
+export declare const getRangePolygons: (state: ToolState, rangeId: string) => {
+    polygons: (Polygon | MultiPolygon)[];
+} | {
+    error: string;
+};
+
 /**
  * Snapshot the user-visible state surface. Call after every assistant turn (to record the
  * "agent-known" baseline) and again before each user prompt (to detect what changed since).
@@ -1171,6 +1781,49 @@ export declare const getDefaultToolPrompts: () => Record<ToolName, readonly stri
  */
 export declare const getStateDigest: (state: ToolState) => StateDigest;
 
+/** @ignore */
+export declare const getViewportBias: (map: BaseMapState, minZoom?: number) => Position | undefined;
+
+/** @ignore */
+export declare const getViewportBoundingBox: (map: BaseMapState) => BBox;
+
+/** @ignore */
+export declare const globalWhereSchema: z.ZodObject<{
+    mode: z.ZodLiteral<"global">;
+}, z.core.$strip>;
+
+/**
+ * Set of LLM-input objects that contain any `*EntryIDs` field. Used by the shared
+ * "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.
+ *
+ * @ignore
+ */
+export declare const hasAnyEntryIds: (value: Record<string, unknown>) => boolean;
+
+/**
+ * Shared factory for the optional `hidePreviousEntries` field — controls which previously-shown
+ * entries get hidden before the new ones are rendered. `entryNoun` is the slice noun
+ * (`'places'`, `'routes'`, `'ranges'`) used inside the description so the LLM sees a slice-specific
+ * hint.
+ *
+ * @ignore
+ */
+export declare const hidePreviousEntriesSchema: (entryNoun: string) => z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>>;
+
+/**
+ * Hide previously-shown entries on a slice that exposes `hideEntry(id)` and a
+ * `shownEntryIds` set (routing, ranges). No-op under `entryMode === 'single'`
+ * (the slice auto-hides others) or when the selector is `undefined`
+ * (omit ⇒ stack on top of existing entries).
+ *
+ * @ignore
+ */
+export declare const hidePreviousShownEntries: (slice: ShownEntriesSlice, keepEntryIds: readonly string[], selector: "all" | readonly string[] | undefined) => Promise<void>;
+
 /**
  * Snapshot of an entry's focus subset. Returned by `getFocus` / payload on `focus-change`.
  *
@@ -1264,6 +1917,8 @@ declare type IncidentMonitorEvents = {
  * back-compat.
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
 export declare type IncidentsAnalysis = EntryAnalysis;
 
@@ -1278,10 +1933,163 @@ export declare type IncidentSnapshot = {
     incidents: TrafficIncident_2[];
 };
 
+/** Lightweight structural check that a sandbox return value is a Chart.js config. */
+export declare const isChartConfiguration: (value: unknown) => value is ChartConfiguration;
+
+/** @ignore */
+export declare const isFitOnMapInput: (value: unknown) => value is FitOnMapInput;
+
+/**
+ * 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;
+
+/**
+ * GeoJSON Feature with a Polygon or MultiPolygon geometry. Generic over
+ * `properties` so callers that need a narrower property shape (e.g. place
+ * footprints with `CommonPlaceProps`) get the typed result without a cast.
+ *
+ * @ignore
+ */
+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>[];
+
+export declare const isResolveError: (r: unknown) => r is ResolveError;
+
+/** A registered job, handed back to the owner as the reference linking a sink record to its recurrence. */
+declare interface Job {
+    /** Ids of every entry this job reads (immutable; a re-arm with different sources is a different job). */
+    readonly affectedEntryIds: readonly string[];
+    /** The recipe behind this job — compared on re-arm to decide whether to drop stale history. */
+    readonly code: string;
+    /** Whether the engine currently scans this job. */
+    readonly active: boolean;
+    /** Pause (`false`) or resume (`true`) scanning. A paused job keeps its recipe for later promotion. */
+    setActive(active: boolean): void;
+    /** Remove the job from the engine. The owner drops its stored reference. */
+    unregister(): void;
+}
+
+/**
+ * Session-level recurrence engine. Held on `ToolState` as `state.engine`; constructed and wired by the
+ * state factory. Owners ({@link Analyses}, {@link EventsState}) register jobs and keep the returned
+ * handles.
+ *
+ * @group Agent Toolkit
+ */
+declare class JobEngine {
+    private readonly jobs;
+    private wired;
+    private scanning;
+    private scheduled;
+    private pending;
+    /** Register a job and return its handle. Stored by the owner as its reference to the recurrence. */
+    register(spec: JobSpec): Job;
+    /* Excluded from this release type: drop */
+    /**
+     * Subscribe the scan to every input slice's `entries-change`, exactly once per session. The state
+     * factory calls this at construction (it holds the slices), so every `ToolState` gets a live engine
+     * without the job builders having to wire lazily.
+     */
+    ensureWired(state: ToolState): void;
+    private sourceSlices;
+    private onChange;
+    private collectOrphans;
+    private hasActiveJob;
+    private scheduleScan;
+    private runScan;
+    /** Drop every job. Walked automatically by `destroyState` (duck-typed `reset`). Subscriptions persist
+     * (harmless without jobs), mirroring the one-shot `wired` guard. */
+    reset(): void;
+}
+
+declare class JobHandle implements Job {
+    private readonly engine;
+    readonly affectedEntryIds: readonly string[];
+    readonly code: string;
+    active: boolean;
+    readonly run: () => Promise<void>;
+    readonly onOrphaned?: () => void;
+    constructor(spec: JobSpec, engine: JobEngine);
+    setActive(active: boolean): void;
+    unregister(): void;
+}
+
+/** What {@link JobEngine.register} needs to mint a {@link Job}. `run` and `onOrphaned` are owner closures. */
+declare 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 — stored as the single home of the code + for re-arm change-detect. */
+    code: string;
+    /** Whether the engine scans this job. A paused job (`false`) is retained but never run. */
+    active: boolean;
+    /** Owner closure: prepare inputs → run sandbox → write result to its sink. The engine never inspects it. */
+    run: () => Promise<void>;
+    /** Owner closure invoked just before the engine drops the job because all its source entries are gone. */
+    onOrphaned?: () => void;
+};
+
 declare type JSONValue = null | string | number | boolean | {
     [key: string]: JSONValue;
 } | JSONValue[];
 
+/** Newest `timestamp` across every resolved source entry, or undefined when none carry one. The
+ * canonical `sampledAt` for a recurring sandbox run over these inputs. */
+export declare const latestTimestamp: (resolved: ResolvedEntries) => number | undefined;
+
+export declare type LocateBias = {
+    position: Position;
+} | {
+    boundingBox: BBox;
+};
+
+/** Convenience wrapper around {@link locatePlaces} for the single-result case. */
+export declare const locatePlace: (query: string, queryAs: QueryAs, bias?: LocateBias) => Promise<Place | null>;
+
+/**
+ * Resolves a query string to up to `limit` Places. POI search when `queryAs === 'poi'`, geocoding
+ * otherwise. Optional `bias` narrows the search to a region.
+ */
+export declare const locatePlaces: (query: string, queryAs: QueryAs, options: {
+    limit: number;
+    bias?: LocateBias;
+}) => Promise<Place[]>;
+
+/** @ignore */
+export declare type LocationInput = z.infer<typeof locationInputSchema>;
+
+/** @ignore */
+export declare const locationInputSchema: z.ZodUnion<readonly [z.ZodObject<{
+    query: z.ZodString;
+    queryAs: z.ZodEnum<{
+        place: "place";
+        poi: "poi";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    position: z.ZodObject<{
+        lng: z.ZodNumber;
+        lat: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    placeId: z.ZodString;
+}, z.core.$strip>]>;
+
+/**
+ * Default executor for Node/SSR (and the in-browser fallback): compiles + runs the
+ * code synchronously in the host realm. Deep-copies data inputs (see
+ * {@link cloneDataArg}) so the body can't mutate live state, but provides no isolation
+ * beyond the global shadowing — see {@link SHADOWED_GLOBALS}.
+ *
+ * @ignore
+ */
+export declare const mainThreadExecutor: SandboxExecutor;
+
 /**
  * The return type of createMapAgent().
  * A real ToolLoopAgent instance with state access and cleanup.
@@ -1295,25 +2103,6 @@ export declare type MapAgentInstance<CS extends ToolState = ToolState> = ToolLoo
     destroy(): void;
 };
 
-/**
- * Options for creating an agent toolkit.
- *
- * @typeParam CS - Full state type. Must extend `ToolState`. Defaults to base `ToolState` (no custom slices).
- *
- * @group Agent Toolkit
- *
- * @example Custom state
- * ```typescript
- * interface MyState extends ToolState {
- *     fleet: FleetState;
- * }
- *
- * createMapAgent<MyState>(map, {
- *     model,
- *     state: { fleet: new FleetState() },
- * });
- * ```
- */
 export declare type MapAgentOptions<CS extends ToolState = ToolState> = {
     /** AI SDK language model instance. REQUIRED — no default provider. */
     model: LanguageModel;
@@ -1450,6 +2239,13 @@ export declare type MapAgentOptions<CS extends ToolState = ToolState> = {
      * Called after each classification. Use to observe selected tools or log.
      */
     onClassify?: (result: ClassificationResult | null) => void;
+    /**
+     * Called after each tool's `execute` settles (success or throw), with its
+     * wall-clock duration and whether it failed. Use to observe per-tool latency
+     * and error rates (e.g. telemetry). Errors are detected both from a thrown
+     * exception and from the standardized `{ error: string }` return shape.
+     */
+    onToolExecute?: OnToolExecute;
     /**
      * Custom prepareStep hook, composed with internal classification step.
      * Your `activeTools` are intersected with the classifier's selection.
@@ -1525,6 +2321,22 @@ declare class MapPOIsState implements StateSlice {
     reset(): void;
 }
 
+/**
+ * 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.
+ *
+ * @ignore
+ */
+export declare const markerTypeSchema: z.ZodEnum<{
+    none: "none";
+    "base-map": "base-map";
+    pin: "pin";
+    "pin-clustered": "pin-clustered";
+}>;
+
+export declare const matchedAreasLabel: (resolvedAreas: ResolvedAreaDisclosure[] | undefined) => string | undefined;
+
 /**
  * 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
@@ -1537,6 +2349,9 @@ export declare type MemberRef = {
     featureIds: string[];
 };
 
+/** @ignore */
+export declare const MIN_VIEWPORT_BIAS_ZOOM = 6;
+
 /**
  * The geographic area a {@link TrafficIncidentsEntry} monitor is polling, captured at
  * monitor-start time and replayed on every tick.
@@ -1549,11 +2364,88 @@ export declare type MonitoredArea = {
     label?: string;
 };
 
+/**
+ * Names injected into the sandbox by analyseData / processData, in fixed order.
+ *
+ * @ignore
+ */
+export declare const MULTI_INPUT_SANDBOX_PARAMS: readonly ["placesByEntry", "routesByEntry", "incidentsByEntry", "geometriesByEntry", "trafficAreaAnalyticsByEntry", "byodByEntry", "h3", "turf", "routeUtils", "cluster"];
+
+/**
+ * Inputs the LLM passes through the tool schema. All optional, but at least one must be set.
+ *
+ * @ignore
+ */
+export declare type MultiInputIds = {
+    placesEntryIDs?: readonly string[];
+    routesEntryIDs?: readonly string[];
+    incidentsEntryIDs?: readonly string[];
+    geometriesEntryIDs?: readonly GeometriesId[];
+    trafficAreaAnalyticsEntryIDs?: readonly string[];
+    byodEntryIDs?: readonly string[];
+};
+
+/** @ignore */
+export declare const multiPolygonInputSchema: z.ZodObject<{
+    type: z.ZodLiteral<"MultiPolygon">;
+    coordinates: z.ZodArray<z.ZodArray<z.ZodArray<z.ZodArray<z.ZodNumber>>>>;
+}, z.core.$strip>;
+
+/** @ignore */
+export declare const nearbyWhereSchema: z.ZodObject<{
+    mode: z.ZodLiteral<"nearby">;
+    position: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    viewport: z.ZodOptional<z.ZodLiteral<true>>;
+    query: z.ZodOptional<z.ZodString>;
+    queryAs: z.ZodOptional<z.ZodEnum<{
+        place: "place";
+        poi: "poi";
+    }>>;
+    radiusMeters: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+
+/** Observer invoked after each tool's `execute` settles. */
+export declare type OnToolExecute = (info: ToolExecutionInfo) => void;
+
+/**
+ * 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
+ * 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
+ * executor `structuredClone`s the data args itself, while the iframe-worker
+ * executor gets a copy for free as `postMessage` clones them across the worker
+ * 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
+ * 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.)
+ *
+ * @ignore
+ */
+export declare const packSandboxArgs: (sandbox: SandboxInputs, libs: {
+    h3: unknown;
+    turf: unknown;
+}) => readonly unknown[];
+
+/**
+ * Default-flag (`experimentalSearch: false`) Places schema doc — preserved as a
+ * named constant so non-flag-aware tools keep working.
+ *
+ * @ignore
+ */
+export declare const PLACES_SCHEMA_DOC: string;
+
 /**
  * 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
+ *
+ * @ignore
  */
 export declare type PlacesAnalysis = EntryAnalysis;
 
@@ -1561,12 +2453,10 @@ export declare type PlacesAnalysis = EntryAnalysis;
  * A single entry in the place search history.
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
-export declare type PlacesEntry = {
-    id: string;
-    timestamp: number;
-    label: string;
-    places: Place[];
+export declare type PlacesEntry = BaseEntry<Place[]> & {
     /** Connections (lines between places) produced alongside this entry, rendered via PlacesModule.showConnections. */
     connections?: PlaceConnectionDisplay[];
     /**
@@ -1594,6 +2484,29 @@ export declare type PlacesEntry = {
     _shownAs?: 'pin' | 'base-map' | 'pin-clustered';
 };
 
+/**
+ * Optional semantic id for a new places entry. Encourages the LLM to derive a compact,
+ * memorable identifier from the user's prompt so later tool calls can reference the entry
+ * without scanning a numeric history. The id is auto-suffixed (`-2`, `-3`, ...) on collision,
+ * so the LLM never has to track uniqueness across calls itself.
+ *
+ * @ignore
+ */
+export declare const placesEntryIdHintSchema: z.ZodOptional<z.ZodString>;
+
+/**
+ * Shared factory for the optional `placesEntryIDs` input field — one or more
+ * existing places-entry IDs that a tool should operate on. Each caller supplies
+ * a `verb` (filter/analyse/display/…) and optional follow-up text so the LLM
+ * sees a description tailored to that tool.
+ *
+ * @ignore
+ */
+export declare const placesEntryIDsSchema: ({ verb, extra }: {
+    verb: string;
+    extra?: string;
+}) => z.ZodOptional<z.ZodArray<z.ZodString>>;
+
 /** How an entry is rendered on the map: as individual pins, base-map POIs, or clustered pins. */
 declare type PlacesMarkerType = 'pin' | 'base-map' | 'pin-clustered';
 
@@ -1650,6 +2563,7 @@ declare class PlacesState implements StateSlice {
         place: Place;
         entryId: string;
     } | undefined;
+    geometryPlaceIdsForEntry(entryId: string): string[] | undefined;
     /**
      * Returns the cached boundary polygon for a place id, or undefined if no geometry has been
      * fetched for it yet. Builds a lazy place-id → feature index per entry on first lookup.
@@ -1743,8 +2657,8 @@ declare type PlacesStateEvents = {
     /**
      * 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`).
+     * added, replaced in place, or removed (the {@link JobEngine} matches these against each job's
+     * `affectedEntryIds`).
      */
     'entries-change': {
         entries: readonly PlacesEntry[];
@@ -1765,25 +2679,74 @@ declare type PlacesStateEvents = {
  * Lifecycle state of a per-entry incidents monitor. `stopped-error` indicates the last
  * poll failed and the timer has been cleared — start the monitor again to retry.
  *
- * @group Agent Toolkit
+ * @group Agent Toolkit
+ */
+export declare type PollingStatus = 'idle' | 'running' | 'stopped-error';
+
+/** @ignore */
+export declare const polygonInputSchema: z.ZodObject<{
+    type: z.ZodLiteral<"Polygon">;
+    coordinates: z.ZodArray<z.ZodArray<z.ZodArray<z.ZodNumber>>>;
+}, z.core.$strip>;
+
+/**
+ * Internal result of {@link prepareMultiInputs} — the resolved entries, the sandbox-facing views, and
+ * the geometries metadata, bundled for the analyse / process tools.
+ *
+ * @ignore
+ */
+export declare type PreparedInputs = {
+    resolved: ResolvedEntries;
+    sandbox: SandboxInputs;
+    geometries: GeometriesMeta;
+};
+
+/**
+ * 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.
+ *
+ * @ignore
  */
-export declare type PollingStatus = 'idle' | 'running' | 'stopped-error';
+export declare const prepareMultiInputs: (ids: MultiInputIds, state: ToolState) => Promise<{
+    value: PreparedInputs;
+} | {
+    error: string;
+}>;
 
 declare type ProviderOptions = Record<string, Record<string, JSONValue | undefined>>;
 
+export declare type QueryAs = 'poi' | 'place';
+
+/**
+ * `queryAs` — what kind of thing the paired `query` string is. Drives whether resolution uses
+ * POI search (venues/landmarks/businesses) or geocoding (addresses, cities, neighborhoods, parks,
+ * postal codes, etc.). Optional everywhere; defaults to `'place'`.
+ * @ignore
+ */
+export declare const queryAsSchema: z.ZodOptional<z.ZodEnum<{
+    place: "place";
+    poi: "poi";
+}>>;
+
+/** A single clarification question shown to the user. Exported so a host can type its form state. */
+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>;
+
 /**
  * A single entry in the reachable range history. Holds one or more
  * {@link ReachableRange} results that were computed together — typically
  * one per origin in a multi-origin call to `findReachableAreas`.
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
-export declare type RangesEntry = {
-    id: string;
-    timestamp: number;
-    label: string;
-    /** One or more ranges sharing this entry — typically one per origin. */
-    ranges: ReachableRange[];
+export declare type RangesEntry = BaseEntry<ReachableRange[]> & {
     /**
      * Per-entry display modules. Each entry owns a dedicated GeometriesModule (for the
      * isochrone polygons) and PlacesModule (for the origin pin(s)), so display state lives
@@ -1897,6 +2860,8 @@ declare type RangeStateEvents = {
  * coverage from several origins under the same query.
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
 export declare type ReachableRange = {
     origin: {
@@ -1908,6 +2873,118 @@ export declare type ReachableRange = {
     polygon?: PolygonFeatures;
 };
 
+/**
+ * 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[];
+
+export declare const resolveAreas: (where: AreaWhere, ctx: WhereContext, opts?: ResolveAreasOptions) => Promise<ResolvedArea[] | ResolveError>;
+
+export declare type ResolveAreasOptions = {
+    /** Resolve `queries` to the top geocode candidate's own bbox only — skip the boundary-polygon
+     * fetch and the geometry-source preference. For callers that consume only bboxes (traffic
+     * incidents), this avoids an unnecessary Geometry Data call and the risk of a lower-ranked
+     * area-with-a-boundary displacing the top result. Callers that need precise polygon filters
+     * (discover-places) leave this off. */
+    bboxOnlyQueries?: boolean;
+};
+
+export declare const resolveBiasPoint: (where: BiasWhere, ctx: WhereContext) => Promise<ResolvedBias>;
+
+/** A resolved geographic area. `bbox` is always present; `polygon` is present when a precise
+ * boundary was available (a Geography boundary or a buffered route corridor). */
+export declare type ResolvedArea = {
+    bbox: BBox;
+    polygon?: Polygon | MultiPolygon;
+    /** The GROUNDED match label — `freeformAddress, <countryCode>` for a `query` area — i.e. what the
+     * data was actually loaded for, NOT the query echo. Lets a consumer surface where a query really
+     * resolved. */
+    label?: string;
+    source: AreaSource;
+    /** The input query text for a `query` area, echoed so a consumer can pair "asked" with the
+     * grounded `label` ("matched"). Absent for non-query sources. */
+    query?: string;
+};
+
+/** The grounded resolution of a named `where` query — `matched` is the place the data was actually
+ * loaded for (NOT the query echo). Surfaced so the agent knows where a query resolved and can
+ * detect/correct a wrong same-name match. */
+export declare type ResolvedAreaDisclosure = {
+    query?: string;
+    matched: string;
+};
+
+export declare const resolvedAreasDisclosure: (areas: ResolvedArea[]) => ResolvedAreaDisclosure[];
+
+/** A resolved point bias for a `nearby`-mode search. `position` is the bias point (absent when the
+ * input was unresolvable — a tolerant no-bias widening, never an error). `query` + `label` are set
+ * ONLY for the `query` sub-case — the grounded-resolution signal, identical in spirit to
+ * {@link ResolvedArea}'s fields: a bias landing on a same-named place elsewhere silently skews
+ * results to the wrong locale (e.g. "coffee near Springfield"). Consumers surface it via
+ * {@link biasDisclosure}. */
+export declare type ResolvedBias = {
+    position?: Position;
+    label?: string;
+    query?: string;
+};
+
+/**
+ * Resolved entries, kept for the attach step in analyseData. Empty arrays for kinds the caller didn't request.
+ *
+ * @ignore
+ */
+export declare type ResolvedEntries = {
+    places: PlacesEntry[];
+    routes: RoutesEntry[];
+    incidents: TrafficIncidentsEntry[];
+    trafficAreaAnalytics: TrafficAreaAnalyticsEntry[];
+    byod: BYODEntry[];
+};
+
+/** @ignore */
+export declare type ResolvedLocation = {
+    /** Resolved place: a Place (with address metadata) or a bare [lng, lat] tuple. */
+    place: WaypointLike;
+    position: Position;
+    name: string;
+    /** Original query string, when the input was resolved from text. */
+    query?: string;
+};
+
+/** Outcome of {@link resolvePoiCategories}. @ignore */
+export declare type ResolvedPoiCategories = {
+    /** Final search filter — known codes plus codes resolved from natural-language synonyms. */
+    resolved: POICategory[] | undefined;
+    /** Inputs that matched neither an exact code nor any synonym. */
+    unresolved: string[];
+};
+
+export declare type ResolveError = {
+    error: string;
+};
+
+export declare const resolveNearbyPosition: (where: {
+    viewport?: true;
+    position?: Position;
+    query?: string;
+    queryAs?: QueryAs;
+}, ctx: WhereContext) => Promise<ResolvedBias>;
+
+/**
+ * Resolve a mixed list of POI inputs to canonical {@link POICategory} codes.
+ *
+ * Each input is either an exact catalog code (kept as-is) or a natural-language term that is
+ * resolved via the POI categories service. Inputs that produce zero matches are reported in
+ * `unresolved` so callers can surface a precise error.
+ *
+ * @ignore
+ */
+export declare const resolvePoiCategories: (poiCategories: string[] | undefined) => Promise<ResolvedPoiCategories>;
+
 /**
  * Merges default tools with user overrides.
  *
@@ -1927,6 +3004,15 @@ 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>>;
 
+export declare const resolveWithinAreas: (where: AreaWhere, ctx: WhereContext, opts?: ResolveAreasOptions) => Promise<ResolveWithinResult | ResolveError>;
+
+export declare type ResolveWithinResult = {
+    areas: ResolvedArea[];
+    /** Display label of the route corridor, when the `where` resolved one — surfaced by callers
+     * that build a human-readable scope label (traffic's defaultLabel, discover's entry label). */
+    routeLabel?: string;
+};
+
 /**
  * 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.
@@ -1998,6 +3084,8 @@ declare type RouteMonitorEvents = {
  * Consumed by setRoute, addWaypointsToRoute, removeWaypointsFromRoute, and replaceWaypointInRoute.
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
 export declare type RouteParams = {
     maxAlternatives?: number;
@@ -2021,11 +3109,16 @@ export declare type RouteParams = {
  */
 declare type RoutePollingStatus = 'idle' | 'running' | 'stopped-error';
 
+/** @ignore */
+export declare const ROUTES_SCHEMA_DOC: string;
+
 /**
  * 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
+ *
+ * @ignore
  */
 export declare type RoutesAnalysis = EntryAnalysis;
 
@@ -2033,12 +3126,10 @@ export declare type RoutesAnalysis = EntryAnalysis;
  * A single entry in the route calculation history.
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
-export declare type RoutesEntry = {
-    id: string;
-    timestamp: number;
-    label: string;
-    data: Routes;
+export declare type RoutesEntry = BaseEntry<Routes> & {
     waypoints: WaypointLike[];
     params: RouteParams;
     /**
@@ -2064,6 +3155,17 @@ export declare type RoutesEntry = {
     _tick?: number;
 };
 
+/**
+ * Shared factory for the optional `routesEntryIDs` input field — one or more existing routes-entry
+ * IDs that a tool should operate on. Mirrors `placesEntryIDsSchema` for routes.
+ *
+ * @ignore
+ */
+export declare const routesEntryIDsSchema: ({ verb, extra }: {
+    verb: string;
+    extra?: string;
+}) => z.ZodOptional<z.ZodArray<z.ZodString>>;
+
 /**
  * A freshly recalculated route from a single monitor tick, with the moment it was sampled.
  * Payload of {@link RoutingStateEvents.monitor-tick}.
@@ -2075,6 +3177,18 @@ declare type RouteSnapshot = {
     routes: Routes_2;
 };
 
+/**
+ * @ignore
+ */
+export declare const routeUtils: {
+    readonly calculateProgressAtRoutePoint: (route: Route, pathIndex: number) => RouteProgressAtPoint | undefined;
+    readonly getCoordinateAtRouteProgress: (route: Route, query: RouteProgressQuery) => RouteCoordinateAtProgress | undefined;
+    readonly getProgressAtNearestRoutePoint: (route: Route, point: HasLngLat) => RouteCoordinateAtProgress | undefined;
+    readonly getRouteProgressBetween: (route: Route, startPathIndex: number, endPathIndex: number) => RouteSegmentProgress | undefined;
+    readonly getRouteProgressForSection: (route: Route, section: SectionProps) => RouteSegmentProgress | undefined;
+    readonly getSectionBBox: (route: Route, section: SectionProps) => OptionalBBox;
+};
+
 /**
  * State for route calculation, waypoint management, and route planning parameters.
  *
@@ -2250,6 +3364,35 @@ declare type RoutingStateEvents = {
     };
 };
 
+/**
+ * Compiles `code` as the body of an `async` function that takes the named
+ * `paramNames`, sanitises injected redeclarations, runs it with `args`, and
+ * returns either `{ value }` or `{ error }`. Centralises the AsyncFunction
+ * dance shared by every sandbox-running tool (analyse-* and process-*) so
+ * each callsite only owns its inputs and result handling.
+ *
+ * In addition to the caller's `paramNames`, a fixed set of network / storage /
+ * DOM globals ({@link SHADOWED_GLOBALS}) is appended as `undefined` parameters
+ * so the body cannot reach them by name. This is defense-in-depth, not a
+ * sandbox: it surfaces accidental/undesired global access as an error rather
+ * than containing a hostile escape (see the note on `SHADOWED_GLOBALS`).
+ *
+ * Injected-redeclaration sanitising happens HERE, once, before dispatch — so every
+ * executor (main-thread and iframe-worker alike) runs identically de-fanged code
+ * and an LLM `const turf = require(...)` can't compile in one realm but throw in
+ * another. `executor` is REQUIRED (no implicit main-thread default): callers must
+ * choose the realm explicitly — `state.codeExecution` for the env-resolved sandbox,
+ * or `mainThreadExecutor` to opt into host-realm execution on purpose. `verb` is the
+ * human-readable action used in the error prefix (e.g. `"Analysis"`).
+ *
+ * @ignore
+ */
+export declare const runSandboxedFn: <Result = unknown>(code: string, paramNames: readonly string[], args: readonly unknown[], verb: string, executor: SandboxExecutor) => Promise<{
+    value: Result;
+} | {
+    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
@@ -2261,6 +3404,9 @@ declare type SandboxClusteringOutput = ClusteringOutput & {
     sampledAt?: number;
 };
 
+/** @ignore */
+export declare const sandboxedGlobalShadows: readonly ["fetch", "XMLHttpRequest", "WebSocket", "EventSource", "localStorage", "sessionStorage", "indexedDB", "document", "window", "globalThis", "self", "navigator", "importScripts", "process"];
+
 /**
  * Pluggable strategy for executing sandbox code. The default
  * {@link mainThreadExecutor} compiles + runs in the host realm; an alternative
@@ -2282,6 +3428,140 @@ export declare type SandboxExecutor = {
     destroy?(): void;
 };
 
+/**
+ * Sandbox-facing inputs. Each kind is exposed as a single `<kind>ByEntry` record keyed by the entry id
+ * the caller passed in `<kind>EntryIDs`; the field is `undefined` when its kind wasn't requested. There
+ * is no flat/merged companion — code accesses one entry by id (`placesByEntry["places-2"]`) or merges
+ * across entries explicitly with `Object.values(...)`, so it always stays aware of which entries it spans.
+ *
+ * @ignore
+ */
+export declare type SandboxInputs = {
+    /**
+     * Per-entry places, keyed by entry id. Each value is a FeatureCollection of that one entry's places.
+     */
+    placesByEntry: Record<string, FeatureCollection_2<Place>> | undefined;
+    /**
+     * Per-entry routes, keyed by entry id. Each value is a FeatureCollection of that one entry's routes.
+     */
+    routesByEntry: Record<string, FeatureCollection_2<Route>> | undefined;
+    /**
+     * Per-entry incidents, keyed by entry id. Each value is a plain array of that one entry's incidents.
+     */
+    incidentsByEntry: Record<string, TrafficIncident[]> | undefined;
+    /**
+     * Per-source polygons collected from every requested source (place / places / ranges / customGeometries).
+     * Keyed by the tagged source `${kind}:${id}` (NOT a bare id: the same id can recur across kinds, e.g. a
+     * `place` vs a `customGeometries` entry), so the kind stays unambiguous. Each feature also self-describes
+     * its origin in `properties._source` (`{ kind, id }`).
+     */
+    geometriesByEntry: Record<string, PolygonFeature[]> | undefined;
+    /**
+     * Per-entry TrafficAreaAnalytics, keyed by entry id. Each value is a full FeatureCollection whose features
+     * are tile/hex regions carrying the SDK metric properties (`congestionLevel`, `speed`, `travelTime`, …)
+     * and whose collection-level `properties` (metrics list, date range) stay intact per entry.
+     */
+    trafficAreaAnalyticsByEntry: Record<string, TrafficAreaAnalytics> | undefined;
+    /**
+     * Per-entry BYOD, keyed by entry id. Each value is a FeatureCollection; mixed geometry types are normal
+     * (BYOD layers can be Point / LineString / Polygon).
+     */
+    byodByEntry: Record<string, FeatureCollection> | undefined;
+};
+
+/**
+ * The multi-region `within` field block shared by discoverPlaces and getTrafficIncidents.
+ * Spread into each tool's `z.object({...})` alongside any tool-specific fields.
+ * @ignore
+ */
+export declare const sharedWithinFields: {
+    queries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        query: z.ZodString;
+        queryAs: z.ZodOptional<z.ZodEnum<{
+            place: "place";
+            poi: "poi";
+        }>>;
+    }, z.core.$strip>>>;
+    placeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    geometries: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodLiteral<"Polygon">;
+        coordinates: z.ZodArray<z.ZodArray<z.ZodArray<z.ZodNumber>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"MultiPolygon">;
+        coordinates: z.ZodArray<z.ZodArray<z.ZodArray<z.ZodArray<z.ZodNumber>>>>;
+    }, z.core.$strip>]>>>;
+    range: z.ZodOptional<z.ZodString>;
+    route: z.ZodOptional<z.ZodObject<{
+        routeId: z.ZodOptional<z.ZodString>;
+        widthMeters: z.ZodNumber;
+    }, z.core.$strip>>;
+    mode: z.ZodLiteral<"within">;
+    viewport: z.ZodOptional<z.ZodLiteral<true>>;
+};
+
+/**
+ * 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>>;
+
+/**
+ * BYOD `show` options. Mirrors {@link showPlacesSchema} but WITHOUT `markerType`
+ * — BYOD entries render through their own geometry-typed MapLibre layers, so
+ * there is no marker style to pick. Presence of this object means "render now";
+ * omit it to store the entry hidden. `zoomMode` drives the camera and
+ * `hidePreviousEntries` controls which already-shown BYOD entries to clear first.
+ *
+ * @ignore
+ */
+export declare const showByodSchema: z.ZodObject<{
+    zoomMode: z.ZodEnum<{
+        none: "none";
+        auto: "auto";
+    }>;
+    hidePreviousEntries: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>>;
+}, z.core.$strip>;
+
+/**
+ * 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>>) => Promise<ShowEntryGeometriesResult>;
+
+/** @ignore */
+export declare type ShowEntryGeometriesResult = {
+    fetched: number;
+    shown: boolean;
+};
+
+/**
+ * Reusable `mode` field for show-on-map options that render polygons into an entry's
+ * own `GeometriesModule`. Controls how the new polygons combine with what is **already
+ * rendered on that single entry's layer** — intra-entry only. Cross-entry visibility
+ * (hiding *other* entries before this one comes up) is a separate concern handled by
+ * `hidePreviousEntries`.
+ *
+ * @ignore
+ */
+export declare const showModeSchema: z.ZodOptional<z.ZodEnum<{
+    add: "add";
+    replace: "replace";
+}>>;
+
+/** @ignore */
+export declare const shownByodSchema: z.ZodObject<{
+    zoomMode: z.ZodBoolean;
+}, z.core.$strip>;
+
 /**
  * State slice that owns a set of "entries" (routes, ranges) where each entry can be hidden
  * individually by id and the slice exposes the currently-shown set. Implemented by
@@ -2299,6 +3579,71 @@ declare interface ShownEntriesSlice extends StateSlice {
     hideEntry(entryId: string): Promise<void>;
 }
 
+/** @ignore */
+export declare const shownSchema: z.ZodObject<{
+    markerType: z.ZodBoolean;
+    zoomMode: z.ZodBoolean;
+}, z.core.$strip>;
+
+/**
+ * Shared schema for the geometry-rendering option on tools that produce a places entry
+ * (discoverPlaces, locatePlace, ...). When provided, the tool batch-fetches boundary
+ * polygons via the Geometry Data service, caches them on the entry, and optionally renders.
+ *
+ * @ignore
+ */
+export declare const showPlaceGeometriesSchema: z.ZodOptional<z.ZodObject<{
+    show: z.ZodOptional<z.ZodBoolean>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        add: "add";
+        replace: "replace";
+    }>>;
+    theme: z.ZodOptional<z.ZodEnum<{
+        filled: "filled";
+        outline: "outline";
+        inverted: "inverted";
+    }>>;
+}, z.core.$strip>>;
+
+/** @ignore */
+export declare const showPlacesSchema: z.ZodObject<{
+    markerType: z.ZodEnum<{
+        none: "none";
+        "base-map": "base-map";
+        pin: "pin";
+        "pin-clustered": "pin-clustered";
+    }>;
+    zoomMode: z.ZodEnum<{
+        none: "none";
+        auto: "auto";
+    }>;
+    hidePreviousEntries: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>>;
+}, z.core.$strip>;
+
+/** @ignore */
+export declare const showResultsOnMap: (state: ToolState, placesEntryIds: readonly string[], show: z.infer<typeof showPlacesSchema>) => Promise<z.infer<typeof shownSchema>>;
+
+/** @ignore */
+export declare type SkippedSource = z.infer<typeof skippedSourceSchema>;
+
+/** @ignore */
+export declare const skippedSourceSchema: z.ZodObject<{
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"place">;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"places">;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"ranges">;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"customGeometries">;
+        id: z.ZodString;
+    }, z.core.$strip>], "kind">;
+    reason: z.ZodString;
+}, z.core.$strip>;
+
 /**
  * Compact snapshot of the user-visible parts of `ToolState`. Designed to be diffable: every field
  * is serialisable to JSON and stable for `===` comparison when the underlying state hasn't changed.
@@ -2409,6 +3754,9 @@ export declare interface StateSlice {
     reset(): void;
 }
 
+/** @ignore */
+export declare const stripInjectedRedeclarations: (code: string, identifiers: readonly string[]) => string;
+
 /**
  * The default body text for each base-prompt section — heading excluded.
  *
@@ -2493,6 +3841,13 @@ export declare type SystemPromptSection = 'identity' | 'capabilities' | 'rejecti
  */
 export declare type SystemPromptSectionOverrides = Partial<Record<SystemPromptSection, string>>;
 
+/** Splits resolved areas into precise polygon filters and coarse bbox filters — the shape
+ * discover-places' search endpoints consume. */
+export declare const toMultiFilters: (areas: ResolvedArea[]) => {
+    geometries: (Polygon | MultiPolygon)[];
+    boundingBoxes: BBox[];
+};
+
 /**
  * All valid default tool names, derived from {@link DEFAULT_TOOLS}.
  *
@@ -2579,6 +3934,22 @@ export declare type ToolEntry<S extends ToolState = ToolState, Scope = unknown>
     relatedTools?: string[];
     /** Tool names that must run before this one. */
     dependsOn?: string[];
+    /**
+     * Keep this tool 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 sparingly —
+     * for tools that may be needed to set up *any* request (e.g. asking the user to clarify intent).
+     * Has no effect on the fail-open path (when classification is skipped, every tool is active).
+     */
+    alwaysActive?: boolean;
+    /**
+     * Halt the agent loop on the SAME step that calls this tool, with no trailing step. Use for tools
+     * whose turn must be a single silent tool call (e.g. clarifyIntent rendering a form). Leave unset to
+     * let the model take one more step after the tool returns — e.g. to present the tool's result as text
+     * before the loop stops naturally on a no-tool-call step. A tool that semantically awaits the user
+     * conveys that through its own result (e.g. clarifyIntent's `status: 'awaiting_user_response'`), not
+     * this flag.
+     */
+    endsTurnOnCall?: boolean;
     /**
      * Optional per-tool scope schema. When set, the classifier may emit a
      * scope value (validated against this schema) and `prepareStep` will
@@ -2610,6 +3981,37 @@ export declare type ToolEntry<S extends ToolState = ToolState, Scope = unknown>
  */
 export declare type ToolEntryBuilder<S extends ToolState = ToolState, Scope = unknown> = (options: ToolBuildOptions<Scope>) => ToolEntry<S, Scope>;
 
+/**
+ * Options for creating an agent toolkit.
+ *
+ * @typeParam CS - Full state type. Must extend `ToolState`. Defaults to base `ToolState` (no custom slices).
+ *
+ * @group Agent Toolkit
+ *
+ * @example Custom state
+ * ```typescript
+ * interface MyState extends ToolState {
+ *     fleet: FleetState;
+ * }
+ *
+ * createMapAgent<MyState>(map, {
+ *     model,
+ *     state: { fleet: new FleetState() },
+ * });
+ * ```
+ */
+/** Per-tool execution outcome reported to {@link MapAgentOptions.onToolExecute}. */
+export declare type ToolExecutionInfo = {
+    /** Registered tool name (the `defaultTools` key). */
+    toolName: string;
+    /** Wall-clock duration of `execute`, in milliseconds (includes any network/IO). */
+    durationMs: number;
+    /** True if the tool threw or returned the standardized `{ error: string }` shape. */
+    isError: boolean;
+    /** Error message when `isError` is true (the thrown message or the returned `error`). */
+    errorMessage?: string;
+};
+
 /**
  * Metadata for an agent toolkit tool.
  *
@@ -2632,6 +4034,10 @@ export declare type ToolMetadata = {
     relatedTools?: ToolNameHint[];
     /** Tool names that must run before this one. */
     dependsOn?: ToolNameHint[];
+    /** Keep this tool active on every step regardless of the classifier's selection. */
+    alwaysActive?: boolean;
+    /** Halt the agent loop on the step that calls this tool (no trailing step) — e.g. clarifyIntent rendering a form. */
+    endsTurnOnCall?: boolean;
     /** When set, the classifier may emit `toolScopes[name]` for this tool to narrow per-turn. */
     scopePrompt?: string;
 };
@@ -2712,33 +4118,43 @@ export declare type ToolState = {
      * to select where sandbox code runs.
      */
     codeExecution: SandboxExecutor;
+    /**
+     * The single recurrence engine. Owners (`analyses`, `trackers`) register entry-anchored jobs and keep
+     * the returned handles; the engine re-runs each active job when its source entries change. Generic —
+     * it never interprets a job's recipe (the tools layer builds the run closure). See {@link JobEngine}.
+     */
+    engine: JobEngine;
     /**
      * 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`.
+     * Results live here, and per-entry views read them on demand via {@link Analyses.getAnalysesForEntry}.
+     * `analyseData` registers a record + a job on {@link JobEngine}; `monitorAnalysis` toggles the job's
+     * active flag.
      */
     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.
+     * Generic trackers — rising-edge reducers fed by their own {@link JobEngine} jobs. A tracker fires an
+     * alert/event when its rule's {@link Verdict} crosses an edge (`ingestVerdict`); owns the durable
+     * {@link TrackerEvent} log.
      */
-    trackers: TrackerState;
+    trackers: EventsState;
 };
 
+/** Adapts the live `ToolState` to the narrow `WhereContext` the resolver depends on. Keeping this
+ * mapping in one place is what lets resolveAreas stay testable without a ToolState. */
+export declare const toolStateToWhereContext: (state: ToolState) => WhereContext;
+
 /**
- * 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.
+ * One tracker = one rule: an NL 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; a verdict's
+ * `members` are 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. */
+    /** Natural-language condition (LLM-readable); the compiled code lives on the tracker's job. */
     rule: string;
-    /** The `type: 'tracker-rule'` analysis whose `data` is this tracker's {@link Verdict}. */
-    analysisId: string;
+    /** Ids of every entry the rule reads — the per-entry lookup key ({@link EventsState.trackersForEntry}). */
+    affectedEntryIds: readonly string[];
     enabled: boolean;
     /** The one bit of memory: was the verdict active at the last recompute (rising-edge detection). */
     wasActive: boolean;
@@ -2767,62 +4183,7 @@ 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
- */
-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}. */
+/** Events emitted by {@link EventsState}. */
 export declare type TrackerStateEvents = {
     /** The tracker set or a tracker's live state changed (create / clear / enable / edge crossed). */
     'trackers-change': readonly Tracker[];
@@ -2836,6 +4197,8 @@ export declare type TrackerStateEvents = {
  * back-compat.
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
 export declare type TrafficAreaAnalyticsAnalysis = EntryAnalysis;
 
@@ -2846,13 +4209,10 @@ export declare type TrafficAreaAnalyticsAnalysis = EntryAnalysis;
  * `TrafficAreaAnalyticsModule`, lazy-initialised on first show.
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
-export declare type TrafficAreaAnalyticsEntry = {
-    id: string;
-    timestamp: number;
-    label: string;
-    /** The aggregated FeatureCollection result. */
-    data: TrafficAreaAnalytics;
+export declare type TrafficAreaAnalyticsEntry = BaseEntry<TrafficAreaAnalytics> & {
     /** Request parameters that produced this entry — provenance only, opaque to consumers. */
     params: TrafficAreaAnalyticsParams;
     /**
@@ -2875,6 +4235,8 @@ export declare type TrafficAreaAnalyticsEntry = {
  * enough context for `recall` / `digest` tools.
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
 export declare type TrafficAreaAnalyticsParams = Record<string, unknown>;
 
@@ -2960,12 +4322,10 @@ declare type TrafficAreaAnalyticsStateEvents = {
  * incidents state, kept in the slice's `clusters` map keyed by entry id (see {@link ClustersRecord}).
  *
  * @group Agent Toolkit
+ *
+ * @ignore
  */
-export declare type TrafficIncidentsEntry = {
-    id: string;
-    timestamp: number;
-    label: string;
-    data: TrafficIncident[];
+export declare type TrafficIncidentsEntry = BaseEntry<TrafficIncident[]> & {
     /**
      * The captured query that produced this entry. Replayed by the monitor on each tick so
      * polling stays in the same slice the entry was loaded with. Reuses the loader's own
@@ -3053,9 +4413,9 @@ declare class TrafficIncidentsState implements StateSlice {
      * 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 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.
+     * That emit is what drives analysis replay: the session-level {@link JobEngine} re-runs every
+     * job 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>;
@@ -3162,7 +4522,7 @@ declare type TrafficIncidentsStateEvents = {
     /**
      * 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
+     * added, replaced in place, or removed. The {@link JobEngine} and the clustering re-run
      * match these against the entries they depend on.
      */
     'entries-change': {
@@ -3236,6 +4596,24 @@ declare class TrafficTilesState implements StateSlice {
     reset(): void;
 }
 
+/** Assumes a non-empty array — callers must guard against empty input before calling. */
+export declare const unionBBox: (bboxes: BBox[]) => BBox;
+
+/**
+ * Validates the value returned by analyse-* sandboxed code: rejects
+ * `undefined`, JSON-normalizes via `toJsonSafe`, and — when
+ * `outputFormat: "chart"` — checks the result is a Chart.js
+ * `ChartConfiguration`. Centralises the contract shared by analyse-places,
+ * analyse-routes, and analyse-geometries.
+ *
+ * @ignore
+ */
+export declare const validateAnalysisResult: (analysis: unknown, outputFormat: AnalysisOutputFormat) => {
+    value: unknown;
+} | {
+    error: string;
+};
+
 /**
  * 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
@@ -3248,6 +4626,83 @@ export declare type Verdict = {
     summary: string;
 };
 
+/** Everything `resolveAreas` needs from the host, as a narrow port. `ToolState` satisfies this in
+ * prod (see tool-state-where-context.ts); tests pass literal fakes. */
+export declare type WhereContext = {
+    viewportBBox(): BBox | undefined;
+    viewportCenter(): Position | undefined;
+    findPlaceById(id: string): Place | undefined;
+    geometryPlaceIdsForEntry(id: string): string[] | undefined;
+    fetchPlaceGeometry(id: string): Promise<Feature | undefined>;
+    geocodeArea(query: string, queryAs: QueryAs, bias?: Position): Promise<Place[]>;
+    geocodeAreas(query: string, bias?: Position): Promise<Place[]>;
+    fetchAreaPolygon(place: Place): Promise<Feature<Polygon | MultiPolygon> | undefined>;
+    getRoute(routeId?: string): {
+        features: Feature[];
+        label: string;
+    } | {
+        error: string;
+    };
+};
+
+/**
+ * locatePlace's `where` schema — `within` (singular fields), `nearby`, or `global`.
+ * discoverPlaces builds its own union in discover-places.ts using the plural-form within schema.
+ * @ignore
+ */
+export declare const whereSchema: z.ZodUnion<readonly [z.ZodObject<{
+    boundingBox: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodNumber>]>>;
+    query: z.ZodOptional<z.ZodString>;
+    queryAs: z.ZodOptional<z.ZodEnum<{
+        place: "place";
+        poi: "poi";
+    }>>;
+    placeId: z.ZodOptional<z.ZodString>;
+    mode: z.ZodLiteral<"within">;
+    viewport: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strip>, z.ZodObject<{
+    mode: z.ZodLiteral<"nearby">;
+    position: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    viewport: z.ZodOptional<z.ZodLiteral<true>>;
+    query: z.ZodOptional<z.ZodString>;
+    queryAs: z.ZodOptional<z.ZodEnum<{
+        place: "place";
+        poi: "poi";
+    }>>;
+    radiusMeters: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    mode: z.ZodLiteral<"global">;
+}, z.core.$strip>]>;
+
+/**
+ * Fields shared by both locatePlace's and discoverPlaces' `within` schemas — `mode` and the
+ * `viewport` flag. Spread into each consumer's `z.object({...})`.
+ * @ignore
+ */
+export declare const withinSharedFields: {
+    mode: z.ZodLiteral<"within">;
+    viewport: z.ZodOptional<z.ZodLiteral<true>>;
+};
+
+/**
+ * locatePlace's `within` schema — exactly one of viewport / boundingBox / query / placeId.
+ * @ignore
+ */
+export declare const withinWhereSchema: z.ZodObject<{
+    boundingBox: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodNumber>]>>;
+    query: z.ZodOptional<z.ZodString>;
+    queryAs: z.ZodOptional<z.ZodEnum<{
+        place: "place";
+        poi: "poi";
+    }>>;
+    placeId: z.ZodOptional<z.ZodString>;
+    mode: z.ZodLiteral<"within">;
+    viewport: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strip>;
+
+/** @ignore */
+export declare const WORKER_PROVIDED_PARAMS: readonly ["turf", "h3", "routeUtils", "log", "cluster"];
+
 export { }