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

package/extensions/team/format.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 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,33 @@
+/**
+ * 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 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." })),
+});

package/extensions/team/tools.ts

@@ -0,0 +1,246 @@
+/**
+ * The `team` tool: the lead's round over the same cards `board` owns.
+ *
+ * Two actions, because those are the two that need the bus. `assign` sends the
+ * handoff **first** and sets the owner **second**: a card assigned without a message
+ * is a card nobody knows about, while a message for a card that then changed is one
+ * the peer can still claim. Either failure is reported with the card as it actually
+ * is, so the lead's next call starts from the truth.
+ *
+ * `reclaim` needs no message — it is the compensation for a dispatch that did not
+ * land — and it belongs here rather than in `board` because it only makes sense in
+ * the lead's context.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { Static } from "typebox";
+import { type Card, cardRef, normalizeCardId } from "../../lib/board/card.ts";
+import { indexOf } from "../../lib/board/links.ts";
+import { type Actor, applyOp } from "../../lib/board/rules.ts";
+import type { BoardSession } from "../../lib/board/session.ts";
+import type { BoardStore } from "../../lib/board/store.ts";
+import { messageOf } from "../../lib/errors.ts";
+import { failedResult, type ToolFailure, textResult } from "../../lib/tool-result.ts";
+import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import { callLine, detailsOrLine } from "../../lib/tui/tool.ts";
+import { plural } from "../../lib/board/round-text.ts";
+import { type Dispatch, handoffText, notListening, offerText, ownerFor, peerFor, sessionDispatch } from "./dispatch.ts";
+import {
+	formatHandoff,
+	formatHandoffFailure,
+	formatOffer,
+	formatOfferFailure,
+	formatRacedAssignment,
+	formatReclaimed,
+} from "./format.ts";
+import { TeamParams } from "./schema.ts";
+import { normalizeTeamAction, TEAM_ACTIONS, TEAM_TOOL, type TeamAction, type TeamDetails } from "./types.ts";
+
+/** The parameters as the schema validates them. */
+type TeamArgs = Static<typeof TeamParams>;
+
+/** One refusal: the reason for the model, the state for the renderer. */
+function refusal(action: TeamAction, message: string, card?: Card): ToolFailure<TeamDetails> {
+	return failedResult(`Error: ${message}`, { action, error: message, ...(card === undefined ? {} : { card }) });
+}
+
+/** The call line's subject: the verb, the card, and the peer it names. */
+function callSubject(action: TeamAction, args: Record<string, unknown>): string {
+	const card = typeof args.card === "string" && args.card.trim() !== "" ? cardRef(args.card.trim()) : "";
+	const to = typeof args.to === "string" && args.to.trim() !== "" ? ` → ${args.to.trim()}` : "";
+	return card === "" ? action : `${action} ${card}${action === "assign" ? to : ""}`;
+}
+
+/** What the tool needs from the outside, so a suite drives it without a bus. */
+export interface TeamToolsDeps {
+	/** Test seam: the handoff transport. */
+	dispatch?: (ctx: Parameters<typeof sessionDispatch>[0]) => Dispatch;
+}
+
+export function registerTools(pi: ExtensionAPI, session: BoardSession, deps: TeamToolsDeps = {}): void {
+	const dispatchFor = deps.dispatch ?? sessionDispatch;
+
+	pi.registerTool({
+		name: TEAM_TOOL,
+		label: "Team",
+		description:
+			"Run a round of work over the shared board: `assign` hands a card to a running session and sends it a handoff " +
+			"(`to` is a teammate's label or id, as `/team` lists them); `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 and " +
+			"sends nothing, so it needs no team. Use `board` for everything else. Nothing here starts a peer's turn: a " +
+			"message waits in its inbox, and a peer that is listening reports it at its next turn.",
+		promptSnippet: "Run a round over the board: assign a card to a running session, offer one, or reclaim one.",
+		promptGuidelines: [
+			"Open the board with `/board` or work a card first, so this session and its peers are on the team.",
+			"Offer a card nobody has taken; assign one you mean a particular peer to hold.",
+			"When a result says `Not listening`, say so: the message waits for that peer's next turn.",
+			"Reclaim a card whose owner has gone quiet rather than editing someone else's work.",
+		],
+		parameters: TeamParams,
+		annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const args = params as TeamArgs;
+			const action = normalizeTeamAction(args.action);
+			if (!action) {
+				return refusal("assign", `unknown action "${String(args.action)}"; use ${TEAM_ACTIONS.join(" or ")}.`);
+			}
+			const id = normalizeCardId(args.card);
+			if (id === undefined) return refusal(action, `"${String(args.card)}" is not a card id.`);
+			const me = session.who(ctx, ctx.cwd);
+			try {
+				const store = await session.store(ctx.cwd);
+				const now = session.now();
+				if (action === "reclaim") return await reclaimCard(store, me, id, now);
+				if (action === "offer") return await offerCard(store, id, args.note, now, dispatchFor(ctx));
+				const to = typeof args.to === "string" ? args.to.trim() : "";
+				if (to === "") return refusal("assign", 'assign needs a peer: pass `to`, e.g. "billing-core".');
+				return await assignCard(store, me, id, to, args.note, now, dispatchFor(ctx));
+			} catch (error) {
+				return refusal(action, messageOf(error));
+			}
+		},
+
+		renderCall(args, theme, context) {
+			const action = normalizeTeamAction(args.action) ?? "assign";
+			return callLine(theme, context.lastComponent, TEAM_TOOL, callSubject(action, args as Record<string, unknown>));
+		},
+
+		renderResult(result, _options, theme, context) {
+			const text = reuseText(context?.lastComponent);
+			const details = toolDetails<TeamDetails>(result.details);
+			const outcome = detailsOrLine(theme, result, false, details);
+			text.setText("line" in outcome ? outcome.line : summaryOf(outcome.details));
+			return text;
+		},
+	});
+}
+
+/**
+ * `assign`: check the preconditions, send the handoff, then set the owner.
+ *
+ * The preconditions are checked with the same `applyOp` the store will use, so an
+ * assignment the rules would refuse never sends a message at all.
+ */
+async function assignCard(
+	store: BoardStore,
+	me: Actor,
+	id: string,
+	to: string,
+	note: string | undefined,
+	now: number,
+	dispatch: Dispatch,
+): Promise<ReturnType<typeof textResult<TeamDetails>> | ToolFailure<TeamDetails>> {
+	const card = await store.read(id);
+	if (!card) return refusal("assign", `${cardRef(id)} does not exist.`);
+	const owner: Actor = { label: to };
+	// The board, not just the card: a card that waits on unfinished work is refused here,
+	// so a handoff for it is never sent.
+	const dry = applyOp(card, { kind: "assign", to: owner }, me, now, indexOf(await store.list()));
+	if (!dry.ok) return refusal("assign", dry.error, card);
+
+	let delivered: string[];
+	try {
+		delivered = (await dispatch.send({ kind: "handoff", to, text: handoffText(card, to, note) })).delivered;
+	} catch (error) {
+		return refusal("assign", formatHandoffFailure(card, to, messageOf(error)), card);
+	}
+
+	// Ask the bus which session answers to the label: an owner recorded with its id
+	// survives the peer renaming itself, which a label alone does not — and the same read
+	// says whether that peer will be woken by the message it just got.
+	const peers = await dispatch.peers().catch(() => undefined);
+	const peer = peerFor(peers, to);
+	const applied = await store.mutate(
+		id,
+		{ kind: "assign", to: peer === undefined ? ownerFor(to, delivered) : { id: peer.id, label: peer.label } },
+		me,
+		now,
+	);
+	if (!applied.ok)
+		return refusal("assign", formatRacedAssignment(applied.card ?? card, to, applied.error), applied.card ?? card);
+	const silent = notListening(peers, delivered);
+	return textResult(formatHandoff(applied.card, to, delivered, silent), {
+		action: "assign",
+		card: applied.card,
+		assigned: applied.card.owner,
+		delivered,
+		...(silent.length === 0 ? {} : { notListening: silent }),
+	});
+}
+
+/**
+ * The actor an offer's preconditions are judged as: nobody in particular.
+ *
+ * `claim` is what the offer asks a peer to do, so the dry run is a claim by someone who
+ * holds nothing — the rules' own refusals decide whether a card may be offered at all,
+ * without a second copy of the sentences.
+ */
+const OFFER_CLAIMANT: Actor = { label: "*" };
+
+/**
+ * `offer`: check the claim's preconditions, broadcast the card, and write nothing.
+ *
+ * The order matters less here than in `assign`, because nothing is written: a failed
+ * broadcast leaves the card exactly as it was, and the first peer to claim is what makes
+ * an offer into work. Two peers racing are settled by the store's compare-and-set.
+ */
+async function offerCard(
+	store: BoardStore,
+	id: string,
+	note: string | undefined,
+	now: number,
+	dispatch: Dispatch,
+): Promise<ReturnType<typeof textResult<TeamDetails>> | ToolFailure<TeamDetails>> {
+	const card = await store.read(id);
+	if (!card) return refusal("offer", `${cardRef(id)} does not exist.`);
+	// The board, not just the card: a card that waits on unfinished work, or one somebody
+	// holds, is refused here, so a broadcast for it is never sent.
+	const dry = applyOp(card, { kind: "claim" }, OFFER_CLAIMANT, now, indexOf(await store.list()));
+	if (!dry.ok) return refusal("offer", dry.error, card);
+
+	let delivered: string[];
+	try {
+		delivered = (await dispatch.send({ kind: "event", to: "*", text: offerText(card, note) })).delivered;
+	} catch (error) {
+		return refusal("offer", formatOfferFailure(card, messageOf(error)), card);
+	}
+	const peers = await dispatch.peers().catch(() => undefined);
+	const silent = notListening(peers, delivered);
+	return textResult(formatOffer(card, delivered, silent), {
+		action: "offer",
+		card,
+		delivered,
+		...(silent.length === 0 ? {} : { notListening: silent }),
+	});
+}
+
+/** `reclaim`: the owner clears and the card returns to To do, notes and all. */
+async function reclaimCard(
+	store: BoardStore,
+	me: Actor,
+	id: string,
+	now: number,
+): Promise<ReturnType<typeof textResult<TeamDetails>> | ToolFailure<TeamDetails>> {
+	const before = await store.read(id);
+	if (!before) return refusal("reclaim", `${cardRef(id)} does not exist.`);
+	const previous = before.owner?.label;
+	if (previous === undefined) return refusal("reclaim", `${cardRef(id)} has no owner to reclaim.`, before);
+	const result = await store.mutate(id, { kind: "reclaim" }, me, now);
+	if (!result.ok) return refusal("reclaim", result.error, result.card ?? before);
+	return textResult(formatReclaimed(result.card, previous), { action: "reclaim", card: result.card });
+}
+
+/** The collapsed line for a successful call, from its details. */
+function summaryOf(details: TeamDetails): string {
+	const card = details.card;
+	if (!card) return details.action === "reclaim" ? "reclaimed" : "handed off";
+	if (details.action === "offer") {
+		const count = details.delivered?.length ?? 0;
+		return `${cardRef(card.id)} offered to ${plural(count, "session")}`;
+	}
+	const who = details.assigned?.label ?? card.owner?.label;
+	const target = details.action === "assign" && who !== undefined ? ` → ${who}` : "";
+	return `${cardRef(card.id)} ${card.status}${target}`;
+}

package/extensions/team/types.ts

@@ -0,0 +1,48 @@
+/**
+ * The shapes `team` registers and reports.
+ *
+ * A `team` result is one card plus what happened to the handoff, so the details say
+ * both: `assigned` is who the card went to, `delivered` is the labels the bus wrote
+ * a message file for, and `messageError` is the send that never landed — a card is
+ * never left in a state the report does not describe.
+ */
+
+import type { Card } from "../../lib/board/card.ts";
+import type { CardOwner } from "../../lib/board/card.ts";
+
+/** The tool's name. `board` owns the cards; `team` owns the round. */
+export const TEAM_TOOL = "team";
+
+/** The three actions: the lead's whole surface — hand out, offer, take back. */
+export const TEAM_ACTIONS = ["assign", "offer", "reclaim"] as const;
+
+/** One action. */
+export type TeamAction = (typeof TEAM_ACTIONS)[number];
+
+/** What one call did. */
+export interface TeamDetails {
+	action: TeamAction;
+	/** The card after the action, or the one a refusal left alone. */
+	card?: Card;
+	/** Who the card was assigned to, when the assignment happened. */
+	assigned?: CardOwner;
+	/**
+	 * The labels a message file was written for, when the send landed: the one peer for
+	 * `assign`, every other live session for `offer`.
+	 */
+	delivered?: string[];
+	/**
+	 * The peers the message reached whose record says they are not listening, so it waits
+	 * for their next turn instead of being raised as one. Absent when every peer listens.
+	 */
+	notListening?: string[];
+	/** Why the handoff was not sent; the card is untouched when this is set. */
+	messageError?: string;
+	/** A refusal's reason, which the renderer draws instead of the details. */
+	error?: string;
+}
+
+/** Whether a value is one of the actions, so an unknown one is a refusal and not a crash. */
+export function normalizeTeamAction(raw: unknown): TeamAction | undefined {
+	return typeof raw === "string" && TEAM_ACTIONS.includes(raw as TeamAction) ? (raw as TeamAction) : undefined;
+}

package/extensions/web-access/fetch/page.ts

@@ -11,6 +11,7 @@
 
 import type { WebFetchConfig } from "./config.ts";
 import { extractReadable } from "./extract.ts";
+import { renderStructured } from "./structured.ts";
 import { extractPdfText, type PdfExtractor } from "../../../lib/pdf.ts";
 import { createFetchRunner, type HttpRunner, type HttpResponse } from "../http.ts";
 import { decodeHtml } from "../charset.ts";
@@ -157,7 +158,9 @@ export async function runFetch(
 		title = page.title;
 		text = page.text;
 	} else if (isTextualType(response.contentType)) {
-		text = response.body;
+		// Rendered here, once per fetch, because the result is what the cache stores:
+		// paging and `find` then read one stable string instead of a fresh rendering.
+		text = renderStructured(response.body, response.contentType) ?? response.body;
 	} else {
 		text = `(binary content: ${response.contentType || "unknown"}, ${response.sizeBytes} bytes; web_fetch returns text only)`;
 	}