@aeondave/pi-persona 1.17.3 → 1.17.4

package/src/tools/exocom-collaboration.ts

@@ -0,0 +1,315 @@
+/** Task, offer, and evidence adapters for the external Exocom collaboration ledger. */
+import { randomUUID } from "node:crypto";
+import { type Static } from "typebox";
+
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import { attributePeer } from "../core/fence.ts";
+import { collaborationOfferStatus, collaborationStatus } from "../exocom/collaboration.ts";
+import type { ExocomPlane } from "../exocom/plane.ts";
+import type { ExocomSemanticFrame } from "../exocom/envelope.ts";
+import type { LedgerState } from "../exocom/ledger.ts";
+import { normalizeMetadataText } from "../exocom/registry.ts";
+import { renderWriteSet, untrusted } from "../exocom/untrusted.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
+import { createReportBody } from "../ui/report-body.ts";
+import {
+	OfferParams,
+	parseOfferInput,
+	parsePublishInput,
+	parseTaskInput,
+	PublishParams,
+	TaskParams,
+} from "./exocom-collaboration-input.ts";
+
+export interface ExocomCollaborationDeps {
+	getPlane: () => ExocomPlane | undefined;
+	sessionId: () => string;
+	name: () => string;
+	now: () => number;
+	/** False for joined foreign workspaces whose file paths differ from the shared ledger scope. */
+	canClaim: () => boolean;
+	/** Recheck the effective capability at execution time, including targeted tool denies. */
+	canCallTool: (name: string) => boolean;
+	/** Canonicalize a public exocom_list target to its authenticated raw session id. */
+	resolveTarget: (target: string) => string;
+	dispatch: (frame: ExocomSemanticFrame) => Promise<{ msg_id: string; peerWakeDeferred?: true }>;
+	ledger: () => LedgerState;
+	/** Resolve attribution from the live registry; self-reported frame names are never used. */
+	labelFor: (sessionId: string) => string | undefined;
+	/** Exact public routing target shown by exocom_list for a live session. */
+	targetForSession: (sessionId: string) => string | undefined;
+}
+
+function toolResult(text: string, details: Record<string, unknown>) {
+	return { content: [{ type: "text" as const, text }], details };
+}
+function checkedIdentity(deps: ExocomCollaborationDeps) {
+	if (!deps.getPlane()) throw new Error("exocom is not active for this persona");
+	const now = deps.now();
+	if (!Number.isFinite(now) || !Number.isFinite(new Date(now).getTime())) throw new Error("exocom: clock returned an invalid timestamp");
+	return { from_session: deps.sessionId(), from_name: deps.name(), ts: new Date(now).toISOString(), now };
+}
+function requireToolPermission(deps: ExocomCollaborationDeps, tool: string): void {
+	if (deps.canCallTool(tool) !== true) throw new Error(`${tool}: this persona cannot call this Exocom tool`);
+}
+function frameIdentity(identity: ReturnType<typeof checkedIdentity>) {
+	return { from_session: identity.from_session, from_name: identity.from_name, ts: identity.ts };
+}
+function requireWriteClaim(deps: ExocomCollaborationDeps, tool: string): void {
+	if (deps.canClaim() !== true || deps.canCallTool("exocom_claim") !== true) {
+		throw new Error(`${tool}: write-set tasks require local workspace scope and callable exocom_claim permission`);
+	}
+}
+function taskByKey(state: LedgerState, workKey: string) {
+	return state.collaboration?.tasks.find((task) => task.created.work_key === workKey);
+}
+function taskByIdentity(state: LedgerState, workKey: string, taskId: string) {
+	return state.collaboration?.tasks.find((task) => task.created.work_key === workKey && task.created.msg_id === taskId);
+}
+function dispatchNotice(deferred: boolean): string {
+	return deferred ? " · ledger committed; peer wake deferred" : "";
+}
+function dispatchDetails(deferred: boolean): Record<string, unknown> {
+	return deferred ? { peerWakeDeferred: true } : {};
+}
+function resolvePeerLabel(deps: ExocomCollaborationDeps, sessionId: string): string {
+	if (sessionId === deps.sessionId()) return `you (${untrusted(deps.name(), 48) || "self"})`;
+	return deps.labelFor(sessionId) ?? sessionId;
+}
+function listPage(deps: ExocomCollaborationDeps, offset: number, limit: number, detail: boolean) {
+	if (detail && limit > 5) throw new Error("exocom_task: limit must be at most 5 when detail=true");
+	const state = deps.ledger();
+	const tasks = state.collaboration?.tasks ?? [];
+	const offers = state.collaboration?.offers ?? [];
+	const total = tasks.length;
+	const page = tasks.slice(offset, offset + limit);
+	const lines = [`exocom tasks · ${total} retained · showing ${page.length} from offset ${offset}`];
+	for (const task of page) {
+		const created = task.created;
+		const status = collaborationStatus(task);
+		const creatorLabel = untrusted(resolvePeerLabel(deps, created.from_session), 64) || created.from_session;
+		lines.push(`\n${created.work_key} · task_id=${created.msg_id} · ${status} · created by ${creatorLabel} · ${created.write_set.length ? `${created.write_set.length} write paths` : "read-only"}`);
+		if (task.taken) {
+			const takerLabel = untrusted(resolvePeerLabel(deps, task.taken.from_session), 64) || task.taken.from_session;
+			lines.push(`taker: ${takerLabel}`);
+		}
+		if (created.write_set.length) {
+			lines.push(`write scope summary (may be clipped; use exocom_task get with work_key=${created.work_key} and task_id=${created.msg_id} for exact paths)`);
+			lines.push(attributePeer(resolvePeerLabel(deps, created.from_session), renderWriteSet(created.write_set)));
+		}
+		const taskOffers = offers.filter((offer) => offer.work_key === created.work_key && offer.task_id === created.msg_id);
+		for (const offer of taskOffers.slice(0, 3)) {
+			const target = offer.to_session
+				? normalizeMetadataText(deps.targetForSession(offer.to_session) ?? `offline:${offer.to_session}`, 80, "offline target")
+				: "pool";
+			const offerState = collaborationOfferStatus(offer, tasks, deps.now());
+			lines.push(`offer ${offer.offer_id} → ${target} · ${offerState} · expires ${offer.expires_at}`);
+		}
+		if (taskOffers.length > 3) lines.push(`offers: +${taskOffers.length - 3} more`);
+		if (detail) {
+			lines.push(attributePeer(resolvePeerLabel(deps, created.from_session), created.description));
+			if (task.progress) lines.push(attributePeer(resolvePeerLabel(deps, task.progress.from_session), `Progress: ${task.progress.note}`));
+			if (task.finished) lines.push(attributePeer(resolvePeerLabel(deps, task.finished.from_session), `Finish (${task.finished.outcome}): ${task.finished.note}`));
+		}
+	}
+	const nextOffset = offset + page.length < total ? offset + page.length : undefined;
+	return toolResult(lines.join("\n"), {
+		action: "list", total, offset, limit, count: page.length,
+		task_ids: page.map((task) => task.created.msg_id),
+		...(nextOffset === undefined ? {} : { nextOffset }), detail,
+	});
+}
+
+function taskDetail(deps: ExocomCollaborationDeps, state: LedgerState, task: NonNullable<ReturnType<typeof taskByIdentity>>) {
+	const created = task.created;
+	const status = collaborationStatus(task);
+	const creator = resolvePeerLabel(deps, created.from_session);
+	const lines = [
+		`exocom task · ${created.work_key} · task_id=${created.msg_id} · ${status}`,
+		`created by ${untrusted(creator, 64) || created.from_session}`,
+		attributePeer(creator, `Description:\n${created.description}`),
+	];
+	if (created.write_set.length) {
+		lines.push(attributePeer(creator, `Exact write_set JSON (${created.write_set.length} paths):\n${JSON.stringify(created.write_set, null, 2)}`));
+	} else {
+		lines.push("write_set: [] (read-only)");
+	}
+	if (task.taken) lines.push(`taken by ${untrusted(resolvePeerLabel(deps, task.taken.from_session), 64) || task.taken.from_session}`);
+	if (task.progress) lines.push(attributePeer(resolvePeerLabel(deps, task.progress.from_session), `Progress:\n${task.progress.note}`));
+	if (task.finished) lines.push(attributePeer(resolvePeerLabel(deps, task.finished.from_session), `Finish (${task.finished.outcome}):\n${task.finished.note}`));
+	const offers = (state.collaboration?.offers ?? []).filter((offer) => offer.work_key === created.work_key && offer.task_id === created.msg_id);
+	for (const offer of offers.slice(0, 3)) {
+		const target = offer.to_session
+			? normalizeMetadataText(deps.targetForSession(offer.to_session) ?? `offline:${offer.to_session}`, 80, "offline target")
+			: "pool";
+		lines.push(`offer ${offer.offer_id} → ${target} · ${collaborationOfferStatus(offer, state.collaboration?.tasks ?? [], deps.now())} · expires ${offer.expires_at}`);
+	}
+	if (offers.length > 3) lines.push(`offers: +${offers.length - 3} more`);
+	return toolResult(lines.join("\n\n"), {
+		action: "get", work_key: created.work_key, task_id: created.msg_id, status,
+		writeSetCount: created.write_set.length, offerIds: offers.map((offer) => offer.offer_id),
+	});
+}
+
+export function registerExocomCollaborationTools(pi: ExtensionAPI, deps: ExocomCollaborationDeps): void {
+	pi.registerTool({
+		name: "exocom_task",
+		label: "Exocom Task",
+		description: "Create or pick up a bounded collaboration task, report progress or finish, inspect full details with get by work_key+task_id, and page through retained tasks. For discovery, use list without work_key/task_id. List pages default to 10 rows (5 with detail=true), cap at 20 summaries and 5 detailed rows; explicit detail limits above 5 are rejected. List write scopes are summaries that may be clipped; get requires both identifiers returned by create/list and shows the exact fenced scope. Write-set tasks require workspace-scoped exocom_claim permission; a foreign-workspace Pi may take read-only tasks.",
+		parameters: TaskParams,
+		async execute(_id, raw: Static<typeof TaskParams>) {
+			const params = parseTaskInput(raw);
+			requireToolPermission(deps, "exocom_task");
+			if (params.action === "list") {
+				checkedIdentity(deps);
+				return listPage(deps, params.offset, params.limit, params.detail);
+			}
+			const identity = checkedIdentity(deps);
+			if (params.action === "create") {
+				if (params.write_set.length) requireWriteClaim(deps, "exocom_task create");
+				if (taskByKey(deps.ledger(), params.work_key)) throw new Error(`exocom_task: work_key ${params.work_key} already exists`);
+				const frame: ExocomSemanticFrame = {
+					kind: "task_create", ...frameIdentity(identity), work_key: params.work_key,
+					description: params.description, write_set: params.write_set, msg_id: randomUUID(),
+				};
+				const sent = await deps.dispatch(frame);
+				return toolResult(`exocom: created task ${params.work_key} · task_id=${sent.msg_id}${dispatchNotice(sent.peerWakeDeferred === true)}`, {
+					action: "create", work_key: params.work_key, task_id: sent.msg_id, msg_id: sent.msg_id, writeSetCount: params.write_set.length,
+					...dispatchDetails(sent.peerWakeDeferred === true),
+				});
+			}
+			const state = deps.ledger();
+			const task = taskByIdentity(state, params.work_key, params.task_id);
+			if (!task) throw new Error(`exocom_task: task_id ${params.task_id} does not match retained task ${params.work_key}`);
+			if (params.action === "get") return taskDetail(deps, state, task);
+			if (params.action === "take") {
+				if (task.created.write_set.length) requireWriteClaim(deps, "exocom_task take");
+				if (collaborationStatus(task) !== "open") throw new Error(`exocom_task: task is ${collaborationStatus(task)}; pickup refused`);
+				const frame: ExocomSemanticFrame = { kind: "task_take", ...frameIdentity(identity), work_key: params.work_key, task_id: params.task_id, msg_id: randomUUID() };
+				const sent = await deps.dispatch(frame);
+				return toolResult(`exocom: took task ${params.work_key} · task_id=${params.task_id} · msg_id=${sent.msg_id}${dispatchNotice(sent.peerWakeDeferred === true)}`, {
+					action: "take", work_key: params.work_key, task_id: params.task_id, msg_id: sent.msg_id, ...dispatchDetails(sent.peerWakeDeferred === true),
+				});
+			}
+			if (task.taken?.from_session !== identity.from_session || collaborationStatus(task) !== "taken") {
+				throw new Error(`exocom_task ${params.action}: only the active task taker may report progress or finish`);
+			}
+			let frame: ExocomSemanticFrame;
+			if (params.action === "progress") {
+				frame = { kind: "progress", ...frameIdentity(identity), work_key: params.work_key, task_id: params.task_id, note: params.note, msg_id: randomUUID() };
+			} else {
+				frame = { kind: "task_finish", ...frameIdentity(identity), work_key: params.work_key, task_id: params.task_id, outcome: params.outcome, note: params.note, msg_id: randomUUID() };
+			}
+			const sent = await deps.dispatch(frame);
+			return toolResult(`exocom: ${params.action} ${params.work_key} · task_id=${params.task_id} · msg_id=${sent.msg_id}`, {
+				action: params.action, work_key: params.work_key, task_id: params.task_id, msg_id: sent.msg_id,
+				...(params.action === "finish" ? { outcome: params.outcome } : {}),
+				...dispatchDetails(sent.peerWakeDeferred === true),
+			});
+		},
+		renderCall(args, theme) {
+			return new Text(`${theme.fg("toolTitle", theme.bold("Exocom Task "))}${theme.fg("accent", normalizeMetadataText(args.action, 24, "task"))}${args.work_key ? ` ${normalizeMetadataText(args.work_key, 80, "work")}` : ""}`, 0, 0);
+		},
+		renderResult(res, options, theme, context) {
+			if (options.expanded && !(context?.isError ?? res.isError) && (res.details?.detail === true || res.details?.action === "get")) {
+				const text = res.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+				return createReportBody(text, theme, {}, context?.lastComponent);
+			}
+			return renderLiteralToolResult(res, options, theme, context);
+		},
+	});
+
+	pi.registerTool({
+		name: "exocom_offer",
+		label: "Exocom Offer",
+		description: "Offer an open task to one peer from exocom_list or to the pool. Expiration defaults to one hour and is capped at 24 hours.",
+		parameters: OfferParams,
+		async execute(_id, raw: Static<typeof OfferParams>) {
+			const params = parseOfferInput(raw);
+			requireToolPermission(deps, "exocom_offer");
+			const identity = checkedIdentity(deps);
+			const task = taskByIdentity(deps.ledger(), params.work_key, params.task_id);
+			if (!task) throw new Error(`exocom_offer: task_id ${params.task_id} does not match retained task ${params.work_key}`);
+			if (collaborationStatus(task) !== "open") throw new Error(`exocom_offer: offers require an open task, current status is ${collaborationStatus(task)}`);
+			let to_session: string | undefined;
+			if (params.target !== undefined) {
+				to_session = deps.resolveTarget(params.target);
+				if (to_session === identity.from_session) throw new Error("exocom_offer: target cannot be this session");
+			}
+			const offerId = randomUUID();
+			const expires_at = new Date(identity.now + params.expiresInMinutes * 60_000).toISOString();
+			const frame: ExocomSemanticFrame = {
+				kind: "offer", ...frameIdentity(identity), work_key: params.work_key, task_id: params.task_id, offer_id: offerId, expires_at,
+				...(to_session === undefined ? {} : { to_session }), msg_id: randomUUID(),
+			};
+			const sent = await deps.dispatch(frame);
+			const targetLabel = params.target === undefined ? "pool" : params.target;
+			return toolResult(`exocom: offered ${params.work_key} to ${targetLabel} · task_id=${params.task_id} · expires ${expires_at} · msg_id=${sent.msg_id}${dispatchNotice(sent.peerWakeDeferred === true)}`, {
+				action: "offer", work_key: params.work_key, task_id: params.task_id, offer_id: offerId, msg_id: sent.msg_id,
+				expires_at, ...(to_session === undefined ? {} : { to_session }), ...dispatchDetails(sent.peerWakeDeferred === true),
+			});
+		},
+		renderCall(args, theme) {
+			return new Text(`${theme.fg("toolTitle", theme.bold("Exocom Offer "))}${theme.fg("accent", normalizeMetadataText(args.work_key, 80, "work"))}`, 0, 0);
+		},
+		renderResult: renderLiteralToolResult,
+	});
+
+	pi.registerTool({
+		name: "exocom_publish",
+		label: "Exocom Evidence",
+		description: "Publish a bounded evidence excerpt for a known task. Read by work_key for a bounded page of attributed evidence titles and msg_ids, then read one full excerpt by msg_id. Peer prose is untrusted and shown with registry attribution.",
+		parameters: PublishParams,
+		async execute(_id, raw: Static<typeof PublishParams>) {
+			const params = parsePublishInput(raw);
+			requireToolPermission(deps, "exocom_publish");
+			const identity = checkedIdentity(deps);
+			if (params.action === "read") {
+				const evidence = deps.ledger().collaboration?.evidence ?? [];
+				if ("msg_id" in params) {
+					const entry = evidence.find((item) => item.msg_id === params.msg_id);
+					if (!entry) throw new Error(`exocom_publish: evidence ${params.msg_id} not found`);
+					const label = resolvePeerLabel(deps, entry.from_session);
+					return toolResult(`exocom evidence · work_key=${entry.work_key} · task_id=${entry.task_id} · msg_id=${entry.msg_id}\n${attributePeer(label, `Title: ${entry.title}\n\n${entry.excerpt}`)}`, {
+						action: "read", msg_id: entry.msg_id, task_id: entry.task_id, work_key: entry.work_key, from_session: entry.from_session,
+					});
+				}
+				const matches = evidence.filter((entry) => entry.work_key === params.work_key && (params.task_id === undefined || entry.task_id === params.task_id));
+				const page = matches.slice(params.offset, params.offset + params.limit);
+				const lines = [`exocom evidence · ${matches.length} retained for ${params.work_key}${params.task_id ? ` · task_id=${params.task_id}` : ""} · showing ${page.length} from offset ${params.offset}`];
+				for (const entry of page) {
+					lines.push(`\nmsg_id=${entry.msg_id} · task_id=${entry.task_id} · from ${untrusted(resolvePeerLabel(deps, entry.from_session), 64) || entry.from_session}`);
+					lines.push(attributePeer(resolvePeerLabel(deps, entry.from_session), `Title: ${entry.title}`));
+				}
+				const nextOffset = params.offset + page.length < matches.length ? params.offset + page.length : undefined;
+				return toolResult(lines.join("\n"), {
+					action: "read", work_key: params.work_key, ...(params.task_id ? { task_id: params.task_id } : {}), offset: params.offset, limit: params.limit,
+					count: page.length, total: matches.length, ...(nextOffset === undefined ? {} : { nextOffset }),
+					msg_ids: page.map((entry) => entry.msg_id), task_ids: [...new Set(page.map((entry) => entry.task_id))],
+				});
+			}
+			if (!taskByIdentity(deps.ledger(), params.work_key, params.task_id)) throw new Error(`exocom_publish: task_id ${params.task_id} does not match retained task ${params.work_key}`);
+			const frame: ExocomSemanticFrame = {
+				kind: "publish", ...frameIdentity(identity), work_key: params.work_key, task_id: params.task_id, title: params.title,
+				excerpt: params.excerpt, msg_id: randomUUID(),
+			};
+			const sent = await deps.dispatch(frame);
+			return toolResult(`exocom: published evidence for ${params.work_key} · task_id=${params.task_id} · msg_id=${sent.msg_id}${dispatchNotice(sent.peerWakeDeferred === true)}`, {
+				action: "publish", work_key: params.work_key, task_id: params.task_id, msg_id: sent.msg_id, ...dispatchDetails(sent.peerWakeDeferred === true),
+			});
+		},
+		renderCall(args, theme) {
+			const label = args.action === "read" ? normalizeMetadataText(args.msg_id ?? args.work_key, 80, "evidence") : normalizeMetadataText(args.work_key, 80, "work");
+			return new Text(`${theme.fg("toolTitle", theme.bold("Exocom Evidence "))}${theme.fg("accent", label)}`, 0, 0);
+		},
+		renderResult(res, options, theme, context) {
+			if (options.expanded && !(context?.isError ?? res.isError) && res.details?.action === "read") {
+				const text = res.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+				return createReportBody(text, theme, {}, context?.lastComponent);
+			}
+			return renderLiteralToolResult(res, options, theme, context);
+		},
+	});
+}

package/src/tools/exocom-profile.ts

@@ -0,0 +1,102 @@
+/** Self-reported Exocom presence. This metadata never grants authority or changes tool gates. */
+import { type Static, Type } from "typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { normalizeExocomProfile, type ExocomProfile } from "../exocom/profile.ts";
+import type { ExocomPlane } from "../exocom/plane.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
+
+const ExocomProfileParams = Type.Object({
+	action: Type.Union([Type.Literal("get"), Type.Literal("set"), Type.Literal("clear")], {
+		description: "get the current self-report · set selected fields · clear it back to unknown",
+	}),
+	capabilities: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 48 }), {
+		maxItems: 8,
+		description: "set: up to 8 self-reported capability labels, each at most 48 characters",
+	})),
+	availability: Type.Optional(Type.Union([
+		Type.Literal("available"), Type.Literal("busy"), Type.Literal("away"),
+	], { description: "set: your self-reported current availability; omitted remains unknown" })),
+});
+
+interface ProfileToolDetails {
+	action: "get" | "set" | "clear";
+	profile?: ExocomProfile;
+}
+
+function formatProfile(profile: ExocomProfile | undefined): string {
+	if (!profile) return "No profile reported; availability is unknown.";
+	const availability = profile.availability ?? "unknown";
+	const capabilities = profile.capabilities.length > 0 ? profile.capabilities.join(" · ") : "not reported";
+	return `Self-reported availability: ${availability}\nSelf-reported capabilities: ${capabilities}`;
+}
+
+function actionText(details: ProfileToolDetails): string {
+	if (details.action === "clear") return "Profile cleared; availability is unknown.";
+	return formatProfile(details.profile);
+}
+
+/** `getPlane` is read on each call so a revoked Exocom plane cannot leave a stale mutator alive. */
+export function registerExocomProfileTool(pi: ExtensionAPI, getPlane: () => ExocomPlane | undefined): void {
+	pi.registerTool({
+		name: "exocom_profile",
+		label: "Exocom Profile",
+		description: [
+			"Report your own optional Exocom presence. `get` reads it, `set` updates the supplied fields,",
+			"and `clear` removes it. Capabilities and availability are self-reported metadata only; they",
+			"do not prove identity, grant permissions, reserve work, or change tool access. An unset",
+			"availability is unknown; a partial update leaves an existing value unchanged. The profile lasts only for this Exocom session.",
+		].join(" "),
+		parameters: ExocomProfileParams,
+		async execute(_toolCallId, params: Static<typeof ExocomProfileParams>): Promise<{
+			content: [{ type: "text"; text: string }];
+			details: ProfileToolDetails;
+		}> {
+			const action = params && typeof params === "object" ? (params as { action?: unknown }).action : undefined;
+			if (typeof action !== "string" || !["get", "set", "clear"].includes(action)) {
+				throw new Error("exocom_profile: action must be get, set, or clear");
+			}
+			const plane = getPlane();
+			if (!plane) throw new Error("exocom is not active for this persona");
+			if (params.action === "get") {
+				const profile = normalizeExocomProfile(plane.getProfile());
+				return { content: [{ type: "text" as const, text: formatProfile(profile) }], details: { action: "get", ...(profile ? { profile } : {}) } satisfies ProfileToolDetails };
+			}
+			if (params.action === "clear") {
+				plane.setProfile(undefined);
+				return { content: [{ type: "text" as const, text: "Profile cleared; availability is unknown." }], details: { action: "clear" } satisfies ProfileToolDetails };
+			}
+			if (params.capabilities === undefined && params.availability === undefined) {
+				throw new Error("exocom_profile set needs at least one of { capabilities, availability }");
+			}
+			const current = normalizeExocomProfile(plane.getProfile());
+			const next = normalizeExocomProfile({
+				capabilities: params.capabilities ?? current?.capabilities ?? [],
+				...(params.availability ?? current?.availability
+					? { availability: params.availability ?? current?.availability }
+					: {}),
+			});
+			if (!next) throw new Error("exocom_profile set needs at least one visible capability or an availability value");
+			plane.setProfile(next);
+			return {
+				content: [{ type: "text" as const, text: formatProfile(next) }],
+				details: { action: "set", profile: next } satisfies ProfileToolDetails,
+			};
+		},
+		renderCall(args, theme) {
+			const action = typeof args.action === "string" ? args.action : "get";
+			return new Text(theme.fg("toolTitle", theme.bold(`Exocom Profile ${action}`)), 0, 0);
+		},
+		renderResult(result, { expanded }, theme, context) {
+			if (context?.isError || result.isError) return renderLiteralToolResult(result, { expanded }, theme, context);
+			const details = result.details as unknown as ProfileToolDetails | undefined;
+			if (!details || !["get", "set", "clear"].includes(details.action)) {
+				return renderLiteralToolResult(result, { expanded }, theme, { isError: true });
+			}
+			return renderLiteralToolResult({
+				...result,
+				content: [{ type: "text", text: actionText(details) }],
+			}, { expanded }, theme);
+		},
+	});
+}

package/src/tools/exocom.ts

@@ -25,6 +25,7 @@ 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 { normalizeExocomProfile, type ExocomProfile } from "../exocom/profile.ts";
 import { normalizeMetadataText, normalizePeerName } from "../exocom/registry.ts";
 import type { ExocomScope } from "../exocom/scope.ts";
 import { compactInlineText } from "../ui/presentation.ts";
@@ -86,6 +87,7 @@ type ExocomPeerSummary = Pick<DisplayPeer, "displayName" | "persona" | "model" |
 	workspace_code?: string;
 	workspace_label?: string;
 	sameWorkspace?: boolean;
+	profile?: ExocomProfile;
 };
 
 function peerWord(count: number): string {
@@ -96,6 +98,14 @@ function peerWord(count: number): string {
  * 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 availability = peer.profile?.availability ?? "unknown";
+	const capabilities = peer.profile?.capabilities ?? [];
+	const visibleCapabilities = capabilities.slice(0, expanded ? 8 : 2).join(" · ")
+		|| "capabilities not reported";
+	const omittedCapabilities = Math.max(0, capabilities.length - (expanded ? 8 : 2));
+	const profileLine = expanded
+		? `  self-reported availability: ${availability} · capabilities: ${compactInlineText(visibleCapabilities, { maxChars: 420 })}${omittedCapabilities ? ` · +${omittedCapabilities} more` : ""}`
+		: `  self-reported: ${availability} · ${compactInlineText(visibleCapabilities, { maxChars: 44 })}${omittedCapabilities ? ` · +${omittedCapabilities} more` : ""}`;
 	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;
@@ -103,12 +113,12 @@ function peerRows(peer: ExocomPeerSummary, expanded: boolean): string[] {
 		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] : [])];
+		return [`- ${name} · ${persona} · ctx ${context}`, `  model: ${model}`, profileLine, ...(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] : [])];
+	return [`- ${name} · ${persona} · ${model} · ctx ${context}`, profileLine, ...(workspace ? [workspace] : [])];
 }
 
 /** The model-facing row carries the ROUTE as well as the human label: a display name is
@@ -118,10 +128,15 @@ 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}`;
+	const availability = peer.profile?.availability ?? "unknown";
+	const capabilities = peer.profile?.capabilities.length
+		? peer.profile.capabilities.join(", ")
+		: "not reported";
+	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")} · self-reported availability: ${availability} · capabilities: ${capabilities}${workspace}`;
 }
 
 function summarizePeer(peer: DisplayPeer, scope: ExocomScope | undefined): ExocomPeerSummary {
+	const profile = normalizeExocomProfile(peer.profile);
 	if (!scope) {
 		return {
 			displayName: normalizeMetadataText(peer.displayName, 80, "peer"),
@@ -129,6 +144,7 @@ function summarizePeer(peer: DisplayPeer, scope: ExocomScope | undefined): Exoco
 			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)),
+			...(profile ? { profile } : {}),
 		};
 	}
 	// Legacy peers predate workspace metadata. Their registry location still proves they belong
@@ -147,6 +163,7 @@ function summarizePeer(peer: DisplayPeer, scope: ExocomScope | undefined): Exoco
 		...(workspaceCode ? { workspace_code: workspaceCode } : {}),
 		workspace_label: normalizeMetadataText(workspaceLabel, 80, "workspace"),
 		sameWorkspace: workspaceId === scope.homeWorkspaceId,
+		...(profile ? { profile } : {}),
 	};
 }
 

package/src/tools/flow.ts

@@ -3,6 +3,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Type } from "typebox";
 import { expandDetailHint, failureDetails, isInline } from "../extension/shared.ts";
 import { fenceUntrusted } from "../core/fence.ts";
+import { resultReceiptHint } from "../results/retrieval.ts";
 import { flowDisposition, type FlowOutcome } from "../orchestration/flow-run.ts";
 import type { FlowSpec } from "../orchestration/flow.ts";
 import { compactInlineText, compactVisibleText, sanitizeTerminalText } from "../ui/presentation.ts";
@@ -10,6 +11,7 @@ import { toolUsageField } from "../ui/usage.ts";
 import { sumUsage } from "../orchestration/reducers.ts";
 import { Text } from "@earendil-works/pi-tui";
 import { createReportBody } from "../ui/report-body.ts";
+import { orchestrationLaunchLines, type OrchestrationLaunchSnapshot } from "../ui/orchestration-launch.ts";
 import type { AgentResult, FailureKind } from "../orchestration/types.ts";
 import { launchReceipt, type BackgroundRuns, type TrackedRun } from "./background-run.ts";
 
@@ -18,6 +20,7 @@ export interface FlowToolDeps {
 	set lastCtx(value: ExtensionContext | undefined);
 	loadFlow(cwd: string, name: string): { ok: true; flow: FlowSpec } | { ok: false; error: string } | undefined;
 	listFlows(cwd: string): string[];
+	launchSnapshot(ctx: ExtensionContext, spec: FlowSpec): OrchestrationLaunchSnapshot;
 	runFlowVisible(ctx: ExtensionContext, spec: FlowSpec, task: string, tracked?: TrackedRun): Promise<FlowOutcome>;
 	/** Launch/join: a flow is one tracked run, like a delegate leg (see background-run.ts). */
 	runs: BackgroundRuns;
@@ -78,7 +81,15 @@ export function registerFlowTool(pi: ExtensionAPI, d: FlowToolDeps): void {
 					isError: true,
 				};
 			}
+			let launch: OrchestrationLaunchSnapshot | undefined;
 			try {
+				try {
+					const snapshot = d.launchSnapshot(ctx, parsed.flow);
+					launch = { ...snapshot, participants: snapshot.participants.map((participant) => ({ ...participant })) };
+				} catch {
+					// This is presentation metadata only; a settings/model lookup must not block the flow.
+					launch = { participants: [], unavailable: true };
+				}
 				// The same launch `delegate` uses: ONE tracked run. Interactive sessions get a receipt now and
 				// the outcome as ONE completion follow-up; a checkpoint is the OPERATOR's modal and never wakes
 				// the model. Headless sessions join the run before returning (and reject every checkpoint).
@@ -93,7 +104,7 @@ export function registerFlowTool(pi: ExtensionAPI, d: FlowToolDeps): void {
 					const name = compactInlineText(parsed.flow.name, { maxChars: 64 });
 					return {
 						content: [{ type: "text", text: launchReceipt("flow", id, name, "when it ends; a checkpoint waits for the operator, not for you") }],
-						details: { runId: id, flow: name },
+						details: { runId: id, flow: name, launch },
 						isError: false,
 					};
 				}
@@ -102,26 +113,28 @@ export function registerFlowTool(pi: ExtensionAPI, d: FlowToolDeps): void {
 				const outcome = ran.outcome;
 				if (!outcome) {
 					const message = run?.error ?? run?.result?.error ?? run?.status ?? "the run record is gone";
-					return { content: [{ type: "text", text: `flow failed: ${message}` }], details: failureDetails({ ok: false, error: message }), isError: true };
+					return { content: [{ type: "text", text: `flow failed: ${message}` }], details: failureDetails({ ok: false, error: message, launch }), isError: true };
 				}
 				const details = {
+					launch,
 					ok: outcome.ok,
 					failedPhase: outcome.failedPhase,
 					failureKind: outcome.failureKind,
 					error: outcome.error,
 					stoppedAtGate: outcome.stoppedAtGate,
+					...(run?.resultReceipt ? { resultReceipt: { ...run.resultReceipt } } : {}),
 				};
 				// An unapproved checkpoint is the operator's choice: the flow stopped, it did not fail.
 				const failed = flowDisposition(outcome) === "failed";
 				return {
-					content: [{ type: "text", text: fenceUntrusted(outcome.output || "(flow produced no output)") }],
+					content: [{ type: "text", text: `${fenceUntrusted(outcome.output || "(flow produced no output)")}${run?.resultReceipt ? `\n\n${resultReceiptHint(run.resultReceipt)}` : ""}` }],
 					details: failed ? failureDetails(details) : details,
 					isError: failed,
 					...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 };
+				return { content: [{ type: "text", text: `flow failed: ${message}` }], details: failureDetails({ ok: false, error: message, ...(launch ? { launch } : {}) }), isError: true };
 			}
 		},
 		renderCall(args, theme) {
@@ -136,6 +149,7 @@ export function registerFlowTool(pi: ExtensionAPI, d: FlowToolDeps): void {
 				stoppedAtGate?: string;
 				runId?: string;
 				flow?: string;
+				launch?: OrchestrationLaunchSnapshot;
 			};
 			const first = result.content[0];
 			const full = sanitizeTerminalText(first?.type === "text" ? first.text : "(no output)");
@@ -144,7 +158,8 @@ export function registerFlowTool(pi: ExtensionAPI, d: FlowToolDeps): void {
 				// Interactive launch receipt: the outcome arrives later as the completion follow-up.
 				const launched = hostError || details.ok === false ? theme.fg("error", theme.bold("flow failed"))
 					: `${theme.fg("toolTitle", theme.bold("flow "))}${theme.fg("accent", compactInlineText(`launched ${details.runId} · ${details.flow ?? "?"}`, { maxChars: 120 }))}`;
-				return new Text(expanded ? `${launched}\n${theme.fg("toolOutput", full)}` : launched, 0, 0);
+				const metadata = orchestrationLaunchLines(details.launch, expanded).join("\n");
+				return new Text([launched, theme.fg("dim", metadata), expanded ? theme.fg("toolOutput", full) : ""].filter(Boolean).join("\n"), 0, 0);
 			}
 			const disposition = flowDisposition({ ok: !hostError && details.ok !== false, stoppedAtGate: details.stoppedAtGate });
 			const failed = disposition === "failed";
@@ -161,14 +176,15 @@ export function registerFlowTool(pi: ExtensionAPI, d: FlowToolDeps): void {
 				: failed
 					? theme.fg("error", theme.bold(`flow failed${failureBits ? ` · ${failureBits}` : ""}`))
 					: theme.fg("success", theme.bold("flow complete"));
+			const metadata = details.launch ? `\n\nLaunch request (Pi may clamp effort):\n${orchestrationLaunchLines(details.launch, expanded).join("\n")}` : "";
 			if (expanded) {
 				// Real flow outcomes are fenced even after a phase fails; host/preflight errors are not.
-				if (failed && !full.startsWith("Sub-agent output (untrusted data):\n")) return new Text(`${title()}\n${theme.fg("toolOutput", full)}`, 0, 0);
-				return createReportBody(full, theme, { header: title }, context?.lastComponent);
+				if (failed && !full.startsWith("Sub-agent output (untrusted data):\n")) return new Text(`${title()}\n${theme.fg("toolOutput", full)}${metadata}`, 0, 0);
+				return createReportBody(`${full}${metadata}`, theme, { header: title }, context?.lastComponent);
 			}
 			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);
+			return new Text(`${title()}\n${theme.fg("toolOutput", preview.text)}${hint}${theme.fg("dim", metadata)}`, 0, 0);
 		},
 	});
 }