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

package/extensions/team/commands.ts

@@ -0,0 +1,145 @@
+/**
+ * `/team` — the lead's round, printed.
+ *
+ * The Team tab is the same round with a mouse; a lead reading a TUI should not have to
+ * open a browser to see what needs a decision, so the command prints the rollup the
+ * tool returns, the work a dead owner left behind, and one line saying who is live. It
+ * reads the cards and the bus's records and writes nothing: acting on the round is
+ * `team`'s tool (`assign`, `reclaim`) or `board`'s.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { type Card, cardRef } from "../../lib/board/card.ts";
+import { buildRound } from "../../lib/board/round.ts";
+import { formatRound, plural } from "../../lib/board/round-text.ts";
+import type { BoardSession } from "../../lib/board/session.ts";
+import { createTeamJoin, type JoinResult, type TeamJoin } from "../../lib/session-tool.ts";
+import { readRoster, type RosterSession, rosterStateOf } from "../../lib/session-roster.ts";
+import { formatJoined, formatNotJoined } from "./format.ts";
+
+/** The command's name, which is also the word a user types. */
+export const TEAM_COMMAND = "team";
+
+/** The words the command accepts besides the round itself. */
+export const TEAM_WORDS = ["join"] as const;
+
+/** How many lines a round may print before it says how many it left out. */
+export const MAX_ROUND_LINES = 10;
+
+export function registerCommands(pi: ExtensionAPI, session: BoardSession, deps: { team?: TeamJoin } = {}): void {
+	const team = deps.team ?? createTeamJoin(pi);
+	pi.registerCommand(TEAM_COMMAND, {
+		description: "The lead's round: who holds what, and what needs a decision; `/team join [<label>]` joins the team",
+		getArgumentCompletions: (prefix: string) => {
+			const text = prefix.trimStart();
+			if (text.includes(" ")) return null;
+			const items = TEAM_WORDS.filter((word) => word.startsWith(text));
+			return items.length > 0 ? items.map((value) => ({ value, label: value })) : null;
+		},
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const [word = "", ...rest] = args.trim().split(/\s+/).filter(Boolean);
+			if (word === "join") {
+				const label = rest.join(" ").trim();
+				const joined = await team.join(ctx, label === "" ? undefined : label);
+				ctx.ui.notify(joinedLine(joined), joined.ok ? "info" : "warning");
+				return;
+			}
+			if (word !== "") {
+				ctx.ui.notify(
+					`team: "${word}" is not a word this command knows — try /team, or /team join [<label>]`,
+					"warning",
+				);
+				return;
+			}
+			const store = await session.store(ctx.cwd);
+			const cards = await store.list();
+			// The roster is read as data, so a repository with no bus prints the round and
+			// says nothing about who is here rather than failing.
+			const roster = await readRoster(await session.busDir(ctx.cwd));
+			ctx.ui.notify(roundText(cards, session.now(), roster), "info");
+		},
+	});
+}
+
+/** `/team join`'s line: who this session is on the team, or why it is on none. */
+export function joinedLine(result: JoinResult): string {
+	return result.ok ? formatJoined(result.label, result.watching) : formatNotJoined(result.error);
+}
+
+/**
+ * The round as the lines a lead reads: the rollup, then who is live.
+ *
+ * Capped, because a notify is a message and not a screen: past its limit the round says
+ * how many lines it left out instead of pushing the rest of the session up the screen.
+ */
+export function roundText(cards: readonly Card[], now: number, roster?: readonly RosterSession[]): string {
+	if (cards.length === 0) return "team: nothing to report — the board is empty";
+	const round = formatRound(cards, buildRound(cards, now)).split("\n");
+	const shown = round.slice(0, MAX_ROUND_LINES);
+	if (round.length > MAX_ROUND_LINES) shown.push(`… ${plural(round.length - MAX_ROUND_LINES, "line")} more`);
+	for (const line of goneLines(cards, roster, now)) shown.push(line);
+	const who = presenceLine(roster, now);
+	if (who !== undefined) shown.push(who);
+	return shown.join("\n");
+}
+
+/**
+ * The work a dead owner left behind, as the line that says who takes it.
+ *
+ * One line per gone owner that still holds cards, before the presence line: `gone: b` at
+ * the end of that line says who died, and this one says what to do about it. A card that
+ * waits on another is left to the board, whose rules would refuse the claim anyway.
+ */
+function goneLines(cards: readonly Card[], roster: readonly RosterSession[] | undefined, now: number): string[] {
+	if (roster === undefined) return [];
+	const gone = new Map<string, string>();
+	for (const session of roster) {
+		if (rosterStateOf(session, now) === "gone") gone.set(session.label.toLowerCase(), session.label);
+	}
+	if (gone.size === 0) return [];
+	const byOwner = new Map<string, string[]>();
+	for (const card of cards) {
+		if (card.owner === undefined || card.status === "done") continue;
+		const label = gone.get(card.owner.label.toLowerCase());
+		if (label === undefined) continue;
+		byOwner.set(label, [...(byOwner.get(label) ?? []), cardRef(card.id)]);
+	}
+	return [...byOwner.entries()].map(([label, refs]) => `reclaim ${refs.join(", ")} — ${label} is not running`);
+}
+
+/**
+ * `live: a, b · not listening: b · quiet: c · gone: d`, or nothing when nobody is here.
+ *
+ * Four facts, and the middle one is the one a lead can act on: a live session that is
+ * not listening reads mail at its next turn rather than being woken for it. It is only
+ * named when its record says so — a session that never wrote the field is not accused of
+ * ignoring anything. `gone` is the loudest and comes last, because it is the one a lead
+ * answers by reclaiming rather than by waiting.
+ */
+function presenceLine(roster: readonly RosterSession[] | undefined, now: number): string | undefined {
+	if (roster === undefined || roster.length === 0) return undefined;
+	const live: string[] = [];
+	const quiet: string[] = [];
+	const dead: string[] = [];
+	const silent: string[] = [];
+	for (const session of roster) {
+		const state = rosterStateOf(session, now);
+		if (state === "gone") {
+			dead.push(session.label);
+			continue;
+		}
+		if (state !== "live") {
+			quiet.push(session.label);
+			continue;
+		}
+		live.push(session.label);
+		if (session.watching?.armed === false) silent.push(session.label);
+	}
+	const parts = [
+		live.length > 0 ? `live: ${live.join(", ")}` : "",
+		silent.length > 0 ? `not listening: ${silent.join(", ")}` : "",
+		quiet.length > 0 ? `quiet: ${quiet.join(", ")}` : "",
+		dead.length > 0 ? `gone: ${dead.join(", ")}` : "",
+	];
+	return parts.filter((part) => part !== "").join(" · ");
+}

package/extensions/team/dispatch.ts

@@ -0,0 +1,133 @@
+/**
+ * The handoff: what `team assign` tells the peer, and how it tells it.
+ *
+ * The peer is a session that is already running, so this is a message and not a
+ * process: `session send` writes it into the recipient's inbox, and its armed watch is
+ * what raises the turn. Nothing here starts anything, and a send that fails leaves the
+ * card exactly as it was — the order is deliberate, because a card assigned without a
+ * message is a card nobody knows about.
+ *
+ * The transport is a seam (`Dispatch`), so the tool's ordering is testable without a
+ * bus, and the one production implementation is `lib/session-tool.ts`'s.
+ */
+
+import type { ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import type { Card } from "../../lib/board/card.ts";
+import { cardRef, type CardOwner } from "../../lib/board/card.ts";
+import { listPeers, MAX_MESSAGE_TEXT, type Peer, send as sendTo } from "../../lib/session-tool.ts";
+
+/** How a handoff reaches a peer, and what the bus can say about the peers there are. */
+export interface Dispatch {
+	/** Send the text as `kind`, and report the labels a message file was written for. Throws on failure. */
+	send(input: { kind: "handoff" | "event"; to: string; text: string }): Promise<{ delivered: string[] }>;
+	/**
+	 * Every session the bus lists, when it can say.
+	 *
+	 * Its record is what makes an assignment survive a rename — `holds` compares ids
+	 * before labels — and what makes the report able to name a peer that cannot be
+	 * woken. It never throws: a resolve that fails must not undo a handoff that landed.
+	 */
+	peers(): Promise<Peer[] | undefined>;
+}
+
+/**
+ * What the peer reads.
+ *
+ * It names the card, its outcome, and the paths, and says what to do next: record the
+ * plan, work, note, finish. It does **not** ask the peer to claim the card — `assign`
+ * has already recorded the owner, and a claim by the holder is a no-op. The claim is
+ * only for the failure path where the send landed and the assignment did not.
+ */
+export function handoffText(card: Card, to: string, note?: string): string {
+	const lines = [
+		`Handoff: ${cardRef(card.id)} "${card.title}" is yours, ${to}.`,
+		card.paths.length > 0 ? `Paths: ${card.paths.join(", ")}` : undefined,
+		card.plan === undefined ? undefined : `Plan: ${card.plan}`,
+		note === undefined ? undefined : `Note: ${note}`,
+		`It is already assigned to you — record the plan with board action "plan" if it has none, then note each phase and move it to done or blocked.`,
+	].filter((line): line is string => line !== undefined);
+	return withinLimit(lines.join("\n"));
+}
+
+/**
+ * What every live session reads when the lead offers a card instead of assigning it.
+ *
+ * An offer names no owner: the first peer to claim the card takes it, so the text says
+ * what the card is and that claiming is the next step, and it never implies the work is
+ * already somebody's.
+ */
+export function offerText(card: Card, note?: string): string {
+	const lines = [
+		`Offer: ${cardRef(card.id)} "${card.title}" is unclaimed.`,
+		card.paths.length > 0 ? `Paths: ${card.paths.join(", ")}` : undefined,
+		card.plan === undefined ? undefined : `Plan: ${card.plan}`,
+		note === undefined ? undefined : `Note: ${note}`,
+		`First to claim it takes it: run board action "claim" with card "${card.id}", then note each phase and move it to done or blocked.`,
+	].filter((line): line is string => line !== undefined);
+	return withinLimit(lines.join("\n"));
+}
+
+/**
+ * Trim to the bus's text limit, which is also this message's limit.
+ *
+ * Not `lib/tui/columns.ts`'s `clip`: that one measures terminal columns, and this one
+ * counts characters, because the bus's limit is characters. The number arrives from
+ * `lib/session-tool.ts` — one copy for the two extensions that send through it.
+ */
+function withinLimit(text: string): string {
+	return text.length > MAX_MESSAGE_TEXT ? `${text.slice(0, MAX_MESSAGE_TEXT - 1)}…` : text;
+}
+
+/** The production dispatch: `lib/session-tool.ts`, with a failure turned into a throw. */
+export function sessionDispatch(ctx: ExtensionToolContext): Dispatch {
+	return {
+		async send(input) {
+			const result = await sendTo(ctx, input);
+			// `assign` and `offer` branch on a failed send, so this seam reports it the way
+			// they read it: the bus's sentence, as the reason the card was not handed over.
+			if (!result.ok) throw new Error(result.error);
+			return { delivered: result.delivered };
+		},
+		peers: () => listPeers(ctx),
+	};
+}
+
+/**
+ * The peer `to` names: an id exactly, else a label ignoring case.
+ *
+ * The send has already proved exactly one session answers to it, so the first match is
+ * the recipient; a miss means the bus could not say, which is why the caller falls back
+ * to the label alone.
+ */
+export function peerFor(peers: readonly Peer[] | undefined, to: string): Peer | undefined {
+	if (peers === undefined) return undefined;
+	const target = to.trim();
+	const byId = peers.find((peer) => peer.id === target);
+	if (byId) return byId;
+	const wanted = target.toLowerCase();
+	return peers.find((peer) => peer.label.toLowerCase() === wanted);
+}
+
+/**
+ * The labels a message reached that cannot be woken: their record says they are not
+ * listening.
+ *
+ * A label the bus could not answer for is left out — "the record does not say" is not
+ * "nobody will read it" — and so is a peer the bus lists as listening.
+ */
+export function notListening(peers: readonly Peer[] | undefined, labels: readonly string[]): string[] {
+	if (peers === undefined) return [];
+	return labels.filter((label) => {
+		const peer = peerFor(peers, label);
+		return peer !== undefined && peer.listening === false;
+	});
+}
+
+/**
+ * The peer a handoff names, as the card records it when the bus cannot say who that
+ * is: the label a message file was written for, else the one that was asked for.
+ */
+export function ownerFor(to: string, delivered: readonly string[]): CardOwner {
+	const label = delivered[0] ?? to;
+	return { label };
+}

package/extensions/team/format.ts

@@ -0,0 +1,119 @@
+/**
+ * The model-facing text for one `team` call.
+ *
+ * A handoff is stated as what happened and what did not: `handed off` names the peer
+ * and the card, a failed send says the card is untouched, and an assignment that lost
+ * a race after the send says the peer should claim it. Nothing here claims the peer
+ * read the message — `delivered` means a message file was written for it.
+ */
+
+import { type Card, cardRef } from "../../lib/board/card.ts";
+
+/** `/team join` landed: the label peers address, and whether mail will reach this session. */
+export function formatJoined(label: string, watching: { armed: boolean }): string {
+	const state = watching.armed ? "listening for handoffs" : "not listening";
+	return `team: on the team as ${label}, ${state}.`;
+}
+
+/** `/team join` did not land, so nothing about this session changed. */
+export function formatNotJoined(reason: string): string {
+	return `team: not on the team — ${reason}`;
+}
+
+/**
+ * A card that was handed over, and the peer that got the message.
+ *
+ * `notListening` is the one fact the send cannot tell you and the record can: a peer
+ * that is not listening reads the handoff at its next turn rather than being woken for
+ * it. Saying so is the difference between "delivered" and "delivered and read".
+ */
+export function formatHandoff(
+	card: Card,
+	to: string,
+	delivered: readonly string[],
+	notListening: readonly string[] = [],
+): string {
+	const who = delivered.length > 0 ? delivered.join(", ") : to;
+	return [
+		`${cardRef(card.id)} handed off to ${who}.`,
+		`  ${card.title}`,
+		card.paths.length > 0 ? `  paths: ${card.paths.join(", ")}` : undefined,
+		"  The card is already owned by the peer; the handoff is in its inbox.",
+		notListeningLine(notListening),
+	]
+		.filter((line): line is string => line !== undefined)
+		.join("\n");
+}
+
+/**
+ * The line that names a peer which will not be woken, or nothing when every peer is
+ * listening.
+ *
+ * One sentence for both verbs: what the mail does instead, and no pronoun, because the
+ * list can hold one peer or three.
+ */
+export function notListeningLine(labels: readonly string[]): string | undefined {
+	if (labels.length === 0) return undefined;
+	return `  Not listening: ${labels.join(", ")} — it reads this at its next turn.`;
+}
+
+/** The send that never landed: the card was not touched. */
+export function formatHandoffFailure(card: Card, to: string, reason: string): string {
+	return `${cardRef(card.id)} was not handed off to ${to}: ${reason}\n  The card is unchanged.`;
+}
+
+/**
+ * A card offered to the team: who heard, and that nobody holds it yet.
+ *
+ * `offer` writes nothing, so the sentence has to say the ownership question is still
+ * open — a reader who took "offered" for "assigned" would stop looking at the card.
+ */
+export function formatOffer(card: Card, delivered: readonly string[], notListening: readonly string[] = []): string {
+	const who = delivered.length > 0 ? delivered.join(", ") : "nobody";
+	return [
+		`${cardRef(card.id)} offered to ${who}.`,
+		`  ${card.title}`,
+		card.paths.length > 0 ? `  paths: ${card.paths.join(", ")}` : undefined,
+		"  The card is unowned until one of them claims it.",
+		notListeningLine(notListening),
+	]
+		.filter((line): line is string => line !== undefined)
+		.join("\n");
+}
+
+/** The broadcast that never landed: no card was touched, and nobody heard. */
+export function formatOfferFailure(card: Card, reason: string): string {
+	return `${cardRef(card.id)} was not offered: ${reason}\n  The card is unchanged.`;
+}
+
+/**
+ * The broadcast landed and recording the offer then lost a race.
+ *
+ * The peers have an event for a card somebody else has since claimed, moved, or taken
+ * over, so the correction says the offer stands as a message and the card is what the
+ * board now says — not that nothing happened.
+ */
+export function formatRacedOffer(card: Card, reason: string): string {
+	return (
+		`${cardRef(card.id)} was offered, but the card changed before the offer could be recorded: ${reason}\n` +
+		"  The peers have the message; the card is as the board shows it now."
+	);
+}
+
+/**
+ * The send landed and the assignment then lost a race.
+ *
+ * The peer has a message telling it the card is its, so the correction names the
+ * claim rather than pretending nothing happened.
+ */
+export function formatRacedAssignment(card: Card, to: string, reason: string): string {
+	return (
+		`${cardRef(card.id)} was handed off to ${to}, but the card changed before it could be assigned: ${reason}\n` +
+		`  ${to} should run \`board\` action \`claim\` with card "${card.id}".`
+	);
+}
+
+/** A card taken back to To do. */
+export function formatReclaimed(card: Card, previous: string): string {
+	return `${cardRef(card.id)} reclaimed from ${previous} and back in To do; its notes are kept.\n  ${card.title}`;
+}

package/extensions/team/index.ts

@@ -0,0 +1,34 @@
+/**
+ * team — the lead's round over the shared board.
+ *
+ * `board` owns the cards and never touches the session bus; `team` owns the two
+ * actions that need it. `assign` hands a card to a session that is already running
+ * and sends it a handoff — dispatch cannot start a peer's turn, and the page and the
+ * docs say so — and `reclaim` takes a card back when its owner is gone or has gone quiet.
+ * Its one
+ * command, `/team`, prints the round the board's Team tab draws, without a browser.
+ *
+ * Either extension works without the other: `board` is the work list any session
+ * uses, and `team` is the lead's. The factory only registers; the store is opened on
+ * first use.
+ *
+ * Load with:  pi --extension ./extensions/team --extension ./extensions/session-bus
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type BoardSession, openBoardSession } from "../../lib/board/session.ts";
+import { isExtensionEnabled } from "../../lib/env.ts";
+import { registerCommands } from "./commands.ts";
+import { registerTools } from "./tools.ts";
+
+export interface TeamDeps {
+	/** Test seam: a session with a temp agent directory and a fixed clock. */
+	session?: BoardSession;
+}
+
+export default function team(pi: ExtensionAPI, deps: TeamDeps = {}): void {
+	if (!isExtensionEnabled("team")) return;
+	const session = deps.session ?? openBoardSession(pi);
+	registerTools(pi, session);
+	registerCommands(pi, session);
+}

package/extensions/team/schema.ts

@@ -0,0 +1,29 @@
+/**
+ * The `team` tool's parameters: two actions over one card.
+ *
+ * `assign` names the peer a handoff goes to, and `reclaim` takes a card back. Both
+ * take the card the way `board` does — `4` or `#4` — because a lead reads ids off
+ * the same board.
+ */
+
+import { Type } from "typebox";
+import { TEAM_ACTIONS } from "./types.ts";
+
+export const TeamParams = Type.Object({
+	action: Type.Union(
+		TEAM_ACTIONS.map((action) => Type.Literal(action)),
+		{
+			description:
+				"`assign` hands a card to a running session and sends it a handoff; `offer` broadcasts an unclaimed card to " +
+				"every other live session and writes nothing, so the first to claim it takes it; `reclaim` takes a card back " +
+				"to To do. A lead's three actions — use `board` to create, claim, move, note, and finish the cards themselves.",
+		},
+	),
+	card: Type.String({ description: 'The card to act on, e.g. "4" or "#4".' }),
+	to: Type.Optional(
+		Type.String({
+			description: "`assign`: the peer to hand the card to, as `/team` lists them — a teammate's label or id.",
+		}),
+	),
+	note: Type.Optional(Type.String({ description: "`assign` or `offer`: a line to include, e.g. what to do first." })),
+});