@sjhmars/happy-bridge 0.2.4 → 0.3.0

package/README.md

@@ -1,5 +1,7 @@
 # @sjhmars/happy-bridge
 
+> **Remote-control bridge for the Happy mobile app.** Pair an already-running `dsh web` / DeepSeek Harness desktop client with [Happy App](https://github.com/slopus/happy) by scanning a QR code, then remote-control the **same harness sessions** from your phone over the Happy encrypted relay: send messages and images, read replies, approve tool calls / plan reviews / questions, stop a running turn, and switch models. Four grant levels: `watch` / `chat` / `approve` / `full`. "Bridge" here means the remote-control link between desktop harness and phone — not a card game.
+
 电脑照常跑 `dsh web` / 桌面客户端。装上这个插件并扫码后，手机 [Happy App](https://github.com/slopus/happy) 遥控的是**同一套对话**（发消息、看回复、点批准），不是另开一个 agent。
 
 不安装 Happy CLI。不要用 `happy acp -- dsh acp`。本插件不改 DeepSeek Harness 源码，也不改 Happy 官方仓库。
@@ -19,7 +21,7 @@
 - 新建：只能选已经在网页登记过的工作区。不会在磁盘上 mkdir。App 里「new worktree」会失败（故意不暴露 bash）。
 - 发文字：已注册 `/命令` 走命令通道；否则当聊天。`/skill名` 仍当普通消息，由 harness 注入。
 - 发图片：相册/拍照/粘贴后，会随下一条文字（也可以只发图）进同一场电脑对话，模型能看见图。`.java` / `.txt` 等普通文件会先下载到工作区 `happy-inbox/`，再走电脑原来的 `read` 工具读内容（和你在仓库里打开一个文件一样）。PDF、Word 这类不是纯文本的文件，电脑的 `read` 会拒绝，插件也不会自己拆文档。远程档至少「能聊」。输入框左边应有图片按钮；发出后电脑网页会出现图片，手机会转圈等回复。电脑网页贴的图也会按同一套加密上传推到手机。
-- 工具批准、计划审阅、选择题：和网页黄框/提问框赛跑，谁先点谁算。手机点「始终允许」只在这次网页进程里记住。提问还在等的时候，用输入框打字等于自己填；审阅计划时打字会关掉审阅，这句话当普通聊天发出去。远程档至少「能批」才能从手机点。
+- 工具批准、计划审阅、选择题：和网页黄框/提问框赛跑，谁先点谁算。手机点「始终允许」只在这次网页进程里记住。选择题走 Happy 表单通道：选项照列，每题下面还有自由输入框，提交后卡片上会一直显示你选的答案（旧版 App 没有这条通道，见 `questionChannel`）。提问还在等的时候，用输入框打字等于自己填；审阅计划时打字会关掉审阅，这句话当普通聊天发出去。批完/拒完的卡片会停在「已批准/已拒绝」状态，按钮失效。远程档至少「能批」才能从手机点。
 - 电脑正在生成时，手机可以点停止（Happy App 的 Stop）。远程档至少「能聊」。只看档点了不会停。
 - 助手回复按整段推到手机（生成中会转圈）。思考收成一行 **Think · 摘要** 的 Note 卡片，点进去看全文。工具用 Happy 认识的名字（Grep / Read / Bash），描述跟网页那一行摘要一样。Happy 没有网页同款图标。
 
@@ -67,10 +69,13 @@ pnpm dsh web --port 3080
         appUrl: https://app.happy.engineering
         pairOnStart: true
         remoteGrant: approve
+        questionChannel: communications
 ```
 
 `remoteGrant`：`watch` | `chat` | `approve` | `full`。设置页下拉框会写入这份配置。会话里也可以 `/remote approve`（只改当前进程，不写设置）。档位「完整」时，手机换模型和思考强度走电脑同一条 `session.selectModel`，网页模型栏和推理等级会跟着变。电脑自己换模型和思考强度同样会写回手机。网页加了新模型后，已镜像的手机会话会重新收到完整名单。
 
+`questionChannel`：`communications`（默认）| `permission`。选择题走的 Happy 通道。`communications` 是 App 的表单通道：每道题带自由输入框，提交后卡片常驻显示你选的答案，会话列表也会显示「等回答」；需要较新版 Happy App。旧版 App 没有这条通道时配成 `permission`：题目选项仍可见可答，但没有自由输入框（此时可在输入框打字作答），答完卡片也不回显。
+
 ## 已知限制
 
 - 第 1 期 `listDirectory` 只列出已登记工作区根，不能在手机里浏览仓库内部文件。

package/lib/client.js

@@ -17,21 +17,21 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var HappyBridgeCard_module_css_default = {
-			"error": "l9rBEq_error",
-			"chevron": "l9rBEq_chevron",
-			"button": "l9rBEq_button",
-			"headText": "l9rBEq_headText",
-			"description": "l9rBEq_description",
 			"body": "l9rBEq_body",
+			"row": "l9rBEq_row",
+			"description": "l9rBEq_description",
 			"name": "l9rBEq_name",
+			"headText": "l9rBEq_headText",
+			"chevron": "l9rBEq_chevron",
+			"qr": "l9rBEq_qr",
 			"card": "l9rBEq_card",
+			"error": "l9rBEq_error",
+			"button": "l9rBEq_button",
+			"status": "l9rBEq_status",
+			"checkbox": "l9rBEq_checkbox",
 			"label": "l9rBEq_label",
-			"header": "l9rBEq_header",
 			"select": "l9rBEq_select",
-			"checkbox": "l9rBEq_checkbox",
-			"qr": "l9rBEq_qr",
-			"status": "l9rBEq_status",
-			"row": "l9rBEq_row"
+			"header": "l9rBEq_header"
 		};
 		//#endregion
 		//#region src/client/HappyBridgeCard.tsx

package/lib/index.js

@@ -74,6 +74,42 @@ async function revealOnHarness(registry, sessionId) {
 		});
 	});
 }
+/**
+* Insert or refresh a completed entry with FIFO eviction. Re-answering an id
+* moves it back to newest; the oldest entry falls off the cap.
+* @param map - per-link completed map.
+* @param id - Happy request / communication id.
+* @param entry - schema-valid completed entry.
+*/
+function rememberCompleted(map, id, entry) {
+	map.delete(id);
+	map.set(id, entry);
+	while (map.size > 50) {
+		const oldest = map.keys().next().value;
+		if (oldest === void 0) break;
+		map.delete(oldest);
+	}
+}
+/** Plain-object view of a completed map for the encrypted snapshot. */
+function snapshotMap(map) {
+	return Object.fromEntries(map);
+}
+/**
+* Build the full agentState snapshot pushed with `update-state`. The pending
+* approval or question sits in `requests` / `communications`; every completed
+* entry rides along so App-side replays keep the answered card states.
+* @param input - pending id + entries, the completed maps, and the grant flag.
+* @returns the plaintext agentState object.
+*/
+function agentStateSnapshot(input) {
+	return {
+		controlledByUser: input.controlledByUser,
+		requests: input.pendingId === void 0 || input.pendingRequest === void 0 ? {} : { [input.pendingId]: input.pendingRequest },
+		communications: input.pendingId === void 0 || input.pendingCommunication === void 0 ? {} : { [input.pendingId]: input.pendingCommunication },
+		completedRequests: snapshotMap(input.completedRequests ?? /* @__PURE__ */ new Map()),
+		completedCommunications: snapshotMap(input.completedCommunications ?? /* @__PURE__ */ new Map())
+	};
+}
 //#endregion
 //#region lib/types/happy-version.js
 /**
@@ -1707,6 +1743,53 @@ function parsePermissionRpc(params) {
 	result.updatedInput = { answers: mapped };
 	return result;
 }
+/**
+* Translate Happy communications answers (`{ [question id]: { options, custom } }`)
+* into harness answer rows. Options become `selected`; free text becomes `custom`.
+* @param answers - communication RPC answers keyed by question id.
+* @param questions - original harness questions in order.
+* @returns one answer row per question.
+*/
+function answersFromCommunication(answers, questions) {
+	return questions.map((question) => {
+		const answer = answers?.[question.id];
+		if (answer === void 0) return {
+			id: question.id,
+			selected: []
+		};
+		return {
+			id: question.id,
+			selected: answer.options,
+			...answer.custom === void 0 ? {} : { custom: answer.custom }
+		};
+	});
+}
+/**
+* Decode a Happy `communication` RPC body (form answers or cancellation).
+* Unknown statuses degrade to `cancelled`, which re-asks instead of silently
+* submitting empty answers.
+* @param params - decrypted RPC params.
+* @returns id, form kind, answered/cancelled status, and per-question answers.
+*/
+function parseCommunicationRpc(params) {
+	const record = asUnknownRecord(params);
+	const result = {
+		id: typeof record.id === "string" ? record.id : "",
+		kind: typeof record.kind === "string" && record.kind !== "" ? record.kind : "form",
+		status: record.status === "answered" ? "answered" : "cancelled"
+	};
+	if (!isUnknownRecord(record.answers)) return result;
+	const answers = {};
+	for (const [key, value] of Object.entries(record.answers)) {
+		if (!isUnknownRecord(value)) continue;
+		answers[key] = {
+			options: Array.isArray(value.options) ? value.options.filter((option) => typeof option === "string") : [],
+			...typeof value.custom === "string" && value.custom !== "" ? { custom: value.custom } : {}
+		};
+	}
+	result.answers = answers;
+	return result;
+}
 function asUnknownRecord(value) {
 	return isUnknownRecord(value) ? value : {};
 }
@@ -2328,6 +2411,11 @@ var HappySessionSocket = class {
 			return { ok: true };
 		}, this.handlers.log);
 		this.rpcMethods.push(`${this.happySessionId}:permission`);
+		await registerRpc(socket, this.happySessionId, "communication", this.crypto, (params) => {
+			this.handlers.onCommunication(parseCommunicationRpc(params));
+			return { ok: true };
+		}, this.handlers.log);
+		this.rpcMethods.push(`${this.happySessionId}:communication`);
 		await registerRpc(socket, this.happySessionId, "abort", this.crypto, () => {
 			this.handlers.onAbort();
 			return { ok: true };
@@ -2548,17 +2636,23 @@ var HappySessionSocket = class {
 	}
 	/**
 	* Encrypt and push agentState (permission requests).
+	* Retries on version-mismatch the same way metadata does; a dropped bump
+	* leaves the App with empty `requests` and no Yes/No card.
 	* @param agentState - plaintext agentState.
 	*/
 	updateState(agentState) {
 		const socket = this.socket;
 		if (socket === void 0) return;
+		this.emitState(socket, agentState, this.agentStateVersion, 0);
+	}
+	emitState(socket, agentState, expected, attempt) {
 		socket.emit("update-state", {
 			sid: this.happySessionId,
 			agentState: encryptB64(this.crypto, agentState),
-			expectedVersion: this.agentStateVersion
+			expectedVersion: expected
 		}, (answer) => {
 			if (typeof answer?.version === "number") this.agentStateVersion = answer.version;
+			if (answer?.result === "version-mismatch" && attempt < 3 && typeof answer.version === "number") this.emitState(socket, agentState, answer.version, attempt + 1);
 		});
 	}
 	sendAgent(ev, time) {
@@ -3300,6 +3394,7 @@ var HappyBridge = class {
 		const socket = new HappySessionSocket(sessionId, credentials.token, this.config.serverUrl, crypto, {
 			onInbound: (message) => this.queueInbound(agent.id, message),
 			onPermission: (rpc) => this.onPermission(agent.id, rpc),
+			onCommunication: (rpc) => this.onCommunication(agent.id, rpc),
 			onAbort: () => this.onPhoneAbort(agent.id),
 			onArchived: () => this.onPhoneArchive(sessionId, agent.id),
 			onResumed: () => this.onPhoneRestore(agent.id),
@@ -3331,7 +3426,9 @@ var HappyBridge = class {
 			cwd,
 			events: [],
 			lastForwardedSeq: lastEventSeq(agent.session.events),
-			parked: false
+			parked: false,
+			completedRequests: /* @__PURE__ */ new Map(),
+			completedCommunications: /* @__PURE__ */ new Map()
 		};
 		this.links.set(agent.id, link);
 		this.happyToDsh.set(sessionId, agent.id);
@@ -3366,6 +3463,7 @@ var HappyBridge = class {
 		const socket = new HappySessionSocket(created.id, credentials.token, this.config.serverUrl, crypto, {
 			onInbound: (message) => this.queueInbound(dshId, message),
 			onPermission: (rpc) => this.onPermission(dshId, rpc),
+			onCommunication: (rpc) => this.onCommunication(dshId, rpc),
 			onAbort: () => this.onPhoneAbort(dshId),
 			onArchived: () => this.onPhoneArchive(created.id, dshId),
 			onResumed: () => this.onPhoneRestore(dshId),
@@ -3397,6 +3495,8 @@ var HappyBridge = class {
 			events: stored.events,
 			lastForwardedSeq: -1,
 			parked: false,
+			completedRequests: /* @__PURE__ */ new Map(),
+			completedCommunications: /* @__PURE__ */ new Map(),
 			...stored.headerAgentPreset === void 0 ? {} : { headerAgentPreset: stored.headerAgentPreset }
 		};
 		this.links.set(dshId, link);
@@ -3614,16 +3714,21 @@ var HappyBridge = class {
 		const files = await this.drainPhoneFiles(link);
 		const pending = link.pendingHuman;
 		if (pending?.kind === "ask") {
-			pending.resolve({ answers: customAnswersFromText(pending.questions, message.text) });
+			const answers = customAnswersFromText(pending.questions, message.text);
+			pending.resolve({ answers });
 			delete link.pendingHuman;
-			this.clearRequest(link, pending.id, "canceled");
+			if (pending.communication !== void 0) this.completeCommunication(link, pending.id, pending.communication, "answered", Object.fromEntries(answers.map((row) => [row.id, {
+				options: [],
+				custom: row.custom
+			}])));
+			else this.clearRequest(link, pending.id, "canceled", pending.request);
 			link.socket.sendToolEnd(pending.id);
 			return;
 		}
 		if (pending?.kind === "plan-review") {
 			pending.reject(new UserQuestionError("the user cancelled ask_user_question", "ASK_CANCELLED"));
 			delete link.pendingHuman;
-			this.clearRequest(link, pending.id, "canceled");
+			this.clearRequest(link, pending.id, "canceled", pending.request);
 			link.socket.sendToolEnd(pending.id);
 		}
 		if (!grantAtLeast(this.config.remoteGrant, "chat")) {
@@ -3965,16 +4070,25 @@ var HappyBridge = class {
 		const id = req.callId;
 		const controller = new AbortController();
 		req.signal = req.signal === void 0 ? controller.signal : AbortSignal.any([req.signal, controller.signal]);
-		this.startTool(link, id, req.toolName, req.reason === void 0 ? {} : { reason: req.reason });
-		this.pushRequests(link);
+		const args = req.reason === void 0 ? {} : { reason: req.reason };
+		const card = happyTool(req.toolName, args);
+		let resolvePhone = () => {};
 		const phone = new Promise((resolve) => {
-			link.pendingHuman = {
-				kind: "approval",
-				id,
-				toolName: req.toolName,
-				resolve
-			};
+			resolvePhone = resolve;
 		});
+		link.pendingHuman = {
+			kind: "approval",
+			id,
+			toolName: req.toolName,
+			request: {
+				tool: card.name,
+				arguments: card.args,
+				createdAt: Date.now()
+			},
+			resolve: resolvePhone
+		};
+		this.pushAgentState(link);
+		link.socket.keepAliveNow(true);
 		const web = next().then((outcome) => ({
 			src: "web",
 			outcome
@@ -3988,10 +4102,11 @@ var HappyBridge = class {
 		})), web]);
 		if (winner.src === "phone") controller.abort();
 		if (winner.src === "web" && link.pendingHuman?.kind === "approval" && link.pendingHuman.id === id) {
+			const pending = link.pendingHuman;
 			delete link.pendingHuman;
-			this.clearRequest(link, id, winner.outcome === "allowed-once" ? "approved" : "canceled");
+			this.clearRequest(link, id, winner.outcome === "allowed-once" ? "approved" : "canceled", pending.request);
 		}
-		if (this.running) link.socket.keepAliveNow(true);
+		if (link.agent?.status === "running") link.socket.keepAliveNow(true);
 		return winner.outcome;
 	}
 	onAsk(questions, original, request) {
@@ -4009,6 +4124,11 @@ var HappyBridge = class {
 				link.pendingHuman = {
 					kind: "plan-review",
 					id,
+					request: {
+						tool: "exit_plan_mode",
+						arguments: { plan },
+						createdAt: Date.now()
+					},
 					resolve,
 					reject,
 					approveLabel: first.intent.approve,
@@ -4016,21 +4136,52 @@ var HappyBridge = class {
 					questionId: first.id
 				};
 				link.socket.sendToolStart(id, "exit_plan_mode", { plan }, "审阅计划", "审阅计划");
-				this.pushRequests(link);
+				this.pushAgentState(link);
 				return;
 			}
 			const id = `ask-${createLocalId()}`;
-			link.pendingHuman = {
-				kind: "ask",
-				id,
-				resolve,
-				reject,
-				questions: request.questions.map((question) => ({
+			const questions = request.questions.map((question) => ({
+				id: question.id,
+				question: question.question
+			}));
+			if (this.config.questionChannel === "communications") {
+				const form = request.questions.map((question) => ({
 					id: question.id,
-					question: question.question
-				}))
-			};
-			link.socket.sendToolStart(id, "AskUserQuestion", { questions: request.questions.map((question) => ({
+					header: question.header ?? question.question.slice(0, 24),
+					question: question.question,
+					options: (question.options ?? []).map((option) => ({
+						label: option.label,
+						...option.description === void 0 ? {} : { description: option.description }
+					})),
+					multiSelect: question.multiSelect === true,
+					allowCustom: true,
+					required: true
+				}));
+				const communication = {
+					kind: "form",
+					createdAt: Date.now(),
+					toolUseId: id,
+					title: "需要你回答",
+					form: { questions: form }
+				};
+				link.pendingHuman = {
+					kind: "ask",
+					id,
+					request: {
+						tool: "request_user_input",
+						arguments: { questions: form },
+						createdAt: communication.createdAt
+					},
+					communication,
+					resolve,
+					reject,
+					questions
+				};
+				link.socket.sendToolStart(id, "request_user_input", { questions: form }, "需要你回答", "需要你回答");
+				this.pushAgentState(link);
+				return;
+			}
+			const arguments_ = { questions: request.questions.map((question) => ({
 				question: question.question,
 				header: question.header ?? question.question.slice(0, 24),
 				options: (question.options ?? []).map((option) => ({
@@ -4038,8 +4189,21 @@ var HappyBridge = class {
 					description: option.description ?? ""
 				})),
 				multiSelect: question.multiSelect === true
-			})) }, "需要你回答", "需要你回答");
-			this.pushRequests(link);
+			})) };
+			link.pendingHuman = {
+				kind: "ask",
+				id,
+				request: {
+					tool: "AskUserQuestion",
+					arguments: arguments_,
+					createdAt: Date.now()
+				},
+				resolve,
+				reject,
+				questions
+			};
+			link.socket.sendToolStart(id, "AskUserQuestion", arguments_, "需要你回答", "需要你回答");
+			this.pushAgentState(link);
 		});
 		const web = original.call(questions, {
 			...request,
@@ -4052,10 +4216,12 @@ var HappyBridge = class {
 			controller.abort();
 			throw error;
 		}), web.then((answer) => {
-			if (link.pendingHuman !== void 0) {
-				this.clearRequest(link, link.pendingHuman.id, "canceled");
-				link.socket.sendToolEnd(link.pendingHuman.id);
+			const pending = link.pendingHuman;
+			if (pending !== void 0) {
 				delete link.pendingHuman;
+				if (pending.kind === "ask" && pending.communication !== void 0) this.completeCommunication(link, pending.id, pending.communication, "cancelled");
+				else this.clearRequest(link, pending.id, "canceled", pending.request);
+				link.socket.sendToolEnd(pending.id);
 			}
 			return answer;
 		})]);
@@ -4079,12 +4245,13 @@ var HappyBridge = class {
 			if (rpc.approved) {
 				if (rpc.decision === "approved_for_session") link.alwaysAllow.add(pending.toolName);
 				pending.resolve("allowed-once");
-				this.clearRequest(link, rpc.id, "approved");
+				delete link.pendingHuman;
+				this.clearRequest(link, rpc.id, "approved", pending.request);
 			} else {
 				pending.resolve("rejected");
-				this.clearRequest(link, rpc.id, "denied");
+				delete link.pendingHuman;
+				this.clearRequest(link, rpc.id, "denied", pending.request);
 			}
-			delete link.pendingHuman;
 			return;
 		}
 		if (pending.kind === "plan-review") {
@@ -4093,15 +4260,15 @@ var HappyBridge = class {
 				id: pending.questionId,
 				selected: [selected]
 			}] });
-			this.clearRequest(link, rpc.id, rpc.approved ? "approved" : "denied");
 			delete link.pendingHuman;
+			this.clearRequest(link, rpc.id, rpc.approved ? "approved" : "denied", pending.request);
 			link.socket.sendToolEnd(rpc.id);
 			return;
 		}
 		if (!rpc.approved) {
 			pending.reject(/* @__PURE__ */ new Error("ASK_ABORTED"));
-			this.clearRequest(link, rpc.id, "denied");
 			delete link.pendingHuman;
+			this.clearRequest(link, rpc.id, "denied", pending.request);
 			link.socket.sendToolEnd(rpc.id);
 			return;
 		}
@@ -4110,44 +4277,74 @@ var HappyBridge = class {
 			id: row.id,
 			selected: row.selected
 		})) });
-		this.clearRequest(link, rpc.id, "approved");
 		delete link.pendingHuman;
+		this.clearRequest(link, rpc.id, "approved", pending.request);
 		link.socket.sendToolEnd(rpc.id);
 	}
-	pushRequests(link) {
-		const pending = link.pendingHuman;
-		const requests = {};
-		if (pending !== void 0) {
-			if (pending.kind === "approval") requests[pending.id] = {
-				tool: pending.toolName,
-				arguments: {},
-				createdAt: Date.now()
-			};
-			else if (pending.kind === "plan-review") requests[pending.id] = {
-				tool: "exit_plan_mode",
-				arguments: {},
-				createdAt: Date.now()
-			};
-			else requests[pending.id] = {
-				tool: "AskUserQuestion",
-				arguments: {},
-				createdAt: Date.now()
-			};
+	/**
+	* Answered / cancelled a communications form. Swap the pending form for a
+	* completed one so the App card keeps showing the user's choice verbatim.
+	*/
+	onCommunication(dshId, rpc) {
+		const link = this.links.get(dshId);
+		const pending = link?.pendingHuman;
+		if (link === void 0 || pending === void 0 || pending.kind !== "ask") return;
+		if (pending.id !== rpc.id || pending.communication === void 0) return;
+		if (rpc.status !== "answered" || rpc.answers === void 0) {
+			pending.reject(new UserQuestionError("the user cancelled ask_user_question", "ASK_CANCELLED"));
+			delete link.pendingHuman;
+			this.completeCommunication(link, rpc.id, pending.communication, "cancelled");
+			link.socket.sendToolEnd(rpc.id);
+			return;
 		}
-		link.socket.updateState({
-			controlledByUser: grantAtLeast(this.config.remoteGrant, "chat"),
-			requests
-		});
+		pending.resolve({ answers: answersFromCommunication(rpc.answers, pending.questions) });
+		delete link.pendingHuman;
+		this.completeCommunication(link, rpc.id, pending.communication, "answered", rpc.answers);
+		link.socket.sendToolEnd(rpc.id);
 	}
-	clearRequest(link, id, status) {
-		link.socket.updateState({
+	/**
+	* Publish the agentState snapshot: the pending approval / question plus
+	* every completed entry. The App zod-validates the whole snapshot and
+	* blanks it on any malformed entry, so completed entries must always carry
+	* the full original request shape.
+	*/
+	pushAgentState(link) {
+		const pending = link.pendingHuman;
+		const communication = pending?.kind === "ask" ? pending.communication : void 0;
+		const request = pending === void 0 || communication !== void 0 ? void 0 : pending.request;
+		link.socket.updateState(agentStateSnapshot({
 			controlledByUser: grantAtLeast(this.config.remoteGrant, "chat"),
-			requests: {},
-			completedRequests: { [id]: {
-				status,
-				completedAt: Date.now()
-			} }
+			...pending === void 0 ? {} : { pendingId: pending.id },
+			...communication === void 0 ? {} : { pendingCommunication: communication },
+			...request === void 0 ? {} : { pendingRequest: request },
+			completedRequests: link.completedRequests,
+			completedCommunications: link.completedCommunications
+		}));
+	}
+	/**
+	* Complete a permission request: keep the original entry fields (the App
+	* schema rejects completed entries without `tool`/`arguments` — that used
+	* to blank the whole snapshot and leave every card stuck `pending`), add
+	* the outcome, then republish the snapshot.
+	*/
+	clearRequest(link, id, status, request, reason) {
+		rememberCompleted(link.completedRequests, id, {
+			...request,
+			completedAt: Date.now(),
+			status,
+			...reason === void 0 ? {} : { reason }
+		});
+		this.pushAgentState(link);
+	}
+	/** Record a finished communications form and republish the snapshot. */
+	completeCommunication(link, id, communication, status, answers) {
+		rememberCompleted(link.completedCommunications, id, {
+			...communication,
+			completedAt: Date.now(),
+			status,
+			...answers === void 0 ? {} : { answers }
 		});
+		this.pushAgentState(link);
 	}
 	async pushMetadata(link) {
 		if (this.credentials === void 0) return;
@@ -4509,7 +4706,8 @@ const Config = Schema.object({
 		Schema.const("chat"),
 		Schema.const("approve"),
 		Schema.const("full")
-	]).default("approve")
+	]).default("approve"),
+	questionChannel: Schema.union([Schema.const("communications"), Schema.const("permission")]).default("communications")
 });
 /**
 * Mount the Host half: settings namespace, Typert Remote, Happy relay.

package/lib/types/agent-state.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure helpers for the Happy agentState snapshot. The App zod-validates the
+ * whole decrypted snapshot and blanks it on any malformed entry, so every
+ * completed entry must carry the full original request shape.
+ * @module agent-state
+ */
+import type { HappyCommunicationEntry, HappyCompletedCommunication, HappyCompletedRequest, HappyRequestEntry } from './types.ts';
+/** Completed entries kept per session, so snapshots cannot grow without bound. */
+export declare const COMPLETED_CAP = 50;
+/**
+ * Insert or refresh a completed entry with FIFO eviction. Re-answering an id
+ * moves it back to newest; the oldest entry falls off the cap.
+ * @param map - per-link completed map.
+ * @param id - Happy request / communication id.
+ * @param entry - schema-valid completed entry.
+ */
+export declare function rememberCompleted<T>(map: Map<string, T>, id: string, entry: T): void;
+/** Plain-object view of a completed map for the encrypted snapshot. */
+export declare function snapshotMap<T>(map: ReadonlyMap<string, T>): Record<string, T>;
+/**
+ * Build the full agentState snapshot pushed with `update-state`. The pending
+ * approval or question sits in `requests` / `communications`; every completed
+ * entry rides along so App-side replays keep the answered card states.
+ * @param input - pending id + entries, the completed maps, and the grant flag.
+ * @returns the plaintext agentState object.
+ */
+export declare function agentStateSnapshot(input: {
+    controlledByUser: boolean;
+    /** Local pending id; also the key in both maps and the tool-call id. */
+    pendingId?: string;
+    /** Pending entry for the permission channel (approvals, plan review, legacy questions). */
+    pendingRequest?: HappyRequestEntry;
+    /** Pending entry for the communications channel (questions). */
+    pendingCommunication?: HappyCommunicationEntry;
+    completedRequests?: ReadonlyMap<string, HappyCompletedRequest>;
+    completedCommunications?: ReadonlyMap<string, HappyCompletedCommunication>;
+}): {
+    controlledByUser: boolean;
+    requests: Record<string, HappyRequestEntry>;
+    communications: Record<string, HappyCommunicationEntry>;
+    completedRequests: Record<string, HappyCompletedRequest>;
+    completedCommunications: Record<string, HappyCompletedCommunication>;
+};
+//# sourceMappingURL=agent-state.d.ts.map

package/lib/types/bridge.d.ts

@@ -205,8 +205,27 @@ export declare class HappyBridge {
      */
     private onPhoneAbort;
     private onPermission;
-    private pushRequests;
+    /**
+     * Answered / cancelled a communications form. Swap the pending form for a
+     * completed one so the App card keeps showing the user's choice verbatim.
+     */
+    private onCommunication;
+    /**
+     * Publish the agentState snapshot: the pending approval / question plus
+     * every completed entry. The App zod-validates the whole snapshot and
+     * blanks it on any malformed entry, so completed entries must always carry
+     * the full original request shape.
+     */
+    private pushAgentState;
+    /**
+     * Complete a permission request: keep the original entry fields (the App
+     * schema rejects completed entries without `tool`/`arguments` — that used
+     * to blank the whole snapshot and leave every card stuck `pending`), add
+     * the outcome, then republish the snapshot.
+     */
     private clearRequest;
+    /** Record a finished communications form and republish the snapshot. */
+    private completeCommunication;
     private pushMetadata;
     private pushAllMetadata;
     private queueOutboundUser;

package/lib/types/inbound.d.ts

@@ -1,5 +1,5 @@
 /** Classify inbound Happy user text as a registered slash command or ordinary chat. */
-import type { PermissionRpc } from './types.ts';
+import type { CommunicationRpc, PermissionRpc } from './types.ts';
 /** Normalized inbound payload from a decrypted Happy message. */
 export type HappyInbound = {
     kind: 'text';
@@ -85,4 +85,29 @@ export declare function planReviewDeclineLabel(question: {
  * @returns id, approved flag, optional Always-allow decision, and answers.
  */
 export declare function parsePermissionRpc(params: unknown): PermissionRpc;
+/**
+ * Translate Happy communications answers (`{ [question id]: { options, custom } }`)
+ * into harness answer rows. Options become `selected`; free text becomes `custom`.
+ * @param answers - communication RPC answers keyed by question id.
+ * @param questions - original harness questions in order.
+ * @returns one answer row per question.
+ */
+export declare function answersFromCommunication(answers: Record<string, {
+    options: string[];
+    custom?: string;
+}> | undefined, questions: readonly {
+    id: string;
+}[]): {
+    id: string;
+    selected: string[];
+    custom?: string;
+}[];
+/**
+ * Decode a Happy `communication` RPC body (form answers or cancellation).
+ * Unknown statuses degrade to `cancelled`, which re-asks instead of silently
+ * submitting empty answers.
+ * @param params - decrypted RPC params.
+ * @returns id, form kind, answered/cancelled status, and per-question answers.
+ */
+export declare function parseCommunicationRpc(params: unknown): CommunicationRpc;
 //# sourceMappingURL=inbound.d.ts.map

package/lib/types/session-socket.d.ts

@@ -1,13 +1,15 @@
 /** One Happy session-scoped socket: encrypt chat, metadata, agentState, permission RPC. */
 import { type CryptoContext } from './encryption.ts';
 import { type HappyInbound } from './inbound.ts';
-import type { PermissionRpc } from './types.ts';
+import type { CommunicationRpc, PermissionRpc } from './types.ts';
 /** Callbacks the bridge installs on one Happy session. */
 export interface SessionHandlers {
     /** Decrypted inbound chat or file. */
     onInbound: (message: InboundMessage) => void;
     /** Phone answered a permission / fake-tool request. */
     onPermission: (rpc: PermissionRpc) => void;
+    /** Phone answered or cancelled a communications-channel form. */
+    onCommunication: (rpc: CommunicationRpc) => void;
     /** Phone tapped Stop. Happy App `sessionAbort` for Rig sends `{}`. */
     onAbort: () => void;
     /** App archived or deleted this Happy session. */
@@ -141,9 +143,12 @@ export declare class HappySessionSocket {
     private emitMetadata;
     /**
      * Encrypt and push agentState (permission requests).
+     * Retries on version-mismatch the same way metadata does; a dropped bump
+     * leaves the App with empty `requests` and no Yes/No card.
      * @param agentState - plaintext agentState.
      */
     updateState(agentState: unknown): void;
+    private emitState;
     private sendAgent;
     private emitEnvelope;
     private onMetadataUpdate;

package/lib/types/types.d.ts

@@ -1,6 +1,8 @@
 /** Shared plugin types: config, credentials, remote grant, and Happy wire extras. */
 /** Remote-control depth the phone is allowed on this Host. */
 export type RemoteGrant = 'watch' | 'chat' | 'approve' | 'full';
+/** Transport for harness `ask_user_question` on the phone. */
+export type QuestionChannel = 'communications' | 'permission';
 /** Validated plugin config. */
 export interface Config {
     /** Master switch. */
@@ -15,6 +17,13 @@ export interface Config {
     pairOnStart: boolean;
     /** How deeply the phone may control this Host. */
     remoteGrant: RemoteGrant;
+    /**
+     * Which Happy channel carries questions. `communications` is the App's form
+     * channel (options plus a free-text answer, with the choice echoed back on
+     * the card); `permission` is the legacy AskUserQuestion fallback for older
+     * App builds.
+     */
+    questionChannel: QuestionChannel;
 }
 /** Encryption variant stored with the account credentials. */
 export type EncryptionVariant = 'legacy' | 'dataKey';
@@ -101,4 +110,70 @@ export interface PermissionRpc {
         answers?: Record<string, string>;
     };
 }
+/** One question published on the Happy communications channel. */
+export interface HappyFormQuestion {
+    /** Harness question id; the App echoes it back as the answer key. */
+    id: string;
+    header: string;
+    question: string;
+    options: {
+        label: string;
+        description?: string;
+    }[];
+    multiSelect: boolean;
+    /** Lets the user write an answer the options did not offer. */
+    allowCustom: boolean;
+    required: boolean;
+}
+/** Pending communications entry published through agentState.communications. */
+export interface HappyCommunicationEntry {
+    kind: 'form';
+    createdAt: number;
+    /** Equals the `request_user_input` tool-call id so the App joins the form to its card. */
+    toolUseId: string;
+    title: string;
+    form: {
+        questions: HappyFormQuestion[];
+    };
+}
+/**
+ * Completed communications entry. The App renders `answers` verbatim on the
+ * card ("header: chosen labels / custom text"), which is the answer echo.
+ */
+export interface HappyCompletedCommunication extends HappyCommunicationEntry {
+    completedAt: number;
+    status: 'answered' | 'cancelled';
+    answers?: Record<string, {
+        options: string[];
+        custom?: string;
+    }>;
+}
+/**
+ * Pending permission request entry, shaped like the official CLI's
+ * `requests[id] = { tool, arguments, createdAt }`.
+ */
+export interface HappyRequestEntry {
+    tool: string;
+    arguments: Record<string, unknown>;
+    createdAt: number;
+}
+/**
+ * Completed permission request entry. The App's zod schema requires `tool`
+ * (and reads `arguments`); an entry without them blanks the whole agentState.
+ */
+export interface HappyCompletedRequest extends HappyRequestEntry {
+    completedAt: number;
+    status: 'approved' | 'denied' | 'canceled';
+    reason?: string;
+}
+/** Happy `communication` RPC body from the App. */
+export interface CommunicationRpc {
+    id: string;
+    kind: string;
+    status: 'answered' | 'cancelled';
+    answers?: Record<string, {
+        options: string[];
+        custom?: string;
+    }>;
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,7 +1,21 @@
 {
   "name": "@sjhmars/happy-bridge",
-  "version": "0.2.4",
-  "description": "Pair an already-running dsh web/desktop client with Happy App so the phone remote-controls the same harness sessions",
+  "version": "0.3.0",
+  "description": "Remote-control bridge: pair a running dsh web/desktop client with the Happy mobile app by QR code, then remote-control the same harness sessions from the phone (send messages, read replies, approve tool calls, switch models)",
+  "keywords": [
+    "deepseek-harness",
+    "dsh-plugin",
+    "dsh",
+    "happy",
+    "happy-app",
+    "remote-control",
+    "remote",
+    "mobile",
+    "companion",
+    "pairing",
+    "qr-code",
+    "bridge"
+  ],
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",