fix(session): surface a diagnostic instead of (no response) when an ACP agent returns an empty 0-token end_turn

[chaodu-agent]

Description

When an ACP agent ends a turn with no content and no error (a successful stopReason: end_turn carrying zero output tokens), OpenAB renders the bare placeholder _(no response)_. This gives the operator no signal about why the turn was empty — in practice it is almost always a recoverable misconfiguration (bad/missing provider credentials, unauthenticated model, provider no-op), but it looks identical to a model that legitimately chose to stay silent.

OpenAB already has the data to do better: the ACP result includes the usage object. A turn that returns end_turn with outputTokens == 0 and an empty composed body is a strong "silent failure" signature and should surface an actionable diagnostic instead of _(no response)_.

Concrete case (verified with RUST_LOG=info,openab_core::acp=debug on a live opencode bot):

• Backend: opencode acp (OpenCode 1.17.9), model cloudflare-workers-ai/@cf/zai-org/glm-5.2
• The opencode config referenced {env:CLOUDFLARE_ACCOUNT_ID} / {env:CLOUDFLARE_API_TOKEN}, which were not present in the agent's environment, so opencode substituted empty strings and the provider call never authenticated.
• The session/prompt reply was a success with zero usage and no error:

acp_recv id=3 result={"stopReason":"end_turn","usage":{"inputTokens":0,"outputTokens":0,"totalTokens":0}}

• No JSON-RPC error object, and nothing on the agent's stderr (OpenAB captures agent stderr at WARN — only the routine [agent].env notice appeared).
• Result: OpenAB showed _(no response)_. There was no error for OpenAB to catch — opencode reported a successful empty turn.

This is the relevant code path — final_content is empty and response_error is None, so it falls through to the placeholder:

openab/crates/openab-core/src/adapter.rs

Lines 1031 to 1041 in d83bbc9

	let final_content =
	compose_display(&tool_lines, &text_buf, false, tool_display);
	let final_content = if final_content.is_empty() {
	if let Some(err) = response_error {
	format!("⚠️ {err}")
	} else {
	"_(no response)_".to_string()
	}
	} else if let Some(err) = response_error {
	format!("⚠️ {err}\n\n{final_content}")
	} else {

Steps to Reproduce

1. Configure any ACP backend whose underlying provider will fail silently — e.g. opencode with a provider whose API key comes from an unset {env:VAR} (so it resolves to an empty string).
2. Start the bot and send any message (@bot hi).
3. Observe the ACP traffic: session/prompt returns result.stopReason = "end_turn" with usage.outputTokens = 0, no error, no stderr.
4. The bot replies _(no response)_ with no indication that the model/provider failed to authenticate.

Expected Behavior

When a turn ends empty due to a silent failure — i.e. stopReason == "end_turn" and usage.outputTokens == 0 and the composed body is empty — OpenAB should do two things instead of silently rendering _(no response)_:

1. Send a meaningful error to the consumer (Discord/Slack/etc.) so the end user knows the turn failed rather than the agent choosing silence:

⚠️ The agent produced no output (0 output tokens). This usually means a provider/model error or missing credentials/config, not an intentional empty reply. Check the agent backend configuration and auth.

2. Log a detailed error in the backend at WARN/ERROR (visible without enabling debug) so operators can diagnose from logs alone — including the signals OpenAB already has: agent command, model, stopReason, inputTokens/outputTokens/totalTokens, and session id. e.g.:

ERROR openab_core::...: agent returned empty turn (0 output tokens) — likely provider/model/auth failure
  agent="opencode acp" model="cloudflare-workers-ai/@cf/zai-org/glm-5.2"
  stop_reason="end_turn" input_tokens=0 output_tokens=0 total_tokens=0
  session_id="ses_…" thread="discord:…"

The existing _(no response)_ placeholder (no consumer error, no backend error log) can remain for the genuinely-silent case: non-zero tokens but empty rendered body (e.g. thought-only / narration-only turns).

Current vs Expected

CURRENT
──────────────────────────────────────────────────────────────────────
  ACP agent (opencode / mimo)
        │  session/prompt
        ▼
  result: { stopReason: "end_turn", usage.outputTokens: 0 }
  (no JSON-RPC error, no stderr)
        │
        ▼
  adapter compose:  final_content == ""   &&   response_error == None
        │
        ▼
  ┌──────────────────────┐
  │   _(no response)_    │   ✗ operator sees nothing actionable
  └──────────────────────┘


EXPECTED
──────────────────────────────────────────────────────────────────────
  ACP agent (opencode / mimo)
        │  session/prompt
        ▼
  result: { stopReason: "end_turn", usage.outputTokens: 0 }
        │
        ▼
  adapter compose:  final_content == ""
        │
        │  stopReason == "end_turn" && outputTokens == 0 && body empty ?
        │
   ┌────┴───────────────────────────┐
   │ yes (silent failure)           │ no  (thought/narration-only: tokens > 0)
   ▼                                ▼
   ├──► (1) CONSUMER  ┌───────────────────────────────┐   ┌──────────────────┐
   │     Discord/Slack│ ⚠️ agent produced no output    │   │  _(no response)_ │
   │                  │ (0 tokens) — likely provider/  │   │  (unchanged)     │
   │                  │ model/auth/config error.       │   └──────────────────┘
   │                  └───────────────────────────────┘
   │
   └──► (2) BACKEND LOG (WARN/ERROR, no debug needed)
         ERROR ... agent returned empty turn (0 output tokens)
           agent="opencode acp" model="…glm-5.2"
           stop_reason="end_turn" in=0 out=0 total=0 session="ses_…"
         ✓ operator diagnoses from logs; user is not left guessing

Upstream context (OpenCode)

This is partly an OpenCode defect — it should surface a real error rather than a silent empty end_turn. Tracked upstream:

• Issue anomalyco/opencode#30411 — "Silent empty assistant response makes long GUI sessions appear stuck"
• Issue anomalyco/opencode#30862 — "STUCK WITH NO RESPOND/ERROR"
• Issue anomalyco/opencode#33847 — "AI 助手根本不回答問題，也不報錯"
• PR anomalyco/opencode#33854 — fix(config): error on missing {env:VAR} in config templates (directly fixes the missing-credential root cause seen here)
• PR anomalyco/opencode#30304 — fix(session): avoid stuck sessions from empty responses… (closes #30411)
• PR anomalyco/opencode#29966 — fix(opencode): no response handling

Upstream context (MiMoCode)

MiMoCode (mimo acp) is a fork of OpenCode and several OpenAB bots use it, so the same silent/empty-turn class applies. Tracked upstream at XiaomiMiMo/MiMo-Code:

• Issue XiaomiMiMo/MiMo-Code#914 — "Loop-thinking: 1,803 repetitions / 569s stuck / zero output tokens" (exact match: model loops in reasoning, emits 0 output tokens, aborts → renders as (no response))
• Issue XiaomiMiMo/MiMo-Code#1181 — "MiMo gets stuck in repeated reasoning loop without making progress"
• Issue XiaomiMiMo/MiMo-Code#250 — "思考陷入重複螺旋" (reasoning stuck in a repeated spiral)
• Issue XiaomiMiMo/MiMo-Code#865 — "ACP mode ignores default model set by mimo auth login" (ACP-specific)

Because MiMoCode forks OpenCode's config code, it also inherits the missing-{env:VAR} → empty-substitution behavior that opencode PR #33854 addresses.

Even after these land upstream, OpenAB surfacing the empty-turn diagnostic is valuable as defense-in-depth across all ACP backends (opencode, mimocode, codex, etc.).

Feasibility / Implementation notes

OpenAB cannot recover the true upstream error (opencode/mimo swallow e.g. a provider 401 and return a clean, successful empty end_turn — no JSON-RPC error, no stderr). So OpenAB can only detect a silent failure by proxy: an empty turn that reported 0 output tokens. Surfacing the real root cause depends on the upstream fixes (opencode #33854 et al.).

The good news: OpenAB already receives the prompt result carrying stopReason + usage — it just discards it. In session_prompt, the oneshot receiver for the session/prompt response is dropped (_resp_rx), and the turn is driven purely off the session/update notification stream:

openab/crates/openab-core/src/acp/connection.rs

Lines 597 to 601 in d83bbc9

	let data = serde_json::to_string(&req)?;
	let (resp_tx, _resp_rx) = oneshot::channel();
	self.pending.lock().await.insert(id, resp_tx);

So the fix is mostly "stop throwing away data we already have." Two tiers:

Tier 1 — no new ACP parsing (uses only existing signals). At the empty-final_content branch (adapter.rs), OpenAB already knows the body is empty, how many tool calls ran (tool_lines), and whether Thinking occurred. Even without the result, it can already (1) send a clearer consumer message ("agent ran N tools but produced no reply" vs "agent produced no output") and (2) emit a WARN/ERROR backend log with agent command + thread + tool count.

Tier 2 — capture the discarded result (recommended). Read _resp_rx to obtain stopReason + usage, surface it to the adapter (e.g. a new AcpEvent::TurnEnd { stop_reason, input_tokens, output_tokens } emitted when the prompt result arrives, or as a return value). Then the empty-turn branch can use the unambiguous signal stopReason == "end_turn" && outputTokens == 0 && body empty to do both outcomes precisely (consumer error + detailed backend log with model/tokens/stop_reason/session id).

Out of scope for OpenAB: identifying which provider error occurred (auth vs rate-limit vs config) — that requires the agent to report it (upstream).

Proposed Implementation Plan

One focused PR (Tier 2): stop discarding the session/prompt result, classify it as a terminal event on the existing stream, and branch the empty-turn case into a consumer error + a backend log. Route the result through the existing classify pipeline (rather than a second await) so the adapter keeps its single rx.recv() loop.

Options considered:

• A — Tier 1, existing signals only (no result parsing). At the empty-final_content branch, use only what the adapter already has (tool_lines, whether Thinking occurred) to emit a clearer consumer message + backend log. Pro: smallest change, no protocol additions. Con: can't distinguish a genuine silent failure from an intentionally-empty/thought-only turn → either over-warns or under-warns. Kept as a fallback, not the primary.
• B — Tier 2, capture stopReason/usage (recommended). Use the precise end_turn && outputTokens == 0 signal. Pro: accurate failure detection; data is already received (just dropped). Con: small protocol/plumbing additions. Chosen.
• Result plumbing — B1 vs B2. B1: change session_prompt to return the oneshot resp_rx and await it after the notification stream ends. B2: forward the result into the notify stream as a terminal TurnEnd event and classify it like any other update. Chose B2 — keeps the adapter's single rx.recv() loop and reuses the classify pipeline; B1 adds a second await with its own error/lifecycle handling.
• Consumer surfacing — reuse vs new path. Reuse the existing response_error → "⚠️ {err}" render path vs introduce a separate empty-turn placeholder type. Chose reuse — minimal diff, consistent rendering/splitting, and it already coexists with the _(no response)_ fallback.
• Out of scope (rejected for this PR): trying to recover the specific provider error (auth vs rate-limit) by scraping agent stderr or probing the provider — unreliable and agent-specific; belongs upstream (opencode#33854).

1. acp/connection.rs — stop dropping the result

• In run_reader_loop, when the id-bearing response matches the in-flight prompt id, forward it to notify_tx as the final message before closing the channel (today it only goes to the dropped pending oneshot — see the _resp_rx discard above).
• Net effect: the adapter receives the prompt result as the last item on rx, then None.

2. acp/protocol.rs — add a terminal event + parser

• AcpEvent::TurnEnd { stop_reason: Option<String>, output_tokens: Option<u64>, total_tokens: Option<u64> }.
• In classify, detect an id-bearing result carrying stopReason/usage → TurnEnd. Parse usage.outputTokens defensively (Option — some agents omit usage).

3. adapter.rs — branch the empty case (at the final_content.is_empty() site)

• Track turn_end: Option<TurnEnd> from the new event.
• silent_failure = final_content.is_empty() && turn_end.stop_reason == "end_turn" && turn_end.output_tokens == Some(0).
• If silent_failure:
  • (consumer) reuse the existing response_error → "⚠️ {err}" render path with: "The agent produced no output (0 output tokens) — likely a provider/model error or missing credentials/config, not an intentional empty reply."
  • (backend) tracing::error!(agent, stop_reason, input_tokens, output_tokens, total_tokens, session_id, thread, "agent returned empty turn (0 output tokens)").
• Else (empty body but output_tokens > 0 or usage absent → thought/narration-only) → keep _(no response)_ (optionally a debug!).

Edge cases / safety (backward-compat):

• usage absent → output_tokens == None → do not label a failure; keep _(no response)_ (avoids false positives for agents that omit usage).
• Process died / JSON-RPC error → unchanged; response_error already wins those paths.
• Non-empty turns → completely untouched (only the empty branch changes).
• Lifecycle: forwarding-then-closing preserves "stream ends → turn ends"; if the agent dies before a result, no TurnEnd arrives and the existing death path handles it.

Tests:

• Extend existing connection.rs stopReason fixtures: end_turn + 0 output + empty body → asserts consumer error + error log fires.
• end_turn + non-zero output + empty body → still _(no response)_.
• Result with no usage → _(no response)_, no false failure.
• Normal non-empty turn → unaffected.

Notes:

• Also improves the mimo loop-thinking case (MiMo-Code#914 — aborts with 0 output tokens would now be surfaced + logged).
• Does not identify which provider error occurred (upstream; opencode#33854).
• Open question: also log the model in the backend line. OpenAB parses configOptions (carries current model) — if not already threaded to the adapter, ship with agent + tokens + stop_reason + session now and add model as a follow-up.

[chaodu-agent]

Group Discussion Summary

We reviewed this issue from five angles: correctness, architecture, documentation/UX, security/CI, and spec validation. Below is the consolidated analysis and recommendations.

---

1. Architecture — Implementation Approach

Consensus: B2 (forward into notify stream) is correct, but with a key refinement.

• ❌ Do NOT add AcpEvent::TurnEnd to classify_notification — that function only handles id-less notifications (session/update stream). The session/prompt final response is an id-bearing response packet and does not belong in the classify pipeline.
• ✅ Forward the final response into the notify rx channel as the terminal message (before closing). In the adapter's rx.recv() loop, detect notification.id.is_some() to identify the terminal response and unpack result/error directly — no new AcpEvent variant needed.
• ✅ This preserves FIFO ordering, keeps the single-loop design, and is naturally extensible for future streaming usage updates.

Error Taxonomy — Do NOT reuse response_error render path:

Category	Source	Log Level	Consumer Rendering
Protocol/System Error	JSON-RPC error field, agent crash	ERROR	⚠️ {err} (existing path)
Silent Failure (new)	end_turn + outputTokens == 0 + empty body	WARN	Dedicated user-friendly message
Thought-only / narration	end_turn + outputTokens > 0 + empty rendered body	DEBUG (optional)	_(no response)_ (unchanged)

These are fundamentally different failure modes and must not be conflated in code or logs.

---

2. Correctness — False Positive / Negative Risk

outputTokens == 0 as silent failure proxy:

• False positive risk: near zero. In a coding-assistant context, a model producing exactly 0 output tokens with no tool calls and an empty body is not a legitimate "chose to stay silent" scenario — it's effectively always a provider/auth/config failure.
• usage absent → safe fallback. If the agent omits usage entirely, output_tokens == None → do NOT classify as failure → keep _(no response)_. This avoids false positives for agents that don't report usage.
• Race condition risk (B2 design): Minimal. Forwarding the final response into the notify channel before closing it provides a natural inline EOF signal. The adapter's single rx.recv() loop handles it sequentially — no select! or second await needed.

---

3. UX — Consumer-Facing Message

Recommendation: De-technicalize the message. End users don't know what "output tokens" means.

Proposed consumer message:

⚠️ The agent did not produce a response. This usually indicates a configuration or authentication issue with the backend — not an intentional empty reply. Please check the agent setup or try again.

• No platform-specific rendering needed (Discord/Slack handle this identically today).
• _(no response)_ remains for thought-only turns — semantics are clear enough as-is.

---

4. Security & CI

Security:

• ✅ The new consumer message is safe (does not reveal credentials or provider error details).
• ⚠️ Backend log must not include: raw prompt content, raw provider error messages (some providers like Azure OpenAI embed key fragments in error responses), or credential values.
• ✅ Safe to log: session_id, model_name, stop_reason, input_tokens, output_tokens, total_tokens, agent_command.
• Consider rate-limiting/deduplication: if the same session triggers repeated silent failures, log once at WARN then drop to DEBUG.

CI Gates:

Gate	Trigger	Test Content
Unit test	Every PR	end_turn + 0 tokens + empty body → fires error path; legitimate empty reply (usage absent) → does NOT fire
Integration/Smoke test	Changes to AcpEvent enum or _resp_rx handling	Notify stream handles terminal event without panic; error propagation is complete

---

5. Spec Validation

• ACP spec compliance: stopReason: "end_turn" + usage.outputTokens: 0 is a syntactically valid success response per ACP protocol. No spec violation.
• Application-layer heuristic is appropriate: The spec governs transport/structure; OpenAB as an application harness is responsible for UX boundaries. Classifying a semantically-empty success as an implied failure is within OAB's domain.
• Upstream fix impact: When OpenCode PR #33854 / MiMoCode fixes land, those agents will return proper JSON-RPC error instead of empty end_turn. At that point, OAB's response_error path handles it directly, and this heuristic becomes dead code for those agents — but not a false positive source (0-token empty turns remain pathological). Retain as defense-in-depth for unpatched or third-party ACP backends.

---

Revised Implementation Plan

1. connection.rs — In run_reader_loop, when the id-bearing response matches the in-flight prompt id, forward it to notify_tx as the final message before closing the channel (stop dropping _resp_rx).

2. adapter.rs — In the rx.recv() loop, detect msg.id.is_some() as terminal response. Extract stop_reason and usage from the result. Store as local state for the empty-turn branch.

3. adapter.rs empty-turn branch — Replace the current single fallback with:

   if silent_failure (end_turn && outputTokens == Some(0) && body empty):
       → consumer: user-friendly diagnostic (see UX section)
       → backend: tracing::warn!(agent, stop_reason, input_tokens, output_tokens, session_id, "agent returned empty turn")
   else (usage absent OR outputTokens > 0):
       → "_(no response)_" (unchanged)
   

4. Log sanitization — Never log prompt content or raw provider error messages in this path. Only structured metadata fields.

5. Tests — Unit tests for all three branches (silent failure, usage-absent, normal turn). Smoke test extension for notify stream terminal event handling.

---

Open Questions

• Should we also log the model field? (Available from configOptions but may not be threaded to the adapter yet — can be a follow-up.)
• Rate-limit strategy for repeated silent failures in the same session — implement now or defer?

---

This comment reflects consolidated analysis from the review team. The issue proposal is sound with the architectural refinements noted above (no classify_notification pollution, separate error taxonomy, de-technicalized UX message). Ready for implementation.

[chaodu-agent]

Final Revised Implementation Plan (Team Consensus)

Status: 5/7 reviewers LGTM ✅ — architecture, UX, security/CI, performance/testing angles covered. No unresolved blockers.

---

Summary of Changes from Original Proposal

Original	Revised (team consensus)
Add AcpEvent::TurnEnd to classify_notification	❌ Do NOT touch classify pipeline — handle id-bearing response directly in adapter
Modify connection.rs to stop dropping _resp_rx	❌ Current main already forwards id-bearing responses — no change needed
Reuse response_error render path for silent failure	❌ Separate error taxonomy — silent failure gets its own dedicated path
Consumer message mentions "output tokens"	❌ De-technicalized: no mention of tokens to end users
TurnEnd has output_tokens + total_tokens only	✅ Add input_tokens: Option<u64> for complete backend log

---

Revised Implementation Plan

Step 1: connection.rs — NO CHANGE NEEDED

Current main already forwards id-bearing responses to the subscriber stream while resolving pending. Confirm existing behavior + ensure regression test coverage exists.

Step 2: adapter.rs — Identify terminal response in rx.recv() loop

When the loop receives a message with id.is_some(), this is the final session/prompt response. Extract:

• stop_reason: Option<String> from result.stopReason
• input_tokens: Option<u64> from result.usage.inputTokens
• output_tokens: Option<u64> from result.usage.outputTokens
• total_tokens: Option<u64> from result.usage.totalTokens

Parse defensively — all fields Option (some agents omit usage).

Step 3: adapter.rs — Branch the empty-turn case

Replace the current single fallback with three-way classification:

let final_content = if final_content.is_empty() {
    if let Some(err) = response_error {
        // Path A: Protocol/System Error (JSON-RPC error, agent crash)
        // Level: ERROR
        format!("⚠️ {err}")
    } else if is_silent_failure(stop_reason, output_tokens) {
        // Path B: Silent Failure (end_turn + 0 output tokens + empty body)
        // Level: WARN
        tracing::warn!(agent, stop_reason, input_tokens, output_tokens, total_tokens, session_id, thread,
            "agent returned empty turn (0 output tokens) — likely provider/model/auth failure");
        "⚠️ The agent did not produce a response. This usually indicates a backend configuration issue — not an intentional empty reply. Please try again later.".to_string()
    } else {
        // Path C: Thought-only / narration-only (tokens > 0 or usage absent)
        // Level: DEBUG (optional)
        "_(no response)_".to_string()
    }
} else if let Some(err) = response_error {
    format!("⚠️ {err}\n\n{final_content}")
} else {
    final_content
};

fn is_silent_failure(stop_reason: &Option<String>, output_tokens: &Option<u64>) -> bool {
    matches!((stop_reason.as_deref(), output_tokens), (Some("end_turn"), Some(0)))
}

Error Taxonomy:

Category	Trigger	Log Level	Consumer Message
Protocol/System Error	JSON-RPC error, agent crash	ERROR	⚠️ {err}
Silent Failure	end_turn + outputTokens == Some(0) + empty body	WARN	Dedicated user-friendly message
Thought-only	Empty body + (outputTokens > 0 OR usage absent)	DEBUG	_(no response)_

Step 4: Log sanitization

Backend log fields (safe to log):

• agent (command), stop_reason, input_tokens, output_tokens, total_tokens, session_id, thread

Never log:

• Raw prompt content (may contain PII)
• Raw provider error messages (may contain key fragments)
• Credential values

Step 5: Tests (layered)

Layer	File	Test Cases
Connection	connection.rs	id-bearing response is forwarded to subscriber (confirm existing behavior)
Protocol	protocol.rs	id-bearing result.stopReason/usage correctly parsed; missing fields handled
Adapter	adapter.rs	1. end_turn + outputTokens=0 + empty body → consumer diagnostic + WARN log
		2. end_turn + outputTokens>0 + empty body → _(no response)_
		3. usage absent + empty body → _(no response)_ (no false positive)
		4. end_turn + outputTokens=0 + inputTokens>0 + empty body → still fires diagnostic
		5. JSON-RPC error present → Protocol error path takes precedence
		6. Non-empty turn → completely unaffected

---

Follow-up Items (out of scope for this PR)

1. Log dedup/rate-limit — If same session triggers repeated silent failures, consider dedup (first N at WARN, subsequent at DEBUG). Track in a follow-up issue linked to fix(session): surface a diagnostic instead of (no response) when an ACP agent returns an empty 0-token end_turn #1212.
2. Model field in log — Add model from configOptions to the WARN log line if already threaded to adapter; otherwise defer.
3. Config flag — Optional diagnostics.surface_empty_turn flag for operators with agents that legitimately produce 0-token responses. Low priority given the usage absent → no diagnostic fallback.

---

Backward Compatibility

• Non-empty turns: completely untouched
• usage absent: falls through to _(no response)_ (no false positives)
• Agent dies before sending result: existing death/error paths handle it (no new hang risk)
• JSON-RPC error present: existing response_error path takes precedence

---

Team Review Verdicts

Reviewer	Angle	Verdict
Reviewer A	Architecture	LGTM ✅
Reviewer B	UX/Docs	LGTM ✅
Reviewer C	Security/CI	LGTM ✅
Reviewer D	Security/CI	LGTM ✅
Reviewer E	Performance/Testing	LGTM ✅

Consensus: Ready for implementation. No unresolved blockers. All CHANGES REQUESTED items have been addressed in this revised plan.