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

package/extensions/plan/web-router.ts

@@ -1,25 +1,25 @@
 /**
  * The request router for browser plan review.
  *
- * A request is validated (method, `Host`, per-session token), matched to a
- * route, and answered with a plain {@link ServeResponse}, so every route can be
- * tested without a socket. The `/events` route is a marker: the node server in
- * `web.ts` keeps that response open as a Server-Sent Events stream used only to
- * notice when the browser tab is gone.
+ * A request is validated (method, `Host`, origin, token), matched to a route,
+ * and answered with a plain {@link ServeResponse}, so every route can be tested
+ * without a socket. The `/events` route is a marker: the node server in `web.ts`
+ * keeps that response open as a Server-Sent Events stream.
  *
- * The token is a per-session secret carried in the page URL. It is not an
- * authentication system — the server is loopback-only — but it stops another
- * local page from driving the session.
+ * The token is a per-session secret carried in the page URL, and on a shared
+ * review it is the only credential a reviewer has: it names the caller — the
+ * role it holds, and the name it posts under — and the router refuses an
+ * owner-only route for a reviewer however the request was built.
  */
 
 import {
+	envelopeRefusal,
 	eventHeaders,
-	isLocalHostHeader,
 	jsonError,
-	jsonHeaders,
 	jsonResponse,
 	pageHeaders,
 	parseRequestUrl,
+	postOnly,
 	scriptHeaders,
 	type ServeResponse,
 } from "../../lib/http/index.ts";
@@ -27,25 +27,38 @@ import { THEME_JS, THEME_JS_PATH } from "../../lib/web/index.ts";
 import { coerceAnnotations, type PlanAnnotation } from "./feedback.ts";
 import { REVIEW_CLIENT_JS } from "./web-client.ts";
 import { renderReviewPage, type ReviewPageData } from "./web-page.ts";
+import type { ReviewCaller, ReviewRole } from "./types.ts";
+import type { ShareResult } from "./web-share.ts";
 
-/** What a save callback reports back. */
-export type SaveResult = { ok: true } | { ok: false; status: number; message: string };
+/** What a save callback reports back. A reviewer's post reports the name it was
+ * stored under, so a page created before the first write can adopt it. */
+export type SaveResult = { ok: true; author?: string } | { ok: false; status: number; message: string };
 
 /** Everything the router needs from the running session. */
 export interface ReviewContext {
-	/** Per-session secret required on the page, event stream, and API routes. */
-	token: string;
+	/** The caller a token names, or undefined when it is not one of this session's. */
+	caller: (token: string) => ReviewCaller | undefined;
+	/** The host names this server answers to now, so a rebound page is refused. */
+	hosts: () => readonly string[];
 	/** Whether the browser may approve the plan (only the `exit_plan_mode` flow). */
 	canApprove: boolean;
-	/** Build the page data (recomputed per request from the current plan). */
-	page: () => Promise<ReviewPageData>;
-	/** Persist the annotations and report the outcome. */
-	save: (annotations: PlanAnnotation[]) => Promise<SaveResult>;
-	/** Called after a successful save; the server resolves the session once the response has flushed. */
+	/** Build the page data for the caller (recomputed per request). */
+	page: (caller: ReviewCaller) => Promise<ReviewPageData>;
+	/** Persist the annotations as the caller and report the outcome. */
+	save: (annotations: PlanAnnotation[], caller: ReviewCaller) => Promise<SaveResult>;
+	/** Start sharing the review, or report why it cannot be shared. */
+	share: () => Promise<ShareResult>;
+	/** Mint one more reviewer link, so each teammate holds their own. */
+	invite: () => Promise<ShareResult>;
+	/** Revoke one link by id; undefined when this review does not hold it. */
+	revoke: (id: string) => Promise<ShareResult | undefined>;
+	/** Revoke reviewer tokens and stop accepting reviewers. */
+	stopShare: () => Promise<ShareResult>;
+	/** Called after the owner's save; the server resolves the session once the response has flushed. */
 	onSaved: (annotations: PlanAnnotation[]) => void;
 	/** Called after a successful approve; the server resolves the session once the response has flushed. */
 	onApprove: (annotations: PlanAnnotation[]) => void;
-	/** Called when the user cancels; the server resolves the session once the response has flushed. */
+	/** Called when the owner cancels; the server resolves the session once the response has flushed. */
 	onCancel: () => void;
 }
 
@@ -70,24 +83,25 @@ function isResponse(value: PlanAnnotation[] | ServeResponse): value is ServeResp
 	return !Array.isArray(value);
 }
 
-/** Validate method and `Host`; returns an error response to send instead. */
-function checkEnvelope(
-	method: string,
-	headers: Record<string, string | string[] | undefined>,
-): ServeResponse | undefined {
-	const upper = method.toUpperCase();
-	if (upper !== "GET" && upper !== "HEAD" && upper !== "POST") {
-		return {
-			...jsonError(405, "Only GET, HEAD, and POST are served."),
-			headers: { ...jsonHeaders(), Allow: "GET, HEAD, POST" },
-		};
-	}
-	// Fail closed: a missing or non-string Host is rejected too, not just a
-	// foreign one, so the DNS-rebinding guard cannot be skipped.
-	if (!isLocalHostHeader(headers, { required: true })) {
-		return jsonError(403, "Unexpected Host header.");
+/**
+ * The 403 for a route the caller's role may not use, or nothing when it may. Each
+ * route keeps its own sentence, because the reason differs: a reviewer posts
+ * comments, and only the owner decides.
+ */
+function roleOnly(caller: ReviewCaller, roles: readonly ReviewRole[], message: string): ServeResponse | undefined {
+	return roles.includes(caller.role) ? undefined : jsonError(403, message);
+}
+
+/** The link id a revoke request names, or undefined when the body has none. */
+function linkIdOf(body: string): string | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		return undefined;
 	}
-	return undefined;
+	const id = (parsed as { id?: unknown } | null)?.id;
+	return typeof id === "string" && id !== "" ? id : undefined;
 }
 
 /**
@@ -101,7 +115,7 @@ export async function handleReviewRequest(
 	headers: Record<string, string | string[] | undefined> = {},
 	body = "",
 ): Promise<ServeResponse> {
-	const envelope = checkEnvelope(method, headers);
+	const envelope = envelopeRefusal({ method, headers, hosts: ctx.hosts() });
 	if (envelope) return envelope;
 
 	const parsed = parseRequestUrl(rawUrl);
@@ -112,34 +126,82 @@ export async function handleReviewRequest(
 	if (pathname === THEME_JS_PATH) return { status: 200, headers: scriptHeaders(), body: THEME_JS };
 	if (pathname === "/client.js") return { status: 200, headers: scriptHeaders(), body: REVIEW_CLIENT_JS };
 
-	if (search.get("token") !== ctx.token) return jsonError(403, "Invalid or missing token.");
+	const token = search.get("token") ?? "";
+	const caller = ctx.caller(token);
+	if (caller === undefined) return jsonError(403, "Invalid or missing token.");
 
 	if (pathname === "/" || pathname === "/index.html") {
-		return { status: 200, headers: pageHeaders(), body: renderReviewPage(await ctx.page()) };
+		return { status: 200, headers: pageHeaders(), body: renderReviewPage(await ctx.page(caller)) };
 	}
 	if (pathname === "/events") return { status: 200, headers: eventHeaders(), stream: true };
 	if (pathname === "/api/cancel") {
-		if (method.toUpperCase() !== "POST") return jsonError(405, "Use POST to cancel.");
+		// Ending the review is the owner's decision; a reviewer closes their tab.
+		const refusal =
+			postOnly(method, "cancel") ?? roleOnly(caller, ["owner"], "Only the plan owner can close this review.");
+		if (refusal) return refusal;
 		ctx.onCancel();
 		return jsonResponse(200, { ok: true });
 	}
+	if (pathname === "/api/share" || pathname === "/api/share/link" || pathname === "/api/share/stop") {
+		// A shared link must never be able to mint another one.
+		const refusal =
+			postOnly(method, "share or stop sharing") ??
+			roleOnly(caller, ["owner"], "Only the plan owner can share this review.");
+		if (refusal) return refusal;
+		const result =
+			pathname === "/api/share/stop"
+				? await ctx.stopShare()
+				: pathname === "/api/share/link"
+					? await ctx.invite()
+					: await ctx.share();
+		return jsonResponse(200, { ok: true, share: result.state, svg: result.svg });
+	}
+	if (pathname === "/api/share/revoke") {
+		const refusal =
+			postOnly(method, "revoke a link") ?? roleOnly(caller, ["owner"], "Only the plan owner can revoke a link.");
+		if (refusal) return refusal;
+		const id = linkIdOf(body);
+		if (id === undefined) return jsonError(400, "The request body must name the link's id.");
+		const result = await ctx.revoke(id);
+		if (!result) return jsonError(404, "That link is not shared.");
+		return jsonResponse(200, { ok: true, share: result.state, svg: result.svg });
+	}
+	if (pathname === "/api/comment") {
+		// A reviewer's whole surface: persist the comments they wrote and end
+		// nothing. Only the owner's own save decides the review.
+		const refusal =
+			postOnly(method, "post comments") ?? roleOnly(caller, ["reviewer"], "Only a shared reviewer posts comments.");
+		if (refusal) return refusal;
+		const annotations = parseAnnotations(body);
+		if (isResponse(annotations)) return annotations;
+		const result = await ctx.save(annotations, caller);
+		if (!result.ok) return jsonError(result.status, result.message);
+		return jsonResponse(200, { ok: true, ...(result.author === undefined ? {} : { author: result.author }) });
+	}
 	if (pathname === "/api/feedback") {
-		if (method.toUpperCase() !== "POST") return jsonError(405, "Use POST to save feedback.");
+		// Returning to the model is the owner's decision; a reviewer posts to
+		// `/api/comment`, so this route can never settle a shared review.
+		const refusal =
+			postOnly(method, "save feedback") ??
+			roleOnly(caller, ["owner"], "Only the plan owner saves this review; a reviewer posts comments.");
+		if (refusal) return refusal;
 		const annotations = parseAnnotations(body);
 		if (isResponse(annotations)) return annotations;
-		const result = await ctx.save(annotations);
+		const result = await ctx.save(annotations, caller);
 		if (!result.ok) return jsonError(result.status, result.message);
 		ctx.onSaved(annotations);
 		return jsonResponse(200, { ok: true });
 	}
 	if (pathname === "/api/approve") {
-		if (method.toUpperCase() !== "POST") return jsonError(405, "Use POST to approve.");
-		// Only the exit_plan_mode flow owns the approval side effects, so a comment-only
-		// review refuses this even if a client posts it directly.
+		// Only the owner's own page approves, and only the exit_plan_mode flow owns
+		// the side effects: a reviewer token is refused whatever it posts.
+		const refusal =
+			postOnly(method, "approve") ?? roleOnly(caller, ["owner"], "A shared review cannot approve the plan.");
+		if (refusal) return refusal;
 		if (!ctx.canApprove) return jsonError(403, "This review cannot be approved from the browser.");
 		const annotations = parseAnnotations(body);
 		if (isResponse(annotations)) return annotations;
-		const result = await ctx.save(annotations);
+		const result = await ctx.save(annotations, caller);
 		if (!result.ok) return jsonError(result.status, result.message);
 		ctx.onApprove(annotations);
 		return jsonResponse(200, { ok: true });

package/extensions/plan/web-share-session.ts

@@ -0,0 +1,191 @@
+/**
+ * The shared review's second listener: one reviewer token, one address on this
+ * network, and the state the owner's page and `/plan share` read.
+ *
+ * Separate from `web.ts` because the review session's job is its own lifecycle —
+ * open, settle, close — while this module owns the address, the links, and the
+ * listener's lifetime. It is handed the one request handler, the token
+ * hooks, and the frame hooks, so it never reaches into the session's maps.
+ */
+
+import { LOOPBACK_HOSTS, type LoopbackHandler, type LoopbackServer, serveLoopback } from "../../lib/http/index.ts";
+import { qrSvg } from "../../lib/qr.ts";
+import type { ReviewFrame, ReviewRole } from "./types.ts";
+import {
+	AT_CAP_REASON,
+	createLinkTable,
+	lanAddresses,
+	NO_SHARE_REASON,
+	shareUrl,
+	type LinkTable,
+	type NetworkInterfaces,
+	type ShareResult,
+	type ShareState,
+} from "./web-share.ts";
+
+/** What the share listener needs from the review session it belongs to. */
+export interface ShareSessionDeps {
+	/** The one request handler: a loopback page and a shared page are the same page. */
+	handleRequest: LoopbackHandler;
+	/** The body cap both listeners read under, so a shared page is not read differently. */
+	maxBodyBytes: number;
+	/** The owner's bound port, reused for the link when it is free. */
+	ownerPort: () => number;
+	/** The machine's interfaces, or a snapshot a test injected. */
+	networkInterfaces: () => NetworkInterfaces;
+	/** Add a reviewer token to the session's role map. */
+	mintReviewer: () => string;
+	/** Remove a reviewer token from the session's role map. */
+	revokeReviewer: (token: string) => void;
+	/** The name a reviewer token has bound, or undefined before its first post. */
+	nameOf: (token: string) => string | undefined;
+	/** Tell the open pages something changed, optionally only one role or link. */
+	broadcast: (kind: ReviewFrame, only?: ReviewRole) => void;
+	/** End streams with a last frame: every reviewer, or one link's. */
+	endStreams: (kind: ReviewFrame, only?: { role?: ReviewRole; token?: string }) => void;
+}
+
+/** The share surface one running review exposes. */
+export interface ShareSession {
+	/** Start sharing with the first link, or report why it cannot; idempotent while on. */
+	share(): Promise<ShareResult>;
+	/** Mint one more link, so each teammate holds their own. */
+	invite(): Promise<ShareResult>;
+	/** Revoke one link, or undefined when this review does not hold that id. */
+	revoke(id: string): Promise<ShareResult | undefined>;
+	/** Revoke every link, tell the reviewers, and close the listener. */
+	stop(): Promise<ShareResult>;
+	/** The current state, without changing it. */
+	state(): ShareState;
+	/** Host names the server answers to: loopback plus the shared address. */
+	hosts(): readonly string[];
+	/** Close the listener as the review ends, without reading it as a decision. */
+	close(): Promise<void>;
+}
+
+export function createShareSession(deps: ShareSessionDeps): ShareSession {
+	let address = "";
+	let port = 0;
+	let server: LoopbackServer | undefined;
+	const links: LinkTable = createLinkTable({
+		mint: deps.mintReviewer,
+		revoke: deps.revokeReviewer,
+		nameOf: deps.nameOf,
+	});
+	let reason: string | undefined;
+	const hosts = (): readonly string[] => (address ? [...LOOPBACK_HOSTS, address] : [...LOOPBACK_HOSTS]);
+
+	/**
+	 * The share surface as it is now, read rather than cached: a link's bound name
+	 * changes when its reviewer posts, and the owner's page has to see that without
+	 * another share action.
+	 */
+	const snapshot = (): ShareState => {
+		const base: ShareState = server === undefined ? { sharing: false, port: 0, links: [] } : links.state(port, address);
+		return reason === undefined ? base : { ...base, reason };
+	};
+
+	/** Bind the shared listener on `chosen`, reusing the owner's port when it is free. */
+	const bind = async (chosen: string): Promise<void> => {
+		try {
+			const bound = await serveLoopback({
+				host: chosen,
+				ports: [deps.ownerPort(), 0],
+				maxBodyBytes: deps.maxBodyBytes,
+				handler: deps.handleRequest,
+			});
+			server = bound;
+			address = chosen;
+			port = bound.port;
+		} catch {
+			// Neither the owner's port nor a free one answered: the caller reports it.
+			server = undefined;
+		}
+	};
+
+	/**
+	 * Bind the one shared listener the first time a link needs it, or report why
+	 * there is nothing to bind to. Every link answers on this same listener, so this
+	 * runs once per share and the rest is bookkeeping.
+	 */
+	const ensureListener = async (): Promise<boolean> => {
+		if (server !== undefined) return true;
+		const chosen = lanAddresses(deps.networkInterfaces())[0];
+		if (chosen === undefined) {
+			reason = NO_SHARE_REASON;
+			return false;
+		}
+		await bind(chosen);
+		if (server === undefined) {
+			reason = NO_SHARE_REASON;
+			return false;
+		}
+		reason = undefined;
+		return true;
+	};
+
+	/** Announce the change and hand back the state, plus the QR of a link just minted. */
+	const settle = async (minted?: string): Promise<ShareResult> => {
+		deps.broadcast("share", "owner");
+		const state = snapshot();
+		if (minted === undefined) return { state };
+		return { state, svg: await qrSvg(shareUrl(address, port, minted)) };
+	};
+
+	const share = async (): Promise<ShareResult> => {
+		reason = undefined;
+		if (!(await ensureListener())) return { state: snapshot() };
+		// One link per share, so a second click re-reads the link it already minted
+		// rather than making another one the owner has to revoke.
+		const added = links.list().length === 0 ? links.add() : undefined;
+		return settle(added?.token ?? links.list().at(-1)?.token);
+	};
+
+	const invite = async (): Promise<ShareResult> => {
+		reason = undefined;
+		if (!(await ensureListener())) return { state: snapshot() };
+		const added = links.add();
+		if (added === undefined) {
+			// At the cap: the page keeps rendering the links it holds and says why.
+			reason = AT_CAP_REASON;
+			return { state: snapshot() };
+		}
+		return settle(added.token);
+	};
+
+	const revoke = async (id: string): Promise<ShareResult | undefined> => {
+		reason = undefined;
+		const link = links.find(id);
+		if (link === undefined) return undefined;
+		// The link is told before its token goes away, so its page reads the reason
+		// rather than falling back to "Offline".
+		deps.endStreams("revoked", { token: link.token });
+		links.remove(id);
+		// The last link leaving is the same thing as stopping: there is nothing left to
+		// answer on the shared listener.
+		if (links.list().length === 0) return stop();
+		return settle();
+	};
+
+	const stop = async (): Promise<ShareResult> => {
+		for (const link of links.list()) links.remove(link.id);
+		// The reviewers are told before their listener goes away; the review itself
+		// stays open for its owner.
+		deps.endStreams("revoked", { role: "reviewer" });
+		const closer = server;
+		server = undefined;
+		address = "";
+		port = 0;
+		reason = undefined;
+		if (closer) await closer.close();
+		return settle();
+	};
+
+	const close = async (): Promise<void> => {
+		const closer = server;
+		server = undefined;
+		if (closer) await closer.close();
+	};
+
+	return { share, invite, revoke, stop, state: snapshot, hosts, close };
+}

package/extensions/plan/web-share.ts

@@ -0,0 +1,169 @@
+/**
+ * Sharing a review with the people on this network (pure).
+ *
+ * A shared review needs one thing the running server cannot discover for
+ * itself: which address a teammate's browser should name. This module answers
+ * that from an injected `networkInterfaces()` snapshot — never by reading the
+ * machine's own NICs — and turns it into the links the owner is shown and the
+ * page renders.
+ *
+ * Only addresses another machine can plausibly reach are offered: IPv4, not
+ * internal, and not the link-local range a machine assigns itself when DHCP
+ * failed. Everything else would print a link that cannot work.
+ */
+
+import type { NetworkInterfaceInfo } from "node:os";
+
+/** The interfaces a review may be shared to, by name. */
+export type NetworkInterfaces = Record<string, NetworkInterfaceInfo[] | undefined>;
+
+/** One address a reviewer can open the review at. */
+export interface ShareLink {
+	/** Stable for the life of this review and never reused, so a page can name one link. */
+	id: string;
+	/** The bare address, as it appears in the URL. */
+	address: string;
+	/** The full tokenized URL a reviewer opens. */
+	url: string;
+	/** The name this link posts under, once its first post has bound it. */
+	name?: string;
+}
+
+/** What the page and the terminal show about a running share. */
+export interface ShareState {
+	/** True while reviewer tokens exist and an address is bound. */
+	sharing: boolean;
+	/** The port reviewers connect to. */
+	port: number;
+	/** Every shared link, oldest first. */
+	links: ShareLink[];
+	/** Why sharing is unavailable, when it is. */
+	reason?: string;
+}
+
+/** What the page gets back from a share or a stop: the state, plus a QR to render. */
+export interface ShareResult {
+	state: ShareState;
+	/** Inline SVG for the first link; absent when nothing is shared. */
+	svg?: string;
+}
+
+/** Why a machine cannot share a review. */
+export const NO_SHARE_REASON =
+	"This machine has no network address to share on. Reviewers can still use a loopback link on this computer.";
+
+/**
+ * IPv4 addresses another machine on this network can reach, deduplicated and
+ * sorted, so the same machine prints the same link every time.
+ */
+export function lanAddresses(interfaces: NetworkInterfaces): string[] {
+	const addresses = new Set<string>();
+	for (const entries of Object.values(interfaces)) {
+		for (const entry of entries ?? []) {
+			if (entry.family !== "IPv4" || entry.internal) continue;
+			if (entry.address === "0.0.0.0" || entry.address.startsWith("169.254.")) continue;
+			addresses.add(entry.address);
+		}
+	}
+	return [...addresses].sort(byAddress);
+}
+
+/** Numeric IPv4 comparison, so `…1.9` sorts before `…1.24`. */
+function byAddress(a: string, b: string): number {
+	const left = a.split(".").map(Number);
+	const right = b.split(".").map(Number);
+	for (let index = 0; index < 4; index++) {
+		const difference = (left[index] ?? 0) - (right[index] ?? 0);
+		if (difference !== 0) return difference;
+	}
+	return 0;
+}
+
+/** The tokenized link for one address. */
+export function shareUrl(address: string, port: number, token: string): string {
+	return `http://${address}:${port}/?token=${token}`;
+}
+
+/**
+ * One link is one person.
+ *
+ * A shared review holds one reviewer token per link, and the token is the only
+ * credential a reviewer has: it names the role, and it binds the name the link
+ * posts under on its first write. Two people on one link are one writer, so the
+ * table exists to let the owner hand out as many as the team has members — and to
+ * take one back without touching the others.
+ */
+
+/** The most links one review may hold: each is a live bearer credential. */
+export const MAX_SHARE_LINKS = 8;
+
+/** Why another link cannot be minted: every link is a live credential. */
+export const AT_CAP_REASON = `This review already holds ${MAX_SHARE_LINKS} links; revoke one before minting another.`;
+
+/** One share the table holds: the id a page names it by, and its token. */
+export interface SharedLink {
+	/** Stable for the life of the review, and never reused after a revoke. */
+	id: string;
+	/** The reviewer token this link carries. */
+	token: string;
+}
+
+/** What the table needs from the review that owns the tokens. */
+export interface LinkTableDeps {
+	/** Mint a reviewer token. */
+	mint: () => string;
+	/** Release a token, so the link that carried it stops answering. */
+	revoke: (token: string) => void;
+	/** The name a link's token has bound, so the owner can see who holds it. */
+	nameOf: (token: string) => string | undefined;
+}
+
+/** The reviewer links one running review has shared. */
+export interface LinkTable {
+	/** Mint a link on a fresh token, or nothing when the review is at the cap. */
+	add(): SharedLink | undefined;
+	/** The link with this id, or nothing when the review does not hold it. */
+	find(id: string): SharedLink | undefined;
+	/** Release one link by id; false when the review does not hold it. */
+	remove(id: string): boolean;
+	/** The links currently shared, oldest first. */
+	list(): readonly SharedLink[];
+	/** The state the owner's page and the terminal read. */
+	state(port: number, address: string): ShareState;
+}
+
+export function createLinkTable(deps: LinkTableDeps): LinkTable {
+	const links: SharedLink[] = [];
+	let minted = 0;
+	return {
+		add() {
+			if (links.length >= MAX_SHARE_LINKS) return undefined;
+			minted += 1;
+			const link: SharedLink = { id: `link-${minted}`, token: deps.mint() };
+			links.push(link);
+			return link;
+		},
+		find: (id) => links.find((link) => link.id === id),
+		remove(id) {
+			const index = links.findIndex((link) => link.id === id);
+			if (index < 0) return false;
+			const [removed] = links.splice(index, 1);
+			if (removed) deps.revoke(removed.token);
+			return true;
+		},
+		list: () => [...links],
+		state: (port, address) => ({
+			sharing: links.length > 0,
+			port,
+			links: links.map((link) => {
+				const name = deps.nameOf(link.token);
+				return {
+					id: link.id,
+					address,
+					url: shareUrl(address, port, link.token),
+					...(name === undefined ? {} : { name }),
+				};
+			}),
+		}),
+	};
+}