Skip to content

The agent that grows with you

fix: a failed onboarding turn shows the beat answer once

alt-glitchc13d6885a118
diff --git a/agent/conversation_loop.py b/agent/conversation_loop.py
index 60666cd1564..b28021f23c3 100644
--- a/agent/conversation_loop.py
+++ b/agent/conversation_loop.py
@@ -43,7 +43,7 @@ from agent.turn_scripted_prelude import Prelude, play_prelude
from agent.turn_api_call import handle_api_interrupt, nous_rate_limit_guard, perform_api_call
from agent.turn_api_error import handle_api_error
from agent.turn_api_request import build_api_request
-from agent.turn_failure_copy import FAILED_TURN_DISPLAY_KIND, failed_turn_notice, site_copy
+from agent.turn_failure_copy import FAILED_TURN_DISPLAY_KIND, OPEN_TURN_TAIL_ROLES, failed_turn_notice, site_copy
from agent.turn_final_response import finish_text_response
from agent.turn_finalizer import finalize_turn
from agent.turn_iteration_prep import (
@@ -1819,8 +1819,9 @@ def _redact_display_metadata(metadata: dict) -> dict:
def _close_durable_failed_turn(agent, result: Any) -> None:
- """Append a Hermes-authored assistant boundary when a failed turn left ``user`` as the
- durable conversation tail (in place, on ``result["messages"]`` and in SessionDB).
+ """Append a Hermes-authored assistant boundary when a failed turn left its durable tail open
+ (``OPEN_TURN_TAIL_ROLES``: the accepted ``user`` row, or a ``tool`` row when a call ran before
+ the failure), in place on ``result["messages"]`` and in SessionDB.
The terminal-failure paths (content-policy refusal, ``_Trunc.end_turn``, retry exhaustion,
interrupt before any assistant text) persist the accepted user row and return without
@@ -1847,7 +1848,7 @@ def _close_durable_failed_turn(agent, result: Any) -> None:
db, session_id = getattr(agent, "_session_db", None), getattr(agent, "session_id", None)
if not isinstance(messages, list) or not messages or db is None or not session_id:
return
- if getattr(agent, "_persist_disabled", False) or db.latest_conversation_role(session_id) != "user":
+ if getattr(agent, "_persist_disabled", False) or db.latest_conversation_role(session_id) not in OPEN_TURN_TAIL_ROLES:
return
# Scope the "did a tool run" scan to this turn when its boundary is proven; otherwise
# hedge over the whole list rather than under-report a possible side effect.
diff --git a/agent/turn_failure_copy.py b/agent/turn_failure_copy.py
index 6fbba663daa..c2bed81efa8 100644
--- a/agent/turn_failure_copy.py
+++ b/agent/turn_failure_copy.py
@@ -50,6 +50,9 @@ AUTOMATION_INTERRUPTED_NOTICE = (
"An automated delivery was interrupted and was not run again. Some "
"actions may already have run; verify their effects."
)
+# Durable tail roles a failed turn leaves open: its accepted ``user`` row, or the ``tool`` row of a
+# call that ran before the failure. An ``assistant`` tail is already closed (a reply or a boundary).
+OPEN_TURN_TAIL_ROLES = frozenset({"user", "tool"})
# ``messages.display_kind`` of that row: display-only (stripped before every provider request),
# so renderers show a Hermes notice and room pollers never read it as the model's reply.
FAILED_TURN_DISPLAY_KIND = "failed_turn"
diff --git a/apps/desktop/src/lib/chat-messages/hydration.ts b/apps/desktop/src/lib/chat-messages/hydration.ts
index ef5006ed789..57a7883e26b 100644
--- a/apps/desktop/src/lib/chat-messages/hydration.ts
+++ b/apps/desktop/src/lib/chat-messages/hydration.ts
@@ -566,7 +566,9 @@ export function toChatMessages(messages: SessionMessage[]): ChatMessage[] {
let pendingAbsorbedRows = 0
- if (message.role === 'assistant') {
+ // A machine notice stored as an assistant row (the failed-turn boundary) is
+ // Hermes speaking: it must not join the tool-call reply it follows.
+ if (displayRole === 'assistant') {
if (pendingToolParts.length) {
if (!appendPartsToActiveAssistant(pendingToolParts, message.timestamp ?? pendingToolTimestamp)) {
parts.unshift(...pendingToolParts)
diff --git a/apps/desktop/src/lib/chat-messages/reconciliation.test.ts b/apps/desktop/src/lib/chat-messages/reconciliation.test.ts
index 1be54eb8543..4d47d48a096 100644
--- a/apps/desktop/src/lib/chat-messages/reconciliation.test.ts
+++ b/apps/desktop/src/lib/chat-messages/reconciliation.test.ts
@@ -455,3 +455,69 @@ it('preserveLocalSystemNotices does not duplicate a notice the page already carr
const preserved = preserveLocalSystemNotices(refreshed, [...refreshed, { ...notice, id: 'other' }])
expect(preserved).toBe(refreshed)
})
+
+it.each([
+ ['no failed-turn boundary row', false],
+ ['the failed-turn boundary row', true]
+])('a failed onboarding beat shows its answer and error card once when the refresh carries %s', (_label, boundary) => {
+ const callId = 'call_setup_beat_name'
+ const answer = { beat: 'name', answer: { name: 'Austin' }, next: 'theme' }
+ const errorSurface = { code: 'rate_limit', layer: 'provider', retryable: true } as const
+
+ const stored = toChatMessages([
+ { role: 'user', content: 'opening', timestamp: 1, display_kind: 'hidden' },
+ {
+ role: 'assistant',
+ content: 'Hi!',
+ timestamp: 2,
+ tool_calls: [{ id: callId, function: { name: 'setup_beat', arguments: '{"beat":"name"}' } }]
+ },
+ { role: 'tool', tool_call_id: callId, tool_name: 'setup_beat', content: JSON.stringify(answer), timestamp: 3 },
+ ...(boundary
+ ? [
+ {
+ role: 'assistant' as const,
+ content: 'This turn did not complete.',
+ timestamp: 4,
+ display_kind: 'failed_turn',
+ display_metadata: { error: 'rate limited', error_surface: errorSurface }
+ }
+ ]
+ : [])
+ ])
+
+ const local: ChatMessage[] = [
+ row('user-opening', 'user', 'opening', { hidden: true, timestamp: 1 }),
+ row('assistant-interim', 'assistant', 'Hi!', { interim: true, timestamp: 2 }),
+ {
+ id: 'assistant-stream',
+ role: 'assistant',
+ error: 'rate limited',
+ errorSurface,
+ timestamp: 3,
+ parts: [
+ {
+ type: 'tool-call',
+ toolCallId: callId,
+ toolName: 'setup_beat',
+ args: { beat: 'name' },
+ argsText: '{"beat":"name"}',
+ result: answer
+ }
+ ]
+ }
+ ]
+
+ const merged = preserveLocalAssistantErrors(stored, local)
+
+ const beatRows = merged.filter(message =>
+ message.parts.some(part => part.type === 'tool-call' && part.toolCallId === callId)
+ )
+
+ const errorCards = merged.filter(message => message.error)
+
+ expect(beatRows).toHaveLength(1)
+ expect(chatMessageText(beatRows[0])).toBe('Hi!')
+ expect(errorCards).toHaveLength(1)
+ expect(errorCards[0]).toMatchObject({ error: 'rate limited', errorSurface: { code: 'rate_limit' } })
+})
diff --git a/apps/desktop/src/lib/chat-messages/reconciliation.ts b/apps/desktop/src/lib/chat-messages/reconciliation.ts
index 307c3e13dbc..852db9b148d 100644
--- a/apps/desktop/src/lib/chat-messages/reconciliation.ts
+++ b/apps/desktop/src/lib/chat-messages/reconciliation.ts
@@ -330,6 +330,42 @@ function hydratedIdResolver(mergedNextMessages: ChatMessage[]): (message: ChatMe
: hydratedIdByRowId.get(message.rowId)
}
+// A failed turn whose only user row is hidden (a scripted onboarding beat) has
+// no visible turn to anchor on, but its bubble still holds the tool calls the
+// store already has: the stored assistant sharing one is the bubble's copy.
+function toolCallTwinIndex(
+ mergedNextMessages: ChatMessage[],
+ currentMessages: ChatMessage[],
+ localIndex: number
+): number {
+ const visibleUser = (message: ChatMessage) => message.role === 'user' && !message.hidden
+
+ const callIds = new Set(
+ currentMessages[localIndex].parts.flatMap(part => (part.type === 'tool-call' ? [part.toolCallId] : []))
+ )
+
+ if (
+ !callIds.size ||
+ currentMessages.slice(localIndex + 1).some(visibleUser) ||
+ currentMessages.slice(0, localIndex).filter(visibleUser).length !== mergedNextMessages.filter(visibleUser).length
+ ) {
+ return -1
+ }
+
+ const turnStart = mergedNextMessages.findLastIndex(visibleUser) + 1
+
+ const twin = mergedNextMessages
+ .slice(turnStart)
+ .findLastIndex(
+ message =>
+ message.role === 'assistant' &&
+ !message.hidden &&
+ message.parts.some(part => part.type === 'tool-call' && callIds.has(part.toolCallId))
+ )
+
+ return twin === -1 ? -1 : turnStart + twin
+}
+
// The refresh already carries this tail turn's error card, rebuilt from its
// failed-turn boundary row (see hydration `failedTurnError`).
function persistedTailErrorMatches(
@@ -357,6 +393,46 @@ function persistedTailErrorMatches(
)
}
+/**
+ * Where the refresh already holds a local failed assistant: the index of the
+ * stored assistant to fold its error onto, `represented` when the refresh
+ * carries the error card itself, or -1 when the turn is not stored.
+ */
+function storedFailedTurnIndex(
+ mergedNextMessages: ChatMessage[],
+ currentMessages: ChatMessage[],
+ index: number,
+ hydratedId: string | undefined
+): number | 'represented' {
+ const hydratedIndex =
+ hydratedId === undefined
+ ? tailTurnAssistantMatchIndex(mergedNextMessages, currentMessages, index)
+ : mergedNextMessages.findIndex(candidate => candidate.id === hydratedId && candidate.role === 'assistant')
+
+ if (hydratedIndex !== -1) {
+ return hydratedIndex
+ }
+
+ // #120978: a rowId-less errored attachment turn cannot be matched by rowId
+ // and the tail-anchor match bails when newer turns already committed. The
+ // preceding local user row's caption, compared tolerantly against every
+ // hydrated user row, still names the turn: fold the error onto the first
+ // settled assistant reply after that row.
+ const attachmentIndex = attachmentTurnAssistantMatchIndex(mergedNextMessages, currentMessages, index)
+
+ if (attachmentIndex !== -1) {
+ return attachmentIndex
+ }
+
+ // #124379: the refresh already carries this tail turn's error card, rebuilt
+ // from its failed-turn boundary row — the local card is redundant, not missing.
+ if (persistedTailErrorMatches(mergedNextMessages, currentMessages, index)) {
+ return 'represented'
+ }
+
+ return toolCallTwinIndex(mergedNextMessages, currentMessages, index)
+}
+
function localAssistantErrorIdsToPreserve(
mergedNextMessages: ChatMessage[],
currentMessages: ChatMessage[]
@@ -409,39 +485,15 @@ function localAssistantErrorIdsToPreserve(
const hydratedId = hydratedIdFor(message)
- const hydratedAssistantIndex =
- hydratedId === undefined
- ? tailTurnAssistantMatchIndex(mergedNextMessages, currentMessages, index)
- : mergedNextMessages.findIndex(candidate => candidate.id === hydratedId && candidate.role === 'assistant')
-
- // #120978: a rowId-less errored attachment turn cannot be matched by rowId
- // and the tail-anchor match bails when newer turns already committed. The
- // preceding local user row's caption, compared tolerantly against every
- // hydrated user row, still names the turn: fold the error onto the first
- // settled assistant reply after that row.
- const hydratedAttachmentAssistantIndex =
- hydratedAssistantIndex === -1 ? attachmentTurnAssistantMatchIndex(mergedNextMessages, currentMessages, index) : -1
-
- if (hydratedAttachmentAssistantIndex !== -1) {
- mergedNextMessages[hydratedAttachmentAssistantIndex] = {
- ...mergedNextMessages[hydratedAttachmentAssistantIndex],
- error: message.error,
- ...(message.errorSurface ? { errorSurface: message.errorSurface } : {}),
- pending: false
- }
-
- continue
- }
+ const twinIndex = storedFailedTurnIndex(mergedNextMessages, currentMessages, index, hydratedId)
- // #124379: the refresh already carries this tail turn's error card, rebuilt
- // from its failed-turn boundary row — the local card is redundant, not missing.
- if (hydratedAssistantIndex === -1 && persistedTailErrorMatches(mergedNextMessages, currentMessages, index)) {
+ if (twinIndex === 'represented') {
continue
}
- if (hydratedAssistantIndex !== -1) {
- mergedNextMessages[hydratedAssistantIndex] = {
- ...mergedNextMessages[hydratedAssistantIndex],
+ if (twinIndex !== -1) {
+ mergedNextMessages[twinIndex] = {
+ ...mergedNextMessages[twinIndex],
error: message.error,
...(message.errorSurface ? { errorSurface: message.errorSurface } : {}),
pending: false
diff --git a/gateway/run_turn_persistence.py b/gateway/run_turn_persistence.py
index a4f108979ab..90e24cc78d5 100644
--- a/gateway/run_turn_persistence.py
+++ b/gateway/run_turn_persistence.py
@@ -12,7 +12,9 @@ import queue
import threading
import time
from agent.i18n import t
-from agent.turn_failure_copy import FAILED_TURN_DISPLAY_KIND, FAILED_TURN_NOTICE, PARTIAL_FAILED_TURN_NOTICE
+from agent.turn_failure_copy import (
+ FAILED_TURN_DISPLAY_KIND, FAILED_TURN_NOTICE, OPEN_TURN_TAIL_ROLES, PARTIAL_FAILED_TURN_NOTICE,
+)
from agent.session_activity import format_iteration_progress
from contextlib import nullcontext, suppress
from contextvars import copy_context
@@ -271,13 +273,14 @@ class GatewayTurnPersistenceMixin:
return FAILED_TURN_NOTICE
async def _hmwa_close_failed_turn(self, session_id, notice):
- """Append the gateway-owned assistant boundary iff the durable tail is an open user row.
+ """Append the gateway-owned assistant boundary iff the durable tail is open (a user row, or the
+ tool row of a call that ran before the failure).
The tail, not "did the gateway write the user row", is the key: on the primary path the
agent's turn-start flush already persisted the row (so the platform-id dedupe skips the
gateway write), and a platform redelivery of an already-closed turn must not stack a
second assistant row."""
- if await self.async_session_store.transcript_tail_role(session_id) != "user":
+ if await self.async_session_store.transcript_tail_role(session_id) not in OPEN_TURN_TAIL_ROLES:
return
await self.async_session_store.append_to_transcript(session_id, {
"role": "assistant", "content": notice, "timestamp": time.time(), "display_kind": FAILED_TURN_DISPLAY_KIND,
diff --git a/tests/acp_adapter/test_failed_turn_closure.py b/tests/acp_adapter/test_failed_turn_closure.py
index 02235e7b42a..ae9b802f12b 100644
--- a/tests/acp_adapter/test_failed_turn_closure.py
+++ b/tests/acp_adapter/test_failed_turn_closure.py
@@ -294,3 +294,49 @@ def test_failed_turn_boundary_keeps_the_error_card_for_rehydration(tmp_path, mon
stored = db.get_messages(sid)[-1]["display_metadata"]
assert (stored if isinstance(stored, dict) else json.loads(stored))["error_surface"]["code"] == "timeout"
db.close()
+
+
+def test_failed_turn_after_a_tool_row_is_closed_with_its_error_card(tmp_path, monkeypatch):
+ """A turn that fails after a tool already ran (an onboarding beat answered, then the provider
+ 429s) leaves a ``tool`` row as the durable tail. It is as open as a bare user tail: without the
+ boundary a client reopening the session has no error card to draw for the turn."""
+ from types import SimpleNamespace
+
+ from agent.conversation_loop import _close_durable_failed_turn
+ from agent.turn_failure_copy import FAILED_TURN_DISPLAY_KIND, PARTIAL_FAILED_TURN_NOTICE
+ from hermes_state import SessionDB
+
+ monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+ db = SessionDB(tmp_path / "state.db")
+ sid = "s1"
+ db.create_session(session_id=sid, source="tui", model="m")
+ call = {"id": "call_setup_beat_name", "type": "function",
+ "function": {"name": "setup_beat", "arguments": '{"beat":"name"}'}}
+ messages = [
+ {"role": "user", "content": "opening"},
+ {"role": "assistant", "content": "Hi!", "tool_calls": [call]},
+ {"role": "tool", "tool_call_id": call["id"], "content": '{"answer":{"name":"Austin"}}'},
+ ]
+ db.append_message(sid, "user", "opening")
+ db.append_message(sid, "assistant", "Hi!", tool_calls=[call])
+ db.append_message(sid, "tool", messages[-1]["content"], tool_call_id=call["id"])
+
+ def flush(rows):
+ last = rows[-1]
+ db.append_message(sid, last["role"], last["content"], display_kind=last.get("display_kind"),
+ display_metadata=last.get("display_metadata"))
+
+ agent = SimpleNamespace(_session_db=db, session_id=sid, _flush_messages_to_session_db=flush,
+ provider="nous", model="m")
+ failed = {"completed": False, "failed": True, "failure_reason": "rate_limit",
+ "error": "429 Too Many Requests", "messages": messages, "current_turn_user_idx": 0}
+ _close_durable_failed_turn(agent, failed)
+ _close_durable_failed_turn(agent, failed) # redelivery: the tail is now the boundary
+
+ stored = db.get_messages(sid)
+ assert [row["role"] for row in stored] == ["user", "assistant", "tool", "assistant"]
+ boundary = stored[-1]
+ assert (boundary["content"], boundary["display_kind"]) == (PARTIAL_FAILED_TURN_NOTICE, FAILED_TURN_DISPLAY_KIND)
+ metadata = boundary["display_metadata"]
+ assert (metadata if isinstance(metadata, dict) else json.loads(metadata))["error_surface"]["code"] == "rate_limit"
+ db.close()
diff --git a/tests/gateway/test_failure_writer_ownership.py b/tests/gateway/test_failure_writer_ownership.py
index b9edeff1d98..d05eb69ee54 100644
--- a/tests/gateway/test_failure_writer_ownership.py
+++ b/tests/gateway/test_failure_writer_ownership.py
@@ -240,3 +240,53 @@ def test_fresh_session_agent_flushed_failed_turn_is_closed(tmp_path):
db.close()
asyncio.run(check())
+
+
+def test_failed_turn_whose_tail_is_a_tool_row_is_closed(tmp_path):
+ """A turn that failed after its tool ran leaves the tool row as the durable tail. That tail is
+ as open as a bare user row: the gateway closer must land the boundary, once."""
+ import asyncio
+ from gateway.config import GatewayConfig, Platform
+ from gateway.platforms.event import MessageEvent
+ from gateway.run import GatewayRunner
+ from gateway.session import SessionSource, SessionStore
+
+ async def check():
+ store = SessionStore(tmp_path / "sessions", GatewayConfig())
+ runner = object.__new__(GatewayRunner)
+ runner.session_store = store
+ runner._session_db = object() # agent_persisted defaults True
+
+ async def noop(*args, **kwargs):
+ return None
+
+ runner._refresh_agent_cache_message_count = noop
+ source = SessionSource(platform=Platform.TELEGRAM, chat_id="tool-tail", user_id="u")
+ entry = store.get_or_create_session(source)
+ sid = entry.session_id
+ db = store._db_for_session_id(sid)
+ call = {"id": "call-1", "type": "function", "function": {"name": "reset_password", "arguments": "{}"}}
+ db.append_message(sid, "user", "reset the password", platform_message_id="m-1")
+ db.append_message(sid, "assistant", "", tool_calls=[call])
+ db.append_message(sid, "tool", "Password reset", tool_call_id="call-1")
+ failed = {"failed": True, "final_response": "429", "error": "429", "history_offset": 0,
+ "last_prompt_tokens": 0, "messages": [
+ {"role": "user", "content": "reset the password"},
+ {"role": "assistant", "content": "", "tool_calls": [call]},
+ {"role": "tool", "tool_call_id": "call-1", "content": "Password reset"},
+ ]}
+ for _ in range(2): # second pass = platform redelivery of the same failed message
+ await runner._hmwa_persist_turn_transcript(
+ event=MessageEvent(text="reset the password", source=source, message_id="m-1"),
+ source=source, session_entry=entry, session_key=entry.session_key, agent_result=failed,
+ agent_messages=failed["messages"],
+ prepared=runner._PreparedTurn([], "", "reset the password", None, None, None, sid, "o"),
+ response="x", agent_failed_early=True, hidden_reasoning_incomplete=False,
+ is_context_overflow_failure=False,
+ )
+ rows = [m for m in db.get_messages(sid) if m["role"] != "session_meta"]
+ assert [m["role"] for m in rows] == ["user", "assistant", "tool", "assistant"]
+ assert (rows[-1]["content"], rows[-1]["display_kind"]) == (PARTIAL_FAILED_TURN_NOTICE, FAILED_TURN_DISPLAY_KIND)
+ db.close()
+
+ asyncio.run(check())