@aeondave/pi-persona 1.15.2

package/src/bus/inproc.ts

@@ -0,0 +1,279 @@
+/**
+ * In-process coordination bus — the semantic communication plane (Bus messages),
+ * kept DISTINCT from engine runtime events and the derived progress view
+ * (guardrails §4.2: EngineEvent / Bus Msg / ProgressView are three disjoint planes).
+ *
+ * Handle-based mailbox: participants register by name; `send` is one-way (a child's
+ * `progress_update`), `ask` blocks for a reply to that message id (a child's
+ * `need_decision`/`interview_request` — the supervisor must be free to answer, i.e.
+ * async coaching, §4.9). No IPC, no naming contract → cross-OS for free; a future
+ * cross-process broker would implement the same surface for separate processes.
+ *
+ * Pure module: no Pi imports, fully unit-tested. This is the seam the in-process
+ * engine wires a child's `contact_supervisor` tool onto.
+ */
+
+/** Why a child reached the supervisor — shapes how the UI/supervisor treats it. */
+export type MsgKind = "progress" | "decision" | "interview";
+
+export interface Envelope {
+	id: string;
+	from: string;
+	to: string;
+	kind: MsgKind;
+	text: string;
+	/** A `decision`/`interview` blocks the sender until `reply(id, …)`; `progress` never does. */
+	expectsReply: boolean;
+}
+
+/** Retention is a bounded escape hatch for drained messages, not a second inbox. */
+export const MAX_RETAINED_MESSAGES = 256;
+export const MAX_RETAINED_MESSAGE_CHARS = 256_000;
+export const MAX_INBOX_MESSAGES = 200;
+
+export interface InProcessBusOptions {
+	/** Override the unread-envelope bound for focused tests or a future host policy. */
+	maxInbox?: number;
+}
+
+export type AskSettlementReason = "replied" | "aborted" | "timeout" | "unregistered" | "inbox-full" | "delivery-error";
+
+export interface AskSettlement {
+	id: string;
+	from: string;
+	to: string;
+	reason: AskSettlementReason;
+}
+
+interface PendingAsk {
+	envelope: Envelope;
+	resolve: (reply: string) => void;
+	reject: (error: Error) => void;
+	timer: ReturnType<typeof setTimeout> | undefined;
+	signal: AbortSignal | undefined;
+	onAbort: () => void;
+}
+
+let seq = 0;
+function nextId(): string {
+	seq += 1;
+	return `m${seq.toString(36)}`;
+}
+
+export class InProcessBus {
+	private readonly inboxes = new Map<string, Envelope[]>();
+	private readonly retainedMessages = new Map<string, Envelope>();
+	private retainedMessageChars = 0;
+	private readonly pendingAsks = new Map<string, PendingAsk>();
+	private readonly observers = new Set<(env: Envelope) => void>();
+	private readonly askSettledListeners = new Set<(event: AskSettlement) => void>();
+	private readonly maxInbox: number;
+
+	constructor(opts: InProcessBusOptions = {}) {
+		this.maxInbox = opts.maxInbox !== undefined && Number.isFinite(opts.maxInbox)
+			? Math.max(1, Math.floor(opts.maxInbox))
+			: MAX_INBOX_MESSAGES;
+	}
+
+	/** Observe every delivered message (for event-wake follow-ups). Returns an unsubscribe. */
+	onMessage(listener: (env: Envelope) => void): () => void {
+		this.observers.add(listener);
+		return () => this.observers.delete(listener);
+	}
+
+	/** Observe ask settlement so notification surfaces can discard stale cached prompts. */
+	onAskSettled(listener: (event: AskSettlement) => void): () => void {
+		this.askSettledListeners.add(listener);
+		return () => this.askSettledListeners.delete(listener);
+	}
+
+	/** Cap on unread messages per inbox — a chatty child must not grow supervisor
+	 *  memory without bound when nobody drains. */
+	private deliver(box: Envelope[], env: Envelope): boolean {
+		if (box.length >= this.maxInbox) {
+			// Evict the oldest ONE-WAY note first. If every unread envelope is a live ask,
+			// reject this delivery instead of silently stranding an existing sender.
+			const idx = box.findIndex((e) => !e.expectsReply);
+			if (idx < 0) return false;
+			box.splice(idx, 1);
+		}
+		box.push(env);
+		for (const fn of this.observers) fn(env);
+		return true;
+	}
+
+	private retireAskEnvelope(pending: PendingAsk): void {
+		pending.envelope.expectsReply = false;
+		const { id, to: recipient } = pending.envelope;
+		const box = this.inboxes.get(recipient);
+		if (box) {
+			const index = box.findIndex((env) => env.id === id);
+			if (index >= 0) box.splice(index, 1);
+		}
+		const retained = this.retainedMessages.get(id);
+		if (retained?.to === recipient) retained.expectsReply = false;
+	}
+
+	private settleAsk(id: string, reason: AskSettlementReason, reply?: string, failure?: Error): boolean {
+		const pending = this.pendingAsks.get(id);
+		if (!pending) return false;
+		this.pendingAsks.delete(id);
+		if (pending.timer !== undefined) clearTimeout(pending.timer);
+		pending.signal?.removeEventListener("abort", pending.onAbort);
+		this.retireAskEnvelope(pending);
+		if (reason === "replied") pending.resolve(reply ?? "");
+		else pending.reject(failure ?? new Error(reason === "inbox-full" ? "inbox full: ask was not delivered" : `ask ${reason}`));
+		const event: AskSettlement = { id, from: pending.envelope.from, to: pending.envelope.to, reason };
+		for (const listener of this.askSettledListeners) {
+			try {
+				listener(event);
+			} catch {
+				// Settlement observers are cleanup hooks; one faulty observer must not alter the ask result.
+			}
+		}
+		return true;
+	}
+
+	private retain(env: Envelope): void {
+		if (env.text.length > MAX_RETAINED_MESSAGE_CHARS || this.retainedMessages.has(env.id)) return;
+		this.retainedMessages.set(env.id, env);
+		this.retainedMessageChars += env.text.length;
+		while (this.retainedMessages.size > MAX_RETAINED_MESSAGES || this.retainedMessageChars > MAX_RETAINED_MESSAGE_CHARS) {
+			const oldest = this.retainedMessages.keys().next().value;
+			if (oldest === undefined) break;
+			const removed = this.retainedMessages.get(oldest);
+			this.retainedMessages.delete(oldest);
+			if (removed) this.retainedMessageChars -= removed.text.length;
+		}
+	}
+
+	private retainAll(messages: readonly Envelope[]): void {
+		for (const message of messages) this.retain(message);
+	}
+
+	register(name: string): void {
+		if (!this.inboxes.has(name)) this.inboxes.set(name, []);
+	}
+
+	unregister(name: string): void {
+		this.inboxes.delete(name);
+		for (const [id, pending] of this.pendingAsks) {
+			if (pending.envelope.from === name || pending.envelope.to === name) this.settleAsk(id, "unregistered");
+		}
+		for (const [id, message] of this.retainedMessages) {
+			if (message.to !== name) continue;
+			this.retainedMessages.delete(id);
+			this.retainedMessageChars -= message.text.length;
+		}
+	}
+
+	participants(): string[] {
+		return [...this.inboxes.keys()];
+	}
+
+	/** One-way message (default `progress`). Returns false if the recipient is not registered. */
+	send(from: string, to: string, text: string, kind: MsgKind = "progress"): boolean {
+		const box = this.inboxes.get(to);
+		if (!box) return false;
+		return this.deliver(box, { id: nextId(), from, to, kind, text, expectsReply: false });
+	}
+
+	/** Blocking request: resolves with the reply to this message, or rejects on timeout. */
+	ask(
+		from: string,
+		to: string,
+		text: string,
+		opts: { kind?: MsgKind; timeoutMs?: number; signal?: AbortSignal } = {},
+	): Promise<string> {
+		const box = this.inboxes.get(to);
+		if (!box) throw new Error(`unknown peer: ${to}`);
+		const id = nextId();
+		const timeoutMs = opts.timeoutMs ?? 600_000;
+		return new Promise<string>((resolve, reject) => {
+			const envelope: Envelope = { id, from, to, kind: opts.kind ?? "decision", text, expectsReply: true };
+			const onAbort = (): void => {
+				this.settleAsk(id, "aborted");
+			};
+			const pending: PendingAsk = {
+				envelope,
+				resolve,
+				reject,
+				timer: undefined,
+				signal: opts.signal,
+				onAbort,
+			};
+			this.pendingAsks.set(id, pending);
+			if (opts.signal?.aborted) {
+				this.settleAsk(id, "aborted");
+				return;
+			}
+			pending.timer = setTimeout(() => {
+				this.settleAsk(id, "timeout", undefined, new Error(`ask timeout after ${timeoutMs}ms`));
+			}, timeoutMs);
+			pending.timer.unref?.();
+			if (opts.signal) opts.signal.addEventListener("abort", onAbort, { once: true });
+			// Deliver only once the resolver is registered: `deliver` notifies observers
+			// synchronously, and one that answers inline would otherwise hit `reply`'s
+			// unknown-id path and strand this ask until its timeout.
+			try {
+				if (!this.deliver(box, envelope)) this.settleAsk(id, "inbox-full");
+			} catch (error) {
+				this.settleAsk(id, "delivery-error", undefined, error instanceof Error ? error : new Error(String(error)));
+			}
+		});
+	}
+
+	/** Answer a pending ask by its message id. Returns false (a harmless no-op) for an
+	 *  unknown/expired id — so the caller can tell the child actually got the answer. */
+	reply(askId: string, text: string): boolean {
+		return this.settleAsk(askId, "replied", text);
+	}
+
+	/** Drain and return a participant's inbox. */
+	take(name: string): Envelope[] {
+		const box = this.inboxes.get(name) ?? [];
+		this.inboxes.set(name, []);
+		this.retainAll(box);
+		return box;
+	}
+
+	/** Drain and return only the messages matching `pred`, leaving the rest in the inbox. */
+	takeWhere(name: string, pred: (env: Envelope) => boolean): Envelope[] {
+		const box = this.inboxes.get(name);
+		if (!box || box.length === 0) return [];
+		const taken: Envelope[] = [];
+		const kept: Envelope[] = [];
+		for (const env of box) (pred(env) ? taken : kept).push(env);
+		this.inboxes.set(name, kept);
+		this.retainAll(taken);
+		return taken;
+	}
+
+	/** Retrieve a drained message by id while it remains inside the bounded retention window. */
+	retrieve(messageId: string, recipient?: string): Envelope | undefined {
+		const message = this.retainedMessages.get(messageId);
+		return message && (recipient === undefined || message.to === recipient) ? message : undefined;
+	}
+
+	/** Peek at a participant's inbox without draining it. */
+	pending(name: string): Envelope[] {
+		return [...(this.inboxes.get(name) ?? [])];
+	}
+
+	/** Whether a participant has any undrained messages. */
+	hasPending(name: string): boolean {
+		return (this.inboxes.get(name)?.length ?? 0) > 0;
+	}
+
+	/** Whether `handle` currently has a live ask (`decision`/`interview`) awaiting a reply.
+	 *  The one question an idle/startup watchdog needs to tell real silence from a leg
+	 *  legitimately blocked on the supervisor: re-arm while this is true, kill once it goes
+	 *  false (settled by reply, abort, or timeout — {@link settleAsk} removes it from
+	 *  `pendingAsks` on every settlement path). */
+	hasPendingAskFrom(handle: string): boolean {
+		for (const pending of this.pendingAsks.values()) {
+			if (pending.envelope.from === handle) return true;
+		}
+		return false;
+	}
+}

package/src/bus/peers.ts

@@ -0,0 +1,114 @@
+/**
+ * `contact_peer` — the CHILD-side sibling-messaging tool of the communication plane
+ * (design: docs/ARCHITECTURE.md § "The comm plane in practice"). Bound by the
+ * in-process engine ONLY when the strategy opted the run into peer comm (`spec.peers`,
+ * gated by the persona's `canUseBus`).
+ *
+ * ONE-WAY by design (decision P1): a "conversation" is reciprocal sends — the receiving
+ * agent replies, if it chooses, with a send of its own. Blocking asks remain a
+ * supervisor-channel privilege, so two peers can never deadlock on each other.
+ *
+ * The peer list comes from an engine-provided `listPeers` closure scoped to the SAME
+ * strategy run — the tool never scans the whole bus, so concurrent runs stay invisible
+ * to each other. A per-member send budget stops ping-pong loops (the idle watchdog
+ * cannot: mutual steers re-arm each other's clocks).
+ *
+ * Pure factory (bus + self handle + deps), unit-tested without a live model, mirroring
+ * `bus/contact.ts`.
+ */
+
+import { type Static, Type } from "typebox";
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+
+import type { InProcessBus } from "./inproc.ts";
+
+/** Anti ping-pong budget: after this many sends the tool tells the member to finalize. */
+export const MAX_PEER_SENDS = 20;
+export const MAX_PEER_MESSAGE_CHARS = 8_000;
+
+export interface PeerInfo {
+	handle: string;
+	label: string;
+}
+
+export interface ContactPeerDeps {
+	/** The live peers of THIS run (excluding self) — scoped by the engine, never the whole bus. */
+	listPeers: () => PeerInfo[] | Promise<PeerInfo[]>;
+	/** Override the send budget (tests). Default {@link MAX_PEER_SENDS}. */
+	maxSends?: number;
+}
+
+const PeerParams = Type.Object({
+	action: Type.Union([Type.Literal("list"), Type.Literal("send")], {
+		description:
+			"list = see which peers are still working · send = push a ONE-WAY note to one peer (you do NOT wait; a peer answers, if at all, with a send of its own).",
+	}),
+	to: Type.Optional(Type.String({ description: "send: the peer handle (from `list`, e.g. reviewer#2)." })),
+	message: Type.Optional(Type.String({ maxLength: MAX_PEER_MESSAGE_CHARS, description: "send: what to tell the peer — specific and self-contained." })),
+});
+
+type PeerDetails = { action: string; delivered?: boolean; peers?: string[] };
+
+function result(t: string, details: PeerDetails): { content: [{ type: "text"; text: string }]; details: PeerDetails } {
+	return { content: [{ type: "text", text: t }], details };
+}
+
+/** Build the child's `contact_peer` tool. Same `defineTool` variance shim as
+ *  `makeContactSupervisorTool`, so it slots into `customTools: ToolDefinition[]`. */
+export function makeContactPeerTool(bus: InProcessBus, selfHandle: string, deps: ContactPeerDeps) {
+	const maxSends = deps.maxSends ?? MAX_PEER_SENDS;
+	let sent = 0;
+	return defineTool({
+		name: "contact_peer",
+		label: "Contact peer",
+		description: [
+			"Message the OTHER members working this same task with you (your strategy peers).",
+			"`list` shows who is still reachable; `send` pushes a one-way note to one of them.",
+			"You never wait for a reply — a peer answers (if it chooses) with its own send, which",
+			'reaches you as a "[message from peer …]" turn. Keep notes short and substantive;',
+			`finalize your own answer once your position is stable. This run allows at most ${maxSends} sends.`,
+		].join(" "),
+		promptSnippet: "contact_peer — list your run's sibling agents or send one a one-way note",
+		parameters: PeerParams,
+		async execute(_toolCallId, params: Static<typeof PeerParams>, _signal, _onUpdate, _ctx) {
+			if (params.action === "list") {
+				const peers = await deps.listPeers();
+				return result(
+					peers.length > 0
+						? `Reachable peers:\n${peers.map((p) => `• ${p.label}`).join("\n")}`
+						: "(no peers are currently reachable — they may all have finalized; proceed solo)",
+					{ action: "list", peers: peers.map((p) => p.handle) },
+				);
+			}
+			if (!params.to || params.message === undefined) {
+				return result("contact_peer send needs { to, message } — use `list` for peer handles.", { action: "send", delivered: false });
+			}
+			if (params.message.length > MAX_PEER_MESSAGE_CHARS) {
+				return result(
+					`contact_peer message exceeds the ${MAX_PEER_MESSAGE_CHARS}-character limit; send a smaller note.`,
+					{ action: "send", delivered: false },
+				);
+			}
+			if (sent >= maxSends) {
+				return result(
+					`(peer-send budget exhausted — ${maxSends} notes already sent; stop debating and finalize your answer)`,
+					{ action: "send", delivered: false },
+				);
+			}
+			sent += 1;
+			// Enforce the run-isolation boundary (previously only convention): a handle that is
+			// not one of THIS run's peers (e.g. "supervisor", or another run's child) never gets
+			// bus.send called at all — same "gone" wording as an actually-finished peer, so the
+			// tool result gives no signal either way about what exists outside this run's scope.
+			const inScope = (await deps.listPeers()).some((p) => p.handle === params.to);
+			const delivered = inScope && bus.send(selfHandle, params.to, params.message, "progress");
+			return result(
+				delivered
+					? `Sent to ${params.to}.`
+					: `Peer "${params.to}" is gone — it may have already finalized. Proceed with your own judgement.`,
+				{ action: "send", delivered },
+			);
+		},
+	});
+}