@aeondave/pi-persona 1.17.1 → 1.17.4

package/src/tools/exocom.ts

@@ -19,11 +19,13 @@ import { type Static, Type } from "typebox";
 
 import { keyHint, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
 
 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";
@@ -85,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 {
@@ -95,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;
@@ -102,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
@@ -117,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"),
@@ -128,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
@@ -146,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 } : {}),
 	};
 }
 
@@ -227,12 +245,11 @@ function isSendDetails(details: unknown): details is ExocomSendDetails {
 	return Array.isArray(shape.failed) || typeof shape.msg_id === "string";
 }
 
-function renderSendResult(details: ExocomSendDetails, expanded: boolean): string {
+function renderSendResult(details: ExocomSendDetails): 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 summary = `queued ${queued} peer${queued === 1 ? "" : "s"}${failed > 0 ? ` · ${failed} failed` : ""}`;
 		const lines = [summary];
 		if (details.msg_ids.length > 0) lines.push(`msg_ids: ${details.msg_ids.join(", ")}`);
 		for (const failure of details.failed) {
@@ -242,8 +259,7 @@ function renderSendResult(details: ExocomSendDetails, expanded: boolean): string
 		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")})`;
+	return `queued to ${details.target} · msg_id=${details.msg_id}`;
 }
 
 /** `getPlane` is a LIVE accessor, not a captured value: a `canUseBus` downgrade (`stopExocom`,
@@ -294,7 +310,7 @@ export function registerExocomTools(
 		renderCall(_args, theme) {
 			return new Text(theme.fg("toolTitle", theme.bold("Exocom List")), 0, 0);
 		},
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, context) {
 			const details = result.details as unknown as {
 				peers?: ExocomPeerSummary[];
 				total?: number;
@@ -303,9 +319,8 @@ export function registerExocomTools(
 				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);
+			if (context?.isError || !details || !Array.isArray(details.peers)) {
+				return renderLiteralToolResult(result, { expanded }, theme, { isError: true });
 			}
 			const peers = details.peers;
 			const total = typeof details.total === "number" ? details.total : peers.length;
@@ -448,15 +463,14 @@ export function registerExocomTools(
 			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) {
+		renderResult(result, { expanded }, theme, context) {
 			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);
+			if (context?.isError || !isSendDetails(details)) {
+				return renderLiteralToolResult(result, { expanded }, theme, { isError: true });
 			}
-			return new Text(theme.fg(expanded ? "toolOutput" : "accent", renderSendResult(details, expanded)), 0, 0);
+			return renderLiteralToolResult({ ...result, content: [{ type: "text", text: renderSendResult(details) }] }, { expanded }, theme, context);
 		},
 	});
 
@@ -475,15 +489,14 @@ export function registerExocomTools(
 		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) {
+		renderResult(result, { expanded }, theme, context) {
 			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);
+			if (context?.isError || !details?.name) {
+				return renderLiteralToolResult(result, { expanded }, theme, { isError: true });
 			}
 			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);
+			return renderLiteralToolResult({ ...result, content: [{ type: "text", text }] }, { expanded }, theme, context);
 		},
 	});
 }

package/src/tools/flow.ts

@@ -1,27 +1,46 @@
 /** `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 { expandDetailHint, failureDetails, isInline } from "../extension/shared.ts";
 import { fenceUntrusted } from "../core/fence.ts";
-import type { FlowOutcome } from "../orchestration/flow-run.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, sanitizeTerminalText } from "../ui/presentation.ts";
-import { compactVisibleText } from "../ui/presentation.ts";
-import { toolUsageField, type ChildUsageLedger } from "../ui/usage.ts";
+import { compactInlineText, compactVisibleText, sanitizeTerminalText } from "../ui/presentation.ts";
+import { toolUsageField } 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";
+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";
 
 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;
+	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;
+}
+
+/** A finished flow as the tracker sees it. A checkpoint the operator declined is a STOP (the run settles
+ *  "stopped", never "failed"); a cancelled run is an abort; anything else that is not ok is a failure. */
+function flowResult(name: string, outcome: FlowOutcome): AgentResult {
+	const base: AgentResult = {
+		agent: `flow ${name}`,
+		output: outcome.output || "(flow produced no output)",
+		usage: sumUsage(Object.values(outcome.results).map((r) => r.usage)),
+		ok: outcome.ok,
+	};
+	const disposition = flowDisposition(outcome);
+	if (disposition === "done") return base;
+	if (disposition === "stopped") {
+		return { ...base, error: `stopped at checkpoint "${outcome.stoppedAtGate}": not approved`, failureKind: "abort" };
+	}
+	return { ...base, error: outcome.error ?? "flow failed", failureKind: outcome.cancelled ? "abort" : (outcome.failureKind ?? "agent") };
 }
 
 export function registerFlowTool(pi: ExtensionAPI, d: FlowToolDeps): void {
@@ -36,9 +55,11 @@ export function registerFlowTool(pi: ExtensionAPI, d: FlowToolDeps): void {
 		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",
+			"phase's output into its dependents. Journaled: re-running the identical task resumes finished phases. 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.",
+			"deterministically, end to end, rather than deciding each step yourself. Interactive sessions run it in",
+			"the BACKGROUND: you get a run id at once and ONE follow-up when it ends (a checkpoint waits for the",
+			"operator, not for you), so end your turn and never poll it; headless sessions block and return inline.",
 		].join(" "),
 		parameters: FlowToolParams,
 		async execute(_id, params, signal, _onUpdate, ctx) {
@@ -60,43 +81,88 @@ export function registerFlowTool(pi: ExtensionAPI, d: FlowToolDeps): void {
 					isError: true,
 				};
 			}
+			let launch: OrchestrationLaunchSnapshot | undefined;
 			try {
-				const outcome = await d.runFlowVisible(ctx, parsed.flow, params.task, signal);
+				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).
+				const inline = isInline(ctx);
+				const ran: { outcome?: FlowOutcome } = {}; // the run's full outcome, which the tracker's AgentResult cannot carry
+				const id = d.runs.launch({ kind: "flow", label: `flow ${parsed.flow.name}`, task: params.task, inline }, async (run) => {
+					const finished = await d.runFlowVisible(ctx, parsed.flow, params.task, run);
+					ran.outcome = finished;
+					return flowResult(parsed.flow.name, finished);
+				});
+				if (!inline) {
+					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, launch },
+						isError: false,
+					};
+				}
+				const { runs, usage } = await d.runs.settle([id], signal);
+				const run = runs[0];
+				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, 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 } } : {}),
 				};
-				const usage = Object.values(outcome.results).length > 0
-					? sumUsage(Object.values(outcome.results).map((r) => r.usage))
-					: emptyUsage();
-				d.childUsage.account(usage);
-				d.publishPersonaCost();
+				// 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)") }],
-					details: outcome.ok ? details : failureDetails(details),
-					isError: !outcome.ok,
+					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) {
 			return new Text(`${theme.fg("toolTitle", theme.bold("flow "))}${theme.fg("accent", compactInlineText(args.name ?? "?", { maxChars: 96 }) || "?")}`, 0, 0);
 		},
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, context) {
 			const details = (result.details ?? {}) as {
 				ok?: boolean;
 				failedPhase?: string;
 				failureKind?: FailureKind;
 				error?: string;
+				stoppedAtGate?: string;
+				runId?: string;
+				flow?: string;
+				launch?: OrchestrationLaunchSnapshot;
 			};
 			const first = result.content[0];
 			const full = sanitizeTerminalText(first?.type === "text" ? first.text : "(no output)");
-			const failed = details.ok === false;
+			const hostError = context?.isError ?? result.isError;
+			if (details.runId) {
+				// 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 }))}`;
+				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";
 			const failureBits = failed
 				? compactInlineText(
 						[details.failedPhase ? `phase ${details.failedPhase}` : undefined, details.failureKind, details.error]
@@ -105,13 +171,20 @@ export function registerFlowTool(pi: ExtensionAPI, d: FlowToolDeps): void {
 						{ 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 title = () => disposition === "stopped"
+				? theme.fg("warning", theme.bold(`flow stopped · checkpoint ${compactInlineText(details.stoppedAtGate ?? "", { maxChars: 64 })}`))
+				: 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)}${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);
 		},
 	});
 }