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

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,135 @@
+/**
+ * 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;
+}
+
+/** Why a server went idle: no stream ever opened, or the last one left. */
+export type IdleReason = "first" | "last";
+
+/** 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;
+	/**
+	 * How long a server may stand with no stream ever opened, in ms.
+	 *
+	 * A page opened in a browser that never came up would otherwise hold its port for the
+	 * rest of the session. Omitted, the grace still waits for the first stream, which is
+	 * what a server whose page is opened by hand wants.
+	 */
+	firstMs?: number;
+	/** Called once no stream has been open for the grace that applied. */
+	onIdle: (reason: IdleReason) => 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;
+	/** Arm the grace for a server nobody may ever read. Does nothing without `firstMs`. */
+	start(): void;
+	/** 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 stream has attached at least once, so a departure is one to wait on. */
+	let sawStream = false;
+	/** The server asked for the first grace, so it may go idle without a reader. */
+	let started = false;
+
+	const standDown = (): void => {
+		cancelIdle?.();
+		cancelIdle = undefined;
+	};
+
+	/** Arm `ms` from now, unless a stream is open or a grace already runs. */
+	const arm = (ms: number, reason: IdleReason): void => {
+		if (deps.idle === undefined || (!started && !sawStream) || streams.size > 0 || cancelIdle !== undefined) return;
+		cancelIdle = timer(ms, () => {
+			cancelIdle = undefined;
+			// A tab that attached while the grace ran has already stood it down, but a
+			// second look costs nothing and keeps a race from closing a page being read.
+			if (streams.size === 0) deps.idle?.onIdle(reason);
+		});
+	};
+
+	return {
+		open(response) {
+			standDown();
+			sawStream = true;
+			const sink = createSink(response, () => {
+				if (!streams.delete(sink)) return;
+				const idle = deps.idle;
+				if (idle !== undefined) arm(idle.ms, "last");
+			});
+			streams.add(sink);
+			return sink;
+		},
+		size: () => streams.size,
+		start() {
+			const idle = deps.idle;
+			if (idle?.firstMs === undefined || started || sawStream) return;
+			started = true;
+			arm(idle.firstMs, "first");
+		},
+		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/plan-entry.ts

@@ -41,6 +41,17 @@ export const PLAN_CONSENT_SHORT =
 	"Enter read-only plan mode? Writes and mutating tools are disabled until you approve a plan.";
 export const PLAN_CONSENT_SHORT_ZH = "进入只读 plan 模式？批准计划前会禁用写入和修改。";
 
+/**
+ * The refusal a command shows when plan mode forbids what it does.
+ *
+ * Plan mode is read-only, so every extension whose command changes something says so the
+ * same way and names the action it is not doing: one sentence in `lib/`, because five
+ * copies is how the guarantee stops reading as one guarantee.
+ */
+export function planModeRefusal(action: string): string {
+	return `Plan mode is read-only. Approve the plan before ${action}.`;
+}
+
 /** What a caller sends on {@link PLAN_ENTER_REQUEST}. */
 export interface PlanEnterRequest {
 	/** The caller's context; `plan` uses it for the footer status. */

package/lib/policy.ts

@@ -9,11 +9,34 @@
  * — `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 { BOARD_READ_ACTION, READ_DOC_TOOL } from "./tool-names.ts";
+
+/**
+ * Whether a call to the `board` tool only reads it.
+ *
+ * The board is one tool over ten actions, so its `readOnlyHint` says "may write" and
+ * cannot answer this. The action can, and it travels in the call's input — and in the
+ * result's `details`, which is all a `tool_execution_end` event carries. Plan mode
+ * asks before the call and the todo nudge after it, so the answer lives here once.
+ */
+export function isBoardRead(call: unknown): boolean {
+	if (typeof call !== "object" || call === null) return false;
+	return (call as { action?: unknown }).action === BOARD_READ_ACTION;
+}
+
+/**
+ * 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,201 @@
+/**
+ * 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.
+ *
+ * The rule answers three things, not two: a record whose process is gone is `gone` at
+ * once, rather than aging into `quiet` for ten minutes while the paths it claimed stay
+ * held and the cards it held read `idle`.
+ *
+ * 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";
+import { isPidAlive, type LivenessFn, startTokenOf, type StartTokenFn } from "./spawn.ts";
+
+/** 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;
+	/**
+	 * The process that owns the record, when the record names one.
+	 *
+	 * Absent is "cannot tell": a record written before this existed, or by a mode that
+	 * is not a local process, is judged by its heartbeat alone rather than being called
+	 * dead on no evidence.
+	 */
+	pid?: number;
+	/** That process's start time, as the bus wrote it, when the record carries it. */
+	startToken?: string;
+	/**
+	 * 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 };
+}
+
+/** What a record's heartbeat and its process say together. */
+export type RosterState = "live" | "quiet" | "gone";
+
+/**
+ * What a record's heartbeat and its process say together.
+ *
+ * The fields the rule reads, rather than the whole roster row: `session-bus` judges its
+ * own records by the same rule without carrying a `mail` count it never shows.
+ */
+export type RosterFacts = Pick<RosterSession, "lastSeen" | "pid" | "startToken">;
+
+/**
+ * The host facts {@link rosterStateOf} reads, injectable so every branch is testable.
+ *
+ * The token spawns a process, so it is asked for only where liveness cannot decide.
+ */
+export interface RosterSeams {
+	alive?: LivenessFn;
+	token?: StartTokenFn;
+}
+
+/**
+ * What one record says about its session: alive, aged out, or attached to nothing.
+ *
+ * Three answers, in the order they are decided:
+ *
+ * - `gone` — the record names a process and that process is not running. A heartbeat
+ *   written ten seconds before a crash is not evidence the process exists, so death
+ *   outranks a fresh one.
+ * - `live` — the heartbeat is fresh. When the pid is alive too, the start token has not
+ *   been asked for yet: a session that wrote ten seconds ago is not the interesting
+ *   case for pid reuse, and `ps` costs a process.
+ * - `quiet` — the heartbeat has aged. If the pid is alive but its start time is not the
+ *   one the record wrote, the process is somebody else's and the session is `gone`
+ *   after all; a platform that cannot answer the start time leaves it at `quiet`.
+ */
+export function rosterStateOf(
+	session: RosterFacts,
+	now: number,
+	ttlMs = SESSION_TTL_MS,
+	seams: RosterSeams = {},
+): RosterState {
+	const alive = seams.alive ?? isPidAlive;
+	if (session.pid !== undefined && !alive(session.pid)) return "gone";
+	if (now - session.lastSeen <= ttlMs) return "live";
+	if (session.pid !== undefined && session.startToken !== undefined) {
+		const current = (seams.token ?? startTokenOf)(session.pid);
+		if (current !== undefined && current !== session.startToken) return "gone";
+	}
+	return "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;
+}
+
+/** A record's pid, read only when it is the shape a pid has. */
+function pidOf(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+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);
+		const pid = pidOf((parsed as { pid?: unknown }).pid);
+		const rawToken = (parsed as { startToken?: unknown }).startToken;
+		sessions.push({
+			id,
+			label,
+			mode,
+			lastSeen,
+			mail: await mailCount(dir, name.slice(0, -".json".length)),
+			...(pid === undefined ? {} : { pid }),
+			...(typeof rawToken === "string" && rawToken !== "" ? { startToken: rawToken } : {}),
+			...(watching === undefined ? {} : { watching }),
+		});
+	}
+	return sessions.sort((a, b) => a.label.localeCompare(b.label) || a.id.localeCompare(b.id));
+}