@gavin-hu/my-pi-agent 0.17.0 → 0.19.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 sink — 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. Liveness is the
+ * sink's own (a write after the end is a no-op), so the registry never asks the
+ * socket whether it is still writable.
+ *
+ * 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 { EventSink } from "../../lib/http/index.ts";
+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(sink: EventSink, record: StreamRecord): void;
+	/** Forget a stream, arming the grace when it was the owner's last one. */
+	remove(sink: EventSink): 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<EventSink, 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(sink, record) {
+			clients.set(sink, record);
+			if (record.role === "owner") {
+				sawOwner = true;
+				cancel();
+			}
+		},
+		remove(sink) {
+			const record = clients.get(sink);
+			clients.delete(sink);
+			if (record?.role === "owner") scheduleDrop();
+		},
+		broadcast(kind, only) {
+			for (const [client, record] of clients) {
+				if (!matches(record, only)) continue;
+				client.write(`data: ${kind}\n\n`);
+			}
+		},
+		end(kind, only) {
+			for (const [client, record] of clients) {
+				if (!matches(record, only)) 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 { mintToken } from "../../lib/http/index.ts";
+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 => mintToken();
+
+/** 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] : [])),
+	};
+}