feat(api): accept exemplar settings on API- and agent-authored tiles - #2809
Open
jordan-simonovski wants to merge 6 commits into
Open
feat(api): accept exemplar settings on API- and agent-authored tiles#2809jordan-simonovski wants to merge 6 commits into
jordan-simonovski wants to merge 6 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
🦋 Changeset detectedLatest commit: be4166f The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
Greptile SummaryThe PR completes external API and MCP support for exemplar settings and addresses all three previously reported validation defects.
Confidence Score: 5/5The PR appears safe to merge. The previously reported malformed-ID, unchanged-tile update, and activation-validation failures are all addressed, and no blocking failure remains.
|
| Filename | Overview |
|---|---|
| packages/api/src/routers/external-api/v2/utils/dashboards.ts | Preserves exemplar fields in both conversion directions and correctly scopes source validation for new, changed, and newly activated references. |
| packages/api/src/mcp/tools/dashboards/schemas.ts | Adds optional exemplar settings to line and stacked-bar MCP tile schemas with shared ObjectId validation and agent-facing eligibility guidance. |
| packages/api/src/utils/zod.ts | Extends the shared external time-chart schema with optional exemplar settings. |
| packages/api/src/routers/external-api/tests/dashboards.int.test.ts | Covers source existence and kind checks, unchanged-tile update exemptions, and revalidation when exemplars are enabled. |
| packages/api/src/mcp/tools/dashboards/tests/exemplarSettings.test.ts | Verifies MCP schema acceptance and rejection behavior for both supported tile types. |
| packages/api/openapi.json | Documents exemplar fields and their rendering eligibility and source requirements for line and stacked-bar tiles. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart LR
Client[External API or MCP client] --> Schema[Validate tile schema]
Schema --> SourceGate[Validate changed exemplar source]
SourceGate --> ConvertIn[Convert to internal tile config]
ConvertIn --> Mongo[(Persist dashboard)]
Mongo --> ConvertOut[Convert to external tile config]
ConvertOut --> Client
Reviews (10): Last reviewed commit: "fix(api): re-validate the exemplar trace..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Contributor
|
<!-- deep-review --> Deep Review✅ No critical issues found. The three-stage round trip this change set out to fix (input schema →
🟡 P2 — recommended
🔵 P3 nitpicks (4)
Reviewers (2 of 10 returned): testing, learnings-researcher. Dispatched but not returned before output was required: correctness, adversarial, security, api-contract, maintainability, kieran-typescript, agent-native, project-standards. Coverage caveats:
Testing gaps:
|
karl-power
previously approved these changes
Aug 5, 2026
jordan-simonovski
dismissed
karl-power’s stale review
August 5, 2026 13:02
The merge-base changed after approval.
jordan-simonovski
force-pushed
the
jordansimonovski/exemplars-agent-surface
branch
from
August 5, 2026 21:52
e5337c3 to
929dfdb
Compare
github-actions
Bot
added
the
review/tier-4
Contributor
🔴 Tier 4 — CriticalTouches authentication, tenancy data models, the public API or shipped database config — or substantially changes background tasks, the OTel pipeline, image build, or release CI. Why this tier:
Review process: Deep review from a domain expert. Synchronous walkthrough may be required. Stats
|
jordan-simonovski
force-pushed
the
jordansimonovski/exemplars-agent-surface
branch
from
August 5, 2026 21:56
929dfdb to
39d5bc8
Compare
Contributor
E2E Test Results✅ All tests passed • 275 passed • 1 skipped • 1006s
Tests ran across 4 shards in parallel. |
jordan-simonovski
force-pushed
the
jordansimonovski/exemplars-agent-surface
branch
from
August 5, 2026 22:12
39d5bc8 to
55718a5
Compare
jordan-simonovski
force-pushed
the
jordansimonovski/exemplars-agent-surface
branch
from
August 5, 2026 22:41
c701502 to
68850ae
Compare
jordan-simonovski
force-pushed
the
jordansimonovski/exemplars-agent-surface
branch
from
August 5, 2026 23:23
3cdb915 to
d4988ea
Compare
Contributor
|
Complete — see structured output. |
jordan-simonovski
force-pushed
the
jordansimonovski/exemplars-agent-surface
branch
from
August 5, 2026 23:44
d4988ea to
e8d3479
Compare
enableExemplars and exemplarTraceSourceId are accepted on line and stacked-bar tiles through the external v2 API and the MCP dashboard tools. The fields have to survive three places, and originally only cleared the first: the input schema, convertToInternalTileConfig's pick list on the way in, and convertToExternalTileChartConfig on the way out. They validated on write and were dropped before persistence, so the overlay could only ever be enabled by a human in the chart editor — the round trip is what makes them usable by an agent. Also documented in the OpenAPI spec, which is hand-maintained JSDoc rather than generated from the zod schemas, so adding the schema fields alone left the published contract silent about them. The MCP describe strings follow the file's own convention for source ids and say to call clickstack_list_sources and pick a trace-kind source, and note that the flag only renders on an exemplar-eligible tile. Stacked on the overlay: these fields do nothing without it.
Addresses review findings on the agent-facing exemplar settings. `exemplarTraceSourceId` was a bare `z.string()` on the MCP surface, so an agent passing a source *name* had the tile saved and every marker's trace link silently dead. It now uses the shared objectIdSchema, matching the external API. Format alone was not enough though: a well-formed id for a source that does not exist, or for a metric or log source, failed the same way. It now goes through the same existence check as every other tile source reference, plus a Trace-kind gate modelled on the heatmap one — which is what the field's own description has been promising all along. The eligibility text in both descriptions omitted the aggregation constraint, so an agent following it with `count` — which the neighbouring aggFn description recommends for histograms — got an inert overlay and no error. Both now name the compatible functions and say why count and sum are excluded. Tests: both tile types through the MCP schema, both directions of the tile conversion (the changeset's headline claim had no coverage, and the two tile types have separate blocks in both converters), and the existence and kind gates end to end.
The round-trip test needs one type assertion: its tile builder takes the display type as a parameter, so `displayType` is the union rather than a literal and TS cannot pick a branch of the external tile config union without it. Writing the two configs out separately to avoid the assertion loses the it.each that makes the line and stacked_bar cases symmetrical — which is the point, since both converters handle them in separate blocks.
…check Addresses a review finding on the previous fix. The kind gate ran over every tile in the request, so an unchanged tile whose trace source had since been deleted or changed kind would fail it on every subsequent save — making an unrelated edit elsewhere on the dashboard impossible to persist. Scoped to new and changed tiles on update, mirroring filterChangedHeatmapTiles, which exists for exactly this reason. The existence check in getMissingSources is deliberately left unscoped: it treats every source reference on the dashboard the same way and reports them with one clear message, and singling this field out would be the inconsistency rather than the fix.
…heck too Addresses a review finding on the previous fix, which only went half way. The kind gate was scoped to changed tiles but the existence check was not, so deleting an exemplar trace source still made every later save of that dashboard fail. The two checks now live together and share one exemption: a deleted source and a source whose kind changed are the same situation to whoever hits them, and nobody could predict that one blocks an edit and the other does not. My earlier reasoning for leaving the existence check unscoped — that getMissingSources should treat every source reference alike — weighted mechanical consistency over what actually happens. A missing `sourceId` means the tile cannot render; a missing `exemplarTraceSourceId` means a marker's trace link is dead on a chart that is otherwise fine. That is not worth refusing an unrelated edit over.
…itched on Addresses a review finding on the previous fix. The unchanged-tile exemption keyed on the trace source id, so a tile carrying a source id while exemplars were disabled kept the exemption when an update turned them on. Nothing was following that reference in the meantime, so the source could have been deleted or stopped being a Trace source with no visible effect — and switching markers on then persisted them pointing at nothing. An id nobody was following is not the same as one about to draw markers, so the off-to-on transition is now checked as if the reference were new. A tile whose exemplars were already on keeps the exemption, which is the case that exemption exists for.
jordan-simonovski
force-pushed
the
jordansimonovski/exemplars-agent-surface
branch
from
August 6, 2026 21:54
e8d3479 to
be4166f
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Last of the PRs replacing #2536. Stacked on #2808 — these fields do nothing without the overlay.
What it does
enableExemplarsandexemplarTraceSourceIdare accepted on line and stacked-bar tiles through the external v2 API and the MCP dashboard tools.The part that was actually broken
The fields have to survive three places, and the original change only cleared the first:
convertToInternalTileConfig'spicklist on the way in,convertToExternalTileChartConfigon the way out.They validated on write and were then dropped before persistence. So the feature could only ever be switched on by a human in the chart editor — an agent could set the field, get a 200, and have it silently vanish. The round trip is what makes them usable.
Also documented in the OpenAPI spec, which is hand-maintained JSDoc rather than generated from the zod schemas — so adding schema fields alone left the published contract silent about them.
MCP describe strings
They follow the file's own convention for source ids: say to call
clickstack_list_sourcesand pick a trace-kind source, and note that the flag only renders on an exemplar-eligible tile (single non-ratio histogram series, no groupBy). Without that an agent gets a 200 and no markers, with nothing explaining why.Verification
make ci-lintandmake ci-unit(5,350 tests) pass. Merged cleanly with main'sseriesLimitaddition, which landed in the same conversion functions — both sets of fields are kept.