@flue/react should expose safe display metadata for tool parts

[dknecht]

Summary

Reduced dynamic-tool parts currently expose raw tool input / output, but there is no separate safe-display contract for UI surfaces that want to show live tool activity without exposing trusted context or user/customer text verbatim.

For agent activity feeds, raw tool payloads are often the wrong presentation boundary:

• tool output may contain retrieved documents, case/customer text, or trusted context;
• tool input may contain large internal prompt/context objects;
• apps often only need a friendly label, lifecycle state, compact safe argument summary, and maybe a safe operator-facing result summary.

Why this matters

A React app consuming useFlueAgent().messages should be able to render a live activity feed from reduced message parts without either:

• displaying raw tool payloads to users/operators by default;
• reconstructing raw events separately;
• or maintaining app-specific deny-lists for every tool whose output is unsafe to show.

Possible API shape

One option would be to let tool definitions or emitted tool events provide explicit display metadata, for example:

{
  type: "dynamic-tool",
  toolName,
  toolCallId,
  state,
  input,
  output,
  display: {
    label: "Loading case context",
    summary: "Loaded case context",
    details?: "operator-safe detail text",
    inputSummary?: "domain=example.com"
  }
}

The exact shape is less important than the principle: raw input/output and safe UI presentation should be distinct.

Related

This is related to origin/visibility metadata for reduced messages: apps need to know which parts are user-visible and which are internal orchestration/debug data.

[dknecht]

A concrete failure mode we hit may help clarify the problem.

This is not just about raw input / output being available for debugging. The issue shows up when a React app uses useFlueAgent().messages as the source for a live activity feed.

During a run, the live reduced message stream can contain one shape of parts, while after reload the hydrated durable history can contain a more complete/settled transcript. That can make the same run appear differently before and after reload:

• before reload, the UI may show a final application state plus stale/running tool activity from the live reducer;
• after reload, the UI may show terminal tool rows plus assistant text summaries from hydrated history;
• if the app renders those parts directly, internal planning/orchestration text can look like user-facing assistant chat;
• if the app exposes dynamic-tool.output as technical details, trusted context or retrieved/customer text can appear in the activity feed.

The local workaround is to render only positive-contract parts: application-authored data-* milestones, safe tool labels, and explicitly external user messages. But that means the app is no longer really able to treat the reduced Flue UI message stream as a safe presentation model. It has to know which parts are internal, which tool outputs are unsafe, and which text parts are actual user-visible assistant responses.

The framework-level gap is that raw execution data and safe display data are currently collapsed into the same reduced parts. For activity feeds, apps need first-class semantics such as:

• message/part origin or visibility (external, internal, debug, etc.);
• safe display labels/summaries/details for tool parts;
• clear lifecycle settling so live and hydrated history do not produce materially different presentation rows for the same run.

Without that, every app has to reconstruct raw events or maintain local filtering conventions/deny-lists. That is easy to get wrong, especially because the unsafe rendering may only appear after a reload when durable history hydrates a different reduced transcript than the live one.