fix(gateway): add WebSocket auto-reconnect and RPC retry logic

WebSocket connections now automatically reconnect with exponential
backoff on unexpected disconnects, and syncHistory catches up on
missed events. RPC calls retry transient network errors (up to 2
attempts) while immediately surfacing auth/business errors via
NonRetryableError. Also replaces the example teach skill with the
latest teach output and updates all references.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: s-JoL

README.md

@@ -113,7 +113,7 @@ Teach a task by demonstrating it once. Understudy learns the **intent**, not the
 
 > *Demo flow: search for a photo → open in Pixelmator Pro → remove background → send via Telegram. Taught once, replayed autonomously.*
 
-> *The published skill artifact from this demo is available at [examples/published-skills/taught-person-photo-cutout-bc88ec/SKILL.md](./examples/published-skills/taught-person-photo-cutout-bc88ec/SKILL.md).*
+> *The published skill artifact from this demo is available at [examples/published-skills/taught-create-a-background-removed-portrait-for-a-requested-person-and-send-it-in-telegram-cd861a/SKILL.md](./examples/published-skills/taught-create-a-background-removed-portrait-for-a-requested-person-and-send-it-in-telegram-cd861a/SKILL.md).*
 
 ### Example Workspaces
 
@@ -172,7 +172,7 @@ The published SKILL.md is a three-layer abstraction: intent procedure (natural l
 
 The draft/publish pipeline is no longer limited to one artifact shape. The current schema can publish `skill`, `worker`, and `playbook` workspace artifacts, although teach-by-demonstration most commonly produces reusable skills today.
 
-A real published output example is available at [examples/published-skills/taught-person-photo-cutout-bc88ec/SKILL.md](./examples/published-skills/taught-person-photo-cutout-bc88ec/SKILL.md). It is kept under `examples/` on purpose, so the repo documents the artifact format without auto-loading it as a real workspace skill.
+A real published output example is available at [examples/published-skills/taught-create-a-background-removed-portrait-for-a-requested-person-and-send-it-in-telegram-cd861a/SKILL.md](./examples/published-skills/taught-create-a-background-removed-portrait-for-a-requested-person-and-send-it-in-telegram-cd861a/SKILL.md). It is kept under `examples/` on purpose, so the repo documents the artifact format without auto-loading it as a real workspace skill.
 
 For the full teach pipeline, evidence pack construction, and validation details, see [Product Design](./docs/Product_Design.md).
 

README.zh-CN.md

@@ -113,7 +113,7 @@ Understudy 使用你已有的消息应用：Telegram、Discord、Slack、WhatsAp
 
 > *演示流程：搜索照片 → 在 Pixelmator Pro 中打开 → 去除背景 → 通过 Telegram 发送。教一次，自主重放。*
 
-> *此演示生成的已发布 skill 产物：[examples/published-skills/taught-person-photo-cutout-bc88ec/SKILL.md](./examples/published-skills/taught-person-photo-cutout-bc88ec/SKILL.md)。*
+> *此演示生成的已发布 skill 产物：[examples/published-skills/taught-create-a-background-removed-portrait-for-a-requested-person-and-send-it-in-telegram-cd861a/SKILL.md](./examples/published-skills/taught-create-a-background-removed-portrait-for-a-requested-person-and-send-it-in-telegram-cd861a/SKILL.md)。*
 
 ### 示例工作区
 
@@ -172,7 +172,7 @@ Planner 决定每一步使用哪条路线。一个任务可能浏览网站、运
 
 Draft / publish 管线现在也不只支持一种产物。当前 schema 可以发布 `skill`、`worker` 和 `playbook` 这几类 workspace artifact，不过演示教学最常见的产物仍然是可复用 skill。
 
-仓库里放了一个真实发布产物示例：[examples/published-skills/taught-person-photo-cutout-bc88ec/SKILL.md](./examples/published-skills/taught-person-photo-cutout-bc88ec/SKILL.md)。它故意放在 `examples/` 下，只用于展示产物格式，不会被当成真正的 workspace skill 自动加载。
+仓库里放了一个真实发布产物示例：[examples/published-skills/taught-create-a-background-removed-portrait-for-a-requested-person-and-send-it-in-telegram-cd861a/SKILL.md](./examples/published-skills/taught-create-a-background-removed-portrait-for-a-requested-person-and-send-it-in-telegram-cd861a/SKILL.md)。它故意放在 `examples/` 下，只用于展示产物格式，不会被当成真正的 workspace skill 自动加载。
 
 完整的 teach 管线、证据包构建和验证细节见 [产品设计](./docs/Product_Design.zh-CN.md)。
 

apps/cli/src/commands/chat-gateway-session.ts

@@ -945,6 +945,8 @@ export async function createGatewayBackedInteractiveSession(
 	};
 
 	const close = async () => {
+		wsIntentionallyClosed = true;
+		if (wsReconnectTimer) clearTimeout(wsReconnectTimer);
 		gatewayState.isStreaming = false;
 		gatewayState.currentTurn = undefined;
 		gatewayState.socket?.removeAllListeners();
@@ -1291,6 +1293,10 @@ export async function createGatewayBackedInteractiveSession(
 		getGatewaySessionId: () => string | undefined;
 	};
 
+	let wsIntentionallyClosed = false;
+	let wsReconnectAttempt = 0;
+	let wsReconnectTimer: ReturnType<typeof setTimeout> | undefined;
+
 	const connectEventStream = () => {
 		const socketUrl = buildGatewaySocketUrl(
 			options.gatewayUrl,
@@ -1299,6 +1305,24 @@ export async function createGatewayBackedInteractiveSession(
 		try {
 			const socket = new WebSocket(socketUrl);
 			gatewayState.socket = socket;
+
+			socket.on("open", () => {
+				wsReconnectAttempt = 0;
+				// Catch up on any events missed while disconnected.
+				syncHistory().catch(() => {});
+			});
+
+			socket.on("close", () => {
+				if (wsIntentionallyClosed) return;
+				scheduleReconnect();
+			});
+
+			socket.on("error", () => {
+				// The "close" event always follows "error", so reconnect
+				// is handled there. Just make sure the socket is cleaned up.
+				try { socket.close(); } catch { /* already closing */ }
+			});
+
 			socket.on("message", (raw) => {
 				try {
 					const parsed = JSON.parse(raw.toString()) as { type?: string; data?: Record<string, unknown> };
@@ -1387,9 +1411,21 @@ export async function createGatewayBackedInteractiveSession(
 			});
 		} catch {
 			gatewayState.socket = null;
+			if (!wsIntentionallyClosed) scheduleReconnect();
 		}
 	};
 
+	const scheduleReconnect = () => {
+		if (wsIntentionallyClosed) return;
+		if (wsReconnectTimer) clearTimeout(wsReconnectTimer);
+		// Exponential backoff: 1s, 2s, 4s, capped at 10s.
+		const delay = Math.min(1000 * Math.pow(2, wsReconnectAttempt), 10_000);
+		wsReconnectAttempt++;
+		wsReconnectTimer = setTimeout(() => {
+			if (!wsIntentionallyClosed) connectEventStream();
+		}, delay);
+	};
+
 	try {
 		releaseSessionManagerOverride = registerGatewaySessionManagerOverride({
 			list: async (cwd, _sessionDir, onProgress) =>

apps/cli/src/rpc-client.ts

@@ -14,6 +14,8 @@ export interface RpcClientOptions {
 
 export interface RpcCallOptions {
 	timeout?: number;
+	/** Max retry attempts on transient network errors (default: 2). */
+	retries?: number;
 }
 
 export class GatewayRpcClient {
@@ -40,64 +42,95 @@ export class GatewayRpcClient {
 		params: Record<string, unknown> = {},
 		options: RpcCallOptions = {},
 	): Promise<T> {
-		const id = randomUUID();
-		const headers: Record<string, string> = { "Content-Type": "application/json" };
-		if (this.token) {
-			headers["Authorization"] = `Bearer ${this.token}`;
-		}
+		const maxRetries = options.retries ?? 2;
+		let lastError: unknown;
 
-		const controller = new AbortController();
-		const timeoutMs = options.timeout ?? this.timeout;
-		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		for (let attempt = 0; attempt <= maxRetries; attempt++) {
+			const id = randomUUID();
+			const headers: Record<string, string> = { "Content-Type": "application/json" };
+			if (this.token) {
+				headers["Authorization"] = `Bearer ${this.token}`;
+			}
 
-		try {
-			const response = await fetch(`${this.baseUrl}/rpc`, {
-				method: "POST",
-				headers,
-				body: JSON.stringify({ id, method, params }),
-				signal: controller.signal,
-			});
+			const controller = new AbortController();
+			const timeoutMs = options.timeout ?? this.timeout;
+			const timer = setTimeout(() => controller.abort(), timeoutMs);
 
-			if (response.status === 401) {
-				throw new Error("Authentication failed. Check UNDERSTUDY_GATEWAY_TOKEN or --token.");
-			}
-			if (response.status === 429) {
-				throw new Error("Rate limited. Try again later.");
-			}
-			if (!response.ok) {
-				throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-			}
+			try {
+				const response = await fetch(`${this.baseUrl}/rpc`, {
+					method: "POST",
+					headers,
+					body: JSON.stringify({ id, method, params }),
+					signal: controller.signal,
+				});
+
+				if (response.status === 401) {
+					throw new NonRetryableError("Authentication failed. Check UNDERSTUDY_GATEWAY_TOKEN or --token.");
+				}
+				if (response.status === 429) {
+					throw new NonRetryableError("Rate limited. Try again later.");
+				}
+				if (!response.ok) {
+					throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+				}
 
-			const result = await response.json() as { id: string; result?: T; error?: { code: number; message: string } };
-			if (result.error) {
-				throw new Error(`RPC error ${result.error.code}: ${result.error.message}`);
+				const result = await response.json() as { id: string; result?: T; error?: { code: number; message: string } };
+				if (result.error) {
+					throw new NonRetryableError(`RPC error ${result.error.code}: ${result.error.message}`);
+				}
+				return result.result as T;
+			} catch (error) {
+				if (error instanceof NonRetryableError) throw error;
+				lastError = error;
+				if (attempt < maxRetries) {
+					await sleep(1000 * (attempt + 1));
+				}
+			} finally {
+				clearTimeout(timer);
 			}
-			return result.result as T;
-		} finally {
-			clearTimeout(timer);
 		}
+		throw lastError;
 	}
 
 	/** Fetch the health endpoint */
 	async health(): Promise<Record<string, unknown>> {
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), this.timeout);
-		try {
-			const response = await fetch(`${this.baseUrl}/health`, { signal: controller.signal });
-			if (!response.ok) {
-				throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+		return this.fetchWithRetry(`${this.baseUrl}/health`);
+	}
+
+	private async fetchWithRetry<T>(url: string, retries = 2): Promise<T> {
+		let lastError: unknown;
+		for (let attempt = 0; attempt <= retries; attempt++) {
+			const controller = new AbortController();
+			const timer = setTimeout(() => controller.abort(), this.timeout);
+			try {
+				const response = await fetch(url, { signal: controller.signal });
+				if (!response.ok) {
+					throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+				}
+				return await response.json() as T;
+			} catch (error) {
+				lastError = error;
+				if (attempt < retries) {
+					await sleep(1000 * (attempt + 1));
+				}
+			} finally {
+				clearTimeout(timer);
 			}
-			return await response.json() as Record<string, unknown>;
-		} finally {
-			clearTimeout(timer);
 		}
+		throw lastError;
 	}
 
 	get url(): string {
 		return this.baseUrl;
 	}
 }
 
+class NonRetryableError extends Error {}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 /** Create an RPC client with default config/env settings */
 export function createRpcClient(options?: RpcClientOptions): GatewayRpcClient {
 	const port = options?.port ?? parseInt(process.env.UNDERSTUDY_GATEWAY_PORT ?? "23333", 10);

docs/index.html

@@ -1100,7 +1100,7 @@ <h3>Show once, publish, replay later</h3>
                 Video has been sped up. Full-length original:
                 <a href="https://drive.google.com/file/d/1VJfodHJD_RSnb8g_vj2bId48tu_1vwHK/view?usp=sharing" target="_blank" rel="noreferrer">Google Drive</a>.
                 Published skill artifact:
-                <a href="https://github.com/understudy-ai/understudy/blob/main/examples/published-skills/taught-person-photo-cutout-bc88ec/SKILL.md" target="_blank" rel="noreferrer">SKILL.md</a>.
+                <a href="https://github.com/understudy-ai/understudy/blob/main/examples/published-skills/taught-create-a-background-removed-portrait-for-a-requested-person-and-send-it-in-telegram-cd861a/SKILL.md" target="_blank" rel="noreferrer">SKILL.md</a>.
               </div>
             </div>
 

docs/zh-CN/index.html

@@ -1100,7 +1100,7 @@ <h3>演示一次，发布后再重放</h3>
                 以上视频经过加速。完整原速视频：
                 <a href="https://drive.google.com/file/d/1VJfodHJD_RSnb8g_vj2bId48tu_1vwHK/view?usp=sharing" target="_blank" rel="noreferrer">Google Drive</a>。
                 已发布的技能产物：
-                <a href="https://github.com/understudy-ai/understudy/blob/main/examples/published-skills/taught-person-photo-cutout-bc88ec/SKILL.md" target="_blank" rel="noreferrer">SKILL.md</a>。
+                <a href="https://github.com/understudy-ai/understudy/blob/main/examples/published-skills/taught-create-a-background-removed-portrait-for-a-requested-person-and-send-it-in-telegram-cd861a/SKILL.md" target="_blank" rel="noreferrer">SKILL.md</a>。
               </div>
             </div>
 

examples/demo-teach/README.md

@@ -20,7 +20,7 @@ Demonstrates Understudy's distinctive learn-from-demonstration stack: teach once
 ## Published Skill Example
 
 The published SKILL.md from this demo is available at:
-[`../published-skills/taught-person-photo-cutout-bc88ec/SKILL.md`](../published-skills/taught-person-photo-cutout-bc88ec/SKILL.md)
+[`../published-skills/taught-create-a-background-removed-portrait-for-a-requested-person-and-send-it-in-telegram-cd861a/SKILL.md`](../published-skills/taught-create-a-background-removed-portrait-for-a-requested-person-and-send-it-in-telegram-cd861a/SKILL.md)
 
 ## Prerequisites