@aeondave/pi-persona 1.15.2

package/src/extension/identity.ts

@@ -0,0 +1,244 @@
+/** Session identity registration and Pi lifecycle adapter. */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { type Static, Type } from "typebox";
+
+import { canCallTool, type EffectiveCapabilities } from "../core/capabilities.ts";
+import {
+	findStoredIdentity,
+	IDENTITY_CONTEXT_CUSTOM_TYPE,
+	IDENTITY_ENTRY_CUSTOM_TYPE,
+	makeIdentityEntry,
+	provisionalIdentityName,
+	sanitizeIdentityName,
+} from "../core/session-identity.ts";
+import { compactInlineText } from "../ui/presentation.ts";
+
+export interface IdentityHost {
+	capabilities(): EffectiveCapabilities | undefined;
+	reservedNames(): string[];
+	exocomActive(): boolean;
+	onChanged(ctx: ExtensionContext): void;
+}
+
+export interface SessionIdentity {
+	start(ctx: ExtensionContext): void;
+	rename(raw: string, ctx: ExtensionContext): string;
+	readonly name: string;
+	readonly chosen: boolean;
+}
+
+const AgentNameParams = Type.Object({
+	name: Type.String({ minLength: 1, maxLength: 32, description: "A short personal handle, separate from persona and role." }),
+});
+
+type SessionManagerCompat = {
+	getSessionId?: () => string;
+	getHeader?: () => { id?: string } | null;
+	getBranch?: () => readonly unknown[];
+	getEntries?: () => readonly unknown[];
+};
+
+function sessionManager(ctx: ExtensionContext): SessionManagerCompat {
+	return (ctx as ExtensionContext & { sessionManager?: SessionManagerCompat }).sessionManager ?? {};
+}
+
+/** Read the real session id when available. Process fallback is intentionally start-only. */
+function readSessionId(ctx: ExtensionContext, allowProcessFallback: boolean): string | undefined {
+	const manager = sessionManager(ctx);
+	try {
+		const id = manager.getSessionId?.();
+		if (typeof id === "string" && id.trim()) return id;
+	} catch {
+		/* Compatibility with light-weight session-manager test doubles. */
+	}
+	try {
+		const id = manager.getHeader?.()?.id;
+		if (typeof id === "string" && id.trim()) return id;
+	} catch {
+		/* Compatibility with light-weight session-manager test doubles. */
+	}
+	return allowProcessFallback ? `process-${process.pid}` : undefined;
+}
+
+function readEntries(ctx: ExtensionContext): readonly unknown[] {
+	const manager = sessionManager(ctx);
+	try {
+		const branch = manager.getBranch?.();
+		if (Array.isArray(branch)) return branch;
+	} catch {
+		/* Fall through to getEntries when a mock or older host has no branch reader. */
+	}
+	try {
+		const entries = manager.getEntries?.();
+		if (Array.isArray(entries)) return entries;
+	} catch {
+		/* Missing persistence only means there is no stored chosen identity to restore. */
+	}
+	return [];
+}
+
+function setIdentityStatus(ctx: ExtensionContext, name: string): void {
+	try {
+		ctx.ui.setStatus("persona-identity", name);
+	} catch {
+		/* Status is cosmetic; the append-only identity entry remains authoritative. */
+	}
+}
+
+function activeTools(pi: ExtensionAPI): readonly string[] {
+	try {
+		const getActiveTools = (pi as unknown as { getActiveTools?: () => string[] }).getActiveTools;
+		const names = getActiveTools?.call(pi);
+		return Array.isArray(names) ? names : [];
+	} catch {
+		return [];
+	}
+}
+
+function toolIsCallable(pi: ExtensionAPI, host: IdentityHost, name: string): boolean {
+	if (!activeTools(pi).includes(name)) return false;
+	const caps = host.capabilities();
+	return caps === undefined || canCallTool(caps, name);
+}
+
+function messageCustomType(message: AgentMessage): string | undefined {
+	const item = message as AgentMessage & { customType?: unknown };
+	return typeof item.customType === "string" ? item.customType : undefined;
+}
+
+function hasInboundPeerRequest(messages: readonly AgentMessage[]): boolean {
+	return messages.some((message) => {
+		const customType = messageCustomType(message);
+		return customType === "exocom_received" || customType === "exocom-inbound" || customType === "pi-persona:exocom-inbound";
+	});
+}
+
+/** Render the one-shot naming bootstrap without copying any user or peer payload into it. */
+export function buildIdentityContext(
+	chosen: boolean,
+	options: { namingTool?: "agent_name" | "exocom_name"; inboundPeer?: boolean } = {},
+): string | undefined {
+	if (chosen || !options.namingTool) return undefined;
+	const source = options.inboundPeer ? "the current task or inbound peer request" : "the current user task or an inbound peer request";
+	return (
+		`[pi-persona] FIRST action: invent a distinct short personal handle from ${source}, ` +
+		`then call ${options.namingTool}({ name: "<your invented handle>" }) before other work. ` +
+		"The handle is separate from your persona and role, persists across turns and persona changes, and must never borrow a peer's or role's name. Do not make an extra model call. " +
+		"After the naming tool succeeds, continue the task; no separate acknowledgement is needed."
+	);
+}
+
+function identityReceipt(name: string, changed: boolean): string {
+	return `Session handle: "${name}" (${changed ? "saved" : "unchanged"}).`;
+}
+
+export function installIdentity(pi: ExtensionAPI, host: IdentityHost): SessionIdentity {
+	let currentSessionId: string | undefined;
+	let currentName = provisionalIdentityName(`process-${process.pid}`);
+	let currentChosen = false;
+	let currentSessionIsFallback = false;
+	let started = false;
+
+	const identity: SessionIdentity = {
+		start(ctx) {
+			const detectedSessionId = readSessionId(ctx, false);
+			const sessionId = detectedSessionId ?? readSessionId(ctx, true)!;
+			if (started && currentSessionId === sessionId) {
+				setIdentityStatus(ctx, currentName);
+				return;
+			}
+			currentSessionId = sessionId;
+			currentSessionIsFallback = detectedSessionId === undefined;
+			const stored = findStoredIdentity(readEntries(ctx), sessionId, host.reservedNames());
+			currentName = stored ?? provisionalIdentityName(sessionId);
+			currentChosen = stored !== undefined;
+			started = true;
+			setIdentityStatus(ctx, currentName);
+		},
+
+		rename(raw, ctx) {
+			const name = sanitizeIdentityName(raw, host.reservedNames());
+			if (!name) throw new Error("identity name is empty, unsafe, generic, or reserved by a persona/agent");
+			const sessionId = readSessionId(ctx, false) ?? (currentSessionIsFallback ? undefined : currentSessionId);
+			if (!sessionId) throw new Error("identity session is unavailable");
+			if (currentChosen && currentSessionId === sessionId && currentName === name) return currentName;
+
+			// Persistence comes first. A failed append therefore cannot leave memory or telemetry
+			// claiming a name that is absent from the session history.
+			pi.appendEntry(IDENTITY_ENTRY_CUSTOM_TYPE, makeIdentityEntry(sessionId, name));
+			currentSessionId = sessionId;
+			currentName = name;
+			currentChosen = true;
+			setIdentityStatus(ctx, currentName);
+			try {
+				host.onChanged(ctx);
+			} catch {
+				/* Identity persistence is authoritative; Exocom/telemetry refresh is best effort. */
+			}
+			return currentName;
+		},
+
+		get name() { return currentName; },
+		get chosen() { return currentChosen; },
+	};
+
+	pi.registerTool({
+		name: "agent_name",
+		label: "Agent Name",
+		description: "Choose a short personal handle for this session. It is separate from the active persona and role, persists across turns and persona changes, and is unavailable while Exocom is active; use exocom_name there.",
+		parameters: AgentNameParams,
+		async execute(_toolCallId, params: Static<typeof AgentNameParams>, _signal, _onUpdate, ctx) {
+			if (host.exocomActive()) throw new Error("agent_name is unavailable while Exocom is active; use exocom_name");
+			if (!activeTools(pi).includes("agent_name")) throw new Error("agent_name is not active in this session");
+			const caps = host.capabilities();
+			if (caps !== undefined && !canCallTool(caps, "agent_name")) throw new Error("agent_name is not permitted by the active persona");
+			const previousName = identity.chosen ? identity.name : undefined;
+			const name = identity.rename(params.name, ctx);
+			const changed = previousName !== name;
+			const text = identityReceipt(name, changed);
+			return { content: [{ type: "text", text }], details: { name, changed } };
+		},
+		renderCall(args, theme) {
+			const name = compactInlineText(args.name, { maxChars: 32 }) || "?";
+			return new Text(`${theme.fg("toolTitle", theme.bold("Agent Name "))}${theme.fg("accent", name)}`, 0, 0);
+		},
+		renderResult(result, { expanded }, theme) {
+			const details = result.details as unknown as { name?: unknown; changed?: unknown } | undefined;
+			const name = typeof details?.name === "string" ? compactInlineText(details.name, { maxChars: 32 }) : "";
+			const first = result.content.find((item) => item.type === "text");
+			const rendered = name
+				? identityReceipt(name, details?.changed !== false)
+				: first?.type === "text" ? compactInlineText(first.text, { maxChars: 96 }) : "Agent name failed";
+			return new Text(theme.fg(name ? (expanded ? "toolOutput" : "accent") : "error", rendered), 0, 0);
+		},
+	});
+
+	// Context is rebuilt for every provider request. The hidden message is actionable only until a
+	// name is chosen; emitting identity metadata afterwards makes it look like a fresh user turn on
+	// every tool-loop continuation. Always strip an older copy, then add only the naming bootstrap.
+	pi.on("context", (event, _ctx) => {
+		const messages = event.messages.filter((message) => messageCustomType(message) !== IDENTITY_CONTEXT_CUSTOM_TYPE);
+		const namingTool: "exocom_name" | "agent_name" | undefined = host.exocomActive()
+			? toolIsCallable(pi, host, "exocom_name") ? "exocom_name" : undefined
+			: toolIsCallable(pi, host, "agent_name") ? "agent_name" : undefined;
+		const contextOptions = {
+			inboundPeer: hasInboundPeerRequest(event.messages),
+			...(namingTool === undefined ? {} : { namingTool }),
+		};
+		const content = buildIdentityContext(currentChosen, contextOptions);
+		if (content === undefined) return { messages };
+		const contextMessage = {
+			role: "custom" as const,
+			customType: IDENTITY_CONTEXT_CUSTOM_TYPE,
+			content,
+			display: false,
+			timestamp: Date.now(),
+		} as unknown as AgentMessage;
+		return { messages: [...messages, contextMessage] };
+	});
+
+	return identity;
+}

package/src/extension/shared.ts

@@ -0,0 +1,175 @@
+/**
+ * Small leaf helpers shared by the extension composition root and extracted hook/tool modules.
+ * This module must not import `extension.ts` or any of the registration modules that consume it.
+ */
+import { type ExtensionAPI, keyHint } from "@earendil-works/pi-coding-agent";
+
+import { sanitizeDisplayLabel } from "../core/display-label.ts";
+import { boundCompletionSurface, MAX_COMPLETION_REPORT_CHARS } from "../engine/async.ts";
+import type { InboundDecision } from "../exocom/inbound.ts";
+import { EXOCOM } from "../exocom/limits.ts";
+import type { DisplayPeer, ExocomInboundResult } from "../exocom/plane.ts";
+import type { DelegateView } from "../tools/delegate.ts";
+import type { AgentNodeStatus } from "../ui/agent-tree.ts";
+import { compactInlineText } from "../ui/presentation.ts";
+
+const PI_PERSONA_TOOL_ERROR = "__piPersonaToolError";
+
+export function failureDetails<T extends object>(details: T): T & { __piPersonaToolError: true } {
+	return { ...details, [PI_PERSONA_TOOL_ERROR]: true };
+}
+
+export function piPersonaToolErrorPatch(details: unknown): { isError: true; details: Record<string, unknown> } | undefined {
+	if (!details || typeof details !== "object" || Array.isArray(details)) return undefined;
+	const record = details as Record<string, unknown>;
+	if (record[PI_PERSONA_TOOL_ERROR] !== true) return undefined;
+	const clean = { ...record };
+	delete clean[PI_PERSONA_TOOL_ERROR];
+	return { isError: true, details: clean };
+}
+
+export function canDeliverPersonaNotification(orchestrating: boolean, processingDeferred: boolean, hostIdle: boolean): boolean {
+	return !orchestrating && !processingDeferred && hostIdle;
+}
+
+export function sanitizePeerField(value: string, max: number): string {
+	return value
+		.normalize("NFKC")
+		.replace(/[^A-Za-z0-9._/@:+#-]+/g, "-")
+		.replace(/-{2,}/g, "-")
+		.replace(/^[-._/@:+#]+|[-._/@:+#]+$/g, "")
+		.slice(0, max);
+}
+
+export function sanitizeLabel(s: string): string {
+	return sanitizePeerField(s, 80) || "peer";
+}
+
+const EXOCOM_ROUTING_TOKEN = /@([a-f0-9]{24})$/i;
+
+/** Mirror transport routing for observability: a qualified target's readable prefix may be stale
+ * after rename, while its session-hash suffix remains authoritative. Ambiguity emits no speculative
+ * edge; the transport will fail the same collision closed. */
+export function canonicalExocomTelemetryTargets(
+	peers: ReadonlyArray<Pick<DisplayPeer, "session_id" | "displayName" | "target">>,
+	target: string,
+): string[] {
+	if (target === "*") return peers.map((peer) => peer.session_id);
+	const routing = EXOCOM_ROUTING_TOKEN.exec(target);
+	if (routing) {
+		const suffix = routing[1]!.toLowerCase();
+		const matches = peers.filter((peer) => EXOCOM_ROUTING_TOKEN.exec(peer.target)?.[1]?.toLowerCase() === suffix);
+		return matches.length === 1 ? [matches[0]!.session_id] : [];
+	}
+	const display = peers.find((peer) => peer.displayName === target);
+	return display ? [display.session_id] : [];
+}
+
+export function exocomInboundDisposition(decision: InboundDecision): ExocomInboundResult {
+	if ("deliver" in decision) return { accepted: true };
+	if ("duplicate" in decision) return { accepted: true, duplicate: true };
+	return { accepted: false, reason: decision.drop };
+}
+
+export function formatExocomQueuedToast(label: string, inReplyTo: string | undefined): string {
+	return `exocom: ${inReplyTo === undefined ? "message" : "reply"} from ${label} queued`;
+}
+
+export interface ExocomQueuedToast {
+	label: string;
+	inReplyTo: string | undefined;
+}
+
+export function formatExocomQueuedBatchToast(items: readonly ExocomQueuedToast[]): string {
+	if (items.length === 0) return "";
+	const first = items[0]!;
+	if (items.length === 1) return formatExocomQueuedToast(first.label, first.inReplyTo);
+	const counts = new Map<string, number>();
+	for (const item of items) counts.set(item.label, (counts.get(item.label) ?? 0) + 1);
+	const senders = [...counts.entries()];
+	const visible = senders.slice(0, 3).map(([label, count]) => count > 1 ? `${label} ×${count}` : label);
+	const omitted = senders.length - visible.length;
+	return `exocom: ${items.length} messages/replies queued from ${visible.join(", ")}${omitted > 0 ? `, +${omitted} more` : ""}`;
+}
+
+export function boundExocomInboundBatch(items: readonly string[]): string {
+	return boundCompletionSurface(
+		items.join("\n\n"),
+		"exocom inbound batch truncated; remaining peer messages stay queued for later delivery",
+	);
+}
+
+export function exocomInboundBatchSize(items: readonly string[]): number {
+	let chars = 0;
+	let count = 0;
+	for (const item of items) {
+		const withItem = chars + (count > 0 ? 2 : 0) + item.length;
+		if (count > 0 && withItem > MAX_COMPLETION_REPORT_CHARS) break;
+		chars = withItem;
+		count += 1;
+	}
+	return Math.max(1, count);
+}
+
+export const EXOCOM_INBOX_MAX = 3 * EXOCOM.SENDER_MAX_MSGS;
+
+export function agentNodeStatusForDelegate(view: Pick<DelegateView, "running" | "ok"> & { failureKind?: DelegateView["failureKind"] }): AgentNodeStatus {
+	if (view.running) return "running";
+	if (view.failureKind === "abort") return "stopped";
+	return view.ok ? "done" : "failed";
+}
+
+export function sendPersonaFollowUp(
+	pi: Pick<ExtensionAPI, "sendMessage">,
+	content: string,
+	customType = "pi-persona",
+): void {
+	const body = customType === "pi-persona" ? content.replace(/^\[pi-persona\]\s*/, "") : content;
+	pi.sendMessage(
+		{ customType, content: body, display: true },
+		{ deliverAs: "followUp", triggerTurn: true },
+	);
+}
+
+export function expandDetailHint(): string {
+	try {
+		return keyHint("app.tools.expand", "to expand");
+	} catch {
+		return "expand to see full detail";
+	}
+}
+
+export function formatCouncilCallLabel(strategy: string, roster: string): string {
+	const safeStrategy = compactInlineText(strategy, { maxChars: 80 }) || "?";
+	const safeRoster = compactInlineText(roster, { maxChars: 80 }) || "?";
+	return `council ${safeStrategy}${strategy === roster ? "" : ` · ${safeRoster}`}`;
+}
+
+export interface PendingAsk {
+	askId: string;
+	text: string;
+}
+
+export function reconcileAnsweredAsk(
+	askId: string,
+	notifier: { discard: (pred: (item: PendingAsk) => boolean) => void },
+	inbox: { takeWhere: (handle: string, pred: (env: { id: string }) => boolean) => unknown },
+	handle: string,
+): void {
+	notifier.discard((item) => item.askId === askId);
+	inbox.takeWhere(handle, (env) => env.id === askId);
+}
+
+export function shouldReportHeartbeatFailure(consecutiveFailures: number): boolean {
+	return consecutiveFailures === 1 || consecutiveFailures % 10 === 0;
+}
+
+export function fenceIntercomOutcome(out: { text: string; details: { action: string; messages?: unknown[] } }, fence: (t: string) => string): string {
+	const untrusted = out.details.action === "inbox" && (out.details.messages?.length ?? 0) > 0;
+	return untrusted ? fence(out.text) : out.text;
+}
+
+export function coachingDisabledHint(personaName: string | undefined): string {
+	const who = sanitizeDisplayLabel(personaName ?? "default", "default");
+	return `(coaching is OFF for persona "${who}" — sub-agents get no contact_supervisor tool, so the message bus is empty. To just watch or redirect them use action "peek"/"steer"; to exchange messages, add \`coaching: true\` or switch to a coaching persona.)`;
+}