Partial Answers#
A tool asked for several things – channels to read, entries to fetch – may answer some of them and not others. Every such tool says how much it answered in one shape, so the agent never has to work it out from prose or by comparing lists.
The rule#
A tool that answers part of a request returns the answered part plus a map of what is missing, each entry carrying the source’s own text. When nothing answered, the tool refuses with the same map. A request the tool refuses as a whole is a different error, with a different remedy.
The map#
missing maps each thing asked for and not answered to the source’s own
text, in request order:
{"missing": {"SR:BPM1:X": "TimeoutError: no reply in 5 s", "e2": null}}
The key is what the request named: the channel address, the entry id.
The value is the text the source gave for that item – for a channel read,
"<ExceptionType>: <message>". It isnullwhen the source gave no text. A tool never makes a reason up.
Three arms#
What happened |
What the tool returns |
|---|---|
Some or all answered |
The result, with |
Every item tried, none answered |
An error whose |
A request refused before any item was tried |
The refusal’s own error type ( |
nothing_answered and a whole-request refusal ask different things of the
agent. A refusal names a request to change; nothing_answered names items
that were tried and did not answer, which the agent reports to the operator
entry by entry.
The tools#
Tool |
A key in |
Its text |
|---|---|---|
|
A channel address, as asked |
The alarm service’s reason for having no state for it |
|
A channel address |
The connector’s error, as |
|
An entry id |
|
|
A corrector setpoint address |
The engine’s text |
|
A channel address, as asked, that no section answered |
The directory section’s reason |
|
A stepped setpoint address, or the measurement kind when none is left |
The first line of what stopped the run; |
Two exceptions#
channel_writeA write answers with one row per channel, and each row’s
outcomeword says what happened to that write (see Connector Contracts). A write’s map is its rows, and a refusal carries them underdetails.results. It has nomissingkey: a written but unconfirmed channel was answered, and a second map would state the refused and failed rows twice.archiver_readA channel with no points in the requested window is answered, not missing: the data file has its column, and the
coverageblock says from the archive’s own facts why the window is empty.