Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
Log when an agent runtime falls back to the event stream (#1031)
Abel Dantas495f309408b4
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 listof packages that already exist, by `id` or by `name`, attached when the roomis 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#### Addeddiff --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.tsindex 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.tsindex 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.pyindex 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, AgentExistsErrorfrom 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.pyindex 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 = Noneartifact: str | None = Noneversion: 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@propertydef 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_protocolelse "unknown",transport,+ _fallback_suffix(declaration),)return conndiff --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.pyindex 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(