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

package/lib/http/serve.ts

@@ -0,0 +1,234 @@
+/**
+ * One loopback server per served surface: bind, accept, route, stream, idle,
+ * close.
+ *
+ * Both browser surfaces build the same socket around `lib/http`'s pieces, so the
+ * socket lives here: an extension supplies a handler that turns one request into
+ * one reply, and this module owns everything the request does not decide — the
+ * body cap, `HEAD` of a stream, the event-stream head, the port retry, the idle
+ * grace, and a close that is safe to call twice.
+ *
+ * The `Host` rule stays with each router: the allowlist is per extension, and for
+ * a shared review it grows while the server is up, so it cannot be passed in
+ * once.
+ *
+ * Value-only: the only state is what a returned closure carries.
+ */
+
+import {
+	createServer,
+	type IncomingHttpHeaders,
+	type IncomingMessage,
+	type Server,
+	type ServerResponse,
+} from "node:http";
+import type { ArmTimer } from "../timer.ts";
+import { jsonHeaders } from "./headers.ts";
+import { type ServeResponse, textResponse } from "./response.ts";
+import { bindHost, createCloser, openEventStream, respond } from "./server.ts";
+import { createSinks, type EventSink, type IdleGrace, type SinkRegistry } from "./sink.ts";
+
+/** One request as a route sees it: the envelope, and a body already capped. */
+export interface LoopbackRequest {
+	/** Upper-cased method, e.g. `GET`. */
+	method: string;
+	/** The request target, path and query. */
+	url: string;
+	/** Headers exactly as the socket carried them; the router applies its `Host` rule. */
+	headers: IncomingHttpHeaders;
+	/** The body, read up to the cap; `""` for every method when no cap was set. */
+	body: string;
+}
+
+/** What a route answers with. */
+export interface LoopbackReply {
+	/** The response to write. A `stream` one needs `openSink` to go with it. */
+	result: ServeResponse;
+	/**
+	 * Runs once, on whichever comes first of the response reaching the wire and the
+	 * socket closing — the point a route may settle a session without a client
+	 * seeing a dropped connection.
+	 */
+	afterResponse?: () => void;
+	/** Open the reply as an event stream; the returned function detaches it. */
+	openSink?: (sink: EventSink) => () => void;
+}
+
+/** One request in, one reply out. A throw is answered as a plain 500. */
+export type LoopbackHandler = (request: LoopbackRequest) => Promise<LoopbackReply> | LoopbackReply;
+
+export interface LoopbackOptions {
+	/** The address to bind; defaults to `127.0.0.1`. */
+	host?: string;
+	/** Ports tried in order, so a remembered port can fall back to an OS-chosen one. */
+	ports: readonly number[];
+	handler: LoopbackHandler;
+	/** Largest body accepted; absent, no body is read and a route sees `""`. */
+	maxBodyBytes?: number;
+	/** Grace after the last event stream leaves; omitted, the server waits for `close()`. */
+	idle?: IdleGrace;
+	/** The timer the idle grace is armed on. */
+	timer?: ArmTimer;
+}
+
+/** A bound loopback server. */
+export interface LoopbackServer {
+	/** The port it actually bound. */
+	port: number;
+	/** `http://<host>:<port>`, the address the caller prints. */
+	origin: string;
+	/**
+	 * End every open stream, stop the idle grace, and close the socket. Idempotent.
+	 *
+	 * A last frame is the caller's to send before it calls this: closing is not a
+	 * conclusion, and only the route knows what its readers were waiting for.
+	 */
+	close(): Promise<void>;
+}
+
+/** The one refusal this layer answers itself: a body it will not read. */
+const BODY_TOO_LARGE: ServeResponse = {
+	status: 413,
+	headers: { ...jsonHeaders(), Connection: "close" },
+	body: JSON.stringify({ error: "The request body is too large." }),
+};
+
+/** A reply that asked to stream but offered no sink cannot be served as events. */
+const STREAM_WITHOUT_SINK: ServeResponse = textResponse(500, "Internal error");
+
+/** A handler that threw, or a socket that failed after its head was written. */
+const INTERNAL_ERROR: ServeResponse = textResponse(500, "Internal error");
+
+/**
+ * Bind the first port that answers, falling back in order. Rejects with the last
+ * bind error, so a caller can still name the reason (`EADDRINUSE` and friends).
+ */
+async function bindFirst(server: Server, host: string, ports: readonly number[]): Promise<number> {
+	let failure: unknown;
+	for (const port of ports.length === 0 ? [0] : ports) {
+		try {
+			return await bindHost(server, host, port);
+		} catch (error) {
+			failure = error;
+		}
+	}
+	throw failure instanceof Error ? failure : new Error(`could not bind ${host}`);
+}
+
+/**
+ * Read a request body, stopping at `limit`. An oversize body is reported rather
+ * than destroyed, so it can still be answered 413 over the open socket instead of
+ * the client seeing a dropped connection.
+ */
+function readBody(request: IncomingMessage, limit: number): Promise<string | undefined> {
+	return new Promise((resolve) => {
+		const chunks: Buffer[] = [];
+		let size = 0;
+		let done = false;
+		const settle = (body: string | undefined): void => {
+			if (done) return;
+			done = true;
+			resolve(body);
+		};
+		request.on("data", (chunk: Buffer) => {
+			if (done) return;
+			size += chunk.length;
+			if (size > limit) {
+				chunks.length = 0;
+				request.pause();
+				settle(undefined);
+				return;
+			}
+			chunks.push(chunk);
+		});
+		request.on("end", () => settle(Buffer.concat(chunks).toString("utf-8")));
+		request.on("error", () => settle(undefined));
+	});
+}
+
+/** A function that runs at most once; `undefined` stays `undefined`. */
+function once(fn: (() => void) | undefined): (() => void) | undefined {
+	if (fn === undefined) return undefined;
+	let done = false;
+	return () => {
+		if (done) return;
+		done = true;
+		fn();
+	};
+}
+
+/** Route one request: read, dispatch, then answer, stream, or refuse. */
+async function answer(
+	request: IncomingMessage,
+	response: ServerResponse,
+	options: LoopbackOptions,
+	sinks: SinkRegistry,
+): Promise<void> {
+	const method = request.method ?? "GET";
+	const body = options.maxBodyBytes === undefined ? "" : await readBody(request, options.maxBodyBytes);
+	if (body === undefined) {
+		respond(request, response, BODY_TOO_LARGE);
+		return;
+	}
+	let reply: LoopbackReply;
+	try {
+		reply = await options.handler({ method, url: request.url ?? "/", headers: request.headers, body });
+	} catch {
+		reply = { result: INTERNAL_ERROR };
+	}
+	const settle = once(reply.afterResponse);
+	if (reply.result.stream === true && reply.openSink === undefined) {
+		respond(request, response, STREAM_WITHOUT_SINK, settle);
+		response.on("close", () => settle?.());
+		return;
+	}
+	// A `HEAD` of a stream is a plain response: there is no body to hold open, and
+	// the client would otherwise wait on frames it asked not to get.
+	if (reply.openSink !== undefined && method.toUpperCase() !== "HEAD") {
+		openEventStream(response, reply.result);
+		const sink = sinks.open(response);
+		const detach = reply.openSink(sink);
+		let closed = false;
+		const finish = (): void => {
+			if (closed) return;
+			closed = true;
+			detach();
+			sink.end();
+			settle?.();
+		};
+		request.on("close", finish);
+		response.on("close", finish);
+		return;
+	}
+	respond(request, response, reply.result, settle);
+	response.on("close", () => settle?.());
+}
+
+/** Start a server on the first port that binds, and close it idempotently. */
+export async function serveLoopback(options: LoopbackOptions): Promise<LoopbackServer> {
+	const host = options.host ?? "127.0.0.1";
+	const sinks = createSinks({ idle: options.idle, timer: options.timer });
+	const server = createServer((request, response) => {
+		// A page that walks away mid-frame must not take the session down.
+		response.on("error", () => {});
+		void answer(request, response, options, sinks).catch(() => {
+			// A route that failed after its head was written can only be cut off; ending
+			// the socket beats a client waiting on a reply that will not come.
+			if (!response.writableEnded) response.end();
+		});
+	});
+	const port = await bindFirst(server, host, options.ports);
+	const closeServer = createCloser(server);
+	let closed = false;
+	return {
+		port,
+		origin: `http://${host}:${port}`,
+		close: async () => {
+			if (closed) return;
+			closed = true;
+			// Streams end first: a connected page must not hold the close open.
+			sinks.endAll();
+			await closeServer();
+		},
+	};
+}

package/lib/http/server.ts

@@ -1,15 +1,17 @@
 /**
- * The socket seam shared by the browser servers: bind, write a response out,
- * and close.
+ * The socket primitives `serveLoopback` is built from: bind, write a response
+ * out, and close.
  *
- * Everything here is behavior a caller cannot get right by accident: a bind on
- * an address the caller names (loopback unless it asked for more), an
- * accept-level `error` listener so a transient failure cannot take the host
- * down, a `HEAD` that sends headers and no body, a `filePath` response streamed
- * instead of buffered, a `stream` response opened as an event stream, and a
- * close that is safe to call twice and drops keep-alive connections. What each
- * server does *around* this — which frames an event stream carries, request
- * bodies, session settling — stays with that server.
+ * Internal to the layer: an extension starts a server through
+ * `serveLoopback`, which composes these, so this module is reached from `lib/http`
+ * and its own suite — not from the barrel. Everything here is behavior a caller
+ * cannot get right by accident: a bind on an address the caller names (loopback
+ * unless it asked for more), an accept-level `error` listener so a transient
+ * failure cannot take the host down, a `HEAD` that sends headers and no body, a
+ * `filePath` response streamed instead of buffered, a `stream` response opened as
+ * an event stream, and a close that is safe to call twice and drops keep-alive
+ * connections. What a server does *around* this — which frames an event stream
+ * carries, request bodies, session settling — stays with `serve.ts`.
  */
 
 import { createReadStream } from "node:fs";

package/lib/http/sink.ts

@@ -0,0 +1,110 @@
+/**
+ * The event streams one loopback server keeps open, and the idle grace that ends
+ * a server nobody is reading.
+ *
+ * The sink is the only thing a route writes: it owns liveness, so a frame after
+ * the end is a no-op and `end` twice is fine, and no caller has to ask the raw
+ * response whether it is still writable. The registry is the one place that knows
+ * how many are open, which is exactly what an idle policy needs — the last one
+ * leaving arms the grace, and a reload re-attaching stands it down.
+ *
+ * Value-only: the only state is what the returned closure carries.
+ */
+
+import type { ServerResponse } from "node:http";
+import { type ArmTimer, defaultTimer } from "../timer.ts";
+
+/** One open event stream, as a route writes it. */
+export interface EventSink {
+	/** Write one frame; a no-op once the stream has ended. */
+	write(frame: string): void;
+	/** End the stream, optionally with a last frame; safe to call twice. */
+	end(frame?: string): void;
+}
+
+/** The idle policy a server was given, or none. */
+export interface IdleGrace {
+	/** How long the last stream's departure is held, in ms. */
+	ms: number;
+	/** Called once no stream has been open for `ms`. */
+	onIdle: () => void;
+}
+
+/** What the registry needs besides the streams themselves. */
+export interface SinkDeps {
+	/** Grace after the last stream leaves; omitted, the server waits for `endAll`. */
+	idle?: IdleGrace;
+	/** The timer the grace is armed on; defaults to an unref'd one. */
+	timer?: ArmTimer;
+}
+
+/** The open streams of one loopback server. */
+export interface SinkRegistry {
+	/** Open a sink over one response; ending it starts the idle grace. */
+	open(response: ServerResponse): EventSink;
+	/** How many streams are open. */
+	size(): number;
+	/** End every open stream, because the server is closing. */
+	endAll(): void;
+}
+
+export function createSinks(deps: SinkDeps = {}): SinkRegistry {
+	const streams = new Set<EventSink>();
+	const timer = deps.timer ?? defaultTimer;
+	let cancelIdle: (() => void) | undefined;
+	/** A grace armed before any page ever attached would close a server nobody opened. */
+	let sawStream = false;
+
+	const standDown = (): void => {
+		cancelIdle?.();
+		cancelIdle = undefined;
+	};
+
+	const arm = (): void => {
+		const idle = deps.idle;
+		if (idle === undefined || !sawStream || streams.size > 0 || cancelIdle !== undefined) return;
+		cancelIdle = timer(idle.ms, () => {
+			cancelIdle = undefined;
+			if (streams.size === 0) deps.idle?.onIdle();
+		});
+	};
+
+	return {
+		open(response) {
+			standDown();
+			sawStream = true;
+			const sink = createSink(response, () => {
+				if (streams.delete(sink)) arm();
+			});
+			streams.add(sink);
+			return sink;
+		},
+		size: () => streams.size,
+		endAll() {
+			standDown();
+			const open = [...streams];
+			streams.clear();
+			for (const sink of open) sink.end();
+		},
+	};
+}
+
+/** A sink over one response, released from its registry exactly once. */
+function createSink(response: ServerResponse, release: () => void): EventSink {
+	let ended = false;
+	return {
+		write(frame) {
+			if (ended || response.writableEnded || response.destroyed) return;
+			response.write(frame);
+		},
+		end(frame) {
+			if (ended) return;
+			ended = true;
+			if (!response.writableEnded && !response.destroyed) {
+				if (frame === undefined) response.end();
+				else response.end(frame);
+			}
+			release();
+		},
+	};
+}

package/lib/http/token.ts

@@ -0,0 +1,38 @@
+/**
+ * The bearer token a loopback page carries in its URL.
+ *
+ * Any page a browser can open is a page any local process can call, so the token
+ * is the only thing standing between a served surface and a stranger's `fetch`:
+ * it is 128 random bits, minted once per server, and it is compared in constant
+ * time. Both halves live here rather than in each extension, because a page that
+ * mints its own secret and a page that verifies one another way is exactly the
+ * drift this directory exists to prevent.
+ *
+ * The comparison digests both sides first, so a wrong-length guess costs the same
+ * as a wrong-value one and the length of the real token is not observable.
+ */
+
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+
+/** Bytes of entropy per token. Hex-encoded, so a token is twice this many characters. */
+export const TOKEN_BYTES = 16;
+
+/** One fresh 128-bit token, as hex. */
+export function mintToken(): string {
+	return randomBytes(TOKEN_BYTES).toString("hex");
+}
+
+/**
+ * Whether `given` is the token `expected`.
+ *
+ * An empty `expected` never matches: a caller that failed to mint one must not
+ * accept the empty string a request without a token presents.
+ */
+export function tokenMatches(expected: string, given: string): boolean {
+	if (expected === "") return false;
+	return timingSafeEqual(sha256Of(expected), sha256Of(given));
+}
+
+function sha256Of(value: string): Buffer {
+	return createHash("sha256").update(value).digest();
+}

package/lib/policy.ts

@@ -9,11 +9,21 @@
  * — `bash`, MCP servers, future extension tools — rather than relying on
  * `write`/`edit` being the only mutators.
  *
- * No runtime dependencies: the caller supplies the annotation lookup. Only the
- * MCP hint type is imported (type-only).
+ * No host dependency beyond the annotation type: the caller supplies the
+ * annotation lookup, and the one reader name comes from `tool-names.ts`, so this
+ * module stays value-only.
  */
 
 import type { ToolAnnotations } from "@earendil-works/pi-coding-agent";
+import { READ_DOC_TOOL } from "./tool-names.ts";
+
+/**
+ * Tools that only read the workspace: the built-in structured readers and the
+ * packaged document reader. One list for the read-only consumers — plan mode's
+ * allowlist, rewind's snapshot policy, and subagent's read-only child allowlist —
+ * so adding a reader is one edit rather than three.
+ */
+export const WORKSPACE_READERS = ["read", "grep", "find", "ls", READ_DOC_TOOL] as const;
 
 interface ReadOnlyPolicyOptions {
 	/** Tools allowed regardless of annotations (structured readers, plan tracker). */

package/lib/requirements.ts

@@ -1,11 +1,8 @@
 /**
- * Per-extension runtime prerequisites.
- *
- * One place that says what each extension needs in order to actually work, plus
- * a pure probe over injected seams. `doctor` reports on this table, and the
- * extensions that own an external dependency format their error text from the
- * same entries, so the hint a model sees in a tool error and the hint `doctor`
- * prints cannot drift apart.
+ * Per-extension runtime prerequisites: one place that says what each extension needs
+ * in order to actually work, plus a pure probe over injected seams. `doctor` reports
+ * on this table, and the extensions that own an external dependency format their error
+ * text from the same entries, so a tool error and a `doctor` line cannot drift apart.
  *
  * The table is data: no module state, no I/O, no host access. Everything a probe
  * needs (running a command, reading a file, loading an optional package, the
@@ -211,6 +208,8 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	},
 	todo: {},
 	goal: {},
+	board: {},
+	team: { notes: ["`assign` needs `session-bus` loaded to deliver a handoff; without it the card is untouched."] },
 	check: {
 		notes: ["Runs the project's detected command through a shell; a stack with no detector needs `check.command`."],
 	},

package/lib/session-label.ts

@@ -0,0 +1,64 @@
+/**
+ * The session label: the one name another session addresses this one by.
+ *
+ * `session-bus` settles a label for every session — the Pi session name, else the
+ * working directory's basename, else the id — and the board records the same name
+ * on a card it claims, so the two surfaces agree on who "billing-core" is without
+ * the board reading the bus. The rules are here rather than in either extension
+ * because a label is a shared vocabulary: it is displayed, it is a send target, and
+ * it is stored in a card file that outlives one session.
+ *
+ * Value-only: no state, no I/O.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { sanitizeLine } from "./format.ts";
+
+/** Longest label, in characters, that a session may be addressed by. */
+export const MAX_LABEL = 40;
+
+/**
+ * A safe label, used both for display and as a target.
+ *
+ * Flattened to one line and capped, so a name can never wrap a row or open a
+ * second line in a page; an empty one falls back rather than leaving a blank chip.
+ */
+export function normalizeLabel(raw: string | undefined, fallback: string): string {
+	const text = sanitizeLine(raw ?? "")
+		.replace(/\s+/g, " ")
+		.trim();
+	return (text || fallback).slice(0, MAX_LABEL);
+}
+
+/** A short, display-only suffix for a session id. */
+export function shortId(id: string): string {
+	const clean = id.replace(/[^a-zA-Z0-9]/g, "");
+	return (clean || id).slice(-6);
+}
+
+/**
+ * The automatic label, before uniqueness is applied.
+ *
+ * The bus appends a suffix when two live sessions share one; that decision belongs
+ * to the registry, so this is only the name a session would pick for itself.
+ */
+export function defaultLabel(sessionName: string | undefined, cwd: string, id: string): string {
+	const directory = cwd.split(/[\\/]/).filter(Boolean).at(-1);
+	const base = normalizeLabel(sessionName, normalizeLabel(directory, "session"));
+	return normalizeLabel(base, `session-${shortId(id)}`);
+}
+
+/**
+ * Pi's session name, which is the first choice for a label.
+ *
+ * A host that has no session name, or refuses the call, yields `undefined` rather
+ * than an error: a label is a convenience, and a session that cannot name itself
+ * still works under the fallback chain above.
+ */
+export function sessionNameOf(ctx: Pick<ExtensionContext, "sessionManager">): string | undefined {
+	try {
+		return ctx.sessionManager.getSessionName();
+	} catch {
+		return undefined;
+	}
+}

package/lib/session-roster.ts

@@ -0,0 +1,130 @@
+/**
+ * Who is on this repository's session bus, read as data.
+ *
+ * The Team tab lists teammates, and `session-bus` owns those records. Neither
+ * extension may import the other, and the board must keep working when the bus is
+ * not loaded — so the records are read where the bus already put them,
+ * `<agentDir>/session-bus/<repo-key>/`, as files rather than through its code. The
+ * directory names, the record fields this reader trusts, and the liveness rule live
+ * here once, and `session-bus` imports them, so a layout change cannot land in one
+ * copy and not the other.
+ *
+ * A missing directory is an answer, not an error: it means no session has ever
+ * joined this repository, and a caller renders that differently from an empty bus.
+ *
+ * Pure I/O, no state: one read answers one caller, and nothing is cached — a
+ * heartbeat is ten seconds old at most, and the caller polls on its own clock.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** The bus directory under the agent dir, `session-bus`. */
+export const BUS_DIR_NAME = "session-bus";
+/** One file per session inside it. */
+export const SESSIONS_DIR_NAME = "sessions";
+/** One directory per session, holding its mail. */
+export const INBOX_DIR_NAME = "inbox";
+/** How long a record's heartbeat stays believable: the rule the bus prunes by. */
+export const SESSION_TTL_MS = 10 * 60_000;
+
+/** One session as the page shows it. The rest of the record stays on disk. */
+export interface RosterSession {
+	id: string;
+	label: string;
+	mode: string;
+	/** When the session last proved it was alive. */
+	lastSeen: number;
+	/** Messages waiting in its inbox. */
+	mail: number;
+	/**
+	 * Whether the session is listening for mail, when its record says.
+	 *
+	 * Absent is "not listening": a record written before this existed and a session that
+	 * stopped listening read the same way, so a reader never claims a peer will be reached.
+	 */
+	watching?: { armed: boolean; wake: boolean };
+}
+
+/** Whether a record's heartbeat is fresh enough to call the session live. */
+export function rosterStateOf(session: RosterSession, now: number, ttlMs = SESSION_TTL_MS): "live" | "quiet" {
+	return now - session.lastSeen <= ttlMs ? "live" : "quiet";
+}
+
+/** The fields this reader trusts; anything else in the file is the bus's business. */
+interface SessionPayload {
+	id: string;
+	label: string;
+	mode: string;
+	lastSeen: number;
+}
+
+function isSessionPayload(value: unknown): value is SessionPayload {
+	if (typeof value !== "object" || value === null) return false;
+	const { id, label, mode, lastSeen } = value as Record<string, unknown>;
+	return (
+		typeof id === "string" && typeof label === "string" && typeof mode === "string" && typeof lastSeen === "number"
+	);
+}
+
+/**
+ * The listening field, read only when it is the shape the bus writes.
+ *
+ * A malformed field is not a reason to hide a teammate: the row still draws, and the
+ * only thing lost is the claim that mail will reach it. Exported because the field is
+ * the record's, and `lib/session-tool.ts` reads the same one over the tool rather than
+ * over the files — one reader for one shape.
+ */
+export function watchingOf(value: unknown): { armed: boolean; wake: boolean } | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	const { armed, wake } = value as Record<string, unknown>;
+	return typeof armed === "boolean" && typeof wake === "boolean" ? { armed, wake } : undefined;
+}
+
+/** How many message files one session's inbox holds. A missing inbox is empty. */
+async function mailCount(dir: string, stem: string): Promise<number> {
+	try {
+		const entries = await readdir(join(dir, INBOX_DIR_NAME, stem));
+		return entries.filter((name) => name.endsWith(".json")).length;
+	} catch {
+		return 0;
+	}
+}
+
+/**
+ * Every session the bus has recorded for one repository, or `undefined` when the bus
+ * has never been used here.
+ *
+ * One file that does not parse is skipped rather than thrown: a roster with three
+ * good sessions is worth more than an error about the fourth.
+ */
+export async function readRoster(dir: string): Promise<RosterSession[] | undefined> {
+	let names: string[];
+	try {
+		names = await readdir(join(dir, SESSIONS_DIR_NAME));
+	} catch {
+		return undefined;
+	}
+	const sessions: RosterSession[] = [];
+	for (const name of names) {
+		if (!name.endsWith(".json")) continue;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(await readFile(join(dir, SESSIONS_DIR_NAME, name), "utf-8"));
+		} catch {
+			continue;
+		}
+		if (!isSessionPayload(parsed)) continue;
+		const { id, label, mode, lastSeen } = parsed;
+		const watching = watchingOf((parsed as { watching?: unknown }).watching);
+		sessions.push({
+			id,
+			label,
+			mode,
+			lastSeen,
+			mail: await mailCount(dir, name.slice(0, -".json".length)),
+			...(watching === undefined ? {} : { watching }),
+		});
+	}
+	return sessions.sort((a, b) => a.label.localeCompare(b.label) || a.id.localeCompare(b.id));
+}