@aeondave/pi-persona 1.17.1 → 1.17.4

package/src/bus/contact.ts

@@ -5,9 +5,8 @@
  * `customTool` by the engine, bound to the shared {@link InProcessBus} + the child's
  * handle.
  *
- * - `progress_update` (one-way): post and return immediately — the supervisor reads it
- *   on its next peek (or it rides back on the run's result in sync mode).
- * - `need_decision` / `interview_request` (blocking): `bus.ask` — the child waits for
+ * - `progress` (one-way): post and return immediately.
+ * - `decision` / `interview` (blocking): `bus.ask` — the child waits for
  *   the supervisor's reply. This only makes sense in **async** runs where the supervisor
  *   is free to answer; the tool aborts cleanly on the run's signal so it never hangs a
  *   sync run with no one listening.
@@ -18,27 +17,68 @@
 import { type Static, Type } from "typebox";
 
 import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 
+import { compactInlineText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
 import type { InProcessBus, MsgKind } from "./inproc.ts";
 
 const ContactParams = Type.Object({
 	kind: Type.Union([Type.Literal("progress"), Type.Literal("decision"), Type.Literal("interview")], {
 		description:
-			"progress = one-way status update (don't wait); decision = ask the supervisor to choose; interview = ask a clarifying question. For decision/interview, async runs wait for a reply; synchronous runs post one-way and continue.",
+			"progress = one-way status update (don't wait); decision = ask the supervisor to choose; interview = ask a clarifying question. Async decision/interview requests wait for a reply; synchronous requests post one-way with no possible answer, so the request remains unresolved.",
 	}),
 	message: Type.String({ description: "What to tell or ask the supervisor — specific and self-contained." }),
 });
 
-type ContactDetails = { kind: MsgKind; delivered: boolean };
+type ContactOutcome = "reported" | "answered" | "unavailable" | "timed-out" | "cancelled" | "failed";
+
+type ContactDetails = {
+	kind: MsgKind;
+	/** Delivery evidence only, never evidence of a reply or approval. False means delivery was not confirmed. */
+	delivered: boolean;
+	outcome: ContactOutcome;
+};
 
 type AskFailure = "aborted" | "timeout" | "inbox-full" | "unavailable" | "generic";
 
+const UNRESOLVED_NEXT_STEP = "Continue only with independent work already authorized; otherwise return a blocked/partial result.";
+
+function unresolvedGuidance(kind: "decision" | "interview"): string {
+	return `The ${kind} remains unresolved. ${UNRESOLVED_NEXT_STEP}`;
+}
+
+function outcomeForAskFailure(failure: AskFailure): ContactOutcome {
+	switch (failure) {
+		case "aborted": return "cancelled";
+		case "timeout": return "timed-out";
+		case "inbox-full":
+		case "unavailable": return "unavailable";
+		case "generic": return "failed";
+	}
+}
+
+function askFailureText(failure: AskFailure): string {
+	switch (failure) {
+		case "aborted": return "The request was cancelled before the supervisor replied.";
+		case "timeout": return "The supervisor did not reply in time.";
+		case "inbox-full": return "The supervisor inbox is full; this request was not delivered. Retry later or consolidate the question.";
+		case "unavailable": return "The supervisor is unavailable; delivery could not be confirmed.";
+		case "generic": return "The supervisor request failed; delivery could not be confirmed.";
+	}
+}
+
 function classifyAskFailure(error: unknown, signal: AbortSignal | undefined): AskFailure {
 	if (signal?.aborted) return "aborted";
 	const message = error instanceof Error ? error.message : "";
 	if (/^ask timeout(?:\s|$)/i.test(message)) return "timeout";
 	if (/^inbox full(?:\s|:|$)/i.test(message)) return "inbox-full";
-	if (/^ask unregistered(?:\s|$)/i.test(message) || /^broker (?:connection|client) closed(?:\s|$)/i.test(message)) return "unavailable";
+	if (
+		/^ask unregistered(?:\s|$)/i.test(message) ||
+		/^unknown peer(?:\s|:|$)/i.test(message) ||
+		/^bridge: not connected(?:\s|$)/i.test(message) ||
+		/^broker (?:connection|client) closed(?:\s|$)/i.test(message)
+	) return "unavailable";
 	return "generic";
 }
 
@@ -52,7 +92,7 @@ function result(t: string, details: ContactDetails): { content: [{ type: "text";
  *
  *  `allowBlocking` (async runs only): when false, a `decision`/`interview` does NOT block —
  *  the supervisor is busy (a sync run holds the turn), so the question is posted one-way and
- *  the child proceeds. This prevents a sync delegate/council from deadlocking on a child ask. */
+ *  returns unresolved. This prevents a sync delegate/council from deadlocking on a child ask. */
 export function makeContactSupervisorTool(
 	bus: InProcessBus,
 	fromHandle: string,
@@ -68,32 +108,49 @@ export function makeContactSupervisorTool(
 			"Use `progress` to report a milestone (one-way, don't wait).",
 			"Use `decision` when you hit a choice only the supervisor should make, or `interview` to ask a clarifying question.",
 			allowBlocking
-				? "This async run waits for the supervisor's reply before continuing."
-				: "This synchronous run cannot block: decision/interview are posted one-way and return immediately; proceed using your best judgement.",
+				? "This async run waits for the supervisor's reply before continuing. If there is no reply, the request remains unresolved: continue only with independent work already authorized, otherwise return a blocked/partial result."
+				: "This synchronous run cannot block: decision/interview are posted one-way and return immediately; no answer is possible in this path, so the request remains unresolved. Continue only with independent work already authorized, otherwise return a blocked/partial result.",
 			`Messages longer than ${MAX_CONTACT_MESSAGE_CHARS} characters are shortened before delivery; use smaller messages to preserve full detail.`,
 		].join(" "),
 		promptSnippet: "contact_supervisor — report progress or ask the supervisor a question",
 		parameters: ContactParams,
 		async execute(_toolCallId, params: Static<typeof ContactParams>, signal, _onUpdate, _ctx) {
 			const kind = params.kind as MsgKind;
+			if (signal?.aborted) {
+				const text = kind === "progress"
+					? "The progress update was cancelled before delivery."
+					: `The request was cancelled before the supervisor was contacted. ${unresolvedGuidance(kind)}`;
+				return result(text, { kind, delivered: false, outcome: "cancelled" });
+			}
 			const message = boundContactMessage(params.message);
 			if (kind === "progress") {
-				const delivered = bus.send(fromHandle, supervisorHandle, message, "progress");
-				return result(
-					delivered ? "Progress reported to the supervisor." : "(no supervisor listening; progress dropped)",
-					{ kind, delivered },
-				);
+				try {
+					const delivered = bus.send(fromHandle, supervisorHandle, message, "progress");
+					return result(
+						delivered ? "Progress reported to the supervisor." : "(no supervisor listening or progress delivery could not be confirmed; progress dropped)",
+						{ kind, delivered, outcome: delivered ? "reported" : "unavailable" },
+					);
+				} catch {
+					return result("(progress could not be sent; delivery could not be confirmed)", { kind, delivered: false, outcome: "failed" });
+				}
 			}
 
 			// In a sync run the supervisor is blocked holding the turn → it cannot answer. Post the
-			// question one-way and let the child proceed, rather than deadlock until timeout.
+			// question one-way, but return unresolved; the send is not authorization to proceed on it.
 			if (!allowBlocking) {
-				const delivered = bus.send(fromHandle, supervisorHandle, message, kind);
+				let delivered: boolean;
+				try {
+					delivered = bus.send(fromHandle, supervisorHandle, message, kind);
+				} catch {
+					return result(
+						`The question could not be sent; no answer is possible in this path. ${unresolvedGuidance(kind)}`,
+						{ kind, delivered: false, outcome: "failed" },
+					);
+				}
+				const delivery = delivered ? "question sent one-way" : "question delivery could not be confirmed";
 				return result(
-					delivered
-						? "The supervisor is busy right now; your question was noted — proceed using your best judgement."
-						: "(no supervisor reachable — proceed using your best judgement)",
-					{ kind, delivered },
+					`The supervisor is busy right now; ${delivery}, and no answer is possible in this path. ${unresolvedGuidance(kind)}`,
+					{ kind, delivered, outcome: "unavailable" },
 				);
 			}
 
@@ -103,30 +160,48 @@ export function makeContactSupervisorTool(
 			let answer: Promise<string>;
 			try {
 				answer = bus.ask(fromHandle, supervisorHandle, message, signal ? { kind, signal } : { kind });
-			} catch {
-				return result("(no supervisor reachable — proceed using your best judgement)", { kind, delivered: false });
+			} catch (error) {
+				const failure = classifyAskFailure(error, signal);
+				return result(`${askFailureText(failure)} ${unresolvedGuidance(kind)}`, {
+					kind,
+					delivered: false,
+					outcome: outcomeForAskFailure(failure),
+				});
 			}
 			try {
 				const reply = await answer;
-				return result(`Supervisor: ${reply}`, { kind, delivered: true });
+				// A response that settles concurrently with cancellation is stale for this call:
+				// never report it as an answer once the caller's signal has aborted.
+				if (signal?.aborted) {
+					return result(`${askFailureText("aborted")} ${unresolvedGuidance(kind)}`, {
+						kind,
+						delivered: false,
+						outcome: "cancelled",
+					});
+				}
+				return result(`Supervisor: ${reply}`, { kind, delivered: true, outcome: "answered" });
 			} catch (error) {
-				const msg = (() => {
-					switch (classifyAskFailure(error, signal)) {
-						case "aborted":
-							return "(the request was cancelled before the supervisor replied)";
-						case "timeout":
-							return "(the supervisor did not reply in time — proceed using your best judgement)";
-						case "inbox-full":
-							return "(the supervisor inbox is full — this request was not delivered; retry later or consolidate the question)";
-						case "unavailable":
-							return "(the supervisor is no longer available — this request was not delivered; proceed using your best judgement)";
-						default:
-							return "(the supervisor request could not be completed — proceed using your best judgement)";
-					}
-				})();
-				return result(msg, { kind, delivered: false });
+				const failure = classifyAskFailure(error, signal);
+				return result(`${askFailureText(failure)} ${unresolvedGuidance(kind)}`, {
+					kind,
+					delivered: false,
+					outcome: outcomeForAskFailure(failure),
+				});
 			}
 		},
+		// Compact purpose line only: the message is the child's own prose, and echoing it in the
+		// call card would overflow the transcript the way the host fallback's raw-args echo does.
+		renderCall(args, theme) {
+			const kind = compactInlineText(args.kind ?? "", { maxChars: 12 });
+			return new Text(theme.fg("toolTitle", theme.bold(kind ? `contact ${kind}` : "contact")), 0, 0);
+		},
+		// One shared literal receipt. An answered ask is bounded collapsed and expands to the full
+		// reply; progress receipts are naturally one compact line. Unresolved outcomes
+		// (unavailable/timed-out/cancelled/failed) are SUCCESSFUL tool results carrying an
+		// unresolved outcome — the error heading appears only when the host context says isError.
+		renderResult(result, { expanded }, theme, context) {
+			return renderLiteralToolResult(result, { expanded }, theme, context);
+		},
 	});
 }
 /** Maximum body accepted by contact_supervisor's message action. Full reports should use the

package/src/bus/peers.ts

@@ -20,7 +20,10 @@
 import { type Static, Type } from "typebox";
 
 import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 
+import { compactInlineText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
 import type { InProcessBus } from "./inproc.ts";
 
 /** Anti ping-pong budget: after this many sends the tool tells the member to finalize. */
@@ -110,5 +113,17 @@ export function makeContactPeerTool(bus: InProcessBus, selfHandle: string, deps:
 				{ action: "send", delivered },
 			);
 		},
+		// Compact purpose line only — same rule as contact_supervisor: no note body in the call
+		// card (the host fallback would echo raw args).
+		renderCall(args, theme) {
+			const action = compactInlineText(args.action ?? "", { maxChars: 12 });
+			return new Text(theme.fg("toolTitle", theme.bold(action ? `peer ${action}` : "peer")), 0, 0);
+		},
+		// One shared literal receipt: a send receipt is one compact line; a long peer list stays
+		// bounded collapsed (expansion hint) and shows every peer expanded. The error heading comes
+		// only from the host's isError flag, never from the semantic content.
+		renderResult(result, { expanded }, theme, context) {
+			return renderLiteralToolResult(result, { expanded }, theme, context);
+		},
 	});
 }

package/src/bus/result-reader.ts

@@ -0,0 +1,88 @@
+/** Narrow result-read boundary. No archive ownership, discovery, paths or session identity.
+ * The parent supplies a reader that checks CURRENT capabilities/owner and its explicit ref
+ * grant on every call. The broker owns attachment, cancellation and wire validation only. */
+import { isResultRef } from "../results/record.ts";
+import { RESULT_READ_DEFAULT, RESULT_READ_MAX, type ResultReadRequest, type ResultProvenance,
+	type TerminalStatus } from "../results/types.ts";
+
+export type { ResultReadRequest } from "../results/types.ts";
+export const RESULT_READ_TIMEOUT_MS = 10_000;
+export const RESULT_READ_MAX_PENDING = 8;
+export const RESULT_READ_MAX_FRAME_BYTES = 128 * 1024;
+/** Bound replay tracking without ever evicting an id and accepting its replay. Exhaustion
+ * ends the reader connection; it does not reconnect or retry. */
+export const RESULT_READ_MAX_REQUESTS = 4096;
+
+const ERROR_MESSAGES = {
+	invalid: "Invalid result read request.",
+	denied: "Result read is not authorized.",
+	revoked: "Result reader was revoked.",
+	unavailable: "Result reader is unavailable.",
+	cancelled: "Result read was cancelled.",
+	timeout: "Result read deadline exceeded.",
+	busy: "Too many pending result reads.",
+	protocol: "Invalid result reader protocol.",
+} as const;
+export type ReadErrorCode = keyof typeof ERROR_MESSAGES;
+export type ReadReply = {
+	ok: true; ref: string; body: string; offset: number; nextOffset?: number;
+	storedChars: number; originalChars: number; truncated: boolean; endOfStoredBody: boolean;
+	status: TerminalStatus; provenance: ResultProvenance;
+} | { ok: false; code: ReadErrorCode; message: string };
+
+export interface ScopedReader {
+	read(request: ResultReadRequest, signal?: AbortSignal): Promise<ReadReply>;
+	revoke(): void;
+}
+
+export interface PreparedResultReader {
+	/** Private spawn environment only. Never put in tasks, receipts or diagnostics. */
+	token: string;
+	revoke(): void;
+	/** Historical attachment evidence, not a promise of continued connectivity. */
+	wasBound(): boolean;
+}
+
+export function readFailure(code: ReadErrorCode): ReadReply & { ok: false } {
+	return { ok: false, code, message: ERROR_MESSAGES[code] };
+}
+
+/** Reject hidden/accessor fields too: this validator is also used on parent callback data. */
+export function closedRecord(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const proto: unknown = Object.getPrototypeOf(value);
+	return (proto === Object.prototype || proto === null) && Reflect.ownKeys(value).every((key) => {
+		const d = Object.getOwnPropertyDescriptor(value, key);
+		return typeof key === "string" && keys.includes(key) && d?.enumerable === true && "value" in d;
+	});
+}
+const counter = (n: unknown): n is number => typeof n === "number" && Number.isSafeInteger(n) && n >= 0;
+
+export function isReadRequest(value: unknown): value is ResultReadRequest {
+	return closedRecord(value, ["ref", "offset", "limit"]) && isResultRef(value.ref)
+		&& (!("offset" in value) || counter(value.offset))
+		&& (!("limit" in value) || (counter(value.limit) && value.limit >= 2 && value.limit <= RESULT_READ_MAX));
+}
+
+export function isReadReply(value: unknown): value is ReadReply {
+	if (!closedRecord(value, ["ok", "ref", "body", "offset", "nextOffset", "storedChars", "originalChars",
+		"truncated", "endOfStoredBody", "status", "provenance", "code", "message"])) return false;
+	if (value.ok === false) return closedRecord(value, ["ok", "code", "message"])
+		&& typeof value.code === "string" && Object.hasOwn(ERROR_MESSAGES, value.code)
+		&& value.message === ERROR_MESSAGES[value.code as ReadErrorCode];
+	if (value.ok !== true || "code" in value || "message" in value || !isResultRef(value.ref)
+		|| typeof value.body !== "string" || value.body.length > RESULT_READ_MAX || !counter(value.offset)
+		|| !counter(value.storedChars) || !counter(value.originalChars) || value.originalChars < value.storedChars
+		|| value.truncated !== (value.originalChars > value.storedChars)
+		|| (value.status !== "done" && value.status !== "failed" && value.status !== "stopped")
+		|| (value.provenance !== "result-output" && value.provenance !== "partial-output" && value.provenance !== "error")) return false;
+	const end = value.offset + value.body.length;
+	if (!Number.isSafeInteger(end) || end > value.storedChars || value.endOfStoredBody !== (end === value.storedChars)) return false;
+	return value.endOfStoredBody ? !("nextOffset" in value) : value.body.length > 0 && value.nextOffset === end;
+}
+
+/** Page offsets are UTF-16; the archive, not transport, owns surrogate-boundary slicing. */
+export function isReadReplyFor(value: unknown, request: ResultReadRequest): value is ReadReply {
+	return isReadReply(value) && (!value.ok || (value.ref === request.ref && value.offset === (request.offset ?? 0)
+		&& value.body.length <= (request.limit ?? RESULT_READ_DEFAULT)));
+}