Failure block

Contract

Accessibility

Anatomy

A failure block with no way out is not a failure block — it is a red message there is nothing to answer. A user of an agent system is stuck: the work has stopped and no decision has been offered.

At least one action. If going on is impossible in principle, the action is "Cancel the run".

"What has already been tried"

<ul class="inst-failure-tried">
  <li>A retry after 1 s — the same code</li>
  <li>A retry after 4 s — the same code</li>
</ul>

This is the one thing that sets an agent's report apart from an ordinary error. Without the list the first thing a user does is press "Retry" — that is, do what the machine has already done twice.

States

<div class="inst-failure" role="alert" data-state="pending">
  <div class="inst-failure-head">Could not read terrain/chunks.bin</div>
  <div class="inst-failure-reason">The file is locked by another process (EBUSY)</div>
  <div class="inst-failure-actions">
    <button class="inst-btn inst-btn--sm inst-btn--primary" type="button">Retry</button>
    <button class="inst-btn inst-btn--sm" type="button">Skip the file</button>
  </div>
</div>
<div class="inst-failure" role="alert" data-state="resolved">
  <div class="inst-failure-head">Could not read terrain/chunks.bin</div>
  <div class="inst-failure-reason">The file is locked by another process (EBUSY)</div>
  <div class="inst-failure-verdict">Resolved at 14:33, on the third retry</div>
</div>

Once resolved or given up, the block steps back the same way an approval does after an answer — the same law, applied to the component that had not been given the means to honour it: the alert ground and the accent on role="alert" come off, and a quiet record remains. A failure that vanished when fixed cannot be checked later against the same file failing again.

JS

Include the module once per page — there is no need to initialise the components one by one, instrument.js works by delegation and sees nodes that arrived later.

<script type="module" src="instrument.js"></script>

What instrument.js does

Nothing, for the same reason as an approval: retrying is a decision about the machine's work rather than the behaviour of a widget.

What the application has to do

1. Send the retry (or the skip) to where it is carried out.
2. Move the block into a resolved state — otherwise the buttons stay live and a person presses "Retry" a second time while the first is still in flight.
3. Leave visible what happened: a failure block is a trace in the history, the same way an answered approval is.

block.addEventListener('click', async (e) => {
  const btn = e.target.closest('[data-decision]');
  if (!btn) return;

  for (const b of block.querySelectorAll('button')) b.disabled = true;
  const ok = await api.retry(block.dataset.id, btn.dataset.decision);

  block.dataset.state = ok ? 'resolved' : 'given-up';
});

The buttons are disabled before the request, for the same reason as an approval's: the network takes seconds, and in that time "Retry" gets pressed twice.

API

Related

BannerEmpty stateNotificationApproval request