@aeondave/pi-persona 1.15.2

package/src/tools/exocom.ts

@@ -0,0 +1,476 @@
+/**
+ * `exocom_list` + `exocom_send` — the supervisor-facing tools over the exocom plane
+ * (Task 7's {@link ExocomPlane}): independent top-level Pi instances in one selected scope
+ * messaging each other peer-to-peer, one-way and non-blocking.
+ *
+ *   - `exocom_list` — who else is reachable right now (live, pruned peers).
+ *   - `exocom_send` — fire a message at a named peer, or `target: "*"` to broadcast to
+ *     all of them. `plane.send` only resolves a SINGLE named target (Task 7), so the
+ *     broadcast fan-out is this tool's job: best-effort, one unreachable peer does not
+ *     abort the rest.
+ *
+ * Pure over `getPlane` (a stub accessor is enough to unit-test), registered directly with
+ * `pi.registerTool` — the same shape as the other `pi.registerTool` calls in extension.ts.
+ * `getPlane` is a live accessor rather than a captured plane so a downgrade can fail these
+ * tools closed without an `unregisterTool` API — see the doc comment on `registerExocomTools`.
+ */
+
+import { type Static, Type } from "typebox";
+
+import { keyHint, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import { fencePeer } from "../core/fence.ts";
+import { inventedExocomNameHint } from "../core/naming.ts";
+import { MAX_IDENTITY_NAME_CHARS } from "../core/session-identity.ts";
+import { ExocomPeerRejection, type DisplayPeer, type ExocomPlane } from "../exocom/plane.ts";
+import { normalizeMetadataText, normalizePeerName } from "../exocom/registry.ts";
+import type { ExocomScope } from "../exocom/scope.ts";
+import { compactInlineText } from "../ui/presentation.ts";
+
+const COLLAPSED_PEER_LIMIT = 8;
+/** Model-facing presence is a sample, not a dump. Keep the count and a refresh action below. */
+export const MAX_MODEL_PEER_ROWS = 24;
+/** Structured broadcast details retain enough IDs/errors to act while exact totals cover the rest. */
+export const MAX_BROADCAST_DETAIL_ITEMS = 64;
+const MODEL_BROADCAST_ID_SAMPLE = 12;
+const MODEL_BROADCAST_FAILURE_SAMPLE = 8;
+
+const ExocomListParams = Type.Object({
+	offset: Type.Optional(Type.Integer({ minimum: 0, maximum: 1_000_000, description: "Zero-based page offset into the live peer list." })),
+	limit: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_MODEL_PEER_ROWS, description: `Maximum peers to show (default ${MAX_MODEL_PEER_ROWS}).` })),
+});
+
+const ExocomSendParams = Type.Object({
+	target: Type.String({ minLength: 1, maxLength: 80, description: 'The peer\'s qualified `target` from `exocom_list`, 1–80 characters; its session suffix stays routable if that peer later renames. A display name alone still works but can be reassigned. Use "*" to broadcast to every reachable peer.' }),
+	message: Type.String({ minLength: 1, maxLength: 1_000_000, description: "The message body." }),
+	in_reply_to: Type.Optional(Type.String({ minLength: 1, maxLength: 128, pattern: "^[A-Za-z0-9._:-]+$", description: 'The original `msg_id` token (1–128 characters matching [A-Za-z0-9._:-]) when replying; omit for a new message. Broadcast target "*" cannot carry a reply id.' })),
+});
+
+const ExocomNameParams = Type.Object({
+	name: Type.String({
+		minLength: 1,
+		maxLength: 96,
+		description: `${inventedExocomNameHint()} Keep it to ${MAX_IDENTITY_NAME_CHARS} characters; longer legacy inputs are accepted for compatibility and clipped by the shared identity validator. Whitespace-only names are rejected.`,
+	}),
+});
+
+/** Single-target send vs. `target: "*"` broadcast — two distinct result shapes, so `execute`'s
+ *  return type is spelled out explicitly instead of leaving it to per-branch inference (which
+ *  otherwise unifies the two into an ill-typed merged shape). */
+type ExocomSendDetails =
+	| { msg_id: string; target: string }
+	| {
+		target: "*";
+		/** The bounded samples below are accompanied by exact totals so a large fan-out never
+		 * turns the tool result into an unbounded model/context payload. */
+		peerCount: number;
+		queuedCount: number;
+		failedCount: number;
+		msg_ids: string[];
+		failed: Array<{ target: string; error: string }>;
+		omittedMsgIds: number;
+		omittedFailures: number;
+	};
+
+type ExocomPeerSummary = Pick<DisplayPeer, "displayName" | "persona" | "model" | "context_pct" | "target"> & {
+	workspace_id?: string;
+	workspace_code?: string;
+	workspace_label?: string;
+	sameWorkspace?: boolean;
+};
+
+function peerWord(count: number): string {
+	return `${count} peer${count === 1 ? "" : "s"}`;
+}
+
+/** Human-facing rows are bounded in terminal columns. Expanded mode spends a second line on the
+ * model so it can retain useful detail without turning one peer into a 300-column wall. */
+function peerRows(peer: ExocomPeerSummary, expanded: boolean): string[] {
+	const context = `${Math.max(0, Math.min(100, Number(peer.context_pct) || 0))}%`;
+	const workspace = peer.workspace_code && peer.workspace_label
+		? `  workspace: ${compactInlineText(peer.workspace_label, { maxChars: expanded ? 64 : 40 }) || "workspace"} [${peer.workspace_code}] · ${peer.sameWorkspace === false ? "external" : "same"}`
+		: undefined;
+	if (expanded) {
+		const name = compactInlineText(peer.displayName, { maxChars: 48 }) || "peer";
+		const persona = compactInlineText(peer.persona, { maxChars: 32 }) || "unknown";
+		const model = compactInlineText(peer.model, { maxChars: 88 }) || "unknown";
+		return [`- ${name} · ${persona} · ctx ${context}`, `  model: ${model}`, ...(workspace ? [workspace] : [])];
+	}
+	const name = compactInlineText(peer.displayName, { maxChars: 24 }) || "peer";
+	const persona = compactInlineText(peer.persona, { maxChars: 18 }) || "unknown";
+	const model = compactInlineText(peer.model, { maxChars: 36 }) || "unknown";
+	return [`- ${name} · ${persona} · ${model} · ctx ${context}`, ...(workspace ? [workspace] : [])];
+}
+
+/** The model-facing row carries the ROUTE as well as the human label: a display name is
+ *  recomputed from the live set on every call, so the label a roster showed can belong to a
+ *  different session by the time the model sends. The TUI row above stays human-sized. */
+function modelPeerRow(peer: ExocomPeerSummary): string {
+	const workspace = peer.workspace_code && peer.workspace_label
+		? ` · workspace: ${normalizeMetadataText(peer.workspace_label, 80, "workspace")} [${peer.workspace_code}] · ${peer.sameWorkspace === false ? "external workspace" : "same workspace"}`
+		: "";
+	return `- ${normalizeMetadataText(peer.displayName, 80, "peer")} · ${normalizeMetadataText(peer.persona, 64, "unknown")} · ${normalizeMetadataText(peer.model, 160, "unknown")} · ctx ${Math.max(0, Math.min(100, Number(peer.context_pct) || 0))}% · target: ${normalizeMetadataText(peer.target, 80, "peer")}${workspace}`;
+}
+
+function summarizePeer(peer: DisplayPeer, scope: ExocomScope | undefined): ExocomPeerSummary {
+	if (!scope) {
+		return {
+			displayName: normalizeMetadataText(peer.displayName, 80, "peer"),
+			target: normalizeMetadataText(peer.target, 80, "peer"),
+			persona: normalizeMetadataText(peer.persona, 64, "unknown"),
+			model: normalizeMetadataText(peer.model, 160, "unknown"),
+			context_pct: Math.max(0, Math.min(100, Number(peer.context_pct) || 0)),
+		};
+	}
+	// Legacy peers predate workspace metadata. Their registry location still proves they belong
+	// to the selected scope; infer that identity, but never invent an absolute path or label.
+	const workspaceId = peer.workspace_id ?? scope.scopeWorkspaceId;
+	const workspaceCode = peer.workspace_code ?? (workspaceId === scope.scopeWorkspaceId ? scope.scopeCode : undefined);
+	const workspaceLabel = peer.workspace_label
+		?? (workspaceId === scope.homeWorkspaceId ? scope.homeWorkspaceLabel : "workspace");
+	return {
+		displayName: normalizeMetadataText(peer.displayName, 80, "peer"),
+		target: normalizeMetadataText(peer.target, 80, "peer"),
+		persona: normalizeMetadataText(peer.persona, 64, "unknown"),
+		model: normalizeMetadataText(peer.model, 160, "unknown"),
+		context_pct: Math.max(0, Math.min(100, Number(peer.context_pct) || 0)),
+		workspace_id: workspaceId,
+		...(workspaceCode ? { workspace_code: workspaceCode } : {}),
+		workspace_label: normalizeMetadataText(workspaceLabel, 80, "workspace"),
+		sameWorkspace: workspaceId === scope.homeWorkspaceId,
+	};
+}
+
+/** One readable line per live peer: `displayName` (not the possibly-shared `.name`) disambiguates
+ *  two peers registered under the same persona name — see plane.ts's `dedupeDisplayNames` — and
+ *  `target` is what the model must actually address with. */
+function formatPeers(peers: DisplayPeer[], offset = 0, limit = MAX_MODEL_PEER_ROWS, scope?: ExocomScope): string {
+	const scopeHead = scope
+		? scope.joined
+			? `Exocom joined scope [${scope.scopeCode}] from workspace ${scope.homeWorkspaceLabel} [${scope.homeWorkspaceCode}]`
+			: `Exocom workspace ${scope.homeWorkspaceLabel} [${scope.scopeCode}]`
+		: "Exocom";
+	const head = `${scopeHead} presence only (${peerWord(peers.length)}; ${peers.length === 0 ? "no reachable peers" : "not a message inbox"})`;
+	if (peers.length === 0) return head;
+	const shown = peers.slice(offset, offset + limit).map((peer) => summarizePeer(peer, scope));
+	const paged = offset > 0 || peers.length > limit;
+	const pageHead = paged
+		? `${scopeHead} presence only (${peerWord(peers.length)}; showing ${shown.length === 0 ? "none" : `${offset + 1}–${offset + shown.length}`} of ${peers.length}; not a message inbox)`
+		: head;
+	const omitted = peers.length - shown.length;
+	const lines = [pageHead, shown.map(modelPeerRow).join("\n")];
+	if (omitted > 0) {
+		const next = offset + shown.length < peers.length ? `call exocom_list with offset: ${offset + shown.length} to continue` : "call exocom_list with offset: 0 to return to the first page";
+		lines.push(`…and ${omitted} peers omitted from this bounded page; ${next}.`);
+	}
+	lines.push("Use each peer's qualified target as shown. Its session suffix stays routable if the peer later renames; display names alone can be reassigned.");
+	return lines.join("\n");
+}
+
+function renderListResult(
+	peers: ExocomPeerSummary[],
+	expanded: boolean,
+	total = peers.length,
+	offset = 0,
+	nextOffset?: number,
+	scope?: { scopeCode: string; homeWorkspace: { label: string; code: string; sameAsScope: boolean } },
+): string {
+	const scopeLabel = scope
+		? scope.homeWorkspace.sameAsScope
+			? ` · workspace ${compactInlineText(scope.homeWorkspace.label, { maxChars: 48 })} [${scope.scopeCode}]`
+			: ` · joined [${scope.scopeCode}] · home ${compactInlineText(scope.homeWorkspace.label, { maxChars: 48 })} [${scope.homeWorkspace.code}]`
+		: "";
+	if (total === 0) return `Exocom${scopeLabel} · 0 peers · no reachable peers`;
+	const shown = expanded ? peers : peers.slice(0, COLLAPSED_PEER_LIMIT);
+	const pageEnd = Math.min(total, offset + shown.length);
+	const paged = offset > 0 || pageEnd < total;
+	const page = paged
+		? shown.length === 0 ? `; showing none of ${total}` : `; showing ${offset + 1}–${pageEnd} of ${total}`
+		: "";
+	const lines = [`Exocom${scopeLabel} · ${peerWord(total)} (presence only${page})`];
+	for (const peer of shown) lines.push(...peerRows(peer, expanded));
+	if (offset > 0) lines.push(`…and ${offset} peers before this page`);
+	if (pageEnd < total) lines.push(`…and ${total - pageEnd} more peers after this page`);
+	if (!expanded && total > shown.length) lines.push(`(${keyHint("app.tools.expand", "to expand")})`);
+	if (nextOffset !== undefined && nextOffset < total) lines.push(`next offset: ${nextOffset}`);
+	return lines.join("\n");
+}
+
+/** A refusal in OUR voice: the peer's own prose is stripped out of it and carried separately, so it
+ *  can travel to the model behind the peer fence instead of inside this agent's tool output. */
+function refusalLine(target: string, err: unknown): string {
+	if (err instanceof ExocomPeerRejection) return `exocom: peer "${normalizeMetadataText(target, 80, "peer")}" rejected the message; its stated reason is quoted below`;
+	return normalizeMetadataText(err instanceof Error ? err.message : String(err), 240, "exocom: send failed");
+}
+
+/** The peer half of one or more refusals, quoted into a single fence. Each reason is flattened to
+ *  one bounded line first (`normalizeMetadataText`), so a peer can neither fake a fence terminator
+ *  nor spend the receiving turn's context, and the fence keeps it marked as what it is. */
+function fencedPeerReasons(reasons: Array<{ target: string; reason: string }>): string {
+	if (reasons.length === 0) return "";
+	return fencePeer(reasons
+		.map((item) => `${normalizeMetadataText(item.target, 80, "peer")}: ${normalizeMetadataText(item.reason, 240, "no reason given")}`)
+		.join("\n"));
+}
+
+function isSendDetails(details: unknown): details is ExocomSendDetails {
+	if (!details || typeof details !== "object") return false;
+	const shape = details as { msg_id?: unknown; failed?: unknown };
+	return Array.isArray(shape.failed) || typeof shape.msg_id === "string";
+}
+
+function renderSendResult(details: ExocomSendDetails, expanded: boolean): string {
+	if ("failed" in details) {
+		const failed = details.failedCount ?? details.failed.length;
+		const queued = details.queuedCount ?? details.msg_ids.length;
+		const summary = `${queued > 0 ? "✓" : "✗"} queued ${queued} peer${queued === 1 ? "" : "s"}${failed > 0 ? ` · ${failed} failed` : ""}`;
+		if (!expanded) return `${summary} (${keyHint("app.tools.expand", "to expand")})`;
+		const lines = [summary];
+		if (details.msg_ids.length > 0) lines.push(`msg_ids: ${details.msg_ids.join(", ")}`);
+		for (const failure of details.failed) {
+			lines.push(`✗ ${normalizeMetadataText(failure.target, 80, "peer")}: ${normalizeMetadataText(failure.error, 240, "send failed")}`);
+		}
+		if ((details.omittedMsgIds ?? 0) > 0) lines.push(`…and ${details.omittedMsgIds} more msg_ids omitted; use the returned count to track the remaining queued peers.`);
+		if ((details.omittedFailures ?? 0) > 0) lines.push(`…and ${details.omittedFailures} more failures omitted; retry only the failed targets shown above.`);
+		return lines.join("\n");
+	}
+	const summary = `✓ queued to ${details.target} · msg_id=${details.msg_id}`;
+	return expanded ? summary : `${summary} (${keyHint("app.tools.expand", "to expand")})`;
+}
+
+/** `getPlane` is a LIVE accessor, not a captured value: a `canUseBus` downgrade (`stopExocom`,
+ *  see extension.ts) nulls the plane out from under these tool closures without needing an
+ *  `unregisterTool` API (pi's `ExtensionAPI` has none) — each call re-reads the current plane and
+ *  fails closed if it's gone, so the tools genuinely stop working the instant exocom is torn down
+ *  (I3: previously the tools captured the plane BY VALUE, so they stayed callable — and `send`
+ *  stayed able to connect out — even after a downgrade revoked the persona's bus capability). */
+export function registerExocomTools(
+	pi: ExtensionAPI,
+	getPlane: () => ExocomPlane | undefined,
+	onRename?: (name: string) => string,
+	getScope?: () => ExocomScope | undefined,
+): void {
+	pi.registerTool({
+		name: "exocom_list",
+		label: "Exocom List",
+		description: "List current exocom peer presence only; this is not a message inbox and replies arrive automatically.",
+		parameters: ExocomListParams,
+		async execute(_toolCallId, params: Static<typeof ExocomListParams>) {
+			const plane = getPlane();
+			if (!plane) throw new Error("exocom is not active for this persona");
+			const peers = plane.listPeers();
+			const scope = getScope?.();
+			const offset = Math.min(peers.length, Math.max(0, Math.floor(params?.offset ?? 0)));
+			const limit = Math.max(1, Math.min(MAX_MODEL_PEER_ROWS, Math.floor(params?.limit ?? MAX_MODEL_PEER_ROWS)));
+			const shown = peers.slice(offset, offset + limit).map((peer) => summarizePeer(peer, scope));
+			return {
+				content: [{ type: "text", text: formatPeers(peers, offset, limit, scope) }],
+				details: {
+					peers: shown,
+					total: peers.length,
+					offset,
+					limit,
+					omitted: peers.length - shown.length,
+					...(scope ? {
+						scopeCode: scope.scopeCode,
+						homeWorkspace: {
+							label: scope.homeWorkspaceLabel,
+							code: scope.homeWorkspaceCode,
+							sameAsScope: !scope.joined,
+						},
+					} : {}),
+					...(offset + shown.length < peers.length ? { nextOffset: offset + shown.length } : {}),
+				},
+			};
+		},
+		renderCall(_args, theme) {
+			return new Text(theme.fg("toolTitle", theme.bold("Exocom List")), 0, 0);
+		},
+		renderResult(result, { expanded }, theme) {
+			const details = result.details as unknown as {
+				peers?: ExocomPeerSummary[];
+				total?: number;
+				offset?: number;
+				nextOffset?: number;
+				scopeCode?: string;
+				homeWorkspace?: { label?: string; code?: string; sameAsScope?: boolean };
+			} | undefined;
+			if (!details || !Array.isArray(details.peers)) {
+				const first = result.content.find((item) => item.type === "text");
+				return new Text(theme.fg("error", first?.type === "text" ? first.text : "Exocom list failed"), 0, 0);
+			}
+			const peers = details.peers;
+			const total = typeof details.total === "number" ? details.total : peers.length;
+			const offset = typeof details.offset === "number" ? Math.max(0, details.offset) : 0;
+			const nextOffset = typeof details.nextOffset === "number" ? details.nextOffset : undefined;
+			const scope = typeof details.scopeCode === "string"
+				&& typeof details.homeWorkspace?.label === "string"
+				&& typeof details.homeWorkspace.code === "string"
+				&& typeof details.homeWorkspace.sameAsScope === "boolean"
+				? {
+					scopeCode: details.scopeCode,
+					homeWorkspace: {
+						label: details.homeWorkspace.label,
+						code: details.homeWorkspace.code,
+						sameAsScope: details.homeWorkspace.sameAsScope,
+					},
+				}
+				: undefined;
+			return new Text(theme.fg(expanded ? "toolOutput" : "accent", renderListResult(peers, expanded, total, offset, nextOffset, scope)), 0, 0);
+		},
+	});
+
+	pi.registerTool({
+		name: "exocom_send",
+		label: "Exocom Send",
+		description: [
+			"Send a ONE-WAY, non-blocking message to another top-level pi instance in this Exocom scope",
+			"(see `exocom_list`) — it returns a `msg_id` immediately and does not wait for the peer to",
+			"act on it. If you're replying to something a peer sent you, set `in_reply_to` to its",
+			'`msg_id`. `target: "*"` broadcasts the message to every reachable peer.',
+		].join(" "),
+		parameters: ExocomSendParams,
+		async execute(
+			_toolCallId,
+			params: Static<typeof ExocomSendParams>,
+		): Promise<{ content: [{ type: "text"; text: string }]; details: ExocomSendDetails }> {
+			const plane = getPlane();
+			if (!plane) throw new Error("exocom is not active for this persona");
+			if (params.target === "*" && params.in_reply_to) {
+				throw new Error('exocom_send: target "*" cannot carry in_reply_to — a broadcast cannot be a reply (N−1 peers would reject it).');
+			}
+			if (params.target === "*") {
+				const peers = plane.listPeers();
+				const sent: Array<{ target: string; msg_id: string }> = [];
+				const failed: Array<{ target: string; error: string }> = [];
+				// Peer-authored refusal prose, kept apart from our own failure lines so the whole
+				// fan-out's worth of it can be quoted into ONE peer fence below.
+				const rejections: Array<{ target: string; reason: string }> = [];
+				const outcomes = await Promise.all(
+					// By the session-pinned target, not the possibly-shared `.name` nor the display
+					// label: two LIVE peers can share a raw name (session_id-keyed registry, PartA),
+					// and a label is recomputed from the live set on every call — a peer that joins or
+					// leaves mid-fan-out can inherit another's label and receive its message.
+					peers.map(async (p) => {
+						try {
+							const { msg_id } = await plane.send(p.target, params.message, params.in_reply_to);
+							return { ok: true as const, target: p.target, msg_id };
+						} catch (err) {
+							return {
+								ok: false as const, target: p.target,
+								error: err instanceof Error ? err.message : String(err),
+								reason: err instanceof ExocomPeerRejection ? err.reason : undefined,
+							};
+						}
+					}),
+				);
+				// Promise completion order is not a presentation contract. Fold after all sends settle so
+				// sampled IDs/errors retain the stable registry order even when peers answer at different speeds.
+				for (const outcome of outcomes) {
+					if (outcome.ok) { sent.push({ target: outcome.target, msg_id: outcome.msg_id }); continue; }
+					failed.push({ target: outcome.target, error: outcome.error });
+					if (outcome.reason !== undefined) rejections.push({ target: outcome.target, reason: outcome.reason });
+				}
+				const failNote = failed.length > 0 ? `; ${failed.length} failed` : "";
+				const marker = sent.length > 0 ? "✓" : "✗";
+				const shownIds = sent.slice(0, MODEL_BROADCAST_ID_SAMPLE).map((item) =>
+					`${normalizeMetadataText(item.target, 80, "peer")}=${normalizeMetadataText(item.msg_id, 128, "msg")}`,
+				);
+				const omittedIds = sent.length - shownIds.length;
+				// The model-facing sample describes each failure in OUR words; a peer's own explanation
+				// travels only inside the fence appended below (`details` keeps it verbatim for the
+				// operator's card, which is rendering, not context).
+				const rejectedTargets = new Set(rejections.map((item) => item.target));
+				const shownFailures = failed.slice(0, MODEL_BROADCAST_FAILURE_SAMPLE).map((item) =>
+					`${normalizeMetadataText(item.target, 80, "peer")}: ${rejectedTargets.has(item.target) ? "rejected by the peer; reason quoted below" : normalizeMetadataText(item.error, 160, "send failed")}`,
+				);
+				const omittedFailures = failed.length - shownFailures.length;
+				const action = omittedIds > 0 || omittedFailures > 0
+					? `; ${[
+						shownIds.length > 0 ? `msg_ids: ${shownIds.join(", ")}${omittedIds > 0 ? `; +${omittedIds} more msg_ids omitted` : ""}` : "",
+						shownFailures.length > 0 ? `failures: ${shownFailures.join("; ")}${omittedFailures > 0 ? `; +${omittedFailures} more failures omitted` : ""}` : "",
+					].filter(Boolean).join("; ")}`
+					: shownIds.length > 0 ? `; msg_ids: ${shownIds.join(", ")}` : "";
+				const quoted = fencedPeerReasons(rejections.slice(0, MODEL_BROADCAST_FAILURE_SAMPLE));
+				const summary = `${marker} queued ${sent.length}/${peers.length} ${peers.length === 1 ? "peer" : "peers"}${failNote}${action}`;
+				return {
+					content: [{ type: "text", text: peers.length === 0 ? "⚠ no reachable peers; nothing queued" : [summary, quoted].filter(Boolean).join("\n") }],
+					details: {
+						target: "*",
+						peerCount: peers.length,
+						queuedCount: sent.length,
+						failedCount: failed.length,
+						msg_ids: sent.slice(0, MAX_BROADCAST_DETAIL_ITEMS).map((item) => normalizeMetadataText(item.msg_id, 128, "msg")),
+						failed: failed.slice(0, MAX_BROADCAST_DETAIL_ITEMS).map((failure) => ({
+							target: normalizeMetadataText(failure.target, 80, "peer"),
+							error: normalizeMetadataText(failure.error, 240, "send failed"),
+						})),
+						omittedMsgIds: Math.max(0, sent.length - MAX_BROADCAST_DETAIL_ITEMS),
+						omittedFailures: Math.max(0, failed.length - MAX_BROADCAST_DETAIL_ITEMS),
+					},
+				};
+			}
+
+			let msg_id: string;
+			try {
+				({ msg_id } = await plane.send(params.target, params.message, params.in_reply_to));
+			} catch (err) {
+				// pi turns a thrown execute() into model-facing tool-result text, so a refusal carrying
+				// the PEER's own NACK prose would land in the supervisor's context as this agent's own
+				// words. Our half stays ours; the peer's half is flattened and fenced, exactly as an
+				// inbound peer message is (src/core/fence.ts).
+				const quoted = err instanceof ExocomPeerRejection ? fencedPeerReasons([{ target: params.target, reason: err.reason }]) : "";
+				throw new Error([refusalLine(params.target, err), quoted].filter(Boolean).join("\n"));
+			}
+			return {
+				content: [{ type: "text", text: `✓ queued to ${params.target} · msg_id=${msg_id}` }],
+				details: { msg_id, target: params.target },
+			};
+		},
+		renderCall(args, theme) {
+			const target = normalizeMetadataText(args.target, 80, "*");
+			const message = String(args.message ?? "").replace(/\s+/g, " ").trim();
+			const preview = normalizeMetadataText(message, 60);
+			const suffix = preview.length < message.length ? "…" : "";
+			return new Text(`${theme.fg("toolTitle", theme.bold("Exocom Send "))}${theme.fg("accent", target)}${preview ? theme.fg("dim", ` ${preview}${suffix}`) : ""}`, 0, 0);
+		},
+		renderResult(result, { expanded }, theme) {
+			const details = result.details as unknown as ExocomSendDetails | undefined;
+			// pi renders this for a FAILED call too, handing us the error's empty details object — an
+			// unrecognised shape is a failure to show, not a send to congratulate the user on.
+			if (!isSendDetails(details)) {
+				const text = result.content.find((item) => item.type === "text");
+				return new Text(theme.fg("error", text?.type === "text" ? text.text : "(no result)"), 0, 0);
+			}
+			return new Text(theme.fg(expanded ? "toolOutput" : "accent", renderSendResult(details, expanded)), 0, 0);
+		},
+	});
+
+	pi.registerTool({
+		name: "exocom_name",
+		label: "Exocom Name",
+		description: inventedExocomNameHint(),
+		parameters: ExocomNameParams,
+		async execute(_toolCallId, params: Static<typeof ExocomNameParams>) {
+			const plane = getPlane();
+			if (!plane || !onRename) throw new Error("exocom is not active for this persona");
+			if (!params.name.trim()) throw new Error("exocom_name: name must contain visible characters");
+			const applied = normalizePeerName(onRename(normalizePeerName(params.name)));
+			return { content: [{ type: "text", text: `exocom: you are now "${applied}"` }], details: { name: applied } };
+		},
+		renderCall(args, theme) {
+			return new Text(`${theme.fg("toolTitle", theme.bold("Exocom Name "))}${theme.fg("accent", normalizeMetadataText(args.name, 96, "peer"))}`, 0, 0);
+		},
+		renderResult(result, { expanded }, theme) {
+			const details = result.details as unknown as { name?: string } | undefined;
+			if (!details?.name) {
+				const first = result.content.find((item) => item.type === "text");
+				return new Text(theme.fg("error", first?.type === "text" ? first.text : "Exocom name failed"), 0, 0);
+			}
+			const name = normalizeMetadataText(details.name, 96, "(unchanged)");
+			const text = `exocom: you are now "${name}"`;
+			return new Text(theme.fg(expanded ? "toolOutput" : "accent", expanded ? text : `${text} (${keyHint("app.tools.expand", "to expand")})`), 0, 0);
+		},
+	});
+}

package/src/tools/flow.ts

@@ -0,0 +1,117 @@
+/** `flow` tool — run a *.flow.json DAG. */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { failureDetails } from "../extension/shared.ts";
+import { fenceUntrusted } from "../core/fence.ts";
+import type { FlowOutcome } from "../orchestration/flow-run.ts";
+import type { FlowSpec } from "../orchestration/flow.ts";
+import { compactInlineText, sanitizeTerminalText } from "../ui/presentation.ts";
+import { compactVisibleText } from "../ui/presentation.ts";
+import { toolUsageField, type ChildUsageLedger } from "../ui/usage.ts";
+import { sumUsage } from "../orchestration/reducers.ts";
+import { emptyUsage } from "../engine/stream.ts";
+import { Text } from "@earendil-works/pi-tui";
+import { expandDetailHint } from "../extension/shared.ts";
+import type { FailureKind } from "../orchestration/types.ts";
+
+export interface FlowToolDeps {
+	get lastCtx(): ExtensionContext | undefined;
+	set lastCtx(value: ExtensionContext | undefined);
+	loadFlow(cwd: string, name: string): { ok: true; flow: FlowSpec } | { ok: false; error: string } | undefined;
+	listFlows(cwd: string): string[];
+	runFlowVisible(ctx: ExtensionContext, spec: FlowSpec, task: string, signal?: AbortSignal): Promise<FlowOutcome>;
+	childUsage: ChildUsageLedger;
+	publishPersonaCost(): void;
+}
+
+export function registerFlowTool(pi: ExtensionAPI, d: FlowToolDeps): void {
+	// ── flow tool (run a *.flow.json DAG over strategies; the supervisor self-launches) ──
+	const FlowToolParams = Type.Object({
+		name: Type.String({ description: "The flow to run — a *.flow.json by name (installed flows are listed in your sub-agents brief; the user can run /flow to list them)" }),
+		task: Type.String({ description: "The objective to run the flow on" }),
+	});
+	pi.registerTool({
+		name: "flow",
+		label: "Flow",
+		description: [
+			"Run a named flow — a declarative DAG over strategies (`*.flow.json`): phases each run a",
+			"strategy over a roster, wired by `needs`, fanning out where independent and threading each",
+			"phase's output into its dependents. Journaled, so an interrupted flow resumes. Reach for it",
+			"when a task has a fixed multi-stage shape (e.g. gather → critique → decide) you want run",
+			"deterministically, end to end, rather than deciding each step yourself.",
+		].join(" "),
+		parameters: FlowToolParams,
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			d.lastCtx = ctx;
+			const parsed = d.loadFlow(ctx.cwd, params.name);
+			if (!parsed) {
+				const installed = d.listFlows(ctx.cwd);
+				const hint = installed.length > 0 ? `Installed flows: ${installed.join(", ")}.` : "No flows are installed — add a *.flow.json under .pi/flows/.";
+				return {
+					content: [{ type: "text", text: `no flow named "${params.name}". ${hint}` }],
+					details: failureDetails({ ok: false, error: `no flow named "${params.name}"` }),
+					isError: true,
+				};
+			}
+			if (!parsed.ok) {
+				return {
+					content: [{ type: "text", text: `flow "${params.name}" is invalid: ${parsed.error}` }],
+					details: failureDetails({ ok: false, failureKind: "contract", error: parsed.error }),
+					isError: true,
+				};
+			}
+			try {
+				const outcome = await d.runFlowVisible(ctx, parsed.flow, params.task, signal);
+				const details = {
+					ok: outcome.ok,
+					failedPhase: outcome.failedPhase,
+					failureKind: outcome.failureKind,
+					error: outcome.error,
+				};
+				const usage = Object.values(outcome.results).length > 0
+					? sumUsage(Object.values(outcome.results).map((r) => r.usage))
+					: emptyUsage();
+				d.childUsage.account(usage);
+				d.publishPersonaCost();
+				return {
+					content: [{ type: "text", text: fenceUntrusted(outcome.output || "(flow produced no output)") }],
+					details: outcome.ok ? details : failureDetails(details),
+					isError: !outcome.ok,
+					...toolUsageField(usage),
+				};
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return { content: [{ type: "text", text: `flow failed: ${message}` }], details: failureDetails({ ok: false, error: message }), isError: true };
+			}
+		},
+		renderCall(args, theme) {
+			return new Text(`${theme.fg("toolTitle", theme.bold("flow "))}${theme.fg("accent", compactInlineText(args.name ?? "?", { maxChars: 96 }) || "?")}`, 0, 0);
+		},
+		renderResult(result, { expanded }, theme) {
+			const details = (result.details ?? {}) as {
+				ok?: boolean;
+				failedPhase?: string;
+				failureKind?: FailureKind;
+				error?: string;
+			};
+			const first = result.content[0];
+			const full = sanitizeTerminalText(first?.type === "text" ? first.text : "(no output)");
+			const failed = details.ok === false;
+			const failureBits = failed
+				? compactInlineText(
+						[details.failedPhase ? `phase ${details.failedPhase}` : undefined, details.failureKind, details.error]
+							.filter((part): part is string => !!part)
+							.join(" · "),
+						{ maxChars: 160 },
+					)
+				: "";
+			const title = failed
+				? theme.fg("error", theme.bold(`flow failed${failureBits ? ` · ${failureBits}` : ""}`))
+				: theme.fg("success", theme.bold("flow complete"));
+			if (expanded) return new Text(`${title}\n${theme.fg("toolOutput", full)}`, 0, 0);
+			const preview = compactVisibleText(full, { maxLines: 3, maxLineChars: 100 });
+			const hint = preview.truncated ? `\n${theme.fg("dim", expandDetailHint())}` : "";
+			return new Text(`${title}\n${theme.fg("toolOutput", preview.text)}${hint}`, 0, 0);
+		},
+	});
+}