From 337de9b078d616f19acdc023c6fff278a61abf5d Mon Sep 17 00:00:00 2001
From: Cristina Poncela Cubeiro
 <140309543+cristinaponcela@users.noreply.github.com>
Date: Thu, 18 Jun 2026 15:59:32 +0200
Subject: [PATCH] fix: RPC parity, UX polish, logging

---
 packages/orchestrator/src/cli.ts        | 20 ++++++++----
 packages/orchestrator/src/radius.ts     | 42 ++++++++++++++++++++-----
 packages/orchestrator/src/rpc-bridge.ts | 14 +++++----
 3 files changed, 56 insertions(+), 20 deletions(-)

diff --git a/packages/orchestrator/src/cli.ts b/packages/orchestrator/src/cli.ts
index bb763730..674376e4 100644
--- a/packages/orchestrator/src/cli.ts
+++ b/packages/orchestrator/src/cli.ts
@@ -18,7 +18,7 @@ const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"),
 
 function printHelp(): void {
 	console.log(
-		`orchestrator v${packageJson.version}\n\nUsage:\n  orchestrator serve\n  orchestrator list\n  orchestrator spawn [--cwd <path>] [--label <label>]\n  orchestrator status <instance-id>\n  orchestrator stop <instance-id>\n  orchestrator rpc <instance-id> <json-command>\n  orchestrator attach <instance-id>\n  orchestrator --help\n  orchestrator --version`,
+		`orchestrator v${packageJson.version}\n\nUsage:\n  orchestrator serve\n  orchestrator list\n  orchestrator spawn [--cwd <path>] [--label <label>]\n  orchestrator status <instance-id>\n  orchestrator stop <instance-id>\n  orchestrator rpc <instance-id> <json-command>\n  orchestrator attach <instance-id>\n  orchestrator --help\n  orchestrator --version\n\nAttach stdin expects JSONL RpcCommand or extension_ui_response messages.`,
 	);
 }
 
@@ -36,6 +36,7 @@ function getFlagValue(args: string[], flag: string): string | undefined {
 
 async function attach(instanceId: string): Promise<void> {
 	const socket = createConnection(getSocketPath());
+	let stdinBuffer = "";
 	process.stdin.setEncoding("utf8");
 
 	await new Promise<void>((resolve, reject) => {
@@ -49,6 +50,7 @@ async function attach(instanceId: string): Promise<void> {
 	socket.on("data", (chunk: Buffer | string) => {
 		process.stdout.write(chunk.toString());
 	});
+	console.error(`attached to ${instanceId}; send JSONL RpcCommand or extension_ui_response on stdin`);
 	socket.on("error", (error) => {
 		console.error(error instanceof Error ? error.message : String(error));
 		process.exit(1);
@@ -57,11 +59,17 @@ async function attach(instanceId: string): Promise<void> {
 		process.exit(0);
 	});
 	process.stdin.on("data", (chunk: string) => {
-		const lines = chunk
-			.split("\n")
-			.map((line) => line.trim())
-			.filter((line) => line.length > 0);
-		for (const line of lines) {
+		stdinBuffer += chunk;
+		while (true) {
+			const newlineIndex = stdinBuffer.indexOf("\n");
+			if (newlineIndex === -1) {
+				return;
+			}
+			const line = stdinBuffer.slice(0, newlineIndex).trim();
+			stdinBuffer = stdinBuffer.slice(newlineIndex + 1);
+			if (!line) {
+				continue;
+			}
 			const parsed = JSON.parse(line) as RpcCommand | RpcExtensionUIResponse;
 			if (parsed.type === "extension_ui_response") {
 				socket.write(encodeMessage(parsed));
diff --git a/packages/orchestrator/src/radius.ts b/packages/orchestrator/src/radius.ts
index 71d39922..cb503fab 100644
--- a/packages/orchestrator/src/radius.ts
+++ b/packages/orchestrator/src/radius.ts
@@ -88,6 +88,22 @@ function computeBackoffDelayMs(failureCount: number): number {
 	return Math.min(HEARTBEAT_BACKOFF_MAX_MS, exponentialDelay + jitterMs);
 }
 
+function formatRadiusError(error: unknown): string {
+	if (error instanceof RadiusHttpError) {
+		return `HTTP ${error.status}: ${error.message}`;
+	}
+	if (error instanceof Error) {
+		return error.message;
+	}
+	return String(error);
+}
+
+function logRadiusRetry(scope: string, action: string, delayMs: number, failureCount: number, error: unknown): void {
+	console.error(
+		`${scope} ${action} failed (attempt ${failureCount}); retrying in ${delayMs}ms: ${formatRadiusError(error)}`,
+	);
+}
+
 export function getRadiusUrl(): string {
 	return process.env.PI_RADIUS_URL || DEFAULT_RADIUS_URL;
 }
@@ -295,7 +311,7 @@ export class RadiusPresence {
 			if (!isNotFoundError(error)) {
 				this.machineTransientFailureCount += 1;
 				const delayMs = computeBackoffDelayMs(this.machineTransientFailureCount);
-				console.error(`Radius machine heartbeat failed; retrying in ${delayMs}ms`, error);
+				logRadiusRetry("Radius machine", "heartbeat", delayMs, this.machineTransientFailureCount, error);
 				this.scheduleMachineHeartbeat(delayMs);
 				return;
 			}
@@ -312,7 +328,13 @@ export class RadiusPresence {
 			} catch (recoveryError) {
 				this.machineTransientFailureCount += 1;
 				const delayMs = computeBackoffDelayMs(this.machineTransientFailureCount);
-				console.error(`Radius machine re-registration failed; retrying in ${delayMs}ms`, recoveryError);
+				logRadiusRetry(
+					"Radius machine",
+					"re-registration",
+					delayMs,
+					this.machineTransientFailureCount,
+					recoveryError,
+				);
 				this.scheduleMachineHeartbeat(delayMs);
 			}
 		}
@@ -337,7 +359,7 @@ export class RadiusPresence {
 			if (!isNotFoundError(error)) {
 				state.transientFailureCount += 1;
 				const delayMs = computeBackoffDelayMs(state.transientFailureCount);
-				console.error(`Radius Pi heartbeat failed for instance ${instanceId}; retrying in ${delayMs}ms`, error);
+				logRadiusRetry(`Radius Pi ${instanceId}`, "heartbeat", delayMs, state.transientFailureCount, error);
 				this.schedulePiHeartbeat(instanceId, delayMs);
 				return;
 			}
@@ -352,14 +374,18 @@ export class RadiusPresence {
 			try {
 				const recovered = await this.reRegisterPi(instanceId);
 				if (!recovered) {
-					console.error(`Radius Pi re-registration skipped for instance ${instanceId}`);
-					this.schedulePiHeartbeat(instanceId, computeBackoffDelayMs(1));
+					const delayMs = computeBackoffDelayMs(1);
+					console.error(`Radius Pi ${instanceId} re-registration skipped; retrying in ${delayMs}ms`);
+					this.schedulePiHeartbeat(instanceId, delayMs);
 				}
 			} catch (recoveryError) {
 				state.transientFailureCount += 1;
 				const delayMs = computeBackoffDelayMs(state.transientFailureCount);
-				console.error(
-					`Radius Pi re-registration failed for instance ${instanceId}; retrying in ${delayMs}ms`,
+				logRadiusRetry(
+					`Radius Pi ${instanceId}`,
+					"re-registration",
+					delayMs,
+					state.transientFailureCount,
 					recoveryError,
 				);
 				this.schedulePiHeartbeat(instanceId, delayMs);
@@ -376,7 +402,7 @@ export class RadiusPresence {
 			try {
 				await this.reRegisterPi(instance.id);
 			} catch (error) {
-				console.error(`Radius Pi re-registration failed for instance ${instance.id}`, error);
+				console.error(`Radius Pi ${instance.id} re-registration failed: ${formatRadiusError(error)}`);
 			}
 		}
 	}
diff --git a/packages/orchestrator/src/rpc-bridge.ts b/packages/orchestrator/src/rpc-bridge.ts
index 4f549c10..7a6cfa8d 100644
--- a/packages/orchestrator/src/rpc-bridge.ts
+++ b/packages/orchestrator/src/rpc-bridge.ts
@@ -11,6 +11,10 @@ function error(id: string | undefined, command: string, message: string): RpcRes
 	return { id, type: "response", command, success: false, error: message };
 }
 
+function assertNeverRpcCommand(command: never): never {
+	throw new Error(`Unknown command: ${(command as { type: string }).type}`);
+}
+
 export async function handleRpcCommand(runtime: AgentSessionRuntime, command: RpcCommand): Promise<RpcResponse> {
 	const session = runtime.session;
 	const id = command.id;
@@ -68,7 +72,7 @@ export async function handleRpcCommand(runtime: AgentSessionRuntime, command: Rp
 
 		case "fork": {
 			const result = await runtime.fork(command.entryId);
-			return success(id, "fork", { text: result.selectedText ?? "", cancelled: result.cancelled });
+			return success(id, "fork", { text: result.selectedText, cancelled: result.cancelled });
 		}
 
 		case "clone": {
@@ -186,7 +190,7 @@ export async function handleRpcCommand(runtime: AgentSessionRuntime, command: Rp
 		}
 
 		case "get_last_assistant_text": {
-			const text = session.getLastAssistantText() ?? null;
+			const text = session.getLastAssistantText();
 			return success(id, "get_last_assistant_text", { text });
 		}
 
@@ -236,9 +240,7 @@ export async function handleRpcCommand(runtime: AgentSessionRuntime, command: Rp
 			return success(id, "get_commands", { commands });
 		}
 
-		default: {
-			const unknownCommand = command as { type: string };
-			return error(id, unknownCommand.type, `Unknown command: ${unknownCommand.type}`);
-		}
+		default:
+			return assertNeverRpcCommand(command);
 	}
 }