Code generation

Experimental. analyseData, processData and executeMaplibreCode run model-written JavaScript; their inputs, injected identifiers and output contracts may change without notice. In the browser, the data tools' code runs isolated with no DOM, storage or network. executeMaplibreCode — and the data tools under Node or when the isolation can't start — run in your app's own realm, with its privileges. Read the threat model before shipping.

Three tools take JavaScript as a parameter instead of a fixed argument list. The model writes the code; the plugin compiles it with new AsyncFunction(...paramNames, code) and calls it with the injected inputs.

That is how the agent answers open-ended questions — "bar chart of POI categories", "union the boundaries of these cities", "focus the camera on the worst traffic on the route" — without a dedicated parameter for every variation: one tool per intent, any computation inside.

Where it shows up

Execution model

Each tool that accepts code builds an AsyncFunction whose parameters are a fixed set of injected identifiers, then calls it. Both data tools narrow their inputs per turn — see Scope-aware data tools.

Where the code runs:

• analyseData / processData in the browser — a Web Worker inside a sandboxed, opaque-origin iframe; see Data-tool execution isolation.
• analyseData / processData under Node or SSR, or when the iframe can't start — the main thread, with only input copying and shadowed globals, which raise the bar but are no boundary.
• executeMaplibreCode — always the page itself, with the live map and none of those measures.

The body works like any other async function body: top-level await is fine, locals and helper consts are fine, and the body must end with return …;. Importantly:

• code is the function body, not a function expression. Writing (args) => { return result; } as the whole code creates an arrow and discards it — drop the wrapper and have the body itself end with return result;.
• The sandbox is not a Node module: require is undefined and ES import / export statements don't parse inside the function body. The libraries you'd reach for (turf, h3, routeUtils, cluster) are already injected, and the sanitiser strips const x = await import(…) redeclarations of those names.
• The sandbox cannot call other tools (no functions.discoverPlaces(...), no tools.X). To bring in new data, call the relevant tool BEFORE the code-generation tool and pass the resulting entry id in.

Pre-flight sanitisation

LLMs regularly prepend const turf = require('@turf/turf'), const h3 = await import('h3-js'), or const placesByEntry = arguments[0].placesByEntry out of habit. These collide with the injected parameters and would throw at parse time ("Identifier 'X' has already been declared") before the body even runs.

stripInjectedRedeclarations defensively removes those lines — but only when the RHS is one of:

• require(…)
• import(…) (with or without await)
• arguments[N].name or arguments[N]['name']

A const geometriesByEntry = … that genuinely shadows an injected name (e.g. const geometriesByEntry = placesByEntry['places-2'].features.map(...)) is left untouched. This is deliberate — a naive name-only filter would silently corrupt legitimate user code.

Input copying

The injected state inputs — the per-entry records such as placesByEntry, plus previous / now on monitored runs — are copied before they reach the code, on every path (the browser's isolated run receives a structured clone). Mutating them in place is safe and local:

// Sorting/splicing the injected collection touches a throwaway copy, never live state.
const places = placesByEntry['places-2'];
places.features.sort((a, b) => a.properties.score - b.properties.score);
return { places: { type: 'FeatureCollection', features: places.features.slice(0, 10) } };

Without the copy, an in-place mutation would corrupt the entry the data came from and leak into later turns. The libraries are passed through as they are.

Shadowed globals

A fixed set of network, storage, DOM and process globals — fetch, XMLHttpRequest, WebSocket, EventSource, localStorage, sessionStorage, indexedDB, document, window, globalThis, self, navigator, importScripts, process — is bound to undefined inside the analyseData / processData body, wherever it runs. Code that reaches for one fails loudly instead of making a network call or touching browser state.

This is a tripwire, not a security boundary: the same capabilities stay reachable through constructor walks (({}).constructor.constructor) and other realm escapes, so it catches accidental access, not a determined or jailbroken model. executeMaplibreCode is not shadowed — it needs live browser access. In the browser, the isolated run is the boundary.

Injected identifiers

There is one per-entry record per kind, mapping an entry id to that entry's data — no merged variable:

• placesByEntry — Record<entryId, FeatureCollection<Place>>
• routesByEntry — Record<entryId, FeatureCollection<Route>>
• incidentsByEntry — Record<entryId, TrafficIncident[]> (values are plain arrays)
• geometriesByEntry — Record<"${kind}:${id}", PolygonFeature[]> (keyed by the composite tagged source ${kind}:${id}, e.g. "customGeometries:abc" — not a bare id; values are plain arrays, and each feature carries properties._source: { kind, id })
• trafficAreaAnalyticsByEntry — Record<entryId, TrafficAreaAnalytics> (each value is a full FeatureCollection; per-entry collection-level properties are preserved — no cross-entry merge)
• byodByEntry — Record<entryId, FeatureCollection>

Read one entry by id (placesByEntry['places-2']), or span every requested entry of a kind by merging with Object.values(...): Object.values(placesByEntry).flatMap((fc) => fc.features) for the FeatureCollection kinds (places / routes / byod / trafficAreaAnalytics), and Object.values(incidentsByEntry).flat() for the array kinds (incidents / geometries).

Each record is undefined when its *EntryIDs argument was omitted from the tool call — code must guard before reading (if (placesByEntry) ..., placesByEntry['places-2']?.features.length, etc.). Scope narrowing trims which kinds the tool documents in its prompt, but the runtime sandbox always carries the full set of names; out-of-scope kinds simply arrive as undefined.

Shared libraries

The two data tools get four libraries; executeMaplibreCode gets none, only map:

• turf — @turf/turf v7: area, length, bbox, centroid, union, intersect, difference, buffer, distance, booleanPointInPolygon, pointsWithinPolygon, clustersDbscan, convex, etc.
• h3 — h3-js: hex-grid math only (latLngToCell, cellToLatLng, cellToBoundary, polygonToCells, gridDisk, cellArea).
• routeUtils — SDK route section / progress helpers, useful when routesByEntry is in scope: getSectionBBox, getRouteProgressForSection, getRouteProgressBetween, calculateProgressAtRoutePoint, getCoordinateAtRouteProgress, getProgressAtNearestRoutePoint. (For a plain route bounding box, turf.bbox(route) is enough.)
• cluster(incidents, params?, previous?, now?) — the DBSCAN incident clustering behind clusterIncidents; params takes eps, minMembers, maxClusters and preFilter.

All four are pure computation. None does spatial search, place lookup, or HTTP. To fetch new places, the agent must call discoverPlaces (or locatePlace) BEFORE the code-generation tool and pass the resulting entry id in.

Turf input gotchas

Turf is fussy about input shape. The runtime hints at the right pattern when it throws, but knowing the rules up front avoids the retry loop:

• A single entry of an FC kind (placesByEntry[id], routesByEntry[id], trafficAreaAnalyticsByEntry[id], byodByEntry[id]) is a FeatureCollection — pass it directly: turf.bbox(placesByEntry['places-2']). Never turf.bbox(placesByEntry['places-2'].features).
• Arrays (incidentsByEntry[id], geometriesByEntry[key], or any merged Object.values(...) list) — iterate per-feature (for (const f of incidentsByEntry[id]) turf.X(f)) or wrap with turf.featureCollection([...]).
• Never .map(f => f.geometry.coordinates).flatMap(...) to feed turf — that strips the feature wrapper turf reads and throws "coordinates must be an Array" or mixes Point/LineString shapes silently.
• Incidents are mixed Point + LineString — guard with if (inc.geometry.type === "LineString") before line-only ops.
• Turf v7 set ops — union / intersect / difference take one FeatureCollection:

  turf.difference(turf.featureCollection([outer, inner]))   // v7 ✓
  turf.difference(outer, inner)                             // v6 — throws in v7
  

Performance hints

For large-N nearest/within queries, pre-bucket points with h3 before running turf:

const cells = points.map((p) => h3.latLngToCell(p.geometry.coordinates[1], p.geometry.coordinates[0], 8));
// Only run turf on same- or neighbour-cell pairs — O(N+M) instead of O(N·M).

Pick res so each cell is approximately your query radius (h3 res 8 ≈ 460 m edge; res 9 ≈ 175 m).

Output contract

analyseData — outputFormat

• "json" (default) — any JSON-serializable value. Rendered as text in the chat.
• "chart" — a Chart.js ChartConfiguration ({ type, data, options? }). The chat UI passes the config straight to new Chart(ctx, analysis).

The accepted chart types are: bar, line, pie, doughnut, radar, polarArea, scatter, bubble. Returning a config with any other type is rejected before the result reaches the model.

For per-point detail you'd normally put in a Chart.js tooltip.callbacks function, use a string[] label — Chart.js renders it multi-line on the axis tick AND in the tooltip title. Functions don't survive the JSON boundary.

processData envelope

processData code returns { places?, placeConnections?, geometries?, fitOnMap?, byod? }, with at least one of places, geometries, fitOnMap or byod:

• places (with optional attached geometries), standalone geometries and byod are mutually exclusive — one is written per call, the others are dropped.
• placeConnections draws lines between output places and requires places.
• fitOnMap moves the camera and composes with any of them.

Return-value validation

Every code-generation tool runs its return value through three checks before handing it to the model:

1. Not undefined. If the body doesn't return (e.g. the code was written as (args) => { return … } so the arrow is created and discarded), the tool surfaces a targeted error telling the model to drop the arrow wrapper.
2. JSON.parse(JSON.stringify(value)). This normalizes NaN, Infinity, undefined object values, and sparse arrays to null / drops them — silent-poison values that would otherwise break the next turn's ModelMessage validation. Circular references throw and surface as a clear LLM-facing error.
3. Chart shape check (for outputFormat: "chart" only). The type must be in the whitelist above and data must be a non-null object.

The net effect: anything that comes out of the sandbox is safe to round-trip through the model's next prompt, or surfaces a precise diagnostic that the model can act on.

Self-correcting error hints

When sandbox code throws, the runtime matches the message against a curated list of common pitfalls and appends a targeted Hint: to the error returned to the model. The model usually corrects on the next attempt.

Patterns recognised include:

So the tool descriptions needn't spell out every guardrail: the runtime corrects the model when it trips.

Threat model

In the browser, the data tools' code is isolated. Everywhere else the security boundary is the model and the prompt path you let users drive, not the runtime: input copying and shadowed globals stop accidental mutation and casual global access, not a determined model. Treat that code like a <script> tag controlled by your model provider:

• executeMaplibreCode holds the live map and, through it, the page — a jailbroken or compromised model can exfiltrate user data or rewrite the page.
• Data tools on the main thread (Node, SSR, or a browser where the iframe failed to start) can reach fetch, storage and the DOM through realm escapes such as ({}).constructor.constructor("return globalThis")().
• Prompt injection from a tool result — say, a place description with adversarial text — can steer the model into writing such code.

If your deployment can't tolerate this — say, a page with privileged session cookies or sensitive in-browser state — remove the code-generation tools:

const agent = createMapAgent(map, {
    model: openai('gpt-4o'),
    tools: {
        analyseData: false,
        processData: false,
        executeMaplibreCode: false,
    },
});

Removing executeMaplibreCode alone keeps the isolated data tools. The fixed-schema tools (locatePlace, setRoute, findReachableAreas, the display tools, …) stay usable either way.

Data-tool execution isolation (experimental)

In the browser, analyseData / processData code runs off the main thread in a locked-down realm — a Web Worker inside a sandboxed, opaque-origin <iframe>. The environment picks where it runs (selection by environment). No setup is needed; the optional codeExecution tunes the browser run:

const agent = createMapAgent(map, {
    model: openai('gpt-4o'),
    codeExecution: {
        timeoutMs: 5000, // wall-clock budget per isolated run (default 10000)
    },
});

What this buys you, and what it doesn't:

• Opaque origin (sandbox="allow-scripts", no allow-same-origin) — the code can't read the parent's cookies / localStorage / DOM.
• No network — the iframe's CSP is default-src 'none', so fetch / XHR / WebSocket / beacon all fail. The data is injected; the sandbox has no legitimate network need.
• Termination — a runaway / infinite-loop body is killed at timeoutMs (the worker is terminated and respawned) without freezing the main thread.
• The iframe is long-lived; the worker stays warm and each call runs in a fresh function scope.

How the pieces fit

The generated code runs two hops away from your app — across an opaque-origin iframe and into a Web Worker — with postMessage + structuredClone as the only channel between them:

The three boundaries map to the threats: the opaque origin stops DOM and storage access, the CSP stops network egress, and worker termination stops runaway loops. The libraries are bundled into the worker, so generated code never imports them.

Why a worker inside an iframe

The two-layer nesting isn't redundant — each layer provides a boundary the other can't:

• Why a worker, not just script in the iframe. The iframe alone gives the opaque origin and the CSP, but code running on the iframe's own thread can't be stopped — a synchronous while (true) {} blocks that thread's event loop and there's no way to interrupt a running thread from outside. worker.terminate() is the only reliable kill switch, so the generated code runs in a worker that can be killed (and respawned) on timeout — leaving the warm iframe intact.
• Why an iframe, not just a bare worker. A bare worker inherits its owner document's CSP; giving it a stricter default-src 'none' would require serving the worker script with a Content-Security-Policy response header — i.e. the consuming app's server would have to cooperate. The SDK ships to arbitrary hosts and can't require that. A <meta> CSP authored in the iframe's srcdoc travels with the SDK code, no host config needed. This is the decisive reason for the iframe.

Running off the main thread is also why heavy turf/h3 computation over large FeatureCollections doesn't freeze the map UI — though the postMessage + structuredClone hop pays a serialization cost at each edge, so it's a net win for compute-heavy bodies, not literally zero main-thread work.

Worker libraries (turf / h3 / routeUtils / cluster)

The worker can't import your app's modules, so it needs the libraries as one self-contained script. The plugin ships them in a separate lazy chunk, loaded only when the isolated run first starts — your main bundle is unaffected.

To pin a build, override with loadWorkerLibrarySource: return UMD or IIFE JavaScript defining self.turf and self.h3, plus self.routeUtils and self.cluster if generated code uses them. The override replaces the bundled source, so re-supply every namespace your code relies on:

codeExecution: {
    loadWorkerLibrarySource: async () => {
        const turf = await (await fetch('/vendor/turf.min.js')).text();
        const h3 = await (await fetch('/vendor/h3-js.umd.js')).text();
        // turf first — routeUtils reads self.turf. Append your own routeUtils / cluster
        // scripts here too if your generated code calls them.
        return `${turf}\n;${h3}`;
    },
},

Selection by environment

Execution mode is not configurable — it's chosen by environment:

There is no opt-out in the browser. If the iframe fails to start, execution falls back to the main thread with a console warning — never silently.

Experimental. The isolation depends on real-browser behaviour — CSP enforcement, opaque-origin iframes, worker termination — which an end-to-end suite verifies in real Chromium on every CI run. executeMaplibreCode is not isolated: it needs the live map.

Example

A user asks "Bar chart of how many places of each category we have." The classifier picks analyseData with toolScopes.analyseData = { kinds: ['places'] }, narrowing its schema to places. The model emits:

analyseData({
    placesEntryIDs: ['places-2'],
    name: 'category-bar',
    outputFormat: 'chart',
    code: `
        const counts = {};
        for (const p of placesByEntry['places-2'].features)
            for (const c of (p.properties.poi?.categories ?? []))
                counts[c] = (counts[c] ?? 0) + 1;
        const entries = Object.entries(counts).sort((a, b) => b[1] - a[1]);
        return {
            type: 'bar',
            data: {
                labels: entries.map((e) => e[0]),
                datasets: [{ label: 'Places', data: entries.map((e) => e[1]) }],
            },
        };
    `,
});

The plugin runs the body, validates the Chart.js config, records it as category-bar against the source entry, and returns it to the model. The chat UI receives the same config and renders the chart inline.

Cross-kind composition

turf and h3 work on every feature, whichever record it came from, so one call can combine placesByEntry (Points), routesByEntry (LineStrings), incidentsByEntry (Point or LineString), geometriesByEntry (Polygon / MultiPolygon), trafficAreaAnalyticsByEntry (Polygon tiles with metrics) and byodByEntry (mixed GeoJSON).

A few common bridges:

• Point ↔ LineString — turf.pointToLineDistance(point, lineFeature, { units: "meters" }), turf.nearestPointOnLine(line, point).
• Point ↔ Polygon — turf.booleanPointInPolygon(point, poly), turf.pointsWithinPolygon(turf.featureCollection(points), poly).
• LineString ↔ Polygon — turf.lineIntersect(line, poly), turf.booleanCrosses(line, poly), turf.lineSplit(line, poly).
• Polygon ↔ Polygon — turf.union/intersect/difference(turf.featureCollection([a, b])) (Turf v7 takes a single collection).
• Point/LineString ↔ trafficAreaAnalytics tile — iterate trafficAreaAnalyticsByEntry[id].features (or Object.values(trafficAreaAnalyticsByEntry).flatMap((fc) => fc.features)) to find which tile a place/route segment falls into and read its metric (tile.properties.congestionLevel, etc.).
• Buffer to bridge kinds — turf.buffer(anyFeature, meters/1000, { units: "kilometers" }) turns a point or line into a polygon you can then filter against.
• h3 — h3.latLngToCell(lat, lng, res) for any Point; h3.polygonToCells(poly.geometry.coordinates, res) for any Polygon.

The arguments are GeoJSON Features — pass the whole feature (placesByEntry[id].features[i], routesByEntry[id].features[0], geometriesByEntry[key][i], …), not the bare geometry.coordinates. A few helpers accept coords directly but most expect Features.

Related

• Scope-aware data tools — how the per-turn scope mechanism keeps the prompt small.
• Bring your own data — feeding BYOD layers into the sandbox via byodEntryIDs.
• Customizing tools — removing the code-generation tools, or wrapping them with policy.
• State — how processData outputs land as new entries.
• Securing your agent — where the sandbox sits among the limits the toolkit does and does not enforce.