@gavin-hu/my-pi-agent 0.20.0 → 0.22.0

package/extensions/serve/registry.ts

@@ -0,0 +1,260 @@
+/**
+ * The session's one server, the prefixes mounted on it, and the LAN listener a
+ * shared page borrows.
+ *
+ * The registry is the only place that knows what a session is serving: it binds on
+ * the first mount, remembers the port so a closed page reopens where it was, keys
+ * every server by Pi session id so a peer session never lands on the host's socket,
+ * and closes a session's socket with its last mount. A page that goes away takes
+ * only its own prefix with it.
+ *
+ * The port is a preference, not a reservation: a session's first bind tries the port
+ * it is pinned to, or the project's own number, and falls back to an OS-chosen one when
+ * that port is taken. Pinning is the session's, not a page's: `serve.port` belongs to the
+ * first session that binds, so a second session in this process (a WeChat peer loads every
+ * other extension, `extensions/wechat/peer/peer-session.ts`) falls back to an OS-chosen
+ * port instead of failing on the host's pin, and a second *process* is told the pin
+ * is in use rather than moved off the address a bookmark names.
+ *
+ * Value-only: every byte of state is in the returned closure.
+ */
+
+import { lazy } from "../../lib/lazy.ts";
+import type {
+	HttpMount,
+	MountOutcome,
+	MountRequest,
+	NetworkInterfaces,
+	ServedMount,
+	ServedServer,
+	SharedListener,
+} from "../../lib/http/index.ts";
+
+/** One prefix as this session's server holds it: the mount, and the spec that remounts it. */
+interface Held {
+	mount: { base: string; release(): Promise<void> };
+	spec: ServedMount;
+}
+
+/** One session's served state. */
+interface Served {
+	server: ServedServer;
+	mounts: Map<string, Held>;
+	/** The LAN listener every shared page of this session answers on. */
+	shared?: ServedServer;
+	/** The address `shared` was bound to, which a link prints. */
+	address?: string;
+	/** The prefixes answered on `shared`, each with the mount that frees it again. */
+	sharedMounts: Map<string, { release(): Promise<void> }>;
+}
+
+/** What the registry needs besides the request it is answering. */
+export interface ServeRegistryDeps {
+	/** The port a session is pinned to, or `0` to pick one. */
+	portFor(session: string): number;
+	/**
+	 * The port a session's first bind tries, before the OS-chosen fallback: the project's
+	 * own number, so a session that starts again lands on the one a bookmark names.
+	 */
+	pickPort(session: string): number | Promise<number>;
+	/** The machine's interfaces; a test injects a snapshot instead. */
+	interfaces: () => NetworkInterfaces;
+	/** Told when a session's port comes up and when it goes away, so a chip can say so. */
+	onPort?: (session: string, port: number | undefined) => void;
+	/** The served-page kit; loaded on the first bind, so registration never pays for it. */
+	loadServe?: () => Promise<typeof import("../../lib/http/index.ts")>;
+}
+
+/** The session's servers, as the extension's bus listener drives them. */
+export interface ServeRegistry {
+	/** Answer one mount request: claims it synchronously, then binds. */
+	handle(request: MountRequest): void;
+	/** Close one session's socket, LAN listener included. */
+	closeSession(session: string): Promise<void>;
+}
+
+/** A bind that failed, or the server it produced. */
+type Opened = { kind: "open"; served: Served } | { kind: "failed"; reason: string };
+
+/**
+ * Why a bind failed, naming the setting when the pinned port was the reason: a bind
+ * error's own text says the address, not the key that chose it.
+ */
+function refusalReason(error: unknown, pinned: number | undefined): string {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	if (pinned !== undefined && code === "EADDRINUSE") {
+		return `port ${pinned} is in use — change "port" in the bytefly.json serve section, or stop what answers on it`;
+	}
+	return error instanceof Error ? error.message : String(error);
+}
+
+export function createServeRegistry(deps: ServeRegistryDeps): ServeRegistry {
+	const sessions = new Map<string, Served>();
+	/** Binds in flight, so two pages opening together share one socket. */
+	const binding = new Map<string, Promise<Opened>>();
+	/** The port each session last bound, so a page that closed reopens where it was. */
+	const remembered = new Map<string, number>();
+	/** The session the pinned port belongs to; every later session picks its own. */
+	let pinnedBy: string | undefined;
+	/** The served-page kit: one load, on the first bind, shared by every later one. */
+	const http = lazy(deps.loadServe ?? (() => import("../../lib/http/index.ts")));
+
+	/** Bind `session`'s server on the pin when it is this session's to take. */
+	const bind = async (session: string): Promise<Opened> => {
+		const { serveHttp } = await http.get();
+		const pinned = deps.portFor(session);
+		const usePin = pinned > 0 && (pinnedBy === undefined || pinnedBy === session);
+		const preferred = remembered.get(session) ?? (await deps.pickPort(session));
+		try {
+			const server = await serveHttp({ ports: usePin ? [pinned] : [preferred, 0] });
+			if (usePin) pinnedBy = session;
+			remembered.set(session, server.port);
+			const served: Served = { server, mounts: new Map(), sharedMounts: new Map() };
+			sessions.set(session, served);
+			deps.onPort?.(session, server.port);
+			return { kind: "open", served };
+		} catch (error) {
+			return { kind: "failed", reason: refusalReason(error, usePin ? pinned : undefined) };
+		}
+	};
+
+	/** This session's server, binding it if no page has yet. */
+	const open = async (session: string): Promise<Opened> => {
+		const existing = sessions.get(session);
+		if (existing !== undefined) return { kind: "open", served: existing };
+		const inflight = binding.get(session);
+		if (inflight !== undefined) return inflight;
+		const started = bind(session).finally(() => binding.delete(session));
+		binding.set(session, started);
+		return started;
+	};
+
+	/** Withdraw one page from the LAN listener, whether it stopped sharing or closed. */
+	const withdraw = async (served: Served, base: string): Promise<void> => {
+		const mounted = served.sharedMounts.get(base);
+		if (mounted === undefined) return;
+		served.sharedMounts.delete(base);
+		await mounted.release();
+	};
+
+	/** Close the LAN listener once no page on this session is sharing itself. */
+	const closeLanIfEmpty = async (served: Served): Promise<void> => {
+		if (served.sharedMounts.size > 0) return;
+		const listener = served.shared;
+		served.shared = undefined;
+		served.address = undefined;
+		if (listener !== undefined) await listener.close();
+	};
+
+	/** Forget a session's server, which the socket has already closed. */
+	const closed = (session: string, served: Served): void => {
+		if (sessions.get(session) !== served) return;
+		sessions.delete(session);
+		deps.onPort?.(session, undefined);
+	};
+
+	const release = async (session: string, base: string): Promise<void> => {
+		const served = sessions.get(session);
+		const held = served?.mounts.get(base);
+		if (served === undefined || held === undefined) return;
+		served.mounts.delete(base);
+		// A page that closes stops being reachable from the network as well: its prefix comes
+		// off the LAN listener before the loopback one, so no link outlives the page.
+		await withdraw(served, base);
+		await held.mount.release();
+		// The last prefix takes the LAN listener with it, then the socket: a session with
+		// no pages has no port to answer on.
+		await closeLanIfEmpty(served);
+		if (served.mounts.size > 0) return;
+		closed(session, served);
+		await served.server.close();
+	};
+
+	const share = async (session: string, base: string): Promise<SharedListener | undefined> => {
+		const { serveHttp, lanAddresses } = await http.get();
+		const served = sessions.get(session);
+		const held = served?.mounts.get(base);
+		if (served === undefined || held === undefined) return undefined;
+		const address = served.address ?? lanAddresses(deps.interfaces())[0];
+		if (address === undefined) return undefined;
+		if (served.shared === undefined) {
+			try {
+				// The same port number on the LAN address, which keeps one link shape; an
+				// OS-chosen one when that address cannot take it.
+				served.shared = await serveHttp({ host: address, ports: [served.server.port, 0] });
+				served.address = address;
+			} catch {
+				served.shared = undefined;
+				served.address = undefined;
+				return undefined;
+			}
+		}
+		if (!served.sharedMounts.has(base)) {
+			const lan = served.shared.mount({ ...held.spec, prefix: base });
+			if (lan === undefined) return undefined;
+			served.sharedMounts.set(base, lan);
+		}
+		return { address, origin: served.shared.origin };
+	};
+
+	const unshare = async (session: string, base: string): Promise<void> => {
+		const served = sessions.get(session);
+		if (served === undefined) return;
+		// Stop sharing is a page leaving the network, not a counter going down: the prefix
+		// comes off the listener, and the socket closes only with the last page that shared.
+		await withdraw(served, base);
+		await closeLanIfEmpty(served);
+	};
+
+	/** Mount `request`'s prefix, or say why this session has none. */
+	const mount = async (request: MountRequest): Promise<MountOutcome> => {
+		const { spec } = request;
+		const opened = await open(spec.session);
+		if (opened.kind === "failed") return { kind: "refused", reason: opened.reason };
+		const { served } = opened;
+		if (served.mounts.has(spec.prefix)) {
+			return { kind: "refused", reason: `${spec.prefix} is already served on :${served.server.port}` };
+		}
+		const mounted = served.server.mount({
+			prefix: spec.prefix,
+			handler: spec.handler,
+			maxBodyBytes: spec.maxBodyBytes,
+			idle: spec.idle,
+		});
+		if (mounted === undefined) {
+			return { kind: "refused", reason: `${spec.prefix} is already served on :${served.server.port}` };
+		}
+		served.mounts.set(mounted.base, { mount: mounted, spec });
+		const handed: HttpMount = {
+			base: mounted.base,
+			origin: served.server.origin,
+			port: served.server.port,
+			release: () => release(spec.session, mounted.base),
+			share: () => share(spec.session, mounted.base),
+			unshare: () => unshare(spec.session, mounted.base),
+		};
+		return { kind: "mounted", mount: handed };
+	};
+
+	const closeSession = async (session: string): Promise<void> => {
+		const served = sessions.get(session);
+		remembered.delete(session);
+		if (served === undefined) return;
+		closed(session, served);
+		served.mounts.clear();
+		served.sharedMounts.clear();
+		await served.shared?.close();
+		served.shared = undefined;
+		await served.server.close();
+	};
+
+	return {
+		handle(request) {
+			// A payload this extension does not recognise is left unclaimed, so the caller
+			// is refused rather than answered with a page nobody serves.
+			if (typeof request?.spec?.handler !== "function" || typeof request.respond !== "function") return;
+			request.respond(mount(request));
+		},
+		closeSession,
+	};
+}

package/extensions/session-bus/commands.ts

@@ -12,11 +12,9 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { messageOf } from "../../lib/errors.ts";
 import { sanitizeLine } from "../../lib/format.ts";
-import { withPolledScreen } from "../../lib/screen-session.ts";
 import { formatJoin, formatStatus } from "./format.ts";
 import { COMMAND_NAME } from "./protocol.ts";
 import type { SessionBus } from "./runtime.ts";
-import { SessionListComponent } from "./tui.ts";
 
 /** How often the open board re-reads the bus. */
 const BOARD_POLL_MS = 1_000;
@@ -29,7 +27,7 @@ const BOARD_POLL_MS = 1_000;
  * record fresh, so a poll never has to write. Both reads are read-only: the
  * snapshot neither prunes nor refreshes, and the peek neither consumes nor marks.
  */
-function createBoardReader(bus: SessionBus): (screen: SessionListComponent) => Promise<void> {
+function createBoardReader(bus: SessionBus): (screen: SessionsScreen) => Promise<void> {
 	let busy = false;
 	return async (screen) => {
 		if (busy) return;
@@ -45,12 +43,19 @@ function createBoardReader(bus: SessionBus): (screen: SessionListComponent) => P
 	};
 }
 
+/** The mounted board's type, without loading the screen at registration. */
+type SessionsScreen = InstanceType<typeof import("./view/session-list.ts")["SessionListComponent"]>;
+
 /** Open the TUI board, and resolve when it closes. */
 async function openSessionsScreen(pi: ExtensionAPI, ctx: ExtensionCommandContext, bus: SessionBus): Promise<void> {
+	// The board is the TUI's: the text paths below and registration load neither it
+	// nor the dock screen's poll loop.
+	const { withPolledScreen } = await import("../../lib/screen-session.ts");
+	const { SessionListComponent } = await import("./view/session-list.ts");
 	await bus.start(ctx);
 	const [status, messages] = await Promise.all([bus.snapshot(), bus.peek()]);
 	const first = { status, messages };
-	let read: ((screen: SessionListComponent) => Promise<void>) | undefined;
+	let read: ((screen: SessionsScreen) => Promise<void>) | undefined;
 	await withPolledScreen(
 		pi,
 		ctx,
@@ -59,9 +64,9 @@ async function openSessionsScreen(pi: ExtensionAPI, ctx: ExtensionCommandContext
 			read = reader;
 			// The verbs repaint the board they belong to; their callbacks only run after
 			// construction, so a holder keeps the wiring one-directional.
-			const holder: { screen?: SessionListComponent } = {};
+			const holder: { screen?: SessionsScreen } = {};
 			const component = new SessionListComponent({
-				latest: () => first,
+				board: first,
 				theme: screen.theme,
 				callbacks: {
 					toggleWatch: async (armed) => {

package/extensions/session-bus/join-request.ts

@@ -7,9 +7,15 @@
  * the same limit `lib/plan-entry.ts` works around for plan mode — so the request
  * travels on `pi.events` and this module answers it with the runtime's own `join`.
  *
- * The answer always comes: every path here ends in `respond`, including a failure, so
- * a caller never waits on a listener that threw. The label also becomes Pi's session
- * name, because a team label and the footer have to agree.
+ * The answer always comes: every path here returns a result, including a failure, so
+ * a caller never waits on a listener that threw. A caller that asks for `name` also gets
+ * Pi's session name, because `/team join <label>` is the one door that means "call me
+ * this from now on"; the footer draws the roster label after every join either way, so a
+ * plain join changes the name on the bar without renaming the session.
+ *
+ * The claim is the answer, not the result: the bus starts and joins asynchronously, so
+ * this answers with the promise and stays claimed while it runs — which is what keeps
+ * the caller's fallback from settling a join that is still happening.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -21,20 +27,22 @@ export function registerJoinRequests(pi: ExtensionAPI, bus: SessionBus): void {
 	pi.events.on(TEAM_JOIN_REQUEST, (data) => {
 		const request = data as TeamJoinRequest | undefined;
 		if (!request || typeof request.respond !== "function") return;
-		void answer(request);
+		request.respond(answer(request));
 	});
 
-	async function answer(request: TeamJoinRequest): Promise<void> {
+	async function answer(request: TeamJoinRequest): Promise<JoinResult> {
 		let result: JoinResult;
 		try {
 			await bus.start(request.ctx);
-			const joined = await bus.join(request.input);
-			// One identity: the bus's label is also the name Pi's footer and `/resume` show.
-			if (request.input.label !== undefined) pi.setSessionName(joined.label);
+			// `name` is this wrapper's business, not the bus's: the record's label and Pi's
+			// session name are two facts, and only a caller that asked gets both changed.
+			const { name, ...input } = request.input;
+			const joined = await bus.join(input);
+			if (name === true && request.input.label !== undefined) pi.setSessionName(joined.label);
 			result = { ok: true, label: joined.label, watching: joined.watching };
 		} catch (error) {
 			result = { ok: false, error: messageOf(error) };
 		}
-		request.respond(result);
+		return result;
 	}
 }

package/extensions/session-bus/mail-watch.ts

@@ -12,11 +12,14 @@
  */
 
 import type { RepeatTimer } from "../../lib/timer.ts";
-import type { BusMessage } from "./types.ts";
+import type { BusMessage, InboxPeek } from "./types.ts";
 
 export interface MailWatchOptions {
-	/** This session's unread mail, read-only: nothing is consumed or marked. */
-	peek(): Promise<BusMessage[]>;
+	/**
+	 * This session's inbox, read-only: up to a page of mail whose ids are not `known`, and
+	 * the ids of every message still there. Nothing is consumed or marked.
+	 */
+	peek(known: ReadonlySet<string>): Promise<InboxPeek>;
 	/** The repeating timer behind the poll. */
 	interval: RepeatTimer;
 	/** Poll interval; 0 disables the ticker (tests). */
@@ -54,7 +57,10 @@ export function createMailWatch(options: MailWatchOptions): MailWatch {
 	let wake = false;
 	let stopTicker: (() => void) | undefined;
 	let pendingMail: BusMessage[] = [];
-	/** Ids already queued, reported, or consumed; a broadcast shares one id. */
+	/**
+	 * Ids already queued, reported, or consumed — pruned by what is still on disk, so it
+	 * holds exactly the announced mail an `inbox` call has not removed yet.
+	 */
 	let reported = new Set<string>();
 	let onWake: (() => void) | undefined;
 
@@ -68,24 +74,27 @@ export function createMailWatch(options: MailWatchOptions): MailWatch {
 	}
 
 	/**
-	 * Queue what arrived since the last poll, once, and wake a turn when this
-	 * session asked for one.
+	 * Queue what this watch has not announced, once, and wake a turn when this session
+	 * asked for one.
 	 *
-	 * The reported set is narrowed to the mail still on disk, so it is bounded by
-	 * the unread count rather than by the session's whole history; an id is unique
-	 * for good, so a message that was consumed can never be queued again.
+	 * The queue and the memory are pruned by what is still on disk, so `reported` is
+	 * bounded by the inbox rather than by a count: an id that leaves the inbox leaves the
+	 * set, and no id still on disk can be forgotten while it is there. A count was how a
+	 * backlog larger than one read made the watch forget an id it had already announced and
+	 * announce it again.
 	 */
 	async function pollOnce(): Promise<void> {
 		if (!armed) return;
-		const mail = await peek();
-		const unread = new Set(mail.map((message) => message.id));
-		reported = new Set([...reported].filter((id) => unread.has(id)));
-		// A message that expired or was consumed leaves the queue with its file.
+		const known = new Set(reported);
+		for (const message of pendingMail) known.add(message.id);
+		const { mail, unread } = await peek(known);
+		// The read names everything still in the inbox, which is a different question from
+		// what one page covered: a message that expired or was consumed leaves the queue and
+		// the memory with its file.
+		for (const id of reported) if (!unread.has(id)) reported.delete(id);
 		pendingMail = pendingMail.filter((message) => unread.has(message.id));
-		const queued = new Set(pendingMail.map((message) => message.id));
-		const fresh = mail.filter((message) => !reported.has(message.id) && !queued.has(message.id));
-		if (fresh.length === 0) return;
-		pendingMail = [...pendingMail, ...fresh];
+		if (mail.length === 0) return;
+		pendingMail = [...pendingMail, ...mail];
 		if (wake) onWake?.();
 	}
 

package/extensions/session-bus/protocol.ts

@@ -65,16 +65,28 @@ export function normalizeLimit(raw: unknown): number {
 	return Math.min(MAX_LIMIT, Math.max(1, Math.floor(raw)));
 }
 
-/** Repository-relative, posix-normalized paths, or an error. */
+/**
+ * Repository-relative, posix-normalized paths, or an error.
+ *
+ * A path that resolves to the repository root is handed on in the caller's own spelling
+ * rather than refused here: what it resolves to is the whole repository, and that
+ * refusal, with the sentence it is worded in, belongs to `resolve.ts` — one rule, one
+ * wording, and one module that owns both.
+ */
 export function normalizePaths(repoRoot: string, cwd: string, raw: unknown): { paths: string[] } | { error: string } {
 	if (!Array.isArray(raw) || raw.length === 0) return { error: "paths must contain at least one path." };
 	if (raw.length > MAX_PATHS) return { error: `at most ${MAX_PATHS} paths are allowed.` };
 	const paths: string[] = [];
 	for (const entry of raw) {
 		if (typeof entry !== "string" || entry.trim() === "") return { error: "every path must be a non-empty string." };
-		const absolute = resolve(cwd, entry.trim());
+		const given = entry.trim();
+		const absolute = resolve(cwd, given);
 		const rel = relative(repoRoot, absolute);
-		if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+		if (rel === "") {
+			if (!paths.includes(given)) paths.push(given);
+			continue;
+		}
+		if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
 			return { error: `path "${entry}" is outside the repository.` };
 		}
 		const normalized = rel.split(sep).join("/");

package/extensions/session-bus/resolve.ts

@@ -6,10 +6,14 @@
  * spelling inside the repository and the file it names are one claim, and a path
  * that leaves the repository is refused before anything is written.
  *
+ * The caller hands in paths that are already relative to the repository (the
+ * spelling rule is `protocol.ts`'s), so what is decided here is what they *resolve*
+ * to: the root itself, a target outside it, or a claim.
+ *
  * `lib/path.ts` owns the containment predicates; this owns the claim's shape.
  */
 
-import { isAbsolute, join, relative, sep } from "node:path";
+import { join, relative, sep } from "node:path";
 import { isInside, realPathOfNearest } from "../../lib/path.ts";
 
 /** A path this module declined, with the reason a caller can print. */
@@ -40,9 +44,6 @@ const ROOT_ITSELF = "is the repository, not a path in it";
 /** What a path outside the root resolves to. */
 const OUTSIDE = "does not resolve to a file in the repository";
 
-/** What an absolute path is refused for: it is not the claim's to place. */
-const ABSOLUTE = "is absolute; a claim is relative to the repository root";
-
 /**
  * Resolve `paths` against `root`, or refuse the first one that is not in it.
  *
@@ -53,9 +54,6 @@ export function resolveClaimPaths(root: string, paths: readonly string[]): Resol
 	const realRoot = realPathOfNearest(root);
 	const canonical: string[] = [];
 	for (const path of paths) {
-		// `join` would re-root an absolute path under the repository, which is not what
-		// a caller meant: refuse it rather than claim a directory it never named.
-		if (isAbsolute(path)) return { error: { path, reason: ABSOLUTE } };
 		const target = realPathOfNearest(join(root, path));
 		const rel = relative(realRoot, target);
 		if (rel === "") return { error: { path, reason: ROOT_ITSELF } };

package/extensions/session-bus/result.ts

@@ -7,39 +7,13 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import type { Component } from "@earendil-works/pi-tui";
 import { sanitizeLine } from "../../lib/format.ts";
 import { SEPARATORS } from "../../lib/tui/glyphs.ts";
-import { TailResult, type TailResultInput, type TailSection } from "../../lib/tui/tool.ts";
+import type { TailResultInput, TailSection } from "../../lib/tui/tool.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { type BusRow, busRowLine, count, sessionRows } from "./rows.ts";
 import type { SessionDetails } from "./types.ts";
 
-/**
- * The transcript block for an expanded `session` result: the shared tail block
- * over the board's rows, one section per entity group.
- */
-export class SessionResult implements Component {
-	private readonly view: TailResult<BusRow>;
-
-	constructor(input: TailResultInput<BusRow>, theme: Theme) {
-		this.view = new TailResult(input, theme);
-	}
-
-	/** Update in place so the transcript can reuse this component across renders. */
-	setInput(input: TailResultInput<BusRow>, theme: Theme): void {
-		this.view.setInput(input, theme);
-	}
-
-	invalidate(): void {
-		this.view.invalidate();
-	}
-
-	render(width: number): string[] {
-		return this.view.render(width);
-	}
-}
-
 /** One section of the expanded result. */
 function section(rows: BusRow[], label?: string): TailSection<BusRow> {
 	return { label, rows, more: 0, rowLine: busRowLine };