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

package/lib/qr.ts

@@ -0,0 +1,64 @@
+/**
+ * A QR code as terminal lines or an inline SVG.
+ *
+ * Uses the `qrcode` package only for the module matrix, then draws Unicode
+ * half-blocks for a terminal and hands the package's SVG to a page. The package
+ * loads on the first QR, not when an extension registers: a session that never
+ * shows one pays nothing for it. No ANSI is emitted; the caller decides colours,
+ * and the width is the matrix width plus a quiet zone.
+ *
+ * Two surfaces share this: `wechat` shows a login QR, and `plan` shows a review
+ * link a teammate can scan.
+ */
+
+interface QrModules {
+	size: number;
+	get(row: number, col: number): boolean;
+}
+
+/** QR error-correction level, one setting for both surfaces. */
+const ERROR_CORRECTION = "M" as const;
+
+/** Build the module matrix for `text`, loading `qrcode` on first use. */
+export async function qrMatrix(text: string): Promise<QrModules> {
+	const { default: QRCode } = await import("qrcode");
+	const qr = QRCode.create(text, { errorCorrectionLevel: ERROR_CORRECTION });
+	return qr.modules as unknown as QrModules;
+}
+
+/**
+ * The QR as terminal lines. Each string is exactly `matrix.size + 2 * quiet`
+ * columns wide (half-block characters are single width), so a caller can test
+ * `qrLines(text)[0].length` against the terminal width.
+ */
+export async function qrLines(text: string, options: { quiet?: number } = {}): Promise<string[]> {
+	const quiet = Math.max(0, options.quiet ?? 2);
+	const matrix = await qrMatrix(text);
+	const size = matrix.size;
+	const isDark = (row: number, col: number): boolean =>
+		row >= 0 && col >= 0 && row < size && col < size && matrix.get(row, col);
+
+	const lines: string[] = [];
+	for (let y = -quiet; y < size + quiet; y += 2) {
+		let line = "";
+		for (let x = -quiet; x < size + quiet; x += 1) {
+			const top = isDark(y, x);
+			const bottom = isDark(y + 1, x);
+			line += top && bottom ? "█" : top ? "▀" : bottom ? "▄" : " ";
+		}
+		lines.push(line);
+	}
+	return lines;
+}
+
+/**
+ * The QR as an inline SVG, for a page that can paste markup instead of pixels.
+ *
+ * The markup is generated by the package from a URL this process built, so it
+ * carries no caller-supplied text; a page still serves it under its own CSP,
+ * which allows no external image.
+ */
+export async function qrSvg(text: string): Promise<string> {
+	const { default: QRCode } = await import("qrcode");
+	return QRCode.toString(text, { type: "svg", errorCorrectionLevel: ERROR_CORRECTION, margin: 1 });
+}

package/lib/repo-key.ts

@@ -0,0 +1,74 @@
+/**
+ * The per-repository storage key that outlives one checkout.
+ *
+ * Two extensions file state by repository — `session-bus` its sessions, mail, and
+ * claims, `plan` its plans — and both must resolve the same key from any
+ * worktree, so a plan approved in `.pi/worktrees/x` is the same plan from the
+ * main checkout. The key is the repository's *common* git directory, which every
+ * worktree of that repository shares; outside a repository the working directory
+ * is the identity.
+ *
+ * Hashing keeps a mail directory, a claims directory, and a plans directory short
+ * enough to read and safe on every filesystem, while staying unique per
+ * repository.
+ */
+
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createExecRunner, gitCommonDir, repoRoot } from "./git/index.ts";
+
+/** Hex characters kept from the digest: collision-free in practice and short enough for a path. */
+export const REPO_KEY_LENGTH = 12;
+
+/** The key for one identity string, hashed and shortened. */
+export function repoKeyOf(value: string): string {
+	return createHash("sha256").update(canonical(value)).digest("hex").slice(0, REPO_KEY_LENGTH);
+}
+
+/**
+ * One path, one spelling.
+ *
+ * git prints the path it was told to work from, so a repository reached through a
+ * symlinked prefix reports a different common dir for the same repository. Two
+ * spellings would file one repository's plans and claims under two keys, so the
+ * real path is what gets hashed; a path that cannot be resolved keeps its own
+ * spelling rather than failing.
+ */
+function canonical(value: string): string {
+	try {
+		return realpathSync.native(value);
+	} catch {
+		return value;
+	}
+}
+
+/** A resolved repository identity. */
+export interface RepoKey {
+	/** Absolute repository root, or `cwd` when git did not answer. */
+	root: string;
+	/** The shared key, derived from the common git directory. */
+	key: string;
+	/**
+	 * Whether git resolved the repository. A caller that needs a *project-local*
+	 * location branches on this; one that only needs a stable directory does not.
+	 */
+	fromGit: boolean;
+}
+
+/**
+ * Resolve the repository identity for `cwd`.
+ *
+ * Never throws: without git, or when a git call fails, the working directory is
+ * the identity — which is what a caller outside a repository wants anyway.
+ */
+export async function repoKeyFor(pi: Pick<ExtensionAPI, "exec">, cwd: string): Promise<RepoKey> {
+	try {
+		const run = createExecRunner(pi);
+		const [common, root] = await Promise.all([gitCommonDir(run, cwd), repoRoot(run, cwd)]);
+		if (root) return { root, key: repoKeyOf(common ?? root), fromGit: true };
+	} catch {
+		// Fall through: no git, or a git call that failed, is the same answer here.
+	}
+	return { root: cwd, key: repoKeyOf(cwd), fromGit: false };
+}

package/lib/report.ts

@@ -2,12 +2,15 @@
  * The pending-report coordinator: how a live feature tells the model what
  * happened without interrupting it.
  *
- * A watcher match and a finished job follow one rule — report at the next turn,
- * and raise at most one triggered turn when the work opted into `wake`. The two
- * traps are subtle enough to have been re-derived once per extension:
+ * A watcher match, a finished job, and arriving mail follow one rule — report at
+ * the next turn, and raise at most one triggered turn per burst when the work
+ * opted into `wake`, as soon as the agent is idle. The three traps are subtle
+ * enough to have been re-derived once per extension:
  *
  * - a wake is only safe while the agent is idle, so an outcome that arrives
- *   mid-turn must be queued rather than sent;
+ *   mid-turn is queued rather than sent, and `agent_settled` retries it;
+ * - an outcome outlives the run it arrived in, so the retry asks
+ *   `wakeRequested()` rather than trusting the one call that queued it;
  * - between the triggered send and the `agent_start` it causes, the agent still
  *   looks idle, so a second outcome in that window must not trigger a second
  *   turn. `waking` closes that window.
@@ -33,6 +36,11 @@ export interface PendingReporterOptions<T> {
 	markReported(items: T[]): void;
 	/** Build the notice for one burst: model text plus renderer details. */
 	buildNotice(items: T[]): NoticeMessage;
+	/**
+	 * Whether any pending outcome asks for a triggered turn. Called by the settle
+	 * retry, so a mid-turn outcome still wakes once the agent is idle.
+	 */
+	wakeRequested(): boolean;
 	/** The notice's source, so only its own stale entries are pruned. */
 	source: string;
 	/** Runs after a wake turn was successfully requested, for an extra announcement. */
@@ -47,8 +55,8 @@ export interface PendingReporter {
 	sessionStart(): void;
 	/** A turn began: outcomes queue up, and none of them triggers a turn. */
 	agentStart(): void;
-	/** The turn settled: a later outcome may wake again. */
-	agentSettled(): void;
+	/** The turn settled: retry a wake it suppressed, unless it was aborted. */
+	agentSettled(event?: { aborted?: boolean }): void;
 	/** Report what is queued at the start of a turn, without triggering one. */
 	beforeAgentStart(): { message: NoticeMessage } | undefined;
 	/** Drop this source's older notices from the outgoing context. */
@@ -56,26 +64,29 @@ export interface PendingReporter {
 }
 
 export function createPendingReporter<T>(options: PendingReporterOptions<T>): PendingReporter {
-	const { wake, pending, markReported, buildNotice, source, onWoke } = options;
+	const { wake, pending, markReported, buildNotice, wakeRequested, source, onWoke } = options;
 	let busy = false;
 	let waking = false;
 
+	const report = (): void => {
+		if (busy || waking) return;
+		if (!wakeRequested()) return;
+		const items = pending();
+		if (items.length === 0) return;
+		try {
+			wake(buildNotice(items));
+		} catch {
+			// Reporting is best-effort; the next turn reports the same items.
+			return;
+		}
+		// Mark only after the send succeeded, so a throw changes nothing.
+		markReported(items);
+		waking = true;
+		onWoke?.(items);
+	};
+
 	return {
-		report: () => {
-			if (busy || waking) return;
-			const items = pending();
-			if (items.length === 0) return;
-			try {
-				wake(buildNotice(items));
-			} catch {
-				// Reporting is best-effort; the next turn reports the same items.
-				return;
-			}
-			// Mark only after the send succeeded, so a throw changes nothing.
-			markReported(items);
-			waking = true;
-			onWoke?.(items);
-		},
+		report,
 		sessionStart: () => {
 			busy = false;
 			waking = false;
@@ -83,9 +94,13 @@ export function createPendingReporter<T>(options: PendingReporterOptions<T>): Pe
 		agentStart: () => {
 			busy = true;
 		},
-		agentSettled: () => {
+		agentSettled: (event) => {
 			busy = false;
 			waking = false;
+			// An interrupted run is not a request to interrupt again; its outcomes
+			// stay queued for the next turn.
+			if (event?.aborted === true) return;
+			report();
 		},
 		beforeAgentStart: () => {
 			const items = pending();
@@ -103,10 +118,14 @@ export function createPendingReporter<T>(options: PendingReporterOptions<T>): Pe
 
 /** The session-scoped state a channel drives, narrowed to what its hooks need. */
 export interface PendingChannelRuntime {
-	/** Load this session's records; called on every session start. */
-	load(ctx: ExtensionContext): void;
-	/** Repaint the status chip. */
-	setStatus(ctx: ExtensionContext): void;
+	/**
+	 * Load this session's records on every session start. A promise is awaited, so a
+	 * runtime that resolves a repository or opens a store is fully loaded before the
+	 * report trigger is armed.
+	 */
+	load(ctx: ExtensionContext): void | Promise<void>;
+	/** Repaint the status chip; a runtime that publishes none omits it. */
+	setStatus?(ctx: ExtensionContext): void;
 	/** Release the session's resources; idempotent. */
 	shutdown(): Promise<void>;
 }
@@ -135,29 +154,29 @@ export function registerPendingChannel(
 	pi: Pick<ExtensionAPI, "on">,
 	{ reporter, runtime, onSessionStart, onSessionShutdown }: PendingChannelOptions,
 ): void {
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", async (_event, ctx) => {
 		reporter.sessionStart();
-		runtime.load(ctx);
+		await runtime.load(ctx);
 		onSessionStart?.(ctx);
 	});
 
 	// Tree navigation does not change the pending records; only repaint.
 	pi.on("session_tree", (_event, ctx) => {
-		runtime.setStatus(ctx);
+		runtime.setStatus?.(ctx);
 	});
 
 	pi.on("agent_start", () => {
 		reporter.agentStart();
 	});
-	pi.on("agent_settled", () => {
-		reporter.agentSettled();
+	pi.on("agent_settled", (event) => {
+		reporter.agentSettled(event);
 	});
 
 	// Report what is queued at the start of the next turn, without triggering one.
 	pi.on("before_agent_start", (_event, ctx) => {
 		const reported = reporter.beforeAgentStart();
 		if (!reported) return undefined;
-		runtime.setStatus(ctx);
+		runtime.setStatus?.(ctx);
 		return reported;
 	});
 

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
@@ -19,7 +16,6 @@ import { configSection, configValueAt, type JsonReadResult, SHARED_CONFIG_FILE }
 import type { WebSearchProviderEvent } from "./events.ts";
 import { pdfGuidance } from "./pdf.ts";
 import { getPiInvocation, type PiInvocation } from "./pi-invocation.ts";
-
 /** How a check came out. Only `missing` is worth interrupting a session for. */
 export type FindingSeverity = "ok" | "missing" | "degraded" | "info";
 
@@ -212,11 +208,12 @@ 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`."],
 	},
 	plan: {
-		optional: [gitCheck("project-local `.pi/plans` (otherwise plans land in the agent directory)")],
 		notes: ["Needs an interactive UI to enter plan mode."],
 	},
 	subagent: {
@@ -267,6 +264,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 		optional: [gitCheck("project-scope memory under the repository root")],
 	},
 	context: {},
+	"session-bus": {},
 	wechat: {
 		optional: [
 			{

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));
+}