Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

Log when an agent runtime falls back to the event stream (#1031)

Abel Dantas495f309408b4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1d2b68cab..05241fef4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -68,6 +68,13 @@ version of their own to them without also giving them a release of their own.
Atlassian, whose tokens cannot be asked for shorter.
#### Added
+- **The `[CONN]` log lines say when a client fell back to the event stream.**
+ `/events` takes optional `fallback` and `fallback_close_code` parameters,
+ and the `[CONN] opened` and `[CONN] reattached` lines end with
+ `fallback=<reason>:<close code>` only when they are present, so a new agent
+ runtime whose WebSocket never opened is told apart from a client built
+ before the socket. Unknown reasons log as `other` and anything but a short
+ numeric close code is dropped.
- **Templates carry packages.** A room in a template takes `packages:`, a list
of packages that already exist, by `id` or by `name`, attached when the room
is created. The person running the template must be able to attach each one
@@ -4125,6 +4132,13 @@ The Switch protocol client and MCP runtime
### [Unreleased]
+#### Added
+- When the WebSocket never opens and the runtime asks for the event stream
+ instead, the request carries `fallback=socket_never_opened` and the
+ socket's close code as `fallback_close_code`, so the server's log can tell
+ it from a client built before the socket. Opening the event stream straight
+ away, against an old server, sends neither.
+
### [0.8.0] - 2026-09-25
#### Added
diff --git a/console/packages/switch-agent-runtime/src/event-stream.old-server.test.ts b/console/packages/switch-agent-runtime/src/event-stream.old-server.test.ts
index 537ad1ade..ddd2aedae 100644
--- a/console/packages/switch-agent-runtime/src/event-stream.old-server.test.ts
+++ b/console/packages/switch-agent-runtime/src/event-stream.old-server.test.ts
@@ -2064,6 +2064,25 @@ describe('choosing the transport', () => {
abort.abort();
});
+ it('says the stream it asks for after a socket that never opened is a fallback, and opening it straight away is not', async () => {
+ vi.useFakeTimers();
+ // A server from before the socket: the first open falls back, the next
+ // goes to the stream straight away.
+ const fetchMock = serving(() => announcingThenClose(6));
+ const { abort } = makeStream(fetchMock, { rooms: [] });
+
+ await vi.advanceTimersByTimeAsync(1500);
+
+ const [fellBack, direct] = urlsFor(fetchMock, '/events').map(
+ (url) => new URL(url).searchParams
+ );
+ expect(fellBack!.get('fallback')).toBe('socket_never_opened');
+ expect(fellBack!.get('fallback_close_code')).toBe('1006');
+ expect(direct!.has('fallback')).toBe(false);
+ expect(direct!.has('fallback_close_code')).toBe(false);
+ abort.abort();
+ });
+
it('keeps trying the socket first when neither answers, and says it could not connect', async () => {
vi.useFakeTimers();
const fetchMock = vi.fn(async () => {
diff --git a/console/packages/switch-agent-runtime/src/event-stream.ts b/console/packages/switch-agent-runtime/src/event-stream.ts
index eff540f43..3d4053dd6 100644
--- a/console/packages/switch-agent-runtime/src/event-stream.ts
+++ b/console/packages/switch-agent-runtime/src/event-stream.ts
@@ -349,7 +349,7 @@ type Transport = 'socket' | 'stream';
/** The socket closed before it opened: the server is unreachable, or has no
* socket to offer. Only a request to the event stream tells the two apart. */
class SocketNeverOpened extends Error {
- constructor(code: number | null) {
+ constructor(readonly code: number | null) {
super(
`could not connect to Switch (socket closed with ${code ?? 'no code'}, and the event stream did not answer either): the server is unreachable`
);
@@ -960,7 +960,9 @@ export class SwitchEventStream {
* `probing` is the socket's failure when this request is the one that tells
* an old server from an unreachable one. Then anything short of a stream
* means unreachable, and that failure is what is reported. A refusal is
- * still the server's answer, and handled as one.
+ * still the server's answer, and handled as one. The request also says it
+ * is a fallback, and the socket's close code, so the server's log can tell
+ * it from a client built before the socket.
*/
private async *readEventStream(
params: URLSearchParams,
@@ -969,9 +971,14 @@ export class SwitchEventStream {
probing: SocketNeverOpened | null
): AsyncGenerator<SocketFrame> {
const { creds, signal } = this.deps;
+ const query = new URLSearchParams(params);
+ if (probing) {
+ query.set('fallback', 'socket_never_opened');
+ if (probing.code !== null) query.set('fallback_close_code', String(probing.code));
+ }
let resp: Response;
try {
- resp = await fetch(`${creds.apiEndpoint}/agents/${creds.agentId}/events?${params}`, {
+ resp = await fetch(`${creds.apiEndpoint}/agents/${creds.agentId}/events?${query}`, {
headers: {
Authorization: `Bearer ${creds.token}`,
Accept: 'text/event-stream',
diff --git a/core/switch_core/bridges/agent/api/handlers.py b/core/switch_core/bridges/agent/api/handlers.py
index 0a2b073fb..cc8a962f5 100644
--- a/core/switch_core/bridges/agent/api/handlers.py
+++ b/core/switch_core/bridges/agent/api/handlers.py
@@ -95,6 +95,7 @@ from switch_core.bridges.agent.protocol.agent_connections import (
UnfencedControlError,
UnknownConnectionError,
evicted_session_warning,
+ sse_fallback,
)
from switch_core.bridges.agent.protocol.agent_core import AgentCore, AgentExistsError
from switch_core.bridges.agent.protocol.event_buffer import TICKET_FLOOR, Reader
@@ -739,6 +740,8 @@ async def poll_events(
client: Annotated[str | None, Query()] = None,
client_version: Annotated[str | None, Query()] = None,
rooms: Annotated[str | None, Query()] = None,
+ fallback: Annotated[str | None, Query()] = None,
+ fallback_close_code: Annotated[str | None, Query()] = None,
last_event_id: Annotated[str | None, Header(alias="last-event-id")] = None,
) -> EventResponse | Response:
"""Deliver the agent's events, as a push stream or a long poll.
@@ -753,6 +756,8 @@ async def poll_events(
The declaration parameters are all optional and all default to None,
meaning *unknown* (CHOO-1865): a client that says nothing still connects.
+ `fallback` (and `fallback_close_code`) come from a runtime that has the
+ WebSocket but whose socket never opened, and only reach the log line.
"""
if accept and "text/event-stream" in accept:
return await _open_event_stream(
@@ -770,6 +775,7 @@ async def poll_events(
accepts=protocol_accepts,
artifact=client,
version=client_version,
+ fallback=sse_fallback(fallback, fallback_close_code),
),
rooms=rooms,
last_event_id=last_event_id,
diff --git a/core/switch_core/bridges/agent/protocol/agent_connections.py b/core/switch_core/bridges/agent/protocol/agent_connections.py
index dc300bd83..2ea7a9347 100644
--- a/core/switch_core/bridges/agent/protocol/agent_connections.py
+++ b/core/switch_core/bridges/agent/protocol/agent_connections.py
@@ -334,6 +334,9 @@ class ClientDeclaration:
accepts: int | None = None
artifact: str | None = None
version: str | None = None
+ # Why a client that has the WebSocket opened the event stream instead, as
+ # `sse_fallback` cleaned it. Logged only: not recorded and not reported.
+ fallback: str | None = None
@property
def declares_protocol(self) -> bool:
@@ -361,6 +364,31 @@ class ClientDeclaration:
}
+SSE_FALLBACK_REASONS = frozenset({"socket_never_opened"})
+
+
+def sse_fallback(reason: str | None, close_code: str | None) -> str | None:
+ """Why a client opened the event stream, as it goes in the log line.
+
+ A runtime that has the WebSocket asks for the event stream only when its
+ socket never opened, and says so, so the log can tell it apart from a
+ client built before the socket. Both values are the client's own, so an
+ unknown reason becomes "other" and a close code that is not a short number
+ is dropped.
+ """
+ if not reason:
+ return None
+ label = reason if reason in SSE_FALLBACK_REASONS else "other"
+ if (
+ close_code
+ and close_code.isascii()
+ and close_code.isdigit()
+ and len(close_code) <= 4
+ ):
+ return f"{label}:{close_code}"
+ return label
+
+
def client_label(declaration: ClientDeclaration) -> str:
"""The declared artifact as a metric value: a registered name, or a bucket.
@@ -375,6 +403,14 @@ def client_label(declaration: ClientDeclaration) -> str:
return "other"
+def _fallback_suffix(declaration: ClientDeclaration) -> str:
+ """` fallback=<why>` for the `[CONN]` log lines, or nothing when the
+ client did not fall back, so the line reads as it always has."""
+ if declaration.fallback is None:
+ return ""
+ return f" fallback={declaration.fallback}"
+
+
class ProtocolVersionError(ConnectionError_):
"""A client's declared agent-protocol range cannot meet this server's.
@@ -728,13 +764,14 @@ class AgentConnectionRegistry:
metrics().increment(AGENT_CONNECTIONS_OPENED, {"kind": "reattach"})
logger.info(
"[CONN] reattached agent=%s connection=%s scope=%s generation=%s "
- "transport=%s%s",
+ "transport=%s%s%s",
agent_id,
connection_id,
scope,
existing.stream_generation,
transport,
f" from process={moved_from}" if moved_from is not None else "",
+ _fallback_suffix(declaration),
)
return existing
@@ -765,7 +802,7 @@ class AgentConnectionRegistry:
)
logger.info(
"[CONN] opened agent=%s connection=%s scope=%s filter=%s spawn=%s "
- "client=%s version=%s protocol=%s transport=%s",
+ "client=%s version=%s protocol=%s transport=%s%s",
agent_id,
connection_id,
scope,
@@ -777,6 +814,7 @@ class AgentConnectionRegistry:
if declaration.declares_protocol
else "unknown",
transport,
+ _fallback_suffix(declaration),
)
return conn
diff --git a/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.py b/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.py
index bd4b43fa8..8ca5b9055 100644
--- a/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.py
+++ b/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.py
@@ -179,6 +179,80 @@ async def test_with_the_sse_accept_header_it_opens_the_event_stream(
assert conn.stream_transport == "sse"
+async def _open_sse(protocol: _Protocol, **kw: Any) -> StreamingResponse:
+ resp = await poll_events(
+ agent_id=AGENT_ID,
+ agent=_agent(),
+ protocol=protocol, # type: ignore[arg-type]
+ config=None, # type: ignore[arg-type]
+ accept="text/event-stream",
+ connection_id="c1",
+ client="agent-runtime",
+ client_version="0.8.0",
+ **kw,
+ )
+ assert isinstance(resp, StreamingResponse)
+ return resp
+
+
+def _opened_lines(caplog: pytest.LogCaptureFixture) -> list[str]:
+ return [r.getMessage() for r in caplog.records if "[CONN] opened" in r.getMessage()]
+
+
+async def test_a_runtime_that_fell_back_from_the_socket_says_so_in_the_log(
+ db_buffer: EventBuffer, caplog: pytest.LogCaptureFixture
+) -> None:
+ """A new runtime whose socket never opened asks for the event stream too,
+ and must not read in the log as a client built before the socket."""
+ caplog.set_level("INFO")
+ await _open_sse(
+ _Protocol(db_buffer),
+ fallback="socket_never_opened",
+ fallback_close_code="1006",
+ )
+
+ (line,) = _opened_lines(caplog)
+ assert line.endswith("transport=sse fallback=socket_never_opened:1006")
+
+
+async def test_a_client_that_did_not_fall_back_logs_the_line_as_before(
+ db_buffer: EventBuffer, caplog: pytest.LogCaptureFixture
+) -> None:
+ caplog.set_level("INFO")
+ await _open_sse(_Protocol(db_buffer))
+
+ (line,) = _opened_lines(caplog)
+ assert line.endswith("transport=sse")
+ assert "fallback" not in line
+
+
+ ("reason", "close_code", "logged"),
+ [
+ ("socket_never_opened", None, "socket_never_opened"),
+ ("x" * 5000, "1006", "other:1006"),
+ ("socket_never_opened", "1006 rm -rf", "socket_never_opened"),
+ ("socket_never_opened", "123456", "socket_never_opened"),
+ ],
+)
+async def test_what_the_client_says_about_its_fallback_is_clamped(
+ reason: str,
+ close_code: str | None,
+ logged: str,
+ db_buffer: EventBuffer,
+ caplog: pytest.LogCaptureFixture,
+) -> None:
+ """Both values are the client's own, so only known reasons and short
+ numeric close codes reach the log."""
+ caplog.set_level("INFO")
+ await _open_sse(
+ _Protocol(db_buffer), fallback=reason, fallback_close_code=close_code
+ )
+
+ (line,) = _opened_lines(caplog)
+ assert line.endswith(f" fallback={logged}")
+
+
async def test_opening_registers_the_connection(db_buffer: EventBuffer) -> None:
protocol = _Protocol(db_buffer)
conn = await _call(