@aeondave/pi-persona 1.15.2

package/src/tools/intercom-tool.ts

@@ -0,0 +1,292 @@
+/** `intercom` tool registration. */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { failureDetails } from "../extension/shared.ts";
+import { Text } from "@earendil-works/pi-tui";
+import { compactInlineText, sanitizeTerminalText } from "../ui/presentation.ts";
+import { compactVisibleText } from "../ui/presentation.ts";
+import { coachingDisabledHint, expandDetailHint, reconcileAnsweredAsk } from "../extension/shared.ts";
+import {
+	type AsyncRun, AsyncRunTracker, boundCompletionSurface, buildPeekDigest, buildWaitTimeoutNote,
+	MAX_ASYNC_STATUS_ROWS,
+	dedupeRunsById, getFullRunOutput, IdleCoalescingNotifier,
+	renderCompletion, runDurationLabel,
+} from "../engine/async.ts";
+import { fenceUntrusted } from "../core/fence.ts";
+import { sanitizeDisplayLabel } from "../core/display-label.ts";
+import { type IntercomOutcome, type IntercomParams, MAX_INTERCOM_MESSAGE_CHARS, MAX_INTERCOM_REF_CHARS, runIntercom } from "./intercom.ts";
+import { fenceIntercomOutcome, type PendingAsk } from "../extension/shared.ts";
+import type { InProcessBus } from "../bus/inproc.ts";
+import type { PersonaController } from "../persona/controller.ts";
+import { emptyUsage } from "../engine/stream.ts";
+import { toolUsageField, type ChildUsageLedger } from "../ui/usage.ts";
+
+export interface IntercomToolDeps {
+	get lastCtx(): ExtensionContext | undefined;
+	set lastCtx(value: ExtensionContext | undefined);
+	tracker: AsyncRunTracker;
+	completionNotifier: IdleCoalescingNotifier<AsyncRun>;
+	intercomNotifier: IdleCoalescingNotifier<PendingAsk>;
+	controller: PersonaController;
+	bus: InProcessBus;
+	SUPERVISOR: string;
+	STALL_FLAG_MS: number;
+	missingRunMessage(id: string, display: string | undefined): string;
+	stopAgent(nodeId: string): boolean;
+	steerAgent(nodeId: string, text: string): boolean;
+	steerRegistry: Map<string, unknown>;
+	stopRequested: Set<string>;
+	drainBusBlock(): string;
+	scanForSurrender(text: string): string | undefined;
+	get disposed(): boolean;
+	childUsage: ChildUsageLedger;
+	publishPersonaCost(): void;
+}
+
+/** Keep an aborted wait honest: its signal may end the join well before the configured window. */
+export function buildIntercomWaitStillNote(ids: readonly string[], timeoutMs: number, interrupted: boolean): string {
+	if (!interrupted) return buildWaitTimeoutNote(ids, timeoutMs);
+	const visibleIds = ids.slice(0, MAX_ASYNC_STATUS_ROWS).map((id) => sanitizeDisplayLabel(id, "run"));
+	const omitted = ids.length - visibleIds.length;
+	const idSummary = `${visibleIds.join(", ")}${omitted > 0 ? `, … +${omitted} more` : ""}`;
+	return (
+		`⏹ wait interrupted before the configured ${timeoutMs}ms window elapsed; still running: ${idSummary}. ` +
+		"Continue useful supervisor work; completion will notify you automatically. Use intercom wait again when ready."
+	);
+}
+
+/** Fence only child-authored payloads; missing-message diagnostics remain actionable tool prose. */
+export function fenceIntercomToolOutcome(out: IntercomOutcome, action: string, fence: (text: string) => string): string {
+	return action === "message" && out.details.ok ? fence(out.text) : fenceIntercomOutcome(out, fence);
+}
+
+export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): void {
+	// ── intercom tool (supervisor side of the comm plane: read/answer children) ───
+	const IntercomToolParams = Type.Object({
+		action: Type.Union(
+			[
+				Type.Literal("peek"),
+				Type.Literal("result"),
+				Type.Literal("wait"),
+				Type.Literal("steer"),
+				Type.Literal("stop"),
+				Type.Literal("list"),
+				Type.Literal("inbox"),
+				Type.Literal("message"),
+				Type.Literal("reply"),
+				Type.Literal("send"),
+			],
+			{
+				description:
+					"peek = watch async sub-agents · result = retrieve one complete settled result by run id · wait = BLOCK until async run(s) settle and collect their bounded reports (a join) · steer = soft redirect into one by run id (it may ignore it) · stop = request engine cancellation by run id · message = retrieve one drained bus message by message id · list/inbox/reply/send = coaching messages (needs a coaching persona)",
+			},
+		),
+		to: Type.Optional(Type.String({ maxLength: MAX_INTERCOM_REF_CHARS, description: "result/steer/stop/peek: the async run id (e.g. 'run-1') · wait: an async run id; omit it to join all running and pending completions · send: the child handle (from `list`)" })),
+		messageId: Type.Optional(Type.String({ maxLength: MAX_INTERCOM_REF_CHARS, description: "message: the drained bus message id shown by `inbox`" })),
+		askId: Type.Optional(Type.String({ maxLength: MAX_INTERCOM_REF_CHARS, description: "reply: the message id of the child's pending question" })),
+		message: Type.Optional(Type.String({ maxLength: MAX_INTERCOM_MESSAGE_CHARS, description: "steer/reply/send: the text to deliver" })),
+		timeoutMs: Type.Optional(Type.Number({ description: "wait: max ms to hold your turn (default 600000; values below 1000 clamp to 1000, values above 600000 clamp to 600000) — on timeout you get what settled + what's still running" })),
+	});
+	pi.registerTool({
+		name: "intercom",
+		label: "Intercom",
+		description: [
+			"See, steer, message, and JOIN your running sub-agents.",
+			"`peek` watches what your async sub-agents are doing; `result` retrieves one complete settled",
+			"payload by run id; `wait` blocks until runs settle and returns a bounded join report;",
+			"`steer` sends a soft course-correction to one (by run id); in-process async runs can receive it mid-run,",
+			"while child-engine (MCP/worktree) async runs receive it as a brokered follow-up.",
+			"`message` retrieves a drained bus message by its message id; `list`/`inbox`/`reply`/`send` exchange coaching messages (a child reaches you via `contact_supervisor`)",
+			"and need a `coaching: on` persona.",
+		].join(" "),
+		parameters: IntercomToolParams,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			d.lastCtx = ctx;
+			// `to` comes from model-authored tool arguments. Use the exact value for routing, but never
+			// interpolate it into trusted prose without reducing it to compact identifier metadata.
+			const displayTarget = params.to === undefined ? undefined : sanitizeDisplayLabel(params.to, "run");
+			// peek + wait + steer + stop are supervisor→child controls over the async d.tracker /
+			// steer handles — available to EVERY persona (no dependency on the coaching bus).
+			if (params.action === "peek") {
+				// No `to` → running legs PLUS any settled-but-not-yet-delivered ones (the settle→deliver
+				// gap), so a peek right after a leg finishes shows its result instead of "No async runs".
+				const runs = params.to
+					? [d.tracker.peek(params.to)].filter((r): r is AsyncRun => !!r)
+					: dedupeRunsById([...d.tracker.running(), ...d.completionNotifier.peekPending()]);
+				return { content: [{ type: "text", text: buildPeekDigest(runs, { now: Date.now(), stallMs: d.STALL_FLAG_MS }) }], details: { action: "peek", ok: true }, isError: false };
+			}
+			if (params.action === "result") {
+				if (!params.to) {
+					return { content: [{ type: "text", text: "intercom result needs { to: <run id> }." }], details: failureDetails({ action: "result", ok: false }), isError: true };
+				}
+				const run = d.tracker.peek(params.to);
+				if (!run) {
+					return { content: [{ type: "text", text: d.missingRunMessage(params.to, displayTarget) }], details: failureDetails({ action: "result", ok: false }), isError: true };
+				}
+				if (run.status === "running") {
+					return {
+						content: [{ type: "text", text: `${displayTarget} is still running. Use intercom peek/wait, or request result after it settles.` }],
+						details: failureDetails({ action: "result", ok: false, status: run.status }),
+						isError: true,
+					};
+				}
+				// Explicit collection owns this delivery: remove a still-buffered passive completion so the
+				// same result cannot appear again as a follow-up a moment later. Telling the d.tracker too
+				// makes this retained copy the first thing retention evicts — the supervisor has read it,
+				// so it is the cheapest payload in the map to lose.
+				d.completionNotifier.discard((pending) => pending.id === run.id);
+				d.tracker.markCollected(run.id);
+				const full = getFullRunOutput(run);
+				const body = full === "(no output)" ? full : fenceUntrusted(full);
+				// The cause is engine/child-authored text too. Keep the run id/status as trusted compact
+				// metadata, but put the diagnostic inside the same untrusted fence as the payload.
+				const cause = run.error ? `\nFailure detail:\n${fenceUntrusted(run.error)}` : "";
+				const displayRun = sanitizeDisplayLabel(run.label ?? run.agent);
+				// The wall time this leg took: an explicit collection is one of the paths a completion reaches
+				// the supervisor through, so it carries the same reading the passive/join reports do.
+				const took = runDurationLabel(run);
+				const billed = d.childUsage.accountMany([{ key: run.id, usage: run.result?.usage ?? emptyUsage() }]);
+				d.publishPersonaCost();
+				return {
+					content: [{ type: "text", text: `${run.id} (${displayRun}) · ${run.status}${took ? ` · ${took}` : ""}${cause}\n${body}` }],
+					details: { action: "result", ok: true, status: run.status, runId: run.id },
+					isError: false,
+					...toolUsageField(billed),
+				};
+			}
+			if (params.action === "wait") {
+				// No `to` → wait on running legs AND collect settled legs still queued for follow-up
+				// delivery, so a wait in the settle→deliver gap returns their results (not "nothing").
+				if (params.to && !d.tracker.peek(params.to)) {
+					return { content: [{ type: "text", text: d.missingRunMessage(params.to, displayTarget) }], details: failureDetails({ action: "wait", ok: false }), isError: true };
+				}
+				const ids = params.to
+					? [params.to]
+					: dedupeRunsById([...d.tracker.running(), ...d.completionNotifier.peekPending()]).map((r) => r.id);
+				if (ids.length === 0) {
+					return { content: [{ type: "text", text: "No async runs to wait for." }], details: { action: "wait", ok: true }, isError: false };
+				}
+				// Bounded join: never longer than a child's ask timeout (bus `ask` default 600s),
+				// so a coaching child blocking on OUR reply can't deadlock us past its own timeout.
+				// Default matches that ceiling — heavy sub-agents (30+ turns) routinely outlast a
+				// short window, and a premature "still running" forces a needless re-wait.
+				const timeoutMs = Math.min(Math.max(params.timeoutMs ?? 600_000, 1_000), 600_000);
+				const runs = await d.tracker.waitFor(ids, timeoutMs, _signal);
+				const settled = runs.filter((r) => r.status !== "running");
+				const still = runs.filter((r) => r.status === "running");
+				// These results are delivered HERE — drop them from the pending follow-up
+				// notifier so they aren't reported a second time. Render through the SAME
+				// renderCompletion the passive path uses, so a leg that came back BLOCKED still
+				// carries the premature-surrender note when it is collected via `wait`.
+				const settledIds = new Set(settled.map((r) => r.id));
+				d.completionNotifier.discard((run) => settledIds.has(run.id));
+				for (const id of settledIds) d.tracker.markCollected(id);
+				const report = settled.length > 0 ? renderCompletion(settled, fenceUntrusted, (t) => d.scanForSurrender(t)) : "";
+				const stillNote = still.length > 0
+					? buildIntercomWaitStillNote(still.map((r) => r.id), timeoutMs, _signal?.aborted === true)
+					: "";
+				const joined = [report, stillNote].filter(Boolean).join("\n\n") || "Nothing to report (unknown run ids?).";
+				const text = boundCompletionSurface(joined);
+				const billed = d.childUsage.accountMany(
+					settled.map((r) => ({ key: r.id, usage: r.result?.usage ?? emptyUsage() })),
+				);
+				d.publishPersonaCost();
+				return {
+					content: [{ type: "text", text }],
+					details: { action: "wait", ok: true, settled: [...settledIds], running: still.map((r) => r.id) },
+					isError: false,
+					...toolUsageField(billed),
+				};
+			}
+			if (params.action === "steer") {
+				if (!params.to || params.message === undefined) {
+					return { content: [{ type: "text", text: "intercom steer needs { to: <run id>, message }." }], details: failureDetails({ action: "steer", ok: false }), isError: true };
+				}
+				const nodeId = `async:${params.to}`;
+				if (!d.steerRegistry.has(nodeId)) {
+					return {
+						content: [{ type: "text", text: `Cannot steer "${displayTarget}" — no live steer handle is available (the run may have finished or not started yet, or its engine/broker does not expose steering).` }],
+						details: failureDetails({ action: "steer", ok: false }),
+						isError: true,
+					};
+				}
+				// Routed through the guarded d.steerAgent so a just-finished/d.disposed handle can't throw.
+				const steered = d.steerAgent(nodeId, params.message);
+				return steered
+					? { content: [{ type: "text", text: `Steering sent to ${displayTarget} (soft request; use action "stop" to request cancellation).` }], details: { action: "steer", ok: true }, isError: false }
+					: { content: [{ type: "text", text: `Could not steer "${displayTarget}" — it may have just finished, or the message was empty.` }], details: failureDetails({ action: "steer", ok: false }), isError: true };
+			}
+			if (params.action === "stop") {
+				if (!params.to) {
+					return { content: [{ type: "text", text: "intercom stop needs { to: <run id> }." }], details: failureDetails({ action: "stop", ok: false }), isError: true };
+				}
+				// Abort the real run signal. The child backend can kill its process tree; the
+				// in-process backend requests host cancellation and settles its lifecycle separately.
+				const nodeId = `async:${params.to}`;
+				const repeated = d.stopRequested.has(nodeId);
+				const stopped = d.stopAgent(nodeId);
+				if (stopped && !repeated) {
+					return { content: [{ type: "text", text: `Cancellation requested for ${displayTarget}. Check its terminal result; changes already made are not undone.` }], details: { action: "stop", ok: true }, isError: false };
+				}
+				// A repeated stop has just invoked the REAL cancel handle again. Only now force-clear
+				// d.tracker state if engine settlement is still lagging; the handle remains registered
+				// until onComplete so cancellation can never be replaced by UI-only bookkeeping.
+				if (stopped && repeated && d.tracker.forceSettle(params.to, "force-stopped by supervisor after repeated engine cancellation")) {
+					return {
+						content: [{ type: "text", text: `Force-cleared ${displayTarget} after repeating the engine cancellation; it will no longer be tracked as running.` }],
+						details: { action: "stop", ok: true },
+						isError: false,
+					};
+				}
+				return {
+					content: [{ type: "text", text: `Cannot stop "${displayTarget}" — no such running run (it already finished).` }],
+					details: failureDetails({ action: "stop", ok: false }),
+					isError: true,
+				};
+			}
+
+			// The message bus (coaching): list / inbox / message / reply / send.
+			const out = runIntercom(params as IntercomParams, d.bus, d.SUPERVISOR);
+			// An answered ask is settled on every surface it reached — never woken again, never
+			// re-listed (the ask envelope is NOT drained by the peek path, which skips expectsReply).
+			if (params.action === "reply" && out.details.ok && params.askId) {
+				reconcileAnsweredAsk(params.askId, d.intercomNotifier, d.bus, d.SUPERVISOR);
+			}
+			// Child-authored inbox bodies are untrusted, exactly like the d.drainBusBlock/peek copies.
+			// A retrieved body is child-authored even though it is no longer an inbox batch; keep the
+			// same trust fence around it as inbox and automatic drain surfaces.
+			let text = fenceIntercomToolOutcome(out, params.action, fenceUntrusted);
+			if ((params.action === "list" || params.action === "inbox") && !d.controller.activePersona?.coaching) {
+				text += `\n\n${coachingDisabledHint(d.controller.activePersona?.name)}`;
+			}
+			return { content: [{ type: "text", text }], details: out.details.ok ? out.details : failureDetails(out.details), isError: !out.details.ok };
+		},
+		renderCall(args, theme) {
+			const action = compactInlineText(args.action ?? "?", { maxChars: 24 }) || "?";
+			let target = "";
+			if (action === "wait" || action === "peek") target = compactInlineText(args.to ?? "all", { maxChars: 80 }) || "all";
+			else if (["result", "steer", "stop", "send"].includes(action)) target = compactInlineText(args.to ?? "?", { maxChars: 80 }) || "?";
+			else if (action === "message") target = compactInlineText(args.messageId ?? "?", { maxChars: 80 }) || "?";
+			else if (action === "reply") target = compactInlineText(args.askId ?? "?", { maxChars: 80 }) || "?";
+			const timeout = action === "wait" && Number.isFinite(args.timeoutMs) && args.timeoutMs !== undefined
+				? ` · ${Math.max(0, Math.floor(args.timeoutMs))}ms`
+				: "";
+			return new Text(
+				`${theme.fg("toolTitle", theme.bold("intercom "))}${theme.fg("accent", action)}${target ? theme.fg("dim", ` ${target}${timeout}`) : ""}`,
+				0,
+				0,
+			);
+		},
+		renderResult(result, { expanded }, theme) {
+			const details = (result.details ?? {}) as { action?: string; ok?: boolean };
+			const first = result.content[0];
+			const full = sanitizeTerminalText(first?.type === "text" ? first.text : "(no output)");
+			const failed = details.ok === false;
+			const prefix = failed ? `${theme.fg("error", theme.bold("failed"))}\n` : "";
+			if (expanded) return new Text(`${prefix}${theme.fg("toolOutput", full)}`, 0, 0);
+			const preview = compactVisibleText(full, { maxLines: 4, maxLineChars: 100 });
+			const hint = preview.truncated ? `\n${theme.fg("dim", expandDetailHint())}` : "";
+			return new Text(`${prefix}${theme.fg("toolOutput", preview.text)}${hint}`, 0, 0);
+		},
+	});
+}

package/src/tools/intercom.ts

@@ -0,0 +1,181 @@
+/**
+ * `intercom` — the SUPERVISOR-side tool of the communication plane (the mirror of the
+ * child's `contact_supervisor`). Pure core: maps an action over the {@link InProcessBus}
+ * and formats a readable result; the extension wraps it in a `pi.registerTool` so the
+ * supervisor can, while async children run:
+ *   - `list`  — who is reachable (running children + peers)
+ *   - `inbox` — read (drain) what children have reported / asked
+ *   - `reply` — answer a child's blocking `need_decision`/`interview_request` by id
+ *   - `send`  — push a one-way note to a running child
+ *
+ * Pure (takes the bus + self handle), so it is unit-tested without a live model.
+ */
+
+import type { Envelope, InProcessBus } from "../bus/inproc.ts";
+import { sanitizeDisplayLabel } from "../core/display-label.ts";
+
+export interface IntercomParams {
+	action: "list" | "inbox" | "message" | "reply" | "send";
+	/** `send` target child handle. */
+	to?: string;
+	/** `message` target — the id shown in an inbox message line. */
+	messageId?: string;
+	/** `reply` target — the message id of the child's pending ask. */
+	askId?: string;
+	/** `send`/`reply` body. */
+	message?: string;
+}
+
+export interface IntercomDetails {
+	action: string;
+	peers?: string[];
+	messages?: Envelope[];
+	message?: Envelope;
+	messageId?: string;
+	totalPeers?: number;
+	omittedPeers?: number;
+	ok: boolean;
+}
+
+export interface IntercomOutcome {
+	text: string;
+	details: IntercomDetails;
+}
+
+/** Automatic intercom payload limits. Explicit `message` retrieval is the escape hatch for detail. */
+export const MAX_INBOX_MESSAGE_CHARS = 2_000;
+export const MAX_INBOX_BATCH_CHARS = 16_000;
+export const MAX_INTERCOM_MESSAGE_CHARS = 8_000;
+export const MAX_INTERCOM_REF_CHARS = 160;
+export const MAX_INTERCOM_LIST_PEERS = 64;
+
+export interface InboxFormatOptions {
+	maxMessageChars?: number;
+	maxBatchChars?: number;
+}
+
+function clipBody(value: string, maxChars: number): { text: string; omitted: number } {
+	if (value.length <= maxChars) return { text: value, omitted: 0 };
+	const marker = `[… ${value.length - maxChars} characters omitted; request the full message by id …]`;
+	if (maxChars <= marker.length) return { text: marker.slice(0, Math.max(0, maxChars)), omitted: value.length };
+	const content = Math.max(0, maxChars - marker.length);
+	const head = Math.ceil(content / 2);
+	const tail = Math.max(0, content - head);
+	return { text: `${value.slice(0, head)}${marker}${tail > 0 ? value.slice(-tail) : ""}`, omitted: value.length - maxChars };
+}
+
+/** One bounded readable line per inbox message; decision/interview lines always show sender + id. */
+export function formatInbox(messages: Envelope[], opts?: InboxFormatOptions): string {
+	if (messages.length === 0) return "(no new messages from sub-agents)";
+	const maxMessageChars = Math.max(128, opts?.maxMessageChars ?? MAX_INBOX_MESSAGE_CHARS);
+	const maxBatchChars = Math.max(512, opts?.maxBatchChars ?? MAX_INBOX_BATCH_CHARS);
+	// Reserve a small footer so the batch can state how much was omitted without pushing the
+	// rendered response over its hard bound. Every message gets an equal slot: one verbose child
+	// cannot consume the whole inbox and hide later reply ids.
+	const slot = Math.max(128, Math.floor((maxBatchChars - 96) / messages.length));
+	let omittedChars = 0;
+	const lines = messages.map((m) => {
+		const from = sanitizeDisplayLabel(m.from, "peer", 40);
+		const kind = sanitizeDisplayLabel(m.kind, "message", 24);
+		const id = sanitizeDisplayLabel(m.id, "message", 40);
+		const tag = m.expectsReply ? `${kind} · reply with id ${id}` : `${kind} · message id ${id}`;
+		const prefix = `• [${from}] (${tag}): `;
+		const body = clipBody(m.text, Math.min(maxMessageChars, Math.max(0, slot - prefix.length)));
+		omittedChars += body.omitted;
+		return `${prefix}${body.text}`;
+	});
+	const footer = omittedChars > 0 ? `\n… ${omittedChars} message characters omitted from this inbox view; use intercom { action: "message", messageId: "<id>" } for full detail.` : "";
+	const rendered = `${lines.join("\n")}${footer}`;
+	if (rendered.length <= maxBatchChars) return rendered;
+	// This is only reachable with unusually long metadata; preserve the first and last lines while
+	// keeping the sender/id and omission signal visible at a predictable size.
+	const marker = `\n… inbox batch truncated at ${maxBatchChars} characters; ${messages.length} message(s) present, use ids for detail.`;
+	const content = Math.max(0, maxBatchChars - marker.length);
+	return `${rendered.slice(0, Math.ceil(content * 0.65))}${marker}${rendered.slice(-Math.floor(content * 0.35))}`.slice(0, maxBatchChars);
+}
+
+export function runIntercom(params: IntercomParams, bus: InProcessBus, self: string): IntercomOutcome {
+	switch (params.action) {
+		case "list": {
+			const peers = bus.participants().filter((p) => p !== self);
+			const listed = peers.slice(0, MAX_INTERCOM_LIST_PEERS);
+			const omittedPeers = Math.max(0, peers.length - listed.length);
+			const omission = omittedPeers > 0 ? `\n… ${omittedPeers} more reachable sub-agents omitted from this bounded view.` : "";
+			return {
+				text: peers.length > 0
+					? `Reachable sub-agents (${peers.length}):\n${listed.map((p) => `• ${sanitizeDisplayLabel(p, "peer")}`).join("\n")}${omission}`
+					: "(no sub-agents are currently reachable)",
+				details: {
+					action: "list",
+					peers: listed,
+					totalPeers: peers.length,
+					...(omittedPeers > 0 ? { omittedPeers } : {}),
+					ok: true,
+				},
+			};
+		}
+		case "inbox": {
+			const messages = bus.take(self);
+			return { text: formatInbox(messages), details: { action: "inbox", messages, ok: true } };
+		}
+		case "message": {
+			if (!params.messageId) {
+				return { text: "intercom message needs { messageId: <message id> }.", details: { action: "message", ok: false } };
+			}
+			if (params.messageId.length > MAX_INTERCOM_REF_CHARS) {
+				return { text: `intercom messageId exceeds the ${MAX_INTERCOM_REF_CHARS}-character limit.`, details: { action: "message", ok: false } };
+			}
+			const message = bus.retrieve(params.messageId, self);
+			const displayMessageId = sanitizeDisplayLabel(params.messageId, "message");
+			if (!message) {
+				return {
+					text: `No retained message with id "${displayMessageId}" — it may still be pending, expired, exceeded the retention limit, or never have been delivered (check "inbox").`,
+					details: { action: "message", ok: false },
+				};
+			}
+			const from = sanitizeDisplayLabel(message.from, "peer", 40);
+			const kind = sanitizeDisplayLabel(message.kind, "message", 24);
+			const id = sanitizeDisplayLabel(message.id, "message", 40);
+			const replyHint = message.expectsReply ? ` · reply with id ${id}` : "";
+			return {
+				text: `[${from}] (${kind}${replyHint}) message id ${id}:\n${message.text}`,
+				details: { action: "message", messageId: message.id, message, ok: true },
+			};
+		}
+		case "reply": {
+			if (!params.askId || params.message === undefined) {
+				return { text: "intercom reply needs { askId, message }.", details: { action: "reply", ok: false } };
+			}
+			if (params.askId.length > MAX_INTERCOM_REF_CHARS) {
+				return { text: `intercom reply askId exceeds the ${MAX_INTERCOM_REF_CHARS}-character limit.`, details: { action: "reply", ok: false } };
+			}
+			if (params.message.length > MAX_INTERCOM_MESSAGE_CHARS) {
+				return { text: `intercom reply message exceeds the ${MAX_INTERCOM_MESSAGE_CHARS}-character limit.`, details: { action: "reply", ok: false } };
+			}
+			const replied = bus.reply(params.askId, params.message);
+			const displayAskId = sanitizeDisplayLabel(params.askId, "ask");
+			return replied
+				? { text: `Replied to ${displayAskId}.`, details: { action: "reply", ok: true } }
+				: {
+						text: `No pending ask with id "${displayAskId}" — it may have timed out or already been answered (check "inbox").`,
+						details: { action: "reply", ok: false },
+					};
+		}
+		case "send": {
+			if (!params.to || params.message === undefined) {
+				return { text: "intercom send needs { to, message }.", details: { action: "send", ok: false } };
+			}
+			if (params.to.length > MAX_INTERCOM_REF_CHARS) {
+				return { text: `intercom send target exceeds the ${MAX_INTERCOM_REF_CHARS}-character limit.`, details: { action: "send", ok: false } };
+			}
+			if (params.message.length > MAX_INTERCOM_MESSAGE_CHARS) {
+				return { text: `intercom send message exceeds the ${MAX_INTERCOM_MESSAGE_CHARS}-character limit.`, details: { action: "send", ok: false } };
+			}
+			const delivered = bus.send(self, params.to, params.message, "progress");
+			const displayPeer = sanitizeDisplayLabel(params.to, "peer");
+			return delivered
+				? { text: `Sent to ${displayPeer}.`, details: { action: "send", ok: true } }
+				: { text: `Unknown peer "${displayPeer}" — nobody by that handle is registered.`, details: { action: "send", ok: false } };
+		}
+	}
+}

package/src/tools/models.ts

@@ -0,0 +1,39 @@
+/** `models` tool — discover/search model ids. */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { Text } from "@earendil-works/pi-tui";
+import { compactInlineText } from "../ui/presentation.ts";
+
+export interface ModelsToolDeps {
+	get lastCtx(): ExtensionContext | undefined;
+	set lastCtx(value: ExtensionContext | undefined);
+	searchModels(ctx: ExtensionContext, query?: string): { lines: string[]; total: number; capped: boolean };
+}
+
+export function registerModelsTool(pi: ExtensionAPI, d: ModelsToolDeps): void {
+	// ── /models + a `models` tool — discover/search model ids ─────────────────────
+	pi.registerTool({
+		name: "models",
+		label: "Models",
+		description: [
+			"List or search the available model ids (provider/id). The same name exists under several",
+			"providers — use an EXACT id from here as a delegate task's `model`. ★ marks your session",
+			"provider; prefer it (it's the authenticated one).",
+		].join(" "),
+		parameters: Type.Object({
+			query: Type.Optional(Type.String({ description: "Filter by substring (provider or id), e.g. 'sonnet'" })),
+		}),
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			d.lastCtx = ctx;
+			const { lines, total, capped } = d.searchModels(ctx, params.query);
+			const text = lines.length
+				? `${total} model(s)${capped ? " (showing 40 — refine with a query)" : ""}; ★ = session provider:\n${lines.join("\n")}`
+				: `no models match "${params.query ?? ""}"`;
+			return { content: [{ type: "text", text }], details: { total }, isError: false };
+		},
+		renderCall(args, theme) {
+			const query = compactInlineText(args.query ?? "(all)", { maxChars: 96 }) || "(all)";
+			return new Text(`${theme.fg("toolTitle", theme.bold("models "))}${theme.fg("dim", query)}`, 0, 0);
+		},
+	});
+}

package/src/tools/monitor.ts

@@ -0,0 +1,66 @@
+/** Background event sources: one executable, explicit argv, bounded session lifetime. */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { Text } from "@earendil-works/pi-tui";
+import type { MonitorManager } from "../core/monitor.ts";
+import { failureDetails } from "../extension/shared.ts";
+import { compactInlineText } from "../ui/presentation.ts";
+
+export interface MonitorToolDeps {
+	get lastCtx(): ExtensionContext | undefined;
+	set lastCtx(value: ExtensionContext | undefined);
+	canRun(): boolean;
+	monitors: Pick<MonitorManager, "arm" | "list" | "cancel">;
+}
+
+export function registerMonitorTool(pi: ExtensionAPI, d: MonitorToolDeps): void {
+	pi.registerTool({
+		name: "monitor",
+		label: "Monitor",
+		description: "Watch a job, file, log or system event using a background program. arm starts command (an executable) with args in the current workspace; no implicit shell. The argument list allows up to 64 literal arguments, each up to 8192 characters and 24,000 characters in total. mode=output wakes on nonempty stdout lines; write an adapter that prints only relevant changes. mode=exit wakes once when the launched job finishes. Returns immediately; continue independent work, then end your turn to receive events automatically. Requires monitor AND bash permission. Default: one event, ten-minute deadline; max eight monitors, twenty events each, twenty-four hours. list shows active watches; cancel stops the owned process tree and queued wakes. Keep this Pi session open; watches stop on session shutdown/reload. Do not wrap delegate or Exocom in a monitor: their notifications are already automatic.",
+		parameters: Type.Object({
+			action: Type.Union([Type.Literal("arm"), Type.Literal("list"), Type.Literal("cancel")]),
+			command: Type.Optional(Type.String({ minLength: 1, maxLength: 4096, description: "arm: executable, e.g. node, python or powershell.exe. Use args for script paths and arguments." })),
+			args: Type.Optional(Type.Array(Type.String({ maxLength: 8192 }), { maxItems: 64, description: "arm: literal argv (up to 64 arguments, each up to 8192 characters; combined argument strings maximum 24000 characters). For shell syntax, explicitly launch the appropriate shell and pass a script file." })),
+			label: Type.Optional(Type.String({ minLength: 1, maxLength: 120, description: "arm: short purpose, e.g. build finished or new application error." })),
+			mode: Type.Optional(Type.Union([Type.Literal("output"), Type.Literal("exit")], { description: "arm: output for event-producing watchers; exit for job completion. Required." })),
+			timeoutSeconds: Type.Optional(Type.Number({ minimum: 1, maximum: 86400, description: "arm: lifetime deadline, default 600 seconds. Expiry stops the process and reports a timeout." })),
+			maxEvents: Type.Optional(Type.Integer({ minimum: 1, maximum: 20, description: "arm/output: stop after this many distinct event lines, default 1." })),
+			id: Type.Optional(Type.String({ minLength: 1, description: "cancel: monitor id returned by arm." })),
+		}),
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			d.lastCtx = ctx;
+			const fail = (text: string) => ({ content: [{ type: "text" as const, text }], details: failureDetails({ ok: false }), isError: true });
+			if (params.action === "list") {
+				const entries = d.monitors.list();
+				return { content: [{ type: "text" as const, text: entries.length ? entries.map((e) => `${e.id} (${compactInlineText(e.label, { maxChars: 120 })}) — ${e.mode}; deadline ${new Date(e.expiresAtEpochMs).toISOString()}`).join("\n") : "No active monitors." }], details: { ok: true, count: entries.length } };
+			}
+			if (params.action === "cancel") {
+				if (typeof params.id !== "string" || !params.id.trim()) return fail("monitor cancel needs { id } from arm or list.");
+				const cancelled = d.monitors.cancel(params.id);
+				return { content: [{ type: "text" as const, text: cancelled ? `Cancelled ${params.id}; its queued events were removed.` : `No active monitor or queued event for ${params.id}.` }], details: { ok: true, cancelled } };
+			}
+			if (params.action !== "arm") return fail("monitor action must be arm, list or cancel.");
+			if (!d.canRun()) return fail("monitor arm requires both monitor and bash permission for the active persona.");
+			if (signal?.aborted) return fail("monitor arm cancelled before launch.");
+			if (typeof params.command !== "string" || !params.command.trim() || typeof params.label !== "string" || !params.label.trim()) return fail("monitor arm needs { command, label, mode }.");
+			if (params.mode !== "output" && params.mode !== "exit") return fail("monitor arm mode must be output or exit.");
+			if (params.args !== undefined && (!Array.isArray(params.args) || !params.args.every((v) => typeof v === "string"))) return fail("monitor args must be an array of literal strings.");
+			if (params.timeoutSeconds !== undefined && (!Number.isFinite(params.timeoutSeconds) || params.timeoutSeconds < 1 || params.timeoutSeconds > 86400)) return fail("monitor timeoutSeconds must be between 1 and 86400.");
+			if (params.maxEvents !== undefined && (!Number.isInteger(params.maxEvents) || params.maxEvents < 1 || params.maxEvents > 20)) return fail("monitor maxEvents must be an integer between 1 and 20.");
+			const result = d.monitors.arm({
+				command: params.command, label: params.label, mode: params.mode, cwd: ctx.cwd,
+				...(params.args !== undefined ? { args: params.args } : {}),
+				...(params.timeoutSeconds !== undefined ? { timeoutMs: Math.round(params.timeoutSeconds * 1000) } : {}),
+				...(params.maxEvents !== undefined ? { maxEvents: params.maxEvents } : {}),
+			});
+			if (!result.ok) return fail(result.error);
+			return { content: [{ type: "text" as const, text: `Armed ${result.entry.id} (${compactInlineText(result.entry.label, { maxChars: 120 })}); ${params.mode === "exit" ? "wakes when this job exits" : "wakes on relevant stdout lines"}. Deadline ${new Date(result.entry.expiresAtEpochMs).toISOString()}. Keep this session open. Continue independent work, or end your turn and wait for the automatic notice.` }], details: { ok: true, id: result.entry.id, expiresAtEpochMs: result.entry.expiresAtEpochMs } };
+		},
+		renderCall(args, theme) {
+			const action = compactInlineText(args.action ?? "", { maxChars: 12 });
+			const label = compactInlineText(args.label ?? args.id ?? "", { maxChars: 96 });
+			return new Text(`${theme.fg("toolTitle", theme.bold(`monitor ${action}`))}${label ? ` ${theme.fg("dim", label)}` : ""}`, 0, 0);
+		},
+	});
+}