#112917·hermes-agent

Expose semantic agent-turn failure to platform completion hooks

Author: drj0717Created Sep 16, 2026Updated Sep 17, 2026
Labelstype/bugcomp/gatewaycomp/pluginsP3

Problem

Platform adapters cannot distinguish a substantively completed agent turn from a normalized pre-work agent failure whose user-facing error text was delivered successfully.

On current origin/main 784d5c3f9c2cb77698d8a9d2e72b1d106a38ea88:

  • gateway/run_turn.py computes agent_failed_early = bool(agent_result.get("failed")) and returns normalized user-facing failure text.
  • gateway/platforms/base.py treats successful delivery of that text as ProcessingOutcome.SUCCESS.
  • BasePlatformAdapter.on_processing_complete(event, outcome) receives only the delivery-shaped outcome, not the agent-level failure state.

This matters for durable platform plugins. A queue/inbox adapter must advance durable read state only after substantive work completes. Today a generic pre-work failure can be delivered, reported to the adapter as SUCCESS, and incorrectly recorded as the durable final—retiring unfinished work.

Reproduction

A platform adapter backed by a durable local queue:

  1. receives an actionable request and writes its protocol ACK;
  2. invokes the normal gateway turn;
  3. the agent fails before doing substantive work;
  4. _hmwa_agent_error_reply returns the sanitized retry/reset message;
  5. delivery succeeds, so the completion hook receives ProcessingOutcome.SUCCESS;
  6. the adapter cannot tell this apart from a substantive result and may advance read/import state.

The plugin-side reproduction used the real GatewayTurnMixin._hmwa_agent_error_reply and real BasePlatformAdapter background task. The durable store ended with ACK + FINAL and no pending request even though no substantive work ran.

Requested supported seam

Expose semantic agent-turn completion/failure to platform completion handling without requiring adapters to inspect localized/user-visible error strings. Possible compatible shapes include:

  • a stable turn-result field on MessageEvent available to on_processing_complete; or
  • a new/additive completion hook carrying the agent result/failure bit while preserving existing two-argument overrides; or
  • a distinct semantic outcome that does not conflate delivery success with agent success.

The exact API shape is a maintainer decision. The required invariant is that an adapter can fail closed when substantive completion was not established, even if a normalized error reply was delivered successfully.

Constraints

  • Do not require string matching against user-facing error prose.
  • Preserve successful delivery of the sanitized failure response to the human-facing platform.
  • Preserve backward compatibility for existing adapter hook overrides.
  • Add behavior tests covering a pre-work agent failure with successfully delivered error text.

Downstream consumer

hive-agent-comm-plugin uses a local append-only backend with protocol ACK/final and durable read-state advancement. Its gateway-ordering PR is intentionally blocked rather than retire unfinished work under a false SUCCESS signal.

Source: NousResearch/hermes-agent