fix(mcp): render notes and app resilience for MCP UI apps

[GeneralistDev]

Problem

A model that runs the exec tool from a supported UI host draws its own chart of data that an interactive view already shows. The second chart costs tokens and review time.

An analytics initialization error also stopped the UI app from rendering at all.

This layer builds on the two desktop layers below it in the stack (#96638, #96639).

Changes

• Supported UI hosts get a render note: the interactive view already shows the result. CLI and JSON output do not change.
• The render-note footer counts in output token estimates.
• A UI app stays alive when posthog-js-lite cannot initialize.

Note

This layer sits on top of the desktop layers on purpose. If the render note landed first, it would tell models that a chart rendered while the desktop fix was not live yet.

How did you test this code?

• Build-tool-result tests pin the render note for UI hosts, CLI clients, and JSON output.
• Exec tests pin the token estimate with the footer included.
• The MCP unit tests, lint, and format checks passed.

👉 Stay up-to-date with PostHog coding conventions for a smoother review.

Automatic notifications

• Publish to changelog?

Docs update

None. This fix does not change a documented setting or workflow.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

This PR is the top layer of a 3-layer stack split from #95878. The user asked for the split and approved the grouping before the work started. The combined tree of the stack matches the original branch tree exactly, so no code changed in the split.

The code itself was authored and tested in #95878. This PR only reorganizes those commits. PostHog Desktop and command-line development tools supported the split.

Skills invoked: /stacking-prs, /writing-pr-descriptions, /unslop.

---

Created with PostHog Desktop

[github-actions]

🤖 CI report

✅ Trunk lane — non-backend lane

This PR is assigned to the non-backend lane. It does not run backend Python tests and may merge in parallel with PRs in other lanes.

🚨 Comment density — 30% of added code lines are comments (52 of 174)

This section warns when comments are more than 3% of the code lines a PR adds, and alerts above 6%. Before agent-assisted PRs, the typical share was about 2%. Only full-line comments count. Docstrings, generated files, snapshots, migrations, and workflow files are left out.

Comments that restate the code, record how the change came about, or narrate the next line add noise for the next reader. Keep the comments that explain a reason the code cannot show, and remove the rest. See .agents/skills/writing-code-comments/SKILL.md for the house rules.

Files with the most added comment lines:

File	Comment lines	Added lines
services/mcp/src/lib/build-tool-result.ts	29	57
services/mcp/src/ui-apps/analytics/posthog.ts	8	23
services/mcp/tests/unit/build-tool-result.test.ts	7	17
services/mcp/tests/unit/exec.test.ts	4	8
services/mcp/tests/unit/ui-apps-analytics.test.ts	4	68

This check does not block merging. It updates on every push and clears when the share drops.

ℹ️ MCP UI apps size — 33 app(s), 17665.2 KB JS

Built size of each MCP UI app (main.js + styles.css).

App	JS	CSS
debug	600.0 KB	195.2 KB
action	458.2 KB	195.2 KB
action-list	564.9 KB	195.2 KB
cohort	457.2 KB	195.2 KB
cohort-list	563.8 KB	195.2 KB
email-template	457.0 KB	195.2 KB
error-details	472.9 KB	195.2 KB
error-issue	457.9 KB	195.2 KB
error-issue-list	564.7 KB	195.2 KB
experiment	562.0 KB	195.2 KB
experiment-list	565.6 KB	195.2 KB
experiment-results	567.1 KB	195.2 KB
feature-flag	567.6 KB	195.2 KB
feature-flag-list	571.4 KB	195.2 KB
feature-flag-testing	461.4 KB	195.2 KB
inline-scan	457.7 KB	195.2 KB
insight-actors	563.0 KB	195.2 KB
invite-email-preview	456.4 KB	195.2 KB
llm-costs	560.0 KB	195.2 KB
session-recording	459.0 KB	195.2 KB
survey	458.8 KB	195.2 KB
survey-global-stats	562.7 KB	195.2 KB
survey-list	565.5 KB	195.2 KB
survey-stats	562.7 KB	195.2 KB
trace-span	457.6 KB	195.2 KB
trace-span-list	564.7 KB	195.2 KB
vision-observation-list	563.9 KB	195.2 KB
workflow	457.5 KB	195.2 KB
workflow-list	564.2 KB	195.2 KB
loops-review	461.9 KB	195.2 KB
query-results	756.3 KB	195.2 KB
render-ui	839.5 KB	195.2 KB
visual-review-snapshots	462.0 KB	195.2 KB

[greptile-apps]

Prompt To Fix All With AI

### Issue 1
services/mcp/src/ui-apps/analytics/posthog.ts:40-52
**Recovery path lacks coverage**

The new initialization-failure path is not tested by making the PostHog constructor or `register` throw. Without that regression coverage, a later refactor could remove the recovery behavior or the `client = null` reset and reintroduce the UI-app crash without the MCP unit suite detecting it.

### Issue 2
services/mcp/src/lib/build-tool-result.ts:104-106
**Token test misses footer**

The token-estimation test only checks that the result exceeds the pointer's token count. That was already true when only `structuredContent` was counted, so the test would still pass if `estimateTokens(footer)` were removed. Assert the structured-content estimate plus the footer estimate so this new accounting behavior is actually protected.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "chore(mcp): trim comments in tool result..." | Re-trigger Greptile}

[trunk-io]

   

View Full Report ↗︎ ⋅ Docs

[posthog]

Thermo-nuclear code quality review

Strict maintainability pass on this layer, run with the thermo-nuclear-code-quality-review rubric. This is the smallest layer of the three, and the try/catch is correct and well explained. One finding is structural.

1. estimateResponseTokens takes the text apart to find what the builder just joined

if (response.structuredContent && text.startsWith(STRUCTURED_CONTENT_ONLY_TEXT)) {
    const footer = text.slice(STRUCTURED_CONTENT_ONLY_TEXT.length)
    return estimateTokens(response.structuredContent) + estimateTokens(footer)
}

buildToolResultPayload joins the pointer and the note into one string. Twenty lines later, estimateResponseTokens cuts that string back apart by prefix length to count the two pieces separately. The two functions are now coupled through the exact text of a constant, and the comment you updated documents the coupling instead of removing it:

estimateResponseTokens keys off the pointer prefix

This breaks quietly. A second footer, a leading note, or any reordering gives a wrong count with no error. The equality check it replaces at least failed loudly.

Please keep the pieces separate until the payload is built. For example, collect the footers in a list:

const footers: string[] = []
if (discoveryHint) footers.push(discoveryHint)
if (includeUiResponseMeta && resourceUri && !useJson) footers.push(UI_APP_RENDER_NOTE)
const text = [body, ...footers].join('\n\n')

Then the token count is estimateTokens(structuredContent) + estimateTokens(footers.join('')) when the body is only the pointer. No string is cut apart, and the two functions stop depending on the wording of a constant. This also removes the duplicated text = \${text}\n\n...`` pattern that now appears twice.

2. includeUiResponseMeta now controls two unrelated things

The same flag gates both:

• line 213 — append prose to the text channel for the model.
• line 223 — move the app payload onto _meta.

The name describes the second one only. A caller who wants the payload move now also gets a sentence added to the model's context, and nothing in the name warns them. tool-executor.ts already documents the flag as the payload-move switch.

Please use a separate option for the note, for example includeRenderNote. The exec.ts call site sets both, so nothing changes in behavior, and each flag then says what it does.

3. The condition uses the raw value where a named one exists

const hasUiResource = !!resourceUri
...
if (includeUiResponseMeta && resourceUri && !useJson) {

hasUiResource is defined for this, and the sibling conditions use it. Please use it here too.

More generally, buildToolResultPayload now gates on isStringResult, useJson, callerWantsJson, hasUiResource, forceUiDataToMeta, includeUiResponseMeta, suppressStructuredContent and structuredContentOnly. Each one arrived for a good reason, and each is explained well. Together they are hard to hold in mind, and this PR adds a ninth gate. It is not this PR's job to fix, but the function is close to needing a typed decision object instead of eight independent booleans.

4. The try/catch also covers register

try {
    client = new PostHog(...)
    client.register({...})
} catch (error) {
    client = null
}

The comment names the constructor as the thing that throws. If register throws instead, this drops a client that works, and the app loses all analytics rather than two properties. Please put only the constructor inside the try, or catch register separately.

Also: is the localStorage read configurable? If posthog-js-lite has a persistence option, setting it is the direct fix, and the try/catch becomes a guard against something else. If it is not configurable, please pin the version in the comment, so a later upgrade that fixes it can also delete this block.

Verdict

The behavior is correct, and the sandbox comment is exactly the kind of note that saves the next reader. Please fix #1 before merge. #2, #3 and #4 are small and worth doing in the same pass.

_{Automated strict code-quality review, requested in Slack.}