Skip to content

fix: keep implementation details out of user-facing output - #348

Merged
vishr merged 2 commits into
mainfrom
fix/user-facing-internals
Oct 18, 2026
Merged

vishr merged 2 commits into
mainfrom
fix/user-facing-internals

Conversation

@vishr

@vishr vishr commented Oct 18, 2026 •

Copy link
Copy Markdown
Member

Summary

  • Chat, dashboards and MCP results showed storage-engine and format names, engine error classes and types, internal relation names, Go error chains, file paths and tool names. A user saw raw engine errors in result output, and recorded clips showed a sql source label, raw column names and the assistant's narration between steps.
  • One presenter in internal/panel publishes errors by cause. Operational failures (trace reads, exemplars, schema discovery, storage) show "Could not read the requested data. Try again." and log the cause. Errors in authored SQL or structured filters keep their meaning and candidate bindings, without engine branding, engine-specific types, the telemetry. qualifier, paths, wrapping chains or expanded server SQL. It applies to panel results, validation problems, previews, save receipts, no_data guidance and MCP tool errors. Product guidance passes through unchanged.
  • Empty-panel diagnoses describe the filter in product language; measure hints use plain words.
  • Panel captions drop the data-source label. Table headers, legends, axes, tooltips and accessibility text use readable labels (avg_ms → "Avg (ms)"); data keys are unchanged.
  • Chat shows only the final answer: provisional reasoning events are no longer emitted, the activity line uses step labels, and tool failures show product step names with presented messages.
  • Explain and Fix post a short visible request. The panel diagnostics travel as AG-UI run context, are stored hidden with that user message (never returned by the thread API), survive follow-ups and retries, and are capped at 16 KiB.
  • Trace and dependency results no longer carry storage sources, schema identifiers or query IDs (MCP reference updated). The agent prompt adds rollups, aggregation tables and internal windows to the never-mention list and requires product language in panel text.

Verification

  • Go table tests push representative engine and wrapped operational errors through every boundary, with native failing SQL for binder, catalog and conversion errors; relation names, standard SQL types, dotted aliases and candidate bindings survive author diagnostics; routes survive product diagnoses through session.CallTool.
  • UI tests for captions, column labels, the removed narration, tool-failure mapping and Explain/Fix context.
  • go test ./..., go test -race on touched packages, 1,418 UI tests, just ui-check, just docs-generate-check.
  • Browser: smoke, accessibility and panel SQL editor, 60 passed.
  • Two Codex adversarial reviews; all six findings fixed with regressions that failed first.
  • just check in the pre-push hook.

Chat, dashboards and MCP results showed storage-engine and format names,
engine error classes and types, internal relation names, Go error chains,
file paths and tool names. A user saw raw engine errors in result output.

- One presenter in internal/panel publishes errors by cause. Operational
  failures (trace reads, exemplars, schema discovery, storage) show "Could
  not read the requested data. Try again." and log the cause. Errors about
  authored SQL or structured filters keep their meaning and candidate
  bindings, without engine branding, internal types, the telemetry schema
  qualifier, paths, wrapping chains or expanded server SQL. It applies to
  panel results, validation problems, previews, save receipts, no_data
  guidance and MCP tool errors; product guidance passes through unchanged.
- Empty-panel diagnoses describe the filter in product language instead of
  quoting SQL; measure hints use plain words.
- Panel captions drop the data-source label. Column headers, legends, axes,
  tooltips and accessibility text use readable labels such as "Avg (ms)";
  data keys are unchanged.
- Chat shows only the final answer: provisional text between tool calls is
  no longer emitted, and the activity line uses step labels. Tool failures
  show product step names and presented messages.
- Explain and Fix post a short visible request. The panel diagnostics travel
  as AG-UI run context, are stored hidden with that user message, survive
  follow-ups and retries, and are capped at 16 KiB.
- Tool results no longer carry data-source names or query IDs. The agent
  prompt adds rollups, aggregation tables and internal windows to the
  never-mention list and requires product language in panel text.

Claude-Session: https://claude.ai/code/session_018HfyEXHyGD1utmKF4CQtyQ
Comment thread internal/panel/errors.go Fixed
CodeQL flagged hand-built quoting of candidate column names. The names are
already restricted to identifier characters; strconv.Quote makes the escaping
explicit.

Claude-Session: https://claude.ai/code/session_018HfyEXHyGD1utmKF4CQtyQ
@vishr
vishr merged commit 3ebde7c into main Oct 18, 2026
16 checks passed
@vishr
vishr deleted the fix/user-facing-internals branch October 18, 2026 20:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants