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

package/extensions/team/tools.ts

@@ -0,0 +1,267 @@
+/**
+ * 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 { strayField } from "../../lib/stray-fields.ts";
+import { type Dispatch, handoffText, notListening, offerText, ownerFor, peerFor, sessionDispatch } from "./dispatch.ts";
+import {
+	formatHandoff,
+	formatHandoffFailure,
+	formatOffer,
+	formatOfferFailure,
+	formatRacedOffer,
+	formatRacedAssignment,
+	formatReclaimed,
+} from "./format.ts";
+import { TeamParams } from "./schema.ts";
+import {
+	ACTION_FIELDS,
+	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 is gone or has gone quiet rather than editing someone else's work. A " +
+				"`gone:` owner's process is not running, so what it held is anyone's to reclaim.",
+		],
+		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 ")}.`);
+			}
+			// Before the store and before the card: a refused call has done nothing, so it
+			// cannot have read a card or sent a message on its way to the refusal.
+			const stray = strayField(action, args, ACTION_FIELDS);
+			if (stray !== undefined) return refusal(action, stray);
+			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, me, 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, then record the offer.
+ *
+ * The broadcast comes first and the record second, because a record of an offer nobody
+ * received would be worse than an offer with no record: the card is unchanged by a failed
+ * send, and the first peer to claim is what makes an offer into work. What the record
+ * adds is the one thing an event cannot carry — when it was made — so a lead can tell an
+ * offer nobody took from a card nobody has looked at.
+ */
+async function offerCard(
+	store: BoardStore,
+	me: Actor,
+	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);
+	}
+	// The peers have the event, so a card that changed underneath is reported as raced
+	// rather than refused: the message is already in their inboxes.
+	const recorded = await store.mutate(id, { kind: "offer" }, me, now);
+	if (!recorded.ok) return refusal("offer", formatRacedOffer(recorded.card ?? card, recorded.error), recorded.card);
+	const peers = await dispatch.peers().catch(() => undefined);
+	const silent = notListening(peers, delivered);
+	return textResult(formatOffer(recorded.card, delivered, silent), {
+		action: "offer",
+		card: recorded.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,65 @@
+/**
+ * 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;
+}
+
+/**
+ * The fields each action acts on: what a call may carry, per action.
+ *
+ * The parameters are one flat object, so a field is published to every action at once,
+ * and only this table stops one reaching an action that would drop it. `to` is `assign`'s
+ * alone: an `offer` that named a peer was broadcast to every live session instead, and a
+ * `reclaim` that named one took the card back from whoever held it.
+ *
+ * A test holds the other direction — every published parameter but `action` is claimed
+ * here — so a field cannot be published without an action that acts on it.
+ */
+export const ACTION_FIELDS: Record<TeamAction, readonly string[]> = {
+	assign: ["card", "to", "note"],
+	offer: ["card", "note"],
+	reclaim: ["card"],
+};
+
+/** 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/todo/index.ts

@@ -60,7 +60,10 @@ export default function todo(pi: ExtensionAPI) {
 	pi.on("tool_execution_end", (event) => {
 		if (event.isError) return;
 		const annotations = pi.getAllTools().find((tool) => tool.name === event.toolName)?.annotations;
-		if (!isMutatingTool(event.toolName, annotations)) return;
+		// The result is the only place a call's own record of what it did survives to this
+		// event, which is why the board's read action is read from here.
+		const details = (event.result as { details?: unknown } | undefined)?.details;
+		if (!isMutatingTool(event.toolName, annotations, details)) return;
 		runtime.noteWork(isFileWrite(event.toolName, annotations));
 	});
 

package/extensions/todo/nudge.ts

@@ -14,7 +14,8 @@
  */
 
 import type { ToolAnnotations } from "@earendil-works/pi-coding-agent";
-import { TODO_TOOL } from "../../lib/tool-names.ts";
+import { isBoardRead } from "../../lib/policy.ts";
+import { BOARD_TOOL, TODO_TOOL } from "../../lib/tool-names.ts";
 import { currentTodo, hasOpenTodos } from "./state.ts";
 import type { Todo } from "./types.ts";
 
@@ -32,9 +33,14 @@ export const MUTATING_TOOL_NAMES: ReadonlySet<string> = new Set(["write", "edit"
  * Whether a finished tool call counts as work for lag detection. The `todo`
  * tool never does (it is the update itself), a known mutator always does, and
  * any other tool counts only when it explicitly declares `readOnlyHint: false`.
+ *
+ * `board` is the one mutator whose read face is provable from what the call
+ * returned: a result whose `details` say `action: "list"` read the cards and changed
+ * nothing, so it counts like every other reader.
  */
-export function isMutatingTool(toolName: string, annotations?: ToolAnnotations): boolean {
+export function isMutatingTool(toolName: string, annotations?: ToolAnnotations, details?: unknown): boolean {
 	if (toolName === TODO_TOOL) return false;
+	if (toolName === BOARD_TOOL && isBoardRead(details)) return false;
 	if (MUTATING_TOOL_NAMES.has(toolName)) return true;
 	return annotations?.readOnlyHint === false;
 }

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