Package com.inductiveautomation.eventstream.gateway.diagnostic.tool


@NullMarked package com.inductiveautomation.eventstream.gateway.diagnostic.tool

The tools the Event Streams diagnostic digest hands its analysis agent: on-demand, full-fidelity diagnostics for a single named event stream, and the listing that lets the agent name a stream the prompt never mentioned.

Everything in the parent diagnostic package is pre-rendered — the model reads it whether or not it needs it, so every section there is capped, sampled, or truncated to keep prompt size independent of how many streams a gateway hosts. This package is the inversion. The model names one stream, pays one tool call, and gets that stream's whole picture back: every stage row and every faulted or erroring stage's full reason, uncapped and untruncated, because the cost is paid per investigation rather than per page load.

The one exception: stack traces

Stack traces are the only thing event_stream_diagnostics still caps. Everything else it renders is one row per stage, and a stream has a dozen stages at the outside, so leaving those uncapped costs nothing. Traces are different because their size is two numbers multiplied together, and the platform bounds only one of them:

  • How many traces — bounded. Each stage keeps at most EventStreamConstants.ERROR_COUNT_MAX errors.
  • How many frames in each trace — unbounded. It is whatever the JVM happened to capture.

So EventStreamDiagnosticsRenderer caps both numbers:

  • 20 frames per trace, which the maxFrames tool parameter can raise per call, up to a hard ceiling of 40.
  • 10 traces per response, newest first.

Every cut is marked in the rendered Markdown, so the model can tell a trimmed trace from a complete one, and each Caused by: / Suppressed: section gets a small frame budget of its own, so a cap can never swallow the root cause.

list_event_streams carries the one other cap in this package — 200 streams per reply, its MAX_STREAMS_LISTED — and for a different reason: it is the only output here whose size tracks how many streams the gateway hosts rather than how many stages one stream has. Its reply says how many matched and how many are shown, so a truncated listing never reads as the whole gateway.

When adding rendering here, ask the same question: does its size track stage count, or does it multiply stage count by something nothing bounds? The first can stay uncapped; the second needs a cap, and a note in the output saying the cap was hit.

Entry point

EventStreamDigestTools.bundle(EventStreamManager) is the only public member, and the only thing the digest agent calls. It returns a ToolBundle carrying both list_event_streams and event_stream_diagnostics, registered on the analysis flow only. Adding a tool means adding an annotated method to that class — Tools.fromAnnotated reflects over every @Tool method on the instance, so no wiring changes. The renderers behind them are package-private on purpose: nothing outside this package should render a per-stream table, because doing so from a pre-rendered section would reintroduce exactly the unbounded prompt growth the tools exist to avoid.

How the model gets here

event_stream_diagnostics takes a project and a path, not a stream handle, so the model needs those two strings before it can drill anything. Three places supply them: the roster lists streams as project / path up to its cap, the scan shortlist says which of those are worth a tool call, and list_event_streams produces the rest on demand. The roster's truncation note is still load-bearing — it is what tells the model to go ask for the remainder rather than assuming the roster was the whole gateway.

Freshness and failure

The tools hold the live EventStreamManager and re-read it on every call, so two calls in one conversation can legitimately disagree — that is a real change in the gateway, not an inconsistency to smooth over. A stream the model names may also have been deleted since the roster rendered, or its path mistyped; that returns a plain sentence rather than throwing, because a thrown tool error reads to the model as something to retry, whereas a sentence tells it what to do differently.

Extension guidance

New analysis-only tools belong here, bundled alongside the existing two. Three rules carry over from the parent package and are not negotiable:

  1. Free text reaching a prompt passes through DigestFormat.redact first.
  2. Metric rendering goes through DigestFormat rather than being formatted inline, so one metric reads identically whether the model saw it in a pre-rendered section or fetched it here.
  3. Anything a tool caps, it says so in the reply, with the total. Being on the on-demand side buys a larger cap, not the right to hide one: a reply that looks complete when it is not is worse than a short one, because the model will report having reviewed everything.

A tool description is the model's only instruction for that tool, so it must name every column the tool actually returns — a column described but not rendered is a column the model will ask about and never receive. Where two tools return overlapping subjects at different fidelities, as list_event_streams and event_stream_diagnostics do, each description must also say what it does not return, or the model will answer from whichever is cheaper.

  • Classes
    Class
    Description
    The two tools the digest's analysis agent calls against live event-stream state: find the stream and read that stream.