Chat Connection States
Pinchy tracks the health of the agent connection in real time so you always know what’s happening — and what to do if something goes wrong.
The four states
Section titled “The four states”| State | Indicator | What it means |
|---|---|---|
| Starting | Yellow | Pinchy is loading your conversation history. |
| Ready | Green | The agent is available and waiting for your message. |
| Responding | Green | The agent is generating a reply. You can still type. |
| Unavailable | Red or Yellow | The agent can’t be reached right now. |
Unavailable reasons
Section titled “Unavailable reasons”When the state is Unavailable, the indicator and status message explain why:
- Disconnected (red): The connection dropped. Pinchy is trying to reconnect automatically.
- Configuring (yellow): You recently changed agent settings. Pinchy is applying the changes and will be ready in a moment.
- Exhausted (red): Reconnection attempts failed. You need to reload the page to resume.
Auto-recovery
Section titled “Auto-recovery”When the agent runtime becomes reachable again — whether after a network drop or after a settings change — Pinchy automatically requests the latest conversation history and resumes where it left off. No reload needed.
Brief disconnects don’t lock the UI
Section titled “Brief disconnects don’t lock the UI”Pinchy waits 2 seconds before showing the Disconnected state. During those 2 seconds the interface stays in its previous state (Ready or Responding) so short network hiccups are absorbed silently without disrupting your flow.
Typing while the agent responds
Section titled “Typing while the agent responds”You can type your next message while the agent is still generating a reply. Only the Send button and the Retry button are disabled during a response — the text input stays active so you can prepare follow-up questions.
Model-unavailable errors
Section titled “Model-unavailable errors”When the model itself is the problem — not the connection — Pinchy shows a dedicated model-unavailable bubble in the chat thread. This is distinct from the connection-state indicators above: the agent runtime is reachable, but the upstream provider returned a server error (HTTP 5xx) that signals the model is offline or discontinued.
The bubble shows the affected agent name, the model identifier, and a plain-English explanation. A Switch model → link takes you straight to the agent’s model settings so you can pick a replacement without leaving the chat.
See Manage LLM Providers — Model-unavailable errors for step-by-step instructions and the list of removed models.
Upstream format errors
Section titled “Upstream format errors”Some providers occasionally reject a request payload because of a known schema defect that retries usually clear — the canonical example is Gemini 3 dropping its required thought_signature field on a tool-call replay turn (upstream openclaw/openclaw#72879). When Pinchy recognises one of these patterns, the chat shows a dedicated transient upstream issue bubble instead of the generic provider-error wording.
The bubble is deliberately different from the model-unavailable one above:
- It names the affected model and explains the cause is upstream, not your configuration.
- It tells you to click Retry — the same message usually succeeds on the next try.
- It does not offer a “Switch model →” link. The model is fine; switching would push you away from the one you actually chose.
Each occurrence writes a throttled agent.upstream_format_error audit entry (one per (agent, model) per 5 minutes) so admins can track frequency from the audit page rather than grepping gateway logs.
Navigating away mid-conversation
Section titled “Navigating away mid-conversation”When you send a message and move to a different page in Pinchy, the chat keeps running in the background. Come back any time during the same browser session and the in-flight reply is right there — no reload, no lost output. A pulse dot next to the agent name in the sidebar shows when an agent is actively responding; a red dot indicates an error on the last turn. Closing the tab or doing a full page reload ends the session.
See also: Message Delivery & Retry for how to recover from failed messages.