@gavin-hu/my-pi-agent 0.17.0 → 0.18.0

package/extensions/plan/web-streams.ts

@@ -0,0 +1,124 @@
+/**
+ * The review's event streams: which pages are listening, what they are told, and
+ * when a closed tab ends the review.
+ *
+ * A frame carries only a kind, so the registry is the only thing that knows who
+ * is connected. It is keyed by response — a page may hold more than one stream —
+ * and records the caller it belongs to, so an owner-only frame, or one revoked
+ * link, can be addressed without the caller reaching into the map.
+ *
+ * The closed-tab rule lives here because it is a fact about streams: a reviewer's
+ * tab opening or closing changes nothing, while the owner's own page going away
+ * ends the review once the grace a reload needs has passed. The grace is a race
+ * against that reload, so it takes the timer as a seam a test can drive by hand.
+ */
+
+import type { ServerResponse } from "node:http";
+import type { ArmTimer } from "../../lib/timer.ts";
+import type { ReviewFrame, ReviewRole } from "./types.ts";
+
+/** Who a stream belongs to: the role it may act as, and the token that names it. */
+export interface StreamRecord {
+	role: ReviewRole;
+	token: string;
+}
+
+/** Which streams a frame is for; absent means every open page. */
+export interface StreamFilter {
+	role?: ReviewRole;
+	token?: string;
+}
+
+/** What the registry needs from the session whose lifetime it reports on. */
+export interface StreamRegistryDeps {
+	/** The review is over because its owner's page went away. */
+	onAbandoned: () => void;
+	/** How long a closed owner tab waits for a reload before it counts as gone. */
+	graceMs: number;
+	/** The timer the grace is armed on. */
+	schedule: ArmTimer;
+	/** A settled review arms nothing, so a stream closing during teardown is silent. */
+	settled: () => boolean;
+}
+
+/** The stream set one running review holds. */
+export interface StreamRegistry {
+	/** Register a stream, and stand down a pending closed-tab grace. */
+	add(response: ServerResponse, record: StreamRecord): void;
+	/** Forget a stream, arming the grace when it was the owner's last one. */
+	remove(response: ServerResponse): void;
+	/** Tell the open pages something changed. */
+	broadcast(kind: ReviewFrame, only?: StreamFilter): void;
+	/** Send one last frame and end the stream with it. */
+	end(kind: ReviewFrame, only?: StreamFilter): void;
+	/** Drop every stream without ending it, after they have all been ended. */
+	clear(): void;
+	/** Stand down the closed-tab grace, because the review is ending anyway. */
+	cancelDrop(): void;
+	/** How many owner streams are open. */
+	ownerOpen(): number;
+}
+
+export function createStreams(deps: StreamRegistryDeps): StreamRegistry {
+	const clients = new Map<ServerResponse, StreamRecord>();
+	let sawOwner = false;
+	let cancelDrop: (() => void) | undefined;
+
+	const ownerOpen = (): number => {
+		let open = 0;
+		for (const record of clients.values()) if (record.role === "owner") open += 1;
+		return open;
+	};
+
+	const cancel = (): void => {
+		cancelDrop?.();
+		cancelDrop = undefined;
+	};
+
+	const scheduleDrop = (): void => {
+		if (ownerOpen() > 0 || !sawOwner || deps.settled() || cancelDrop) return;
+		cancelDrop = deps.schedule(deps.graceMs, () => {
+			cancelDrop = undefined;
+			if (ownerOpen() === 0) deps.onAbandoned();
+		});
+	};
+
+	const matches = (record: StreamRecord, only: StreamFilter | undefined): boolean => {
+		if (only === undefined) return true;
+		if (only.role !== undefined && record.role !== only.role) return false;
+		if (only.token !== undefined && record.token !== only.token) return false;
+		return true;
+	};
+
+	return {
+		add(response, record) {
+			clients.set(response, record);
+			if (record.role === "owner") {
+				sawOwner = true;
+				cancel();
+			}
+		},
+		remove(response) {
+			const record = clients.get(response);
+			clients.delete(response);
+			if (record?.role === "owner") scheduleDrop();
+		},
+		broadcast(kind, only) {
+			for (const [client, record] of clients) {
+				if (!matches(record, only)) continue;
+				if (client.writableEnded || client.destroyed) continue;
+				client.write(`data: ${kind}\n\n`);
+			}
+		},
+		end(kind, only) {
+			for (const [client, record] of clients) {
+				if (!matches(record, only)) continue;
+				if (client.writableEnded || client.destroyed) continue;
+				client.end(`data: ${kind}\n\n`);
+			}
+		},
+		clear: () => clients.clear(),
+		cancelDrop: cancel,
+		ownerOpen,
+	};
+}

package/extensions/plan/web-tokens.ts

@@ -0,0 +1,63 @@
+/**
+ * The token table: who a review's bearer token names.
+ *
+ * A review has two roles and, once shared, one token per reviewer link. The role
+ * travels with the token, and a reviewer's name is added to it the first time that
+ * link writes. Everything that decides "may this caller approve, save, or close"
+ * reads this table, so the rules live here rather than in the session that mints
+ * them:
+ *
+ * - two roles may never share one token, or a reviewer token could displace the
+ *   owner's and hand a reviewer the approval route;
+ * - a removed token is forgotten rather than tombstoned, so a re-shared link may
+ *   claim the name the revoked one released;
+ * - a name already bound elsewhere is visible, because the marker in the plan
+ *   carries only the name, so a shared name is a shared marker.
+ */
+
+import { randomBytes } from "node:crypto";
+import type { ReviewCaller, ReviewRole } from "./types.ts";
+
+/** The token → caller table one running review holds. */
+export interface TokenTable {
+	/** Mint a token for `role`, replacing a colliding one until it is unique. */
+	mint(role: ReviewRole): string;
+	/** The caller a token names, or undefined when it is not one of this review's. */
+	get(token: string): ReviewCaller | undefined;
+	/** Forget a token, so the link that used it stops answering. */
+	revoke(token: string): void;
+	/**
+	 * The names every other live link has bound, so one review cannot hold two
+	 * reviewers called `alice`: the marker carries only the name, so a shared name
+	 * is a shared marker.
+	 */
+	namesExcept(self: ReviewCaller): string[];
+}
+
+/** How many times a colliding generator is retried before the table names it itself. */
+const COLLISION_ATTEMPTS = 8;
+
+/** A 128-bit token; the one credential a reviewer holds. */
+const defaultToken = (): string => randomBytes(16).toString("hex");
+
+/** Build the table for one review. `mint` is the generator a test replaces. */
+export function createTokens(mint: () => string = defaultToken): TokenTable {
+	const callers = new Map<string, ReviewCaller>();
+	return {
+		mint(role) {
+			// A role is keyed by its token, so two roles may never share one: a
+			// generator that repeats would otherwise let a reviewer token displace the
+			// owner's and hand a reviewer the approval route.
+			let value = mint();
+			for (let attempt = 0; callers.has(value) && attempt < COLLISION_ATTEMPTS; attempt++) value = mint();
+			if (callers.has(value)) value = `${value}-${callers.size}`;
+			callers.set(value, { role });
+			return value;
+		},
+		get: (token) => callers.get(token),
+		revoke: (token) => {
+			callers.delete(token);
+		},
+		namesExcept: (self) => [...callers.values()].flatMap((entry) => (entry !== self && entry.name ? [entry.name] : [])),
+	};
+}

package/extensions/plan/web.ts

@@ -10,8 +10,8 @@
  * and it takes injected seams so tests can run one on `127.0.0.1:0`.
  */
 
-import { randomBytes } from "node:crypto";
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { networkInterfaces } from "node:os";
 import { basename } from "node:path";
 import { openInBrowser } from "../../lib/browser.ts";
 import {
@@ -19,25 +19,33 @@ import {
 	createCloser,
 	jsonHeaders,
 	openEventStream,
+	parseRequestUrl,
 	respond,
 	type ServeResponse,
 } from "../../lib/http/index.ts";
 import { fenceLanguage, highlightLines } from "../../lib/highlight.ts";
-import { type ArmTimer, defaultTimer } from "../../lib/timer.ts";
+import { type ArmTimer, defaultInterval, defaultTimer, type RepeatTimer } from "../../lib/timer.ts";
 import { codeBody, fenceInfo, planBlocks } from "./blocks.ts";
 import {
+	claimAuthor,
 	MAX_ANNOTATIONS,
 	MAX_COMMENT_LENGTH,
 	MAX_QUOTE_LENGTH,
+	normalizeAuthor,
 	parseFeedback,
 	stripFeedback,
 	type PlanAnnotation,
 } from "./feedback.ts";
 import { planTitle, type PlanStore, type StoredPlan } from "./plans.ts";
-import { changedSections, type SectionDigest } from "./plan-text.ts";
+import { changedSections, planDigest, type SectionDigest } from "./plan-text.ts";
 import { extractPlanSections, extractPlanSteps } from "./steps.ts";
+import type { ReviewCaller } from "./types.ts";
 import { handleReviewRequest, type ReviewContext, type SaveResult } from "./web-router.ts";
 import type { ReviewPageData } from "./web-page.ts";
+import { createShareSession, type ShareSession } from "./web-share-session.ts";
+import { createStreams } from "./web-streams.ts";
+import { createTokens } from "./web-tokens.ts";
+import type { NetworkInterfaces, ShareResult, ShareState } from "./web-share.ts";
 
 /** How a browser review ended. */
 export type PlanReviewResult =
@@ -47,13 +55,13 @@ export type PlanReviewResult =
 
 /** A running review the caller awaits and then closes. */
 export interface PlanReviewSession {
-	/** Tokenized URL to open or print. */
+	/** Tokenized URL to open or print; the owner's own page. */
 	url: string;
 	/** Bound loopback port. */
 	port: number;
 	/** Resolves once, when the review ends. */
 	done: Promise<PlanReviewResult>;
-	/** Stop the server. Safe to call more than once. */
+	/** Stop the server(s). Safe to call more than once. */
 	close(): Promise<void>;
 }
 
@@ -63,13 +71,29 @@ export interface PlanReviewOptions {
 	signal?: AbortSignal;
 	/** Whether the browser may approve the plan (only the `exit_plan_mode` flow). */
 	canApprove?: boolean;
+	/** A line the page shows the owner, such as why approval belongs in the terminal. */
+	note?: string;
 	/** The section digests the previous review showed, so this page can mark changed sections. */
 	baseline?: SectionDigest[];
+	/**
+	 * Called when a shared reviewer's post lands, so the owner's terminal can say so:
+	 * an open page updates itself, and whoever is waiting in the TUI is told nothing
+	 * until this fires.
+	 */
+	onReviewerComment?: (author: string, count: number) => void;
 }
 
 /** Starts and tracks review sessions. */
 export interface PlanWebReview {
 	start(cwd: string, plan: StoredPlan, options?: PlanReviewOptions): Promise<PlanReviewSession | undefined>;
+	/** The session currently serving a review, if any. */
+	current(): PlanReviewSession | undefined;
+	/** Start (or re-read) the share link for the running review, if one is open. */
+	share(): Promise<ShareResult | undefined>;
+	/** Revoke every reviewer token and stop accepting reviewers. */
+	stopSharing(): Promise<ShareResult | undefined>;
+	/** The running review's share state, without changing it. */
+	shareState(): ShareState | undefined;
 	/** Stop every running session (session shutdown). */
 	closeAll(): Promise<void>;
 }
@@ -93,12 +117,31 @@ export interface PlanWebReviewDeps {
 	schedule?: ArmTimer;
 	/** Override the accepted body size; a test keeps it small. */
 	maxBodyBytes?: number;
+	/**
+	 * Override the repeating timer that polls the plan file.
+	 *
+	 * A poll is a race against an edit made elsewhere, so a test drives it by hand
+	 * rather than waiting for a tick that makes a busy machine fail.
+	 */
+	tick?: RepeatTimer;
+	/** How often to check the plan file for an edit this review did not make. */
+	pollMs?: number;
+	/** Override the machine's network interfaces (tests), never read live in a test. */
+	networkInterfaces?: () => NetworkInterfaces;
 }
 
 /** Largest feedback body accepted, in bytes. */
 const MAX_BODY_BYTES = 1024 * 1024;
 /** Grace period before an empty client set counts as a closed tab. */
 const DROP_GRACE_MS = 1500;
+/**
+ * How often a running review checks the plan file.
+ *
+ * One stat and one read of a small markdown file, only while a page is open: a
+ * second is fast enough that an edit under an open page reaches it while the
+ * reader is still looking, and slow enough to be free.
+ */
+const PLAN_POLL_MS = 1000;
 
 /** A request body, or the fact that it was too large to read. */
 type BodyResult = { ok: true; body: string } | { ok: false };
@@ -136,6 +179,9 @@ function readBody(request: IncomingMessage, limit: number): Promise<BodyResult>
 
 export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps = {}): PlanWebReview {
 	const sessions = new Set<PlanReviewSession>();
+	// What each running review can do about sharing; the session itself stays the
+	// four things a caller awaits and closes.
+	const shares = new Map<PlanReviewSession, ShareSession>();
 	// Last bound port per plan path, so the same plan keeps one origin across
 	// review turns (and its saved browser theme with it).
 	const ports = new Map<string, number>();
@@ -148,21 +194,37 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 		const { signal } = options;
 		const canApprove = options.canApprove === true;
 		const maxBody = deps.maxBodyBytes ?? MAX_BODY_BYTES;
-		const token = (deps.token ?? (() => randomBytes(16).toString("hex")))();
+		// One token per holder: the owner's is minted here and never shared, and a
+		// reviewer token is minted by `share()`. The table owns the collision rule and
+		// the name each link has bound.
+		const tokens = createTokens(deps.token);
+		const token = tokens.mint("owner");
+		// The owner's bound port, so a shared listener can reuse it for the same URL shape.
+		let currentPort = 0;
 		let settled = false;
 		let resolveDone!: (result: PlanReviewResult) => void;
 		const done = new Promise<PlanReviewResult>((resolve) => {
 			resolveDone = resolve;
 		});
-		let cancelDrop: (() => void) | undefined;
-		const clearDrop = (): void => {
-			cancelDrop?.();
-			cancelDrop = undefined;
-		};
+		// Live event streams, used only to notice a closed owner tab: a reviewer's
+		// tab is not the review's lifetime. The explicit Cancel button and the abort
+		// signal are the deterministic paths.
+		const streams = createStreams({
+			onAbandoned: () => finish({ status: "cancelled" }),
+			graceMs: deps.dropGraceMs ?? DROP_GRACE_MS,
+			schedule: deps.schedule ?? defaultTimer,
+			settled: () => settled,
+		});
+
+		let stopTicker: () => void = () => {};
 		const finish = (result: PlanReviewResult): void => {
 			if (settled) return;
 			settled = true;
-			clearDrop();
+			streams.cancelDrop();
+			stopTicker();
+			// A page still open has no decision to make, so it is told why it stops
+			// updating, and its stream is ended with that frame rather than after it.
+			streams.end("closed");
 			resolveDone(result);
 		};
 
@@ -181,11 +243,41 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 		 */
 		const refreshPageText = async (): Promise<StoredPlan> => {
 			const current = (await store.read(cwd, plan.path)) ?? plan;
-			pageText = stripFeedback(current.content);
+			const next = stripFeedback(current.content);
+			// Someone saved the plan outside this page: the readers must see the new
+			// body, and the next save must anchor against it rather than 409.
+			if (next !== pageText) notifyPlanChange();
+			pageText = next;
 			return current;
 		};
+		// Set below, once the stream set exists; a page load before that has no
+		// reader to notify and nothing to notify it about.
+		let notifyPlanChange: () => void = () => {};
+		notifyPlanChange = () => streams.broadcast("plan");
 
-		const page = async (): Promise<ReviewPageData> => {
+		/**
+		 * Notice a plan file this review did not write.
+		 *
+		 * A review owns the page, not the file: `/plan review` runs in normal mode, and
+		 * the plan is a markdown file a user or another tool can rewrite while the page
+		 * is open. The check compares the stripped text with what the page rendered and
+		 * only announces — it never writes `pageText`, which is the anchor a save is
+		 * validated against. So an edit under an open page reaches every reader, and the
+		 * review's own save, whose text is unchanged, says nothing.
+		 *
+		 * A poll rather than an `fs.watch`: the house rule, and one stat plus one read
+		 * per interval costs less than the watcher's platform-dependent event
+		 * semantics (see `file-browse`'s note). It stops with the session.
+		 */
+		const checkPlanFile = async (): Promise<void> => {
+			const current = await store.read(cwd, plan.path);
+			if (!current) return;
+			if (stripFeedback(current.content) !== pageText) notifyPlanChange();
+		};
+		stopTicker = (deps.tick ?? defaultInterval)(deps.pollMs ?? PLAN_POLL_MS, () => void checkPlanFile());
+
+		const page = async (caller: ReviewCaller): Promise<ReviewPageData> => {
+			const { role } = caller;
 			const stored = await refreshPageText();
 			const current = pageText;
 			const blocks = planBlocks(current);
@@ -231,29 +323,79 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 				code,
 				limits: { comments: MAX_ANNOTATIONS, comment: MAX_COMMENT_LENGTH, quote: MAX_QUOTE_LENGTH },
 				token,
-				canApprove,
+				role,
+				// What the page keys this tab's unsaved draft on: same plan text, same draft.
+				rev: planDigest(current),
+				...(caller.name === undefined ? {} : { author: caller.name }),
+				canApprove: role === "owner" && canApprove,
+				...(role === "owner" && options.note !== undefined ? { note: options.note } : {}),
+				share: role === "owner" ? shareSession.state() : undefined,
 			};
 		};
 
-		const save = async (annotations: PlanAnnotation[]): Promise<SaveResult> => {
+		/**
+		 * The owner's save decides the review; a reviewer's post only writes.
+		 * Both replace the comments of the writer they carry — the owner's are
+		 * untagged, a reviewer's are tagged with the name bound to that link — so
+		 * neither touches another writer's markers, and both refuse a plan that
+		 * changed since the page was rendered.
+		 */
+		const save = async (annotations: PlanAnnotation[], caller: ReviewCaller): Promise<SaveResult> => {
+			const { role } = caller;
 			const current = await store.read(cwd, plan.path);
 			if (!current) return { ok: false, status: 404, message: "The plan file is gone." };
 			if (stripFeedback(current.content) !== pageText) {
 				return { ok: false, status: 409, message: "The plan changed on disk; reload the page and review again." };
 			}
 			try {
-				savedPlan = await store.saveFeedback(cwd, plan.path, annotations);
-				return { ok: true };
+				if (role === "owner") {
+					savedPlan = await store.saveFeedback(cwd, plan.path, annotations);
+					streams.broadcast("comment");
+					return { ok: true };
+				}
+				// The link, not the payload, decides whose markers this post replaces: the name
+				// is bound to the token on its first write, and a page that signs another one
+				// is a stale tab rather than an authorized writer.
+				const claim = claimAuthor({ bound: caller.name, taken: tokens.namesExcept(caller) }, annotations);
+				if (!("name" in claim)) return { ok: false, status: claim.status, message: claim.message };
+				const own = annotations.filter((annotation) => normalizeAuthor(annotation.author) === claim.name);
+				// The saved plan is deliberately not recorded here: a post is not a result
+				// the session can return, so there is nothing for a later flush to resolve.
+				await store.saveFeedback(cwd, plan.path, own, { author: claim.name });
+				caller.name ??= claim.name;
+				streams.broadcast("comment");
+				if (own.length > 0) options.onReviewerComment?.(claim.name, own.length);
+				return { ok: true, author: claim.name };
 			} catch (error) {
 				return { ok: false, status: 500, message: error instanceof Error ? error.message : String(error) };
 			}
 		};
 
+		// The second listener, its reviewer token, and the state the page and
+		// `/plan share` read. It is handed the request handler, the role map, and the
+		// frame hooks, so sharing stays one concern instead of five fields here.
+		const shareSession = createShareSession({
+			handleRequest,
+			ownerPort: () => currentPort,
+			networkInterfaces: deps.networkInterfaces ?? networkInterfaces,
+			mintReviewer: () => tokens.mint("reviewer"),
+			revokeReviewer: (value) => tokens.revoke(value),
+			nameOf: (value) => tokens.get(value)?.name,
+			broadcast: (kind, only) => streams.broadcast(kind, only === undefined ? undefined : { role: only }),
+			endStreams: (kind, only) => streams.end(kind, only),
+		});
+		const hosts = (): readonly string[] => shareSession.hosts();
+
 		const context: ReviewContext = {
-			token,
+			caller: (value) => tokens.get(value),
+			hosts,
 			canApprove,
 			page,
 			save,
+			share: () => shareSession.share(),
+			invite: () => shareSession.invite(),
+			revoke: (id) => shareSession.revoke(id),
+			stopShare: () => shareSession.stop(),
 			onSaved: (annotations) => {
 				pendingResult = savedPlan ? { status: "saved", plan: savedPlan, annotations } : { status: "cancelled" };
 			},
@@ -265,21 +407,12 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 			},
 		};
 
-		// Live event streams, used only to notice a closed tab. The explicit Cancel
-		// button and the abort signal are the deterministic paths.
-		const clients = new Set<ServerResponse>();
-		let hadClient = false;
-		const dropGrace = deps.dropGraceMs ?? DROP_GRACE_MS;
-		const schedule = deps.schedule ?? defaultTimer;
-		const scheduleDrop = (): void => {
-			if (clients.size > 0 || !hadClient || settled || cancelDrop) return;
-			cancelDrop = schedule(dropGrace, () => {
-				cancelDrop = undefined;
-				if (clients.size === 0) finish({ status: "cancelled" });
-			});
-		};
-
-		const server = createServer((request, response) => {
+		// Live event streams, used only to notice a closed owner tab: a reviewer's
+		// tab is not the review's lifetime. The explicit Cancel button and the abort
+		// signal are the deterministic paths.
+		const server = createServer(handleRequest);
+		/** One request, on either listener: the loopback page or a shared one. */
+		function handleRequest(request: IncomingMessage, response: ServerResponse): void {
 			void (async () => {
 				const method = request.method ?? "GET";
 				const read =
@@ -302,13 +435,12 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 				}
 				if (result.stream) {
 					openEventStream(response, result);
-					hadClient = true;
-					clients.add(response);
-					clearDrop();
-					request.on("close", () => {
-						clients.delete(response);
-						scheduleDrop();
-					});
+					// A page that walks away mid-frame must not take the session down.
+					response.on("error", () => {});
+					const token = parseRequestUrl(request.url ?? "/")?.search.get("token") ?? "";
+					const streamCaller = context.caller(token);
+					if (streamCaller !== undefined) streams.add(response, { role: streamCaller.role, token });
+					request.on("close", () => streams.remove(response));
 					return;
 				}
 				// A save or cancel only resolves the session after its response is on the
@@ -324,9 +456,9 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 				respond(request, response, result, settlePending);
 				response.on("close", settlePending);
 			})();
-		});
+		}
 
-		// The accept-level `error` listener lives in `bindLoopback`, so a transient
+		// The accept-level `error` listener lives in `bindHost`, so a transient
 		// failure cannot take the host down; the review still ends through its own
 		// paths: cancel, abort, drop, or shutdown.
 		const preferred = deps.port ?? ports.get(plan.path) ?? 0;
@@ -348,6 +480,7 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 			return undefined;
 		}
 		ports.set(plan.path, port);
+		currentPort = port;
 		const closeServer = createCloser(server);
 
 		const url = `http://127.0.0.1:${port}/?token=${token}`;
@@ -358,14 +491,19 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 			closed = true;
 			if (signal && abortHandler) signal.removeEventListener("abort", abortHandler);
 			sessions.delete(session);
-			for (const client of clients) client.end();
-			clients.clear();
+			shares.delete(session);
+			// `finish` ends every open stream with its last frame, so it runs before
+			// the set is cleared rather than after it.
 			finish({ status: "cancelled" });
+			stopTicker();
+			streams.clear();
+			await shareSession.close();
 			await closeServer();
 		};
 
 		const session: PlanReviewSession = { url, port, done, close };
 		sessions.add(session);
+		shares.set(session, shareSession);
 
 		if (signal) {
 			abortHandler = (): void => void close();
@@ -377,8 +515,18 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 		return session;
 	};
 
+	const current = (): PlanReviewSession | undefined => [...sessions].at(-1);
+	const controls = () => {
+		const session = current();
+		return session ? shares.get(session) : undefined;
+	};
+
 	return {
 		start,
+		current,
+		share: async () => controls()?.share(),
+		stopSharing: async () => controls()?.stop(),
+		shareState: () => controls()?.state(),
 		closeAll: async () => {
 			await Promise.all([...sessions].map((session) => session.close()));
 		},

package/extensions/question/README.md

@@ -32,6 +32,9 @@ on.
   `Other` row `Space` opens the editor, like `Enter`.
 - `Esc` cancels; the model receives “User cancelled the question.” and can
   continue or ask in prose.
+- On a dialog-only host (RPC/WeChat), one question uses the normal select/input.
+  Two or more become one batch editor prompt and one reply (`1: 2; 2: A, B`),
+  with one retry if the format is unclear; the TUI keeps its tabbed screen.
 
 ## Tool