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

package/lib/board/rules.ts

@@ -0,0 +1,437 @@
+/**
+ * The card lifecycle: every transition, as a pure function of the card, the
+ * operation, who asked, the clock, and the board's other cards.
+ *
+ * One table decides who may do what — the tool, the router, the page, and `team` all
+ * route through {@link applyOp} — so a lane change cannot be reachable from one
+ * surface and refused from another. Nothing here touches the filesystem or the bus:
+ * ownership is advisory (the bus's path claims are the lock), and the store owns the
+ * compare-and-set that makes a concurrent writer lose.
+ *
+ * The board index is a parameter rather than a lookup because three operations need a
+ * *different* card: a claim or a move is refused while a dependency is unfinished, and
+ * a drop is refused while somebody waits on the card. `lib/board/links.ts` answers
+ * those questions; this module decides what to do with the answer.
+ *
+ * Two shapes of failure, and the difference matters. A refusal is `{ ok: false }`
+ * with the reason, and the caller returns the card untouched. A *no-op* is
+ * `{ ok: true, changed: false }`: the operation's preconditions already hold
+ * (claiming a card you already hold), so nothing is written and the revision does
+ * not move.
+ *
+ * `add` is {@link createCard} rather than an operation, because it has no card to
+ * transition — and because a card is born `todo` with no owner, which is the one
+ * state the other operations never produce.
+ */
+
+import {
+	type Card,
+	type CardOwner,
+	type CardStatus,
+	cardRef,
+	DEFAULT_PRIORITY,
+	dependsOf,
+	MAX_LOG,
+	MAX_NOTES,
+	normalizeBlockedBy,
+	normalizeNote,
+	normalizePathHints,
+	normalizePlanPath,
+	normalizePriority,
+	normalizeTitle,
+	type Priority,
+	priorityOf,
+} from "./card.ts";
+import { type BoardIndex, dependedOn, normalizeDepends, waitingOn } from "./links.ts";
+
+/** Who is attempting an operation: a session when it has one, and the label it is addressed by. */
+export interface Actor {
+	id?: string;
+	label: string;
+}
+
+/** One named mutation of one card. */
+export type CardOp =
+	| { kind: "claim" }
+	/**
+	 * Hand a card to `to`, and — from the page, which cannot message a peer — a note that
+	 * says so. `team assign` sends a handoff instead and passes none.
+	 */
+	| { kind: "assign"; to: Actor; note?: unknown }
+	| { kind: "release" }
+	/**
+	 * Change lane. `blockedBy` says what a block waits on, and `landed` says which commit
+	 * closed a card: both are read only by the lane they belong to, and both are optional,
+	 * because a card may be blocked with nothing recorded and a `done` card may predate the
+	 * field or live outside a repository.
+	 */
+	| { kind: "move"; status: Exclude<CardStatus, "todo">; blockedBy?: unknown; landed?: { commit: string } }
+	// `text` and `path` are whatever the model sent: `card.ts` validates them, and the
+	// refusal it produces is the one the caller shows.
+	| { kind: "note"; text: unknown }
+	| { kind: "plan"; path: unknown }
+	// Every field but `kind` is optional, and an absent one is left as it was: the page
+	// sends the three it can show, and omitting a link must not clear it.
+	| { kind: "edit"; title: unknown; paths: unknown; priority: unknown; dependsOn: unknown }
+	| { kind: "reclaim" }
+	/**
+	 * Record that the card was offered to the team: `team offer` broadcasts it on the bus
+	 * and then writes this, because an event nobody answers otherwise leaves no trace.
+	 */
+	| { kind: "offer" }
+	/**
+	 * Set a finished card aside: the store moves its file out of the board, and the record
+	 * itself is unchanged, because the pile its file lies in is the whole of the state.
+	 */
+	| { kind: "archive" }
+	| { kind: "drop" };
+
+/** What an operation did: the new card, or the reason it was refused. */
+export type OpResult = { ok: true; card: Card; changed: boolean } | { ok: false; error: string };
+
+/** A card's first state: `todo`, no owner, one note at most. */
+export function createCard(
+	id: string,
+	input: { title: string; paths: string[]; note?: string; priority?: Priority },
+	actor: Actor,
+	now: number,
+): Card {
+	return {
+		v: 1,
+		id,
+		title: input.title,
+		status: "todo",
+		paths: [...input.paths],
+		// A new card says its priority out loud, even when it is the ordinary one, so a
+		// file on disk tells a reader the whole story without a default to know.
+		priority: input.priority ?? DEFAULT_PRIORITY,
+		notes: input.note === undefined ? [] : [{ by: actor.label, at: now, text: input.note }],
+		notesDropped: 0,
+		// A card is born in `todo`, and that is a transition like any other: a reader asking
+		// "how long has this been waiting" gets an answer rather than an absence.
+		log: [{ status: "todo", at: now, by: actor.label }],
+		logDropped: 0,
+		rev: 1,
+		createdAt: now,
+		updatedAt: now,
+		by: actor.label,
+	};
+}
+
+/**
+ * Whether `actor` is the owner of `card`.
+ *
+ * The id decides when both sides have one — a session that renamed itself is still
+ * the same holder — and the label decides otherwise, case-insensitively, the way
+ * the bus resolves a target.
+ */
+export function holds(card: Card, actor: Actor): boolean {
+	const owner = card.owner;
+	if (owner === undefined) return false;
+	if (owner.id !== undefined && actor.id !== undefined) return owner.id === actor.id;
+	return owner.label.toLowerCase() === actor.label.toLowerCase();
+}
+
+/**
+ * Apply one operation.
+ *
+ * A refused operation returns the reason and no card: the caller already holds the
+ * card it read, and a "refused" copy of it would be a second version of the truth.
+ */
+export function applyOp(card: Card, op: CardOp, actor: Actor, now: number, board: BoardIndex): OpResult {
+	switch (op.kind) {
+		case "claim":
+			return claim(card, actor, now, board);
+		case "assign":
+			return assign(card, op.to, op.note, actor, now, board);
+		case "release":
+			return release(card, actor, now);
+		case "move":
+			return move(card, op, actor, now, board);
+		case "note":
+			return note(card, op.text, actor, now);
+		case "plan":
+			return plan(card, op.path, actor, now);
+		case "edit":
+			return edit(card, op, actor, now, board);
+		case "reclaim":
+			return reclaim(card, actor, now);
+		case "offer":
+			return offer(card, actor, now, board);
+		case "archive":
+			return archive(card);
+		case "drop":
+			return drop(card, actor, board);
+	}
+}
+
+function claim(card: Card, actor: Actor, now: number, board: BoardIndex): OpResult {
+	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; it cannot be claimed.` };
+	if (holds(card, actor)) return { ok: true, card, changed: false };
+	if (card.owner !== undefined) return { ok: false, error: heldBy(card) };
+	const waiting = waitingOn(card, board);
+	if (waiting !== undefined) return { ok: false, error: waiting };
+	return {
+		ok: true,
+		card: write(card, actor, now, { status: "doing", owner: ownerOf(actor), offeredAt: undefined }),
+		changed: true,
+	};
+}
+
+function assign(card: Card, to: Actor, rawNote: unknown, actor: Actor, now: number, board: BoardIndex): OpResult {
+	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; it cannot be assigned.` };
+	if (card.owner !== undefined && !holds(card, to)) return { ok: false, error: heldBy(card) };
+	if (holds(card, to) && card.status === "doing") return { ok: true, card, changed: false };
+	const waiting = waitingOn(card, board);
+	if (waiting !== undefined) return { ok: false, error: waiting };
+	const fields: Partial<Card> = { status: "doing", owner: ownerOf(to), offeredAt: undefined };
+	if (rawNote !== undefined) {
+		const parsed = normalizeNote(rawNote);
+		if ("error" in parsed) return { ok: false, error: parsed.error };
+		// One revision, not two: the history says who it went to in the same write that
+		// recorded the owner, so a reader never sees the assignment without the sentence.
+		Object.assign(fields, appendNote(card, actor, now, parsed.text));
+	}
+	return { ok: true, card: write(card, actor, now, fields), changed: true };
+}
+
+function release(card: Card, actor: Actor, now: number): OpResult {
+	// Finished work is history: every other transition refuses it, and a release that did
+	// not would be the one way a `done` card could go backwards — reopening the order a
+	// dependency was recorded against.
+	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; it cannot be released.` };
+	if (card.owner === undefined) return { ok: false, error: `${cardRef(card.id)} is not claimed.` };
+	if (!holds(card, actor)) return { ok: false, error: `${heldBy(card)} Release is the owner's decision.` };
+	return {
+		ok: true,
+		card: write(card, actor, now, { status: "todo", owner: undefined, offeredAt: undefined }),
+		changed: true,
+	};
+}
+
+function move(
+	card: Card,
+	op: Extract<CardOp, { kind: "move" }>,
+	actor: Actor,
+	now: number,
+	board: BoardIndex,
+): OpResult {
+	const status = op.status;
+	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; it cannot be moved.` };
+	if (card.owner === undefined) {
+		return { ok: false, error: `${cardRef(card.id)} is unclaimed; claim it before moving it to ${status}.` };
+	}
+	if (!holds(card, actor)) return { ok: false, error: `${heldBy(card)} Only its owner can move it.` };
+	// A block's reason is checked before the no-op: a caller that repeats a move with a new
+	// sentence meant to change it, and a refusal is clearer than a silent nothing.
+	let blockedBy: string | undefined;
+	if (status === "blocked" && op.blockedBy !== undefined) {
+		const parsed = normalizeBlockedBy(op.blockedBy);
+		if ("error" in parsed) return { ok: false, error: parsed.error };
+		blockedBy = parsed.blockedBy;
+	}
+	if (card.status === status && blockedBy === undefined) return { ok: true, card, changed: false };
+	// Parking is what a link is for, so only the two lanes that put a card back in flight
+	// are gated: a card that waits may be blocked, it may not be taken or finished.
+	if (status !== "blocked") {
+		const waiting = waitingOn(card, board);
+		if (waiting !== undefined) return { ok: false, error: waiting };
+	}
+	return { ok: true, card: write(card, actor, now, laneFields(status, blockedBy, op, now)), changed: true };
+}
+
+/**
+ * The fields one lane change writes.
+ *
+ * `blockedBy` belongs to `blocked` alone: a card that leaves for `doing` or `done` has
+ * had its decision or stopped needing one, and a stale sentence would be read as a
+ * current one. `landed` belongs to `done` alone, and only when the caller could name a
+ * commit — a board outside git still finishes cards, it just cannot say with what.
+ */
+function laneFields(
+	status: Exclude<CardStatus, "todo">,
+	blockedBy: string | undefined,
+	op: Extract<CardOp, { kind: "move" }>,
+	now: number,
+): Partial<Card> {
+	const fields: Partial<Card> = { status };
+	if (status === "blocked") {
+		if (blockedBy !== undefined) fields.blockedBy = blockedBy;
+	} else {
+		fields.blockedBy = undefined;
+	}
+	if (status === "done" && op.landed !== undefined) fields.landed = { commit: op.landed.commit, at: now };
+	return fields;
+}
+
+function note(card: Card, raw: unknown, actor: Actor, now: number): OpResult {
+	const parsed = normalizeNote(raw);
+	if ("error" in parsed) return { ok: false, error: parsed.error };
+	return { ok: true, card: write(card, actor, now, appendNote(card, actor, now, parsed.text)), changed: true };
+}
+
+/** A card's notes after one more, with the oldest dropped and counted. */
+function appendNote(card: Card, actor: Actor, now: number, text: string): Pick<Card, "notes" | "notesDropped"> {
+	const notes = [...card.notes, { by: actor.label, at: now, text }];
+	const overflow = Math.max(0, notes.length - MAX_NOTES);
+	return {
+		notes: overflow === 0 ? notes : notes.slice(overflow),
+		notesDropped: card.notesDropped + overflow,
+	};
+}
+
+/** A card's log after one more transition, with the oldest dropped and counted. */
+function appendTransition(card: Card, status: CardStatus, actor: Actor, now: number): Pick<Card, "log" | "logDropped"> {
+	const log = [...(card.log ?? []), { status, at: now, by: actor.label }];
+	const overflow = Math.max(0, log.length - MAX_LOG);
+	return {
+		log: overflow === 0 ? log : log.slice(overflow),
+		logDropped: (card.logDropped ?? 0) + overflow,
+	};
+}
+
+function plan(card: Card, raw: unknown, actor: Actor, now: number): OpResult {
+	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; its plan cannot change.` };
+	if (!holds(card, actor)) return { ok: false, error: `${heldBy(card)} Only its owner records a plan.` };
+	const parsed = normalizePlanPath(raw);
+	if ("error" in parsed) return { ok: false, error: parsed.error };
+	if (card.plan === parsed.path) return { ok: true, card, changed: false };
+	return { ok: true, card: write(card, actor, now, { plan: parsed.path }), changed: true };
+}
+
+/**
+ * Fix what a card says: its title, its hints, its priority, and what it waits for.
+ *
+ * The holder decides for a held card and anyone decides for an unclaimed one — and
+ * that includes a `done` card, because a title is what a reader reads, not a step of
+ * the work: a finished feature whose title says the wrong thing would stay wrong for
+ * as long as the board keeps history.
+ *
+ * Every field is optional and an absent one is left alone; a field that already holds
+ * the value asked for is not a write, so re-editing the same card is a no-op.
+ */
+function edit(
+	card: Card,
+	op: Extract<CardOp, { kind: "edit" }>,
+	actor: Actor,
+	now: number,
+	board: BoardIndex,
+): OpResult {
+	if (card.owner !== undefined && !holds(card, actor)) {
+		return { ok: false, error: `${heldBy(card)} Only its owner can edit it.` };
+	}
+	const fields: Partial<Card> = {};
+	if (op.title !== undefined) {
+		const parsed = normalizeTitle(op.title);
+		if ("error" in parsed) return { ok: false, error: parsed.error };
+		if (parsed.title !== card.title) fields.title = parsed.title;
+	}
+	if (op.paths !== undefined) {
+		const parsed = normalizePathHints(op.paths);
+		if ("error" in parsed) return { ok: false, error: parsed.error };
+		if (!sameList(parsed.paths, card.paths)) fields.paths = parsed.paths;
+	}
+	if (op.priority !== undefined) {
+		const parsed = normalizePriority(op.priority);
+		if ("error" in parsed) return { ok: false, error: parsed.error };
+		if (parsed.priority !== priorityOf(card)) fields.priority = parsed.priority;
+	}
+	if (op.dependsOn !== undefined) {
+		const parsed = normalizeDepends(op.dependsOn, card.id, board);
+		if ("error" in parsed) return { ok: false, error: parsed.error };
+		if (!sameList(parsed.dependsOn, dependsOf(card))) fields.dependsOn = parsed.dependsOn;
+	}
+	if (Object.keys(fields).length === 0) return { ok: true, card, changed: false };
+	return { ok: true, card: write(card, actor, now, fields), changed: true };
+}
+
+/**
+ * Record that the card was offered to the team, and nobody has taken it.
+ *
+ * The same preconditions a claim would meet, because the offer asks a peer to claim: a
+ * held card, a finished one, or one waiting on unfinished work is refused before anything
+ * is broadcast. Re-offering refreshes the age rather than refusing as a no-op — a lead
+ * who offers again is asking again, and the age is the record of when they last did.
+ */
+function offer(card: Card, actor: Actor, now: number, board: BoardIndex): OpResult {
+	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; it cannot be offered.` };
+	if (card.owner !== undefined) return { ok: false, error: heldBy(card) };
+	const waiting = waitingOn(card, board);
+	if (waiting !== undefined) return { ok: false, error: waiting };
+	return { ok: true, card: write(card, actor, now, { offeredAt: now }), changed: true };
+}
+
+function reclaim(card: Card, actor: Actor, now: number): OpResult {
+	if (card.status === "done") return { ok: false, error: `${cardRef(card.id)} is done; there is nothing to reclaim.` };
+	if (card.owner === undefined) return { ok: false, error: `${cardRef(card.id)} has no owner to reclaim.` };
+	return {
+		ok: true,
+		card: write(card, actor, now, { status: "todo", owner: undefined, offeredAt: undefined }),
+		changed: true,
+	};
+}
+
+/**
+ * Set a finished card aside, out of the board and into the archive beside it.
+ *
+ * Only a finished card leaves this way: `done` is terminal, and a card still in flight
+ * has an owner, a plan, and a decision in it. No field moves and no transition is
+ * appended — the record is unchanged, and what changed is which pile its file lies in,
+ * which is the store's write. `changed` is still true, because the board lost a card.
+ */
+function archive(card: Card): OpResult {
+	if (card.status !== "done") {
+		return { ok: false, error: `${cardRef(card.id)} is in ${card.status}; only a finished card can be archived.` };
+	}
+	return { ok: true, card, changed: true };
+}
+
+function drop(card: Card, actor: Actor, board: BoardIndex): OpResult {
+	// A drop takes its id with it, so a card another one waits on cannot leave: the
+	// remaining link would name nothing, and nothing on the board would say so.
+	const depended = dependedOn(card.id, board);
+	if (depended !== undefined) return { ok: false, error: depended };
+	if (card.status === "todo" || card.status === "done") return { ok: true, card, changed: true };
+	if (!holds(card, actor)) return { ok: false, error: `${heldBy(card)} It cannot be dropped while someone holds it.` };
+	return { ok: true, card, changed: true };
+}
+
+/** Whether two string lists are the same list, in the same order. */
+function sameList(left: readonly string[], right: readonly string[]): boolean {
+	return left.length === right.length && left.every((entry, index) => entry === right[index]);
+}
+
+/**
+ * A card with `fields` applied and its write marks moved.
+ *
+ * This is the one place a lane change is observed, because it is the one place every
+ * transition ends: a note, a plan, or an edit writes fields and leaves the lane alone,
+ * while a claim, an assign, a release, a reclaim, and a move all name the new one. So
+ * the log is appended from here rather than from each operation, and an operation added
+ * later cannot forget it.
+ */
+function write(card: Card, actor: Actor, now: number, fields: Partial<Card>): Card {
+	const status = fields.status;
+	const transition =
+		status !== undefined && status !== card.status ? appendTransition(card, status, actor, now) : undefined;
+	const next: Card = { ...card, ...fields, ...transition, rev: card.rev + 1, updatedAt: now, by: actor.label };
+	// `owner: undefined` must clear the field rather than store a key holding it, so a
+	// released card reads back exactly like one that was never claimed. Only an
+	// explicit `owner` in `fields` may delete it: every other write keeps the holder.
+	if ("owner" in fields && fields.owner === undefined) delete next.owner;
+	// The same for the block: a card that left `blocked` has no reason, and a key holding
+	// undefined would be one more shape for a reader to know about.
+	if ("blockedBy" in fields && fields.blockedBy === undefined) delete next.blockedBy;
+	if ("offeredAt" in fields && fields.offeredAt === undefined) delete next.offeredAt;
+	return next;
+}
+
+/** The owner recorded for an actor: the id only when this actor has one. */
+function ownerOf(actor: Actor): CardOwner {
+	return actor.id === undefined ? { label: actor.label } : { id: actor.id, label: actor.label };
+}
+
+/** The refusal for an operation on a card someone else holds. */
+function heldBy(card: Card): string {
+	return `${cardRef(card.id)} is held by ${card.owner?.label ?? "another session"}.`;
+}

package/lib/board/session.ts

@@ -0,0 +1,105 @@
+/**
+ * What a board call works on, and who it writes as.
+ *
+ * One store per working directory, opened on first use and kept for the session:
+ * a tool call is frequent and the repository lookup shells out to git, so the
+ * answer is remembered per `cwd`. The identity is the same pair a card records —
+ * the session id Pi knows, and the label `session-bus` would settle by default —
+ * which is why the board can name its owner without reading the bus.
+ *
+ * The store and its cache live in this closure, not in a module variable: Pi loads
+ * each extension with an isolated module cache, so module state would be one copy
+ * per extension and none of them the same one.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { basename, join } from "node:path";
+import { defaultLabel, sessionNameOf } from "../session-label.ts";
+import { BUS_DIR_NAME } from "../session-roster.ts";
+import type { Actor } from "./rules.ts";
+import { type BoardStore, openBoard } from "./store.ts";
+
+/** What a tool, a page, and a round need from the session, without any of them owning it. */
+export interface BoardSession {
+	/** The board for `cwd`'s repository. */
+	store(cwd: string): Promise<BoardStore>;
+	/** The session a write is made as. */
+	who(ctx: ExtensionContext, cwd: string): Actor;
+	/** The clock, so a test drives a deadline instead of waiting on one. */
+	now(): number;
+	/**
+	 * Where this repository's session bus files its records, for the page's roster.
+	 *
+	 * A path, not a dependency: the board reads those files when they are there and
+	 * behaves exactly as before when they are not, which is what keeps the page working
+	 * with `session-bus` unloaded.
+	 */
+	busDir(cwd: string): Promise<string>;
+	/** Whether this session has already joined the team, so a card write joins once. */
+	joined(): boolean;
+	/** Record that the join landed; a failed one leaves this false so the next write asks. */
+	markJoined(): void;
+}
+
+/** Test seams and the one place a caller may redirect the store. */
+export interface BoardSessionOptions {
+	now?: () => number;
+	agentDir?: string;
+}
+
+/**
+ * Build the session around one extension's `pi`.
+ *
+ * Shared by `board` and `team`: both work on the same store and must name a write
+ * as the same session, and two copies are how a card's owner label drifts from the
+ * label the board writes.
+ */
+export function openBoardSession(pi: ExtensionAPI, options: BoardSessionOptions = {}): BoardSession {
+	const stores = new Map<string, Promise<BoardStore>>();
+	const busDirs = new Map<string, Promise<string>>();
+	let teamJoined = false;
+	const agentDir = options.agentDir;
+	const session: BoardSession = {
+		store(cwd) {
+			const cached = stores.get(cwd);
+			if (cached) return cached;
+			const opened = openBoard(pi, cwd, agentDir === undefined ? {} : { agentDir });
+			stores.set(cwd, opened);
+			return opened;
+		},
+		who(ctx, cwd) {
+			const id = sessionIdOf(ctx);
+			const label = defaultLabel(sessionNameOf(ctx), cwd, id ?? "session");
+			return id === undefined ? { label } : { id, label };
+		},
+		now: options.now ?? Date.now,
+		// The board's own directory is `<agentDir>/board/<key>` and the bus's is
+		// `<agentDir>/session-bus/<key>`, both keyed by the same repository, so the key is
+		// read back off the board rather than resolved a second time through git.
+		busDir(cwd) {
+			const cached = busDirs.get(cwd);
+			if (cached) return cached;
+			const resolved = session
+				.store(cwd)
+				.then((store) => join(agentDir ?? getAgentDir(), BUS_DIR_NAME, basename(store.dir)));
+			busDirs.set(cwd, resolved);
+			return resolved;
+		},
+		joined: () => teamJoined,
+		markJoined: () => {
+			teamJoined = true;
+		},
+	};
+	return session;
+}
+
+/** The session id, or undefined when the host does not report one. */
+function sessionIdOf(ctx: ExtensionContext): string | undefined {
+	try {
+		const id = ctx.sessionManager.getSessionId();
+		return typeof id === "string" && id !== "" ? id : undefined;
+	} catch {
+		return undefined;
+	}
+}