Your lightweight open-source personal agent.
Python agent-frameworkai-agentai-agentschatbotchatopsdiscord-botllm-agentsllmslocal-llmmcpmodel-context-protocolmulti-agentopenai-compatibleopenclawpersonal-ai-assistantpythonself-hostedtelegram-bot-ai-assistantwebuiworkflow-automation
fix(tui): surface chat connection failures (#5543)
chengyongru3a62b0b74402
diff --git a/nanobot/cli/tui_launcher.py b/nanobot/cli/tui_launcher.pyindex 4d4075709..b0ddfb487 100644--- a/nanobot/cli/tui_launcher.py+++ b/nanobot/cli/tui_launcher.py@@ -21,6 +21,7 @@ from nanobot.cli.process_identity import named_executablefrom nanobot.cli.runtime_config import _model_displayfrom nanobot.cli.webui_support import (_gateway_health_ready,+ _gateway_health_url,_gateway_instance_command,_host_for_local_browser,_webui_endpoint_reachable,@@ -96,6 +97,10 @@ def launch_tui(env.update({"NANOBOT_TUI_BOOTSTRAP_URL": f"{base_url}/webui/bootstrap",+ "NANOBOT_TUI_HEALTH_URL": _gateway_health_url(+ config.gateway.host,+ config.gateway.port,+ ),"NANOBOT_TUI_API_URL": base_url,"NANOBOT_TUI_MODEL": _model_display(config)[0],"NANOBOT_TUI_MODEL_PRESET": config.agents.defaults.model_preset or "default",diff --git a/tests/cli/test_tui_launcher.py b/tests/cli/test_tui_launcher.pyindex a4b7fede2..5cc1f4a65 100644--- a/tests/cli/test_tui_launcher.py+++ b/tests/cli/test_tui_launcher.py@@ -142,6 +142,7 @@ def test_launcher_passes_the_canonical_model_preset_to_the_tui(assert captured["NANOBOT_TUI_BOOTSTRAP_URL"] == ("http://127.0.0.1:8765/webui/bootstrap")+ assert captured["NANOBOT_TUI_HEALTH_URL"] == "http://127.0.0.1:18790/health"assert captured["NANOBOT_TUI_BOOTSTRAP_SECRET"] == "bootstrap-secret"assert "NANOBOT_TUI_WS_URL" not in capturedassert "NANOBOT_TUI_API_TOKEN" not in captureddiff --git a/tui/src/app.test.ts b/tui/src/app.test.tsindex b5a1b47ac..b170efb9b 100644--- a/tui/src/app.test.ts+++ b/tui/src/app.test.ts@@ -182,7 +182,7 @@ describe("NanobotTui layout", () => {expect(setup.renderer.height).toBe(height)expect(occurrences(frame, "Ask nanobot anything")).toBe(1)expect(occurrences(frame, "Ready")).toBe(0)- expect(occurrences(frame, "Connecting…")).toBe(1)+ expect(occurrences(frame, "Getting ready…")).toBe(1)expect(occurrences(frame, "nanobot · test/model")).toBe(1)}@@ -2384,6 +2384,85 @@ describe("NanobotTui layout", () => {expect(state()).toBe(false)})+ test("shows actionable connection states without implementation details", async () => {+ setup = await createRenderer({ width: 100, height: 20, screenMode: "alternate-screen" })+ const app = mount(setup)+ const ui = app as unknown as {+ status: TextRenderable+ handleStatus(+ status: "starting" | "connecting" | "connected" | "reconnecting" | "unavailable" | "error",+ detail?: string,+ info?: {+ endpoint: string+ attempt: number+ elapsedMs: number+ health?: "ready" | "degraded" | "unreachable"+ },+ ): void+ }++ ui.handleStatus("starting", undefined, {+ endpoint: "127.0.0.1:8769",+ attempt: 1,+ elapsedMs: 0,+ })+ expect(ui.status.plainText).toBe("Getting ready…")++ ui.handleStatus("connecting")+ expect(ui.status.plainText).toBe("Getting ready…")++ ui.handleStatus("connected")+ expect(ui.status.plainText).toBe("Getting ready…")++ ui.handleStatus("error", "gateway sent an invalid event")+ expect(ui.status.plainText).toBe("Getting ready…")+ expect(ui.status.plainText).not.toContain("Unable")++ ui.handleStatus("reconnecting", "connection closed", {+ endpoint: "127.0.0.1:8769",+ attempt: 2,+ elapsedMs: 800,+ })+ expect(ui.status.plainText).toBe("Resuming…")++ ui.handleStatus("reconnecting", "connection closed", {+ endpoint: "127.0.0.1:8769",+ attempt: 2,+ elapsedMs: 900,+ health: "degraded",+ })+ expect(ui.status.plainText).toBe("Resuming…")++ ui.handleStatus("unavailable", "connection refused", {+ endpoint: "127.0.0.1:8769",+ attempt: 7,+ elapsedMs: 3_200,+ health: "degraded",+ })+ expect(ui.status.plainText).toBe("Still getting ready…")+ expect(ui.status.plainText).not.toContain("Unable")++ ui.handleStatus("unavailable", "connection refused", {+ endpoint: "127.0.0.1:8769",+ attempt: 8,+ elapsedMs: 3_500,+ health: "unreachable",+ })+ expect(ui.status.plainText).toBe("Nanobot is taking longer to respond…")+ expect(ui.status.plainText).not.toContain("Unable")++ ui.handleStatus("error", "gateway bootstrap failed: HTTP 401", {+ endpoint: "127.0.0.1:8769",+ attempt: 9,+ elapsedMs: 3_800,+ })+ expect(ui.status.plainText).toBe("Nanobot unavailable · restart nanobot")+ expect(ui.status.plainText).not.toContain("gateway")+ expect(ui.status.plainText).not.toContain("127.0.0.1")+ expect(ui.status.plainText).not.toContain("HTTP")+ expect(ui.status.plainText).not.toContain("attempt")+ })+test("replays events after asynchronous history hydration", async () => {setup = await createRenderer({ width: 80, height: 22, screenMode: "alternate-screen" })const original = globalThis.fetch@@ -2444,7 +2523,12 @@ describe("NanobotTui layout", () => {client(sent),new MockTreeSitterClient({ autoResolveTimeout: 0 }),)- const composer = (app as unknown as { composer: TextareaRenderable }).composer+ const ui = app as unknown as {+ composer: TextareaRenderable+ ready: boolean+ status: TextRenderable+ }+ const composer = ui.composertry {app.accept({ event: "attached", chat_id: "chat" })@@ -2452,16 +2536,18 @@ describe("NanobotTui layout", () => {app.accept({ event: "attached", chat_id: "chat" })composer.setText("sent during reconnect")composer.submit()- await Bun.sleep(5)+ await waitUntil(() => ui.status.plainText.includes("Not sent"))expect(sent).toEqual([])expect(composer.plainText).toBe("sent during reconnect")+ expect(ui.status.plainText).toContain("Not sent · press Enter to retry when ready")resolveReconnect(new Response(JSON.stringify({messages: [{ role: "assistant", content: "restored history" }],page: { has_more_before: false },})))- await waitUntil(() => (app as unknown as { ready: boolean }).ready)+ await waitUntil(() => ui.ready)+ expect(ui.status.plainText).toBe("Not sent · press Enter to retry")composer.submit()await waitUntil(() => sent.length === 1)await setup.flush()@@ -2480,24 +2566,38 @@ describe("NanobotTui layout", () => {const app = mount(setup, sent)const composer = (app as unknown as { composer: TextareaRenderable }).composerconst connection = app as unknown as {- handleStatus(status: "connecting" | "connected", detail?: string): void+ handleStatus(+ status: "reconnecting" | "connected",+ detail?: string,+ info?: { endpoint: string; attempt: number; elapsedMs: number },+ ): void}app.accept({ event: "attached", chat_id: "chat" })await Bun.sleep(1)- connection.handleStatus("connecting", "reconnecting")+ connection.handleStatus("reconnecting", "connection closed", {+ endpoint: "127.0.0.1:8769",+ attempt: 1,+ elapsedMs: 0,+ })connection.handleStatus("connected")composer.setText("draft before attach")composer.submit()await Bun.sleep(5)+ composer.submit()+ await Bun.sleep(5)expect(sent).toEqual([])expect(composer.plainText).toBe("draft before attach")+ app.accept({ event: "attached", chat_id: "chat" })app.accept({ event: "attached", chat_id: "chat" })await waitUntil(() => (app as unknown as { ready: boolean }).ready)+ expect(sent).toEqual([])composer.submit()await waitUntil(() => sent.length === 1)+ app.accept({ event: "attached", chat_id: "chat" })+ await Bun.sleep(5)expect(sent).toEqual(["draft before attach"])})diff --git a/tui/src/app.ts b/tui/src/app.tsindex f12716c63..20689a14e 100644--- a/tui/src/app.ts+++ b/tui/src/app.ts@@ -20,7 +20,9 @@ import {import {NanobotClient,+ connectionEndpoint,fetchAvailableSkills,+ fetchGatewayHealth,fetchHistory,fetchGatewayConnection,fetchMentionCandidates,@@ -29,6 +31,7 @@ import {fetchSlashCommands,type ApiReauthenticator,type ConnectionStatus,+ type ConnectionStatusInfo,type FileEditEvent,type GatewayApiConnection,type HistoryMessage,@@ -93,6 +96,7 @@ interface AppOptions {wsUrl?: stringbootstrapUrl?: stringbootstrapSecret?: string+ healthUrl?: stringapiUrl: stringapiToken: stringchatId?: string@@ -374,6 +378,21 @@ function formatElapsed(milliseconds: number): string {return `${Math.floor(seconds / 60)}m ${String(seconds % 60).padStart(2, "0")}s`}+function connectionStatusText(+ status: ConnectionStatus,+ info?: ConnectionStatusInfo,+): string {+ if (["starting", "connecting", "connected"].includes(status)) return "Getting ready…"+ if (status === "reconnecting") return "Resuming…"+ if (status === "unavailable") {+ return info?.health === "degraded"+ ? "Still getting ready…"+ : "Nanobot is taking longer to respond…"+ }+ if (status === "error") return "Nanobot unavailable · restart nanobot"+ return "Session ended"+}+function singleLine(value: string, limit = 120): string {return value.replace(/\s+/gu, " ").trim().slice(0, limit)}@@ -449,6 +468,8 @@ export class NanobotTui {private shimmerTimer: ReturnType<typeof setInterval> | null = nullprivate submitPending = falseprivate submitGeneration = 0+ private unsentSubmit = false+ private connectionMessage = "Getting ready…"private readonly promptHistory: string[] = []private historyCursor = 0private historyDraft = ""@@ -556,11 +577,14 @@ export class NanobotTui {options.apiUrl,`tui-${process.pid}`,),+ ...(options.healthUrl+ ? { checkHealth: () => fetchGatewayHealth(options.healthUrl || "") }+ : {}),onConnection: (connection) => this.useGatewayConnection(connection.apiUrl,connection.apiToken,),- connectionRetryLabel: "Starting local gateway",+ targetEndpoint: connectionEndpoint(options.bootstrapUrl),reconnectDelayMs: 100,startupRetryMaxDelayMs: 250,}@@ -571,7 +595,7 @@ export class NanobotTui {access_mode: options.access.toLocaleLowerCase().includes("full") ? "full" : "restricted",},onEvent: (event) => this.accept(event),- onStatus: (status, detail) => this.handleStatus(status, detail),+ onStatus: (status, detail, info) => this.handleStatus(status, detail, info),})// The terminal owns its canvas. Keeping the default-background intent is@@ -723,6 +747,8 @@ export class NanobotTui {},onContentChange: () => {this.draft.prune(this.composer.plainText)+ const clearedUnsent = this.unsentSubmit && !this.composer.plainText.trim()+ if (clearedUnsent) this.unsentSubmit = falsethis.runtimeControls.hide()if (this.contextPanel.visible && this.composer.plainText) this.contextPanel.hide()this.syncComposerPlaceholder()@@ -730,6 +756,9 @@ export class NanobotTui {else if (this.branchMenu.visible) this.syncBranchMenu()else this.syncComposerMenus()this.resizeComposer()+ if (clearedUnsent && !this.activeTurn) {+ this.status.content = this.ready ? this.readyStatus() : this.connectionMessage+ }},// IMEs may commit their final composed glyph after Enter. Matching the// OpenCode/OpenTUI integration, defer twice before reading plainText.@@ -738,7 +767,7 @@ export class NanobotTui {})this.status = new TextRenderable(renderer, {id: "nanobot-tui-status",- content: "Connecting…",+ content: "Getting ready…",fg: this.palette.muted,height: 1,width: "auto",@@ -824,7 +853,7 @@ export class NanobotTui {// Network setup and small menu payloads do not depend on terminal colors.// Start them while OSC theme detection is in flight instead of serializing// up to one second of otherwise independent startup work.- this.host.reportState("unknown", "Connecting")+ this.host.reportState("unknown", "Getting ready")this.client.connect()void this.loadCommands()void this.loadMentions()@@ -899,6 +928,10 @@ export class NanobotTui {return}if (["/continue", "/dismiss"].includes(visibleContent.toLowerCase())) {+ if (!this.ready) {+ this.markSubmitUnsent()+ return+ }this.clearComposer()this.commandMenu.hide()void this.updateRecovery(visibleContent.toLowerCase() === "/continue" ? "continue" : "dismiss")@@ -932,7 +965,7 @@ export class NanobotTui {return}if (!this.ready) {- this.status.content = "Preparing chat…"+ this.markSubmitUnsent()return}const prompt = { content, options: mentionOptions(content, this.availableMentions()) }@@ -947,10 +980,11 @@ export class NanobotTui {let turnId: stringtry {turnId = this.client.send(prompt.content, prompt.options)- } catch (error) {- this.status.content = error instanceof Error ? error.message : String(error)+ } catch {+ this.markSubmitUnsent(true)return false}+ this.unsentSubmit = falsethis.clearComposer()this.commandMenu.hide()this.mentionMenu.hide()@@ -1392,36 +1426,58 @@ export class NanobotTui {}}- private handleStatus(status: ConnectionStatus, detail?: string): void {+ private handleStatus(+ status: ConnectionStatus,+ _detail?: string,+ info?: ConnectionStatusInfo,+ ): void {+ // Invalid frames do not mean the transport is unavailable. Keep the last+ // accurate user-facing state unless the protocol supplied connection diagnostics.+ if (status === "error" && !info) return+ this.connectionMessage = connectionStatusText(status, info)if (status === "connected") {this.ready = false- this.host.reportState("unknown", "Connecting")- this.status.content = "Connected · preparing chat…"+ this.host.reportState("unknown", "Getting ready")+ this.renderConnectionMessage()return}- if (status === "connecting") {+ if (["starting", "connecting", "reconnecting", "unavailable"].includes(status)) {this.ready = false- const label = detail === "Starting local gateway"- ? detail- : detail ? "Reconnecting" : "Connecting"- this.host.reportState("unknown", label)- if (detail) this.setActive(false)- this.status.content = `${label}…`+ this.host.reportState("unknown", this.connectionMessage)+ if (status === "reconnecting" || status === "unavailable") this.setActive(false)+ this.renderConnectionMessage()return}if (status === "error") {+ if (info) this.ready = falsethis.setActive(false)- this.host.reportState("unknown", detail || "Connection error")- this.status.content = detail || "Connection error"+ this.host.reportState("unknown", this.connectionMessage)+ this.renderConnectionMessage()return}if (!this.quitting) {+ this.ready = falsethis.setActive(false)this.host.reportState("unknown", "Disconnected")- this.status.content = "Disconnected"+ this.renderConnectionMessage()}}+ private renderConnectionMessage(): void {+ this.status.content = this.unsentSubmit+ ? `Not sent · press Enter to retry when ready · ${this.connectionMessage}`+ : this.connectionMessage+ }++ private markSubmitUnsent(sendFailed = false): void {+ this.unsentSubmit = true+ if (sendFailed) {+ this.status.content = "Not sent · send failed; press Enter to retry when ready"+ return+ }+ this.renderConnectionMessage()+ }+private setActive(active: boolean, startedAt?: number): void {if (this.activeTurn === active) {if (active && startedAt !== undefined) this.activeStartedAt = startedAt@@ -1460,6 +1516,7 @@ export class NanobotTui {}private readyStatus(detail = this.readyDetail): string {+ if (this.unsentSubmit) return "Not sent · press Enter to retry"if (this.transcriptNavigation.awayFromBottom) {return this.transcriptNavigation.unseenOutput? "New output · Ctrl+End latest"@@ -2083,6 +2140,7 @@ export class NanobotTui {}private clearComposer(): void {+ this.unsentSubmit = falsethis.draft.clear()this.composer.setText("")}@@ -2383,7 +2441,7 @@ export class NanobotTui {options: MessageOptions = {},): void {if (!this.ready) {- this.status.content = "Preparing chat…"+ this.markSubmitUnsent()return}if (this.activeTurn && lifecycle === "agent_turn") {@@ -2393,10 +2451,11 @@ export class NanobotTui {let turnId: stringtry {turnId = this.client.send(content, options)- } catch (error) {- this.status.content = error instanceof Error ? error.message : String(error)+ } catch {+ this.markSubmitUnsent(true)return}+ this.unsentSubmit = falsethis.commandTurns.set(turnId, lifecycle)if (silent) this.silentCommandTurns.add(turnId)if (/^\/model(?:\s|$)/iu.test(content)) this.modelCommandTurns.add(turnId)diff --git a/tui/src/index.ts b/tui/src/index.tsindex f9b2d07fe..e78eb5112 100644--- a/tui/src/index.ts+++ b/tui/src/index.ts@@ -14,6 +14,7 @@ const workspace = process.env.NANOBOT_TUI_WORKSPACE?.trim() || ""const hostWorkspace = process.cwd()const bootstrapUrl = process.env.NANOBOT_TUI_BOOTSTRAP_URL?.trim() || ""const wsUrl = process.env.NANOBOT_TUI_WS_URL?.trim() || ""+const healthUrl = process.env.NANOBOT_TUI_HEALTH_URL?.trim() || ""const gatewayStopCommand = process.env.NANOBOT_TUI_GATEWAY_STOP_COMMAND?.trim()|| "nanobot gateway stop"if (!bootstrapUrl && !wsUrl) {@@ -24,6 +25,7 @@ const options: AppOptions = {? {bootstrapUrl,bootstrapSecret: process.env.NANOBOT_TUI_BOOTSTRAP_SECRET?.trim() || "",+ healthUrl: healthUrl || undefined,}: { wsUrl }),apiUrl: process.env.NANOBOT_TUI_API_URL?.trim() || "",diff --git a/tui/src/protocol.test.ts b/tui/src/protocol.test.tsindex edb5c4e50..bb3d8412e 100644--- a/tui/src/protocol.test.ts+++ b/tui/src/protocol.test.ts@@ -3,14 +3,19 @@ import { describe, expect, test } from "bun:test"import {NanobotClient,GatewayConnectionError,+ connectionEndpoint,fetchAvailableSkills,fetchGatewayConnection,+ fetchGatewayHealth,fetchHistory,fetchMentionCandidates,fetchRuntimeControls,fetchSessionContext,fetchSessions,fetchSlashCommands,+ sanitizeConnectionFailure,+ type ConnectionStatus,+ type ConnectionStatusInfo,type InboundEvent,} from "./protocol"@@ -39,6 +44,12 @@ class FakeSocket {}}+async function waitUntil(predicate: () => boolean, timeout = 1_000): Promise<void> {+ const deadline = Date.now() + timeout+ while (!predicate() && Date.now() < deadline) await Bun.sleep(2)+ if (!predicate()) throw new Error(`condition was not met within ${timeout}ms`)+}+describe("gateway protocol", () => {test("bootstraps fresh websocket and API credentials", async () => {const original = globalThis.fetch@@ -70,6 +81,41 @@ describe("gateway protocol", () => {}})+ test("classifies gateway health without sending credentials", async () => {+ const original = globalThis.fetch+ const requests: Array<{ url: string; headers: Headers }> = []+ const responses = [+ new Response(JSON.stringify({+ status: "degraded",+ process: "alive",+ ready: false,+ websocket: "unavailable",+ }), { status: 503 }),+ new Response(JSON.stringify({+ status: "ok",+ process: "alive",+ ready: true,+ websocket: "running",+ })),+ new Response("not json"),+ ]+ globalThis.fetch = ((input: string | URL | Request, init?: RequestInit) => {+ requests.push({ url: String(input), headers: new Headers(init?.headers) })+ return Promise.resolve(responses.shift() || new Response("missing", { status: 500 }))+ }) as typeof fetch++ try {+ const healthUrl = "http://127.0.0.1:18790/health"+ expect(await fetchGatewayHealth(healthUrl)).toBe("degraded")+ expect(await fetchGatewayHealth(healthUrl)).toBe("ready")+ expect(await fetchGatewayHealth(healthUrl)).toBe("unreachable")+ expect(requests.map(({ url }) => url)).toEqual([healthUrl, healthUrl, healthUrl])+ expect(requests.every(({ headers }) => [...headers].length === 0)).toBe(true)+ } finally {+ globalThis.fetch = original+ }+ })+test("rejects malformed bootstrap responses without retrying", async () => {const original = globalThis.fetchglobalThis.fetch = (() => Promise.resolve(new Response("not json"))) as unknown as typeof fetch@@ -138,8 +184,13 @@ describe("gateway protocol", () => {try {const connections: string[] = []+ let healthChecks = 0const client = new NanobotClient({resolveConnection: () => new Promise((resolve) => { resolveConnection = resolve }),+ checkHealth: async () => {+ healthChecks += 1+ return "ready"+ },onConnection: (connection) => connections.push(connection.apiToken),onEvent: () => undefined,onStatus: () => undefined,@@ -155,6 +206,7 @@ describe("gateway protocol", () => {await Bun.sleep(1)expect(requestedUrl).toBe("ws://nanobot.test/ws?token=fresh")expect(connections).toEqual(["fresh-api-token"])+ expect(healthChecks).toBe(0)client.close()} finally {Object.defineProperty(globalThis, "WebSocket", { configurable: true, value: original })@@ -200,6 +252,133 @@ describe("gateway protocol", () => {}})+ test("escalates a refused bootstrap with safe endpoint and retry diagnostics", async () => {+ const original = globalThis.fetch+ const bootstrapUrl = "http://bootstrap-user:[email protected]:8769"+ + "/webui/bootstrap?token=socket-secret"+ const bootstrapSecret = "bootstrap-secret"+ const statuses: Array<{+ status: ConnectionStatus+ detail?: string+ info?: ConnectionStatusInfo+ }> = []+ const refused = new TypeError(+ `fetch failed for ${bootstrapUrl}&api_token=api-secret`,+ {+ cause: Object.assign(new Error("connect ECONNREFUSED 127.0.0.1:8769"), {+ code: "ECONNREFUSED",+ }),+ },+ )+ globalThis.fetch = (() => Promise.reject(refused)) as unknown as typeof fetch+ const client = new NanobotClient({+ resolveConnection: () => fetchGatewayConnection(+ bootstrapUrl,+ bootstrapSecret,+ "http://127.0.0.1:8769",+ "tui-42",+ ),+ targetEndpoint: connectionEndpoint(bootstrapUrl),+ checkHealth: async () => "degraded",+ startupFailureDelayMs: 8,+ reconnectDelayMs: 100,+ onEvent: () => undefined,+ onStatus: (status, detail, info) => statuses.push({ status, detail, info }),+ })++ try {+ client.connect()+ await waitUntil(() => statuses.some(({ status }) => status === "unavailable"))+ const failure = [...statuses].reverse().find(({ status }) => status === "unavailable")++ expect(statuses[0]?.status).toBe("starting")+ expect(failure?.detail).toBe("connection refused")+ expect(failure?.info).toMatchObject({+ endpoint: "127.0.0.1:8769",+ attempt: 1,+ elapsedMs: expect.any(Number),+ health: "degraded",+ })+ const visible = JSON.stringify(statuses)+ expect(visible).not.toContain("bootstrap-user")+ expect(visible).not.toContain("bootstrap-pass")+ expect(visible).not.toContain(bootstrapSecret)+ expect(visible).not.toContain("socket-secret")+ expect(visible).not.toContain("api-secret")+ expect(visible).not.toContain("/webui/bootstrap")+ } finally {+ client.close()+ globalThis.fetch = original+ }+ })++ test("recovers after sustained bootstrap failures without hiding the outage", async () => {+ const original = globalThis.WebSocket+ const sockets: FakeSocket[] = []+ let available = false+ let attempts = 0+ const statuses: ConnectionStatus[] = []+ Object.defineProperty(globalThis, "WebSocket", {+ configurable: true,+ value: class extends FakeSocket {+ constructor() {+ super()+ sockets.push(this)+ }+ },+ })+ const client = new NanobotClient({+ resolveConnection: async () => {+ attempts += 1+ if (!available) {+ throw Object.assign(new Error("connect ECONNREFUSED"), { code: "ECONNREFUSED" })+ }+ return {+ wsUrl: "ws://127.0.0.1:8769/ws?token=fresh",+ apiUrl: "http://127.0.0.1:8769",+ apiToken: "fresh-api-token",+ }+ },+ targetEndpoint: "127.0.0.1:8769",+ checkHealth: async () => available ? "ready" : "degraded",+ startupFailureDelayMs: 8,+ reconnectDelayMs: 2,+ startupRetryMaxDelayMs: 2,+ onEvent: () => undefined,+ onStatus: (status) => statuses.push(status),+ })++ try {+ client.connect()+ await waitUntil(() => statuses.includes("unavailable"))+ available = true+ await waitUntil(() => sockets.length === 1)+ sockets[0]?.emit("open")+ await waitUntil(() => statuses.at(-1) === "connected")++ expect(attempts).toBeGreaterThan(1)+ expect(statuses.indexOf("starting")).toBeLessThan(statuses.indexOf("unavailable"))+ expect(statuses.indexOf("unavailable")).toBeLessThan(statuses.lastIndexOf("connected"))+ } finally {+ client.close()+ Object.defineProperty(globalThis, "WebSocket", { configurable: true, value: original })+ }+ })++ test("sanitizes arbitrary connection errors and authenticated URLs", () => {+ const authenticated = "wss://user:[email protected]:8769/ws"+ + "?token=socket-secret&api_token=api-secret"+ const unknown = new Error(`could not reach ${authenticated}`)+ const refused = Object.assign(new Error(`ECONNREFUSED ${authenticated}`), {+ code: "ECONNREFUSED",+ })++ expect(connectionEndpoint(authenticated)).toBe("127.0.0.1:8769")+ expect(sanitizeConnectionFailure(unknown)).toBe("connection failed")+ expect(sanitizeConnectionFailure(refused)).toBe("connection refused")+ expect(sanitizeConnectionFailure(unknown)).not.toContain("socket-secret")+ })+test("reports a permanent bootstrap rejection without retrying", async () => {let attempts = 0const statuses: string[] = []@@ -588,13 +767,19 @@ describe("gateway protocol", () => {})try {+ const statuses: Array<{+ status: ConnectionStatus+ detail?: string+ info?: ConnectionStatusInfo+ }> = []const client = new NanobotClient({url: "ws://nanobot.test/ws",reconnectDelayMs: 1,onEvent: () => undefined,- onStatus: () => undefined,+ onStatus: (status, detail, info) => statuses.push({ status, detail, info }),})client.connect()+ sockets[0]?.emit("open")sockets[0]?.emit("message", {data: JSON.stringify({ event: "ready", chat_id: "", client_id: "client" }),})@@ -605,11 +790,21 @@ describe("gateway protocol", () => {await Bun.sleep(5)expect(sockets).toHaveLength(2)+ const reconnecting = [...statuses].reverse().find(+ ({ status }) => status === "reconnecting",+ )+ expect(reconnecting).toMatchObject({+ status: "reconnecting",+ detail: "connection closed",+ info: { endpoint: "nanobot.test", attempt: 1 },+ })+ sockets[1]?.emit("open")sockets[1]?.emit("message", {data: JSON.stringify({ event: "ready", chat_id: "", client_id: "client-2" }),})const outbound = sockets[1]?.sent.map((value) => JSON.parse(value)) || []expect(outbound).toEqual([{ type: "attach", chat_id: "generated-chat" }])+ expect(statuses.at(-1)?.status).toBe("connected")client.close()} finally {Object.defineProperty(globalThis, "WebSocket", { configurable: true, value: original })diff --git a/tui/src/protocol.ts b/tui/src/protocol.tsindex de5e6c0b1..f895e9515 100644--- a/tui/src/protocol.ts+++ b/tui/src/protocol.ts@@ -1,4 +1,21 @@-export type ConnectionStatus = "connecting" | "connected" | "closed" | "error"+export type ConnectionStatus =+ | "starting"+ | "connecting"+ | "connected"+ | "reconnecting"+ | "unavailable"+ | "closed"+ | "error"++export interface ConnectionStatusInfo {+ endpoint: string+ attempt: number+ elapsedMs: number+ retryInMs?: number+ health?: GatewayHealthStatus+}++export type GatewayHealthStatus = "ready" | "degraded" | "unreachable"export interface ToolProgressEvent {version?: number@@ -172,14 +189,16 @@ type OutboundEvent =export interface ClientOptions {url?: stringresolveConnection?: () => Promise<GatewayConnection>+ checkHealth?: () => Promise<GatewayHealthStatus>onConnection?: (connection: GatewayConnection) => void- connectionRetryLabel?: string+ targetEndpoint?: string+ startupFailureDelayMs?: numberstartupRetryMaxDelayMs?: numberchatId?: stringinitialWorkspaceScope?: WorkspaceScopePayloadreconnectDelayMs?: numberonEvent: (event: InboundEvent) => void- onStatus: (status: ConnectionStatus, detail?: string) => void+ onStatus: (status: ConnectionStatus, detail?: string, info?: ConnectionStatusInfo) => void}export interface GatewayApiConnection {@@ -940,6 +959,92 @@ export async function fetchGatewayConnection(}}+/** Read gateway readiness without sending bootstrap or API credentials. */+export async function fetchGatewayHealth(+ healthUrl: string,+ timeoutMs = 400,+): Promise<GatewayHealthStatus> {+ const controller = new AbortController()+ const timer = setTimeout(() => controller.abort(), timeoutMs)+ try {+ const response = await fetch(healthUrl, { signal: controller.signal })+ if (response.status !== 200 && response.status !== 503) return "unreachable"+ const payload: unknown = await response.json()+ if (!isRecord(payload)) return "unreachable"+ if (+ response.status === 503+ && payload.status === "degraded"+ && payload.ready === false+ && payload.process === "alive"+ ) return "degraded"+ if (response.status === 200 && payload.status === "ok" && payload.ready !== false) {+ return "ready"+ }+ return "unreachable"+ } catch {+ return "unreachable"+ } finally {+ clearTimeout(timer)+ }+}++/** Return only the authority users can act on, never credentials or an authenticated path. */+export function connectionEndpoint(value: string | undefined): string {+ if (!value) return "local gateway"+ try {+ return new URL(value).host || "local gateway"+ } catch {+ return "local gateway"+ }+}++/** Reduce arbitrary fetch/WebSocket errors to a small set of credential-safe reasons. */+export function sanitizeConnectionFailure(error: unknown): string {+ const signals: string[] = []+ const seen = new Set<unknown>()+ const collect = (value: unknown): void => {+ if (value === null || value === undefined || seen.has(value)) return+ if (typeof value === "object") seen.add(value)+ if (typeof value === "string") {+ signals.push(value)+ return+ }+ if (value instanceof Error) {+ signals.push(value.name, value.message)+ collect(value.cause)+ if (value instanceof AggregateError) {+ for (const nested of value.errors) collect(nested)+ }+ return+ }+ if (!isRecord(value)) return+ if (typeof value.code === "string") signals.push(value.code)+ collect(value.cause)+ if (Array.isArray(value.errors)) {+ for (const nested of value.errors) collect(nested)+ }+ }+ collect(error)+ const signal = signals.join(" ")+ if (/ECONNREFUSED|connection refused/iu.test(signal)) return "connection refused"+ if (/ETIMEDOUT|timed? out|timeout/iu.test(signal)) return "connection timed out"+ if (/ENOTFOUND|EAI_AGAIN|name not resolved|host not found/iu.test(signal)) {+ return "host not found"+ }+ if (/certificate|TLS|SSL/iu.test(signal)) return "secure connection failed"+ const bootstrapStatus = signal.match(/gateway bootstrap failed:\s*HTTP\s*(\d{3})/iu)+ if (bootstrapStatus?.[1]) return `gateway bootstrap failed: HTTP ${bootstrapStatus[1]}`+ if (/bootstrap response is missing ws_url/iu.test(signal)) {+ return "gateway bootstrap response is missing ws_url"+ }+ if (/bootstrap response (?:has an invalid ws_url|is invalid)/iu.test(signal)) {+ return "gateway bootstrap response is invalid"+ }+ if (/gateway is still starting/iu.test(signal)) return "gateway is still starting"+ if (/fetch failed|failed to fetch|network error/iu.test(signal)) return "network request failed"+ return "connection failed"+}+export class NanobotClient {private socket: WebSocket | null = nullprivate chatId = ""@@ -949,13 +1054,22 @@ export class NanobotClient {private closedByClient = falseprivate opening = falseprivate connectedOnce = false+ private connectionAttempt = 0+ private retryStartedAt = 0+ private nextRetryAt = 0+ private lastFailure = ""+ private healthStatus: GatewayHealthStatus | undefined+ private failureEscalationTimer: ReturnType<typeof setTimeout> | null = null+ private readonly endpoint: stringprivate readonly pendingMutations = new Map<string, {resolve: (value: unknown) => voidreject: (error: Error) => voidtimer: ReturnType<typeof setTimeout>}>()- constructor(private readonly options: ClientOptions) {}+ constructor(private readonly options: ClientOptions) {+ this.endpoint = options.targetEndpoint || connectionEndpoint(options.url)+ }get activeChatId(): string {return this.chatId@@ -963,13 +1077,21 @@ export class NanobotClient {connect(): void {this.closedByClient = false+ this.connectionAttempt = 0+ this.reconnectAttempt = 0+ this.retryStartedAt = Date.now()+ this.nextRetryAt = 0+ this.lastFailure = ""+ this.healthStatus = undefinedvoid this.open()}private async open(): Promise<void> {if (this.socket || this.opening || this.closedByClient) returnthis.opening = true- this.options.onStatus("connecting")+ this.nextRetryAt = 0+ this.connectionAttempt += 1+ this.reportConnectionProgress()let url = this.options.urltry {if (this.options.resolveConnection) {@@ -980,37 +1102,52 @@ export class NanobotClient {}} catch (error) {if (!this.closedByClient) {+ this.lastFailure = sanitizeConnectionFailure(error)if (error instanceof GatewayConnectionError && !error.retryable) {- this.options.onStatus("error", error.message)+ this.clearFailureEscalation()+ this.options.onStatus("error", this.lastFailure, this.connectionInfo())return}- this.options.onStatus(- "connecting",- this.options.connectionRetryLabel || "gateway unavailable",- )- this.scheduleReconnect(false)+ await this.checkHealthAndScheduleReconnect()}return} finally {this.opening = false}if (!url) {- this.options.onStatus("error", "gateway URL is not configured")+ this.options.onStatus("error", "gateway URL is not configured", this.connectionInfo())return}- const socket = new WebSocket(url)+ let socket: WebSocket+ try {+ socket = new WebSocket(url)+ } catch (error) {+ this.lastFailure = sanitizeConnectionFailure(error)+ await this.checkHealthAndScheduleReconnect()+ return+ }+ let opened = falsethis.socket = socketsocket.addEventListener("open", () => {if (this.socket !== socket) return+ opened = truethis.connectedOnce = true+ this.connectionAttempt = 0this.reconnectAttempt = 0- this.options.onStatus("connected")+ this.retryStartedAt = 0+ this.nextRetryAt = 0+ this.lastFailure = ""+ this.healthStatus = "ready"+ this.clearFailureEscalation()+ this.options.onStatus("connected", undefined, this.connectionInfo())})socket.addEventListener("message", (message) => {if (this.socket === socket) this.handleMessage(String(message.data))})socket.addEventListener("error", () => {- if (this.socket === socket) this.options.onStatus("error", "connection failed")+ if (this.socket !== socket) return+ this.lastFailure = "connection failed"+ this.reportRetryState()})socket.addEventListener("close", () => {if (this.socket !== socket) return@@ -1020,7 +1157,14 @@ export class NanobotClient {this.options.onStatus("closed")return}- this.scheduleReconnect()+ if (opened) {+ this.connectionAttempt = 0+ this.reconnectAttempt = 0+ this.retryStartedAt = Date.now()+ }+ if (!this.lastFailure) this.lastFailure = "connection closed"+ this.reportRetryState()+ void this.checkHealthAndScheduleReconnect()})}@@ -1028,6 +1172,7 @@ export class NanobotClient {this.closedByClient = trueif (this.reconnectTimer) clearTimeout(this.reconnectTimer)this.reconnectTimer = null+ this.clearFailureEscalation()const socket = this.socketthis.socket = nullsocket?.close()@@ -1182,20 +1327,80 @@ export class NanobotClient {this.options.onEvent(event)}- private scheduleReconnect(announce = true): void {+ private scheduleReconnect(): void {if (this.reconnectTimer || this.closedByClient) return+ if (!this.retryStartedAt) this.retryStartedAt = Date.now()const base = this.options.reconnectDelayMs ?? 500const maxDelay = this.connectedOnce? 8_000: this.options.startupRetryMaxDelayMs ?? 8_000const delay = Math.min(maxDelay, base * 2 ** Math.min(this.reconnectAttempt++, 4))- if (announce) this.options.onStatus("connecting", `reconnecting in ${delay}ms`)+ this.nextRetryAt = Date.now() + delay+ this.reportRetryState()this.reconnectTimer = setTimeout(() => {this.reconnectTimer = nullvoid this.open()}, delay)}+ private async checkHealthAndScheduleReconnect(): Promise<void> {+ if (this.options.checkHealth) {+ try {+ this.healthStatus = await this.options.checkHealth()+ } catch {+ this.healthStatus = "unreachable"+ }+ }+ if (!this.closedByClient) this.scheduleReconnect()+ }++ private connectionInfo(): ConnectionStatusInfo {+ return {+ endpoint: this.endpoint,+ attempt: Math.max(1, this.connectionAttempt),+ elapsedMs: this.retryStartedAt ? Math.max(0, Date.now() - this.retryStartedAt) : 0,+ ...(this.nextRetryAt+ ? { retryInMs: Math.max(0, this.nextRetryAt - Date.now()) }+ : {}),+ ...(this.healthStatus ? { health: this.healthStatus } : {}),+ }+ }++ private reportConnectionProgress(): void {+ if (this.connectedOnce) {+ this.options.onStatus("reconnecting", this.lastFailure || undefined, this.connectionInfo())+ return+ }+ const phase = this.options.resolveConnection ? "starting" : "connecting"+ this.options.onStatus(phase, undefined, this.connectionInfo())+ }++ private reportRetryState(): void {+ const info = this.connectionInfo()+ if (this.connectedOnce) {+ this.options.onStatus("reconnecting", this.lastFailure, info)+ return+ }+ const failureDelay = this.options.startupFailureDelayMs ?? 3_000+ if (info.elapsedMs >= failureDelay) {+ this.clearFailureEscalation()+ this.options.onStatus("unavailable", this.lastFailure, info)+ return+ }+ this.reportConnectionProgress()+ if (this.failureEscalationTimer) return+ this.failureEscalationTimer = setTimeout(() => {+ this.failureEscalationTimer = null+ if (this.closedByClient || this.connectedOnce || !this.lastFailure) return+ this.options.onStatus("unavailable", this.lastFailure, this.connectionInfo())+ }, Math.max(0, failureDelay - info.elapsedMs))+ }++ private clearFailureEscalation(): void {+ if (this.failureEscalationTimer) clearTimeout(this.failureEscalationTimer)+ this.failureEscalationTimer = null+ }+private write(event: OutboundEvent): void {if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {throw new Error("gateway connection is not open")