pi-roundtable 0.9.11 → 0.9.13

package/src/core/runtime/extensions/confirmation-gate.ts

@@ -1,5 +1,3 @@
-import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
-import type { ToolTurn } from "../../define.ts";
 import type {
 	HeldCall,
 	PendingConfirmation,
@@ -14,67 +12,47 @@ import {
 } from "../../holds.ts";
 import { messages } from "../../i18n/index.ts";
 import { type OwnerIdentity, ownerWords } from "../../identity.ts";
-import type { LateAnswer, Prompts } from "../../interactions/prompts.ts";
-import type { Speaker } from "../../speakers.ts";
+import type {
+	ApprovalOptions,
+	ApprovedBy,
+	LateAnswer,
+	Prompts,
+} from "../../interactions/prompts.ts";
 import type { ToolTiers } from "../../tool-tiers.ts";
-import type { PromptSlot } from "../prompt-slot.ts";
 import { approvalCard, approvalDetails } from "./approval-card.ts";
+import {
+	askSpeaker,
+	type Needing,
+	namesOf,
+	type Release,
+	remembered,
+	type SpeakerRef,
+	unlessNamed,
+} from "./gate-refusals.ts";
+import {
+	canonicalJson,
+	mayApproveNamed,
+	namedApprover,
+	unexpired,
+} from "./held-calls.ts";
+import {
+	awaited,
+	type Described,
+	type HoldTurn,
+	joinApprovers,
+	STOPPED,
+} from "./hold-lookups.ts";
 
-/** Held actions older than this cannot be approved any more. */
-export const CONFIRMATION_TTL_MS = 24 * 3_600_000;
-
-/** The held actions when they can still be approved at `now`; expired ones count as none. */
-export function unexpired(
-	pending: PendingConfirmation | undefined,
-	now = new Date(),
-): PendingConfirmation | undefined {
-	if (!pending) return undefined;
-	return now.getTime() - pending.heldAt.getTime() > CONFIRMATION_TTL_MS
-		? undefined
-		: pending;
-}
-
-/** The turn a hold that looks things up sees; see `HoldRule.describeInTurn`. */
-export interface HoldTurn {
-	/** Aborts when the turn stops; a call being described then opens no card. */
-	signal?: AbortSignal;
-	/** The turn a hold receives, with `signal` as the signal that ends its wait. */
-	toolTurn(signal: AbortSignal): ToolTurn;
-}
-
-/** The answer of a description wait the turn's stop cut short. */
-const STOPPED = Symbol("stopped");
-
-/** What waiting for a call's description comes to: its text, or the turn stopped first. */
-type Described = string | undefined | typeof STOPPED;
-
-/** JSON with object keys sorted at every level, so equal inputs compare equal. */
-// pi-lens-ignore: no-unknown-parameters — tool input is untyped model JSON; this is where it is read
-export function canonicalJson(value: unknown): string {
-	// pi-lens-ignore: no-unknown-parameters — tool input is untyped model JSON; this is where it is read
-	return JSON.stringify(value, (_key, v: unknown) =>
-		isPlainObject(v) ? withSortedKeys(v) : v,
-	);
-}
-
-// pi-lens-ignore: no-unknown-parameters — tool input is untyped model JSON; this is where it is read
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-/** The same object with its keys in code-unit order. */
-function withSortedKeys(
-	value: Record<string, unknown>,
-): Record<string, unknown> {
-	return Object.fromEntries(
-		Object.entries(value).sort(([a], [b]) => byCodeUnit(a, b)),
-	);
-}
-
-function byCodeUnit(a: string, b: string): number {
-	if (a < b) return -1;
-	return a > b ? 1 : 0;
-}
+export { confirmationGateExtension } from "./confirmation-gate-extension.ts";
+export {
+	CONFIRMATION_TTL_MS,
+	canonicalJson,
+	confirmedTurnText,
+	mayApproveNamed,
+	namedApprover,
+	unexpired,
+} from "./held-calls.ts";
+export type { HoldTurn } from "./hold-lookups.ts";
 
 /**
  * Per-channel state of held actions. With the owner's prompts bound, a call that needs their
@@ -86,12 +64,16 @@ function byCodeUnit(a: string, b: string): number {
 // pi-lens-ignore: large-class — one gate per conversation; its state is the held calls and their approvals
 export class ConfirmationGate {
 	#selectionId: string | undefined;
-	/** The running turn's speaker, whom the actions it holds belong to. */
-	#speaker: Pick<Speaker, "id" | "principalId"> | undefined;
+	/** The running turn's speaker, whom the actions it holds belong to, and who approves those a message confirmed. */
+	#speaker: SpeakerRef | undefined;
+	/** Whether the running turn's conversation is private to its speaker, who then alone answers its cards. */
+	#private = false;
 	#pending: PendingConfirmation | undefined;
-	#approved: HeldCall[] = [];
+	#approved: Release[] = [];
 	/** Calls approved on their cards after the turn that asked stopped waiting; each runs once, in any turn. */
-	#lateApproved: HeldCall[] = [];
+	#lateApproved: Release[] = [];
+	/** Who approved each call that is running, by tool call id, until its result is back. */
+	readonly #approvers = new Map<string, ApprovedBy>();
 	readonly #holds: HoldCheck;
 	readonly #owner: OwnerIdentity;
 	/** Whom the running turn's held actions and refusals speak of: the turn's speaker. */
@@ -101,6 +83,12 @@ export class ConfirmationGate {
 	/** Where the session's relative file paths resolve, for the sizes a card shows. */
 	readonly #fileRoot: string | undefined;
 	readonly #describeTimeoutMs: number;
+	/** The name a principal goes by, for telling a speaker who may approve a call; undefined when unknown. */
+	readonly #nameOf:
+		| ((principalId: string) => Promise<string | undefined>)
+		| undefined;
+	/** The held calls a partial release kept, until this turn records a hold of its own. */
+	#kept: PendingConfirmation | undefined;
 	/** Settles when the descriptions asked for so far have all been used, in the order they were asked. */
 	#describing: Promise<void> = Promise.resolve();
 	/** Descriptions asked for and not used yet. */
@@ -112,6 +100,8 @@ export class ConfirmationGate {
 	 * `fileRoot` is the session's working directory, where a card resolves relative file paths;
 	 * it defaults to the workspace. A hold that looks things up gets `describeTimeoutMs` to answer
 	 * (`HOLD_DESCRIBE_TIMEOUT_MS` by default) before its call is held under a generic description.
+	 * `nameOf` gives the name of a principal a call names as an approver, which the text a speaker
+	 * who cannot approve it is given lists.
 	 */
 	constructor(
 		holds: HoldCheck,
@@ -121,8 +111,10 @@ export class ConfirmationGate {
 		tiers?: ToolTiers,
 		fileRoot?: string,
 		describeTimeoutMs = HOLD_DESCRIBE_TIMEOUT_MS,
+		nameOf?: (principalId: string) => Promise<string | undefined>,
 	) {
 		this.#describeTimeoutMs = describeTimeoutMs;
+		this.#nameOf = nameOf;
 		this.#tiers = tiers;
 		this.#fileRoot = fileRoot ?? context.workspace;
 		this.#holds = holds;
@@ -137,32 +129,102 @@ export class ConfirmationGate {
 		return unexpired(this.#pending, now);
 	}
 
+	/**
+	 * The held calls a message from `speaker` may release: all of them, except those that named
+	 * approvers the speaker is neither among nor an owner of, which stay held whoever else asked for
+	 * them to run. Undefined when there are none.
+	 */
+	releasable(speaker?: SpeakerRef): PendingConfirmation | undefined {
+		const pending = this.pending();
+		if (!pending) return undefined;
+		const calls = pending.calls.filter((call) =>
+			mayApproveNamed(speaker, call),
+		);
+		return calls.length === pending.calls.length
+			? pending
+			: { ...pending, calls };
+	}
+
 	/**
 	 * `addressee` is who the turn is for; without one, the owner. `speaker` is who spoke the turn,
 	 * recorded with what it holds by their id and principal; without one, only the owners may
-	 * approve them.
+	 * approve them. When `confirmed`, the speaker's message approved the held calls, and they are
+	 * the approver the calls' `run` sees; a call that named approvers is released only when the
+	 * speaker is one of them or an owner, and otherwise stays held. `isPrivate` says the turn's
+	 * conversation is private to its speaker: they alone then answer its cards.
 	 */
 	beginTurn(
 		selectionId: string,
 		confirmed: boolean,
 		addressee?: OwnerIdentity,
-		speaker?: Pick<Speaker, "id" | "principalId">,
+		speaker?: SpeakerRef,
+		isPrivate = false,
 	): void {
 		this.#selectionId = selectionId;
 		this.#speaker = speaker;
+		this.#private = isPrivate;
 		this.#addressee = addressee ?? this.#owner;
-		this.#approved = confirmed ? [...(this.pending()?.calls ?? [])] : [];
-		this.#pending = undefined;
+		const by: ApprovedBy | undefined = speaker
+			? {
+					principalId: speaker.principalId,
+					speakerId: speaker.id,
+					name: speaker.name ?? speaker.id,
+					...(speaker.tier === "owner" ? { owner: true as const } : {}),
+				}
+			: undefined;
+		const held = this.pending();
+		const released = confirmed ? this.releasable(speaker) : undefined;
+		this.#approved = (released?.calls ?? []).map((call) => ({
+			call,
+			...(by ? { by } : {}),
+		}));
+		// What the speaker could not release stays held for those who may.
+		const kept = (held?.calls ?? []).filter(
+			(call) => confirmed && !released?.calls.includes(call),
+		);
+		this.#pending =
+			held && kept.length > 0 ? { ...held, calls: kept } : undefined;
+		this.#kept = this.#pending;
 	}
 
 	endTurn(): void {
 		this.#approved = [];
+		this.#approvers.clear();
+	}
+
+	/** The running turn's speaker as an approver; undefined without one. */
+	#speakerAsApprover(): ApprovedBy | undefined {
+		const speaker = this.#speaker;
+		if (!speaker) return undefined;
+		return {
+			principalId: speaker.principalId,
+			speakerId: speaker.id,
+			name: speaker.name ?? speaker.id,
+			...(speaker.tier === "owner" ? { owner: true as const } : {}),
+		};
+	}
+
+	/** Who approved the held call running under this tool call id; undefined when it was not held or they are unknown. */
+	approvedBy(toolCallId: string): ApprovedBy | undefined {
+		return this.#approvers.get(toolCallId);
+	}
+
+	/** Notes who approved the call running under a tool call id, for its `run` to read. */
+	grant(toolCallId: string, by: ApprovedBy): void {
+		this.#approvers.set(toolCallId, by);
+	}
+
+	/** Forgets who approved a tool call, once its result is back. */
+	finish(toolCallId: string): void {
+		this.#approvers.delete(toolCallId);
 	}
 
 	/** Returns the reason a call is held, or undefined to let it run. */
 	hold(tool: string, input: Record<string, unknown>): string | undefined {
-		const call = this.#needing(tool, input);
-		return call ? this.#record(call) : undefined;
+		const needing = this.#needing(tool, input);
+		return needing && "held" in needing
+			? this.#record(needing.held)
+			: undefined;
 	}
 
 	/**
@@ -193,14 +255,29 @@ export class ConfirmationGate {
 	): Promise<{
 		reason?: string;
 		approvedOnCard?: true;
+		/** Who approved the call, when it was held and a surface or a confirming message said who. */
+		approvedBy?: ApprovedBy;
 		/** Why a hold refused the call, for a surface that tells that from a failure; absent when it ran or the turn stopped. */
 		refused?: HoldRefusal;
 	}> {
 		const found = this.#needingIn(tool, input, turn);
-		const call = isPromise(found) ? await found : found;
-		if (call === STOPPED) return { reason: "The turn was stopped." };
-		if (!call) return {};
-		if (!ask) return { reason: this.#record(call), refused: "held" };
+		const needing = isPromise(found) ? await found : found;
+		if (needing === STOPPED) return { reason: "The turn was stopped." };
+		if (!needing) return {};
+		if ("released" in needing)
+			return needing.released ? { approvedBy: needing.released } : {};
+		const call = needing.held;
+		if (!ask) return { reason: await this.#held(call), refused: "held" };
+		// In a private conversation only its person answers: a call that names others is not theirs.
+		if (this.#private && !mayApproveNamed(this.#speaker, call))
+			return { reason: await this.#held(call), refused: "held" };
+		let approvedBy: ApprovedBy | undefined;
+		const options: ApprovalOptions = {
+			...(call.approverIds ? { approvers: call.approverIds } : {}),
+			approvedBy: (by) => {
+				approvedBy = by;
+			},
+		};
 		const answer = await ask.prompts.confirm(
 			messages().confirmTitle(ask.asker),
 			approvalCard(call, this.#fileRoot),
@@ -208,8 +285,20 @@ export class ConfirmationGate {
 			higherTier(this.#tiers?.minTier(call.tool), call.minTier),
 			{ late: (late) => this.#late(call, late) },
 			approvalDetails(call, this.#fileRoot),
+			options,
 		);
-		if (answer === "approved") return { approvedOnCard: true };
+		if (answer === "approved") {
+			// A private conversation's answer to a call that names approvers is its person's, whom a surface need not name.
+			const by =
+				approvedBy ??
+				(this.#private && call.approverIds
+					? this.#speakerAsApprover()
+					: undefined);
+			// A call that names approvers runs only on the word of one of them, or an owner.
+			if (!namedApprover(call, by))
+				return { reason: await this.#held(call), refused: "held" };
+			return { approvedOnCard: true, ...(by ? { approvedBy: by } : {}) };
+		}
 		if (answer === "pending") {
 			const o = ownerWords(this.#addressee);
 			return {
@@ -227,8 +316,8 @@ export class ConfirmationGate {
 		if (answer === "cancelled") return { reason: "The turn was stopped." };
 		// No card was shown: no one may approve it, or it could not be posted.
 		if (answer === "unavailable")
-			return { reason: this.#record(call), refused: "held" };
-		return { reason: this.#record(call), refused: "expired" };
+			return { reason: await this.#held(call), refused: "held" };
+		return { reason: await this.#held(call), refused: "expired" };
 	}
 
 	/**
@@ -237,16 +326,21 @@ export class ConfirmationGate {
 	 */
 	#late(call: HeldCall, late: LateAnswer): string | undefined {
 		if (late.kind !== "approval") return undefined;
+		if (late.approved && !namedApprover(call, late.approvedBy))
+			return undefined;
 		if (!late.approved)
 			return `(${late.by} declined on its card the action you were waiting on: it would ${call.action}. It did not run; do not make the call again. Go on without it, or ask what ${late.by} wants instead.)`;
-		this.#lateApproved.push(call);
+		this.#lateApproved.push({
+			call,
+			...(late.approvedBy ? { by: late.approvedBy } : {}),
+		});
 		return `(${late.by} approved on its card the action you were waiting on: it would ${call.action}. Make this call now with exactly this input, and it runs once; then report its result.)\n- ${call.tool} ${call.input}`;
 	}
 
-	/** The call when it needs the owner's confirmation and no approval releases it. */
-	#needing(tool: string, input: Record<string, unknown>): HeldCall | undefined {
+	/** What a call needs when a rule holds it; undefined when none does. */
+	#needing(tool: string, input: Record<string, unknown>): Needing | undefined {
 		const action = this.#holds(tool, input, this.#context);
-		return action ? this.#unlessApproved(tool, input, action) : undefined;
+		return action ? this.#unlessApproved(tool, input, { action }) : undefined;
 	}
 
 	/**
@@ -259,10 +353,10 @@ export class ConfirmationGate {
 		input: Record<string, unknown>,
 		turn: HoldTurn | undefined,
 	):
-		| HeldCall
+		| Needing
 		| undefined
 		| typeof STOPPED
-		| Promise<HeldCall | undefined | typeof STOPPED> {
+		| Promise<Needing | undefined | typeof STOPPED> {
 		const inTurn = this.#holds.inTurn;
 		if (!turn || !inTurn) return this.#needing(tool, input);
 		const controller = new AbortController();
@@ -280,45 +374,31 @@ export class ConfirmationGate {
 			answer = messages().holdGeneric(tool);
 		}
 		const described: Described | Promise<Described> = isPromise(answer)
-			? this.#awaited(answer, tool, controller, turn.signal)
+			? awaited(
+					answer,
+					messages().holdGeneric(tool),
+					controller,
+					turn.signal,
+					this.#describeTimeoutMs,
+				)
 			: answer;
-		return this.#inOrder(described, (action) => {
-			if (action === STOPPED) return STOPPED;
-			return action ? this.#unlessApproved(tool, input, action) : undefined;
-		});
-	}
-
-	/**
-	 * What a hold that answers later comes to: its text; the generic description when it rejects or
-	 * outlasts the timeout, so the call is still held; `STOPPED` when the turn stops first. Whatever
-	 * the hold is still doing is aborted when the wait ends.
-	 */
-	#awaited(
-		answer: Promise<string | undefined>,
-		tool: string,
-		hold: AbortController,
-		stop: AbortSignal | undefined,
-	): Promise<Described> {
-		return new Promise<Described>((resolve) => {
-			const onStop = () => end(STOPPED);
-			const timer = setTimeout(
-				() => end(messages().holdGeneric(tool)),
-				this.#describeTimeoutMs,
-			);
-			let ended = false;
-			const end = (described: Described) => {
-				if (ended) return;
-				ended = true;
-				clearTimeout(timer);
-				stop?.removeEventListener("abort", onStop);
-				hold.abort();
-				resolve(described);
-			};
-			// Handled first, so a rejection after the wait ended is never left unhandled.
-			answer.then(end, () => end(messages().holdGeneric(tool)));
-			if (stop?.aborted) return end(STOPPED);
-			stop?.addEventListener("abort", onStop, { once: true });
-		});
+		return this.#inOrder(
+			joinApprovers(
+				described,
+				{
+					holds: this.#holds,
+					context: this.#context,
+					timeoutMs: this.#describeTimeoutMs,
+				},
+				tool,
+				input,
+				turn,
+			),
+			(judged) => {
+				if (judged === STOPPED) return STOPPED;
+				return judged ? this.#unlessApproved(tool, input, judged) : undefined;
+			},
+		);
 	}
 
 	/**
@@ -344,108 +424,76 @@ export class ConfirmationGate {
 		return used;
 	}
 
-	/** The call for `action`, unless an approval releases it, which that approval then spends. */
+	/**
+	 * The call for a description, unless an approval releases it, which that approval then spends
+	 * and whose approver the release names.
+	 */
 	#unlessApproved(
 		tool: string,
 		input: Record<string, unknown>,
-		action: string,
-	): HeldCall | undefined {
+		judged: { action: string; approvers?: readonly string[] },
+	): Needing {
 		const minTier = this.#holds.approvalTier?.(tool, input, this.#context);
 		const call: HeldCall = {
 			tool,
 			input: canonicalJson(input),
-			action,
+			action: judged.action,
 			...(minTier ? { minTier } : {}),
+			...(judged.approvers ? { approverIds: [...judged.approvers] } : {}),
 		};
 		for (const released of [this.#approved, this.#lateApproved]) {
 			const approved = released.findIndex(
-				(c) => c.tool === call.tool && c.input === call.input,
+				(r) => r.call.tool === call.tool && r.call.input === call.input,
 			);
-			if (approved !== -1) {
-				released.splice(approved, 1);
-				return undefined;
-			}
+			const [spent] = approved === -1 ? [] : released.splice(approved, 1);
+			if (spent) return { released: spent.by };
 		}
-		return call;
+		return { held: call };
 	}
 
+	/** Records the call as held and returns what the model is told about it. */
 	#record(call: HeldCall): string {
+		this.#remember(call);
+		const refusal = unlessNamed(
+			call,
+			this.#speaker,
+			this.#addressee,
+			this.#private,
+		);
+		return refusal ? refusal([], false) : askSpeaker(this.#addressee, call);
+	}
+
+	/**
+	 * `#record` for a call that names approvers the speaker is not among: the text then lists who
+	 * may approve it, which looks their names up first.
+	 */
+	async #held(call: HeldCall): Promise<string> {
+		this.#remember(call);
+		const refusal = unlessNamed(
+			call,
+			this.#speaker,
+			this.#addressee,
+			this.#private,
+		);
+		if (!refusal) return askSpeaker(this.#addressee, call);
+		const { names, missing } = await namesOf(
+			this.#nameOf,
+			call.approverIds ?? [],
+		);
+		return refusal(names, missing);
+	}
+
+	#remember(call: HeldCall): void {
 		const selectionId = this.#selectionId;
 		if (selectionId === undefined)
 			throw new Error("a call was held outside a turn");
-		const pending: PendingConfirmation = this.#pending ?? {
+		this.#pending = remembered(
+			this.#pending,
+			this.#kept,
 			selectionId,
-			heldAt: new Date(),
-			calls: [],
-			...(this.#speaker
-				? {
-						speakerId: this.#speaker.id,
-						principalId: this.#speaker.principalId,
-					}
-				: {}),
-		};
-		if (
-			!pending.calls.some((c) => c.tool === call.tool && c.input === call.input)
-		)
-			pending.calls.push(call);
-		this.#pending = pending;
-		const o = ownerWords(this.#addressee);
-		return `Held for ${o.name}'s confirmation: this would ${call.action}. Do not retry it in this turn. Tell ${o.him} exactly what will happen and ask ${o.him} to confirm; once ${o.he} agrees in ${o.his} next message, make the same call with the same input and it runs.`;
+			this.#speaker,
+			call,
+		);
+		this.#kept = undefined;
 	}
 }
-
-/** The owner's approving message, preceded by the held calls it releases, so the model makes them again. */
-export function confirmedTurnText(
-	pending: PendingConfirmation,
-	text: string,
-	owner: OwnerIdentity,
-): string {
-	const calls = pending.calls
-		.map((call) => `- ${call.action}: ${call.tool} ${call.input}`)
-		.join("\n");
-	return `(${owner.name} approved the held actions below with this message. Make each call now with exactly this input.)\n${calls}\n\n${text}`;
-}
-
-/**
- * Without a slot, or with an empty one, every call that needs confirmation is held. `turnOf` builds
- * the turn a hold that looks things up receives; without it, such a hold is not asked in a turn.
- */
-export function confirmationGateExtension(
-	gate: ConfirmationGate,
-	slot?: PromptSlot,
-	turnOf?: (signal: AbortSignal) => ToolTurn,
-): ExtensionFactory {
-	return (pi) => {
-		/** Calls a card's approval released, until their results are back. */
-		const approved = new Set<string>();
-		pi.on("tool_result", (event) => {
-			if (!approved.delete(event.toolCallId)) return undefined;
-			const outcome = event.isError
-				? "It was approved on its card and ran, but it failed:"
-				: "It was approved on its card and ran; its result follows.";
-			return {
-				content: [{ type: "text", text: outcome }, ...event.content],
-			};
-		});
-		pi.on("tool_call", async (event, ctx) => {
-			const prompts = slot?.prompts;
-			let ask: Parameters<ConfirmationGate["review"]>[2];
-			if (prompts && slot) {
-				ask = { prompts, asker: slot.asker };
-				if (ctx.signal) ask.signal = ctx.signal;
-			}
-			const turn: HoldTurn | undefined = turnOf
-				? { toolTurn: turnOf, ...(ctx.signal ? { signal: ctx.signal } : {}) }
-				: undefined;
-			const { reason, approvedOnCard, refused } = await gate.decide(
-				event.toolName,
-				event.input as Record<string, unknown>,
-				ask,
-				turn,
-			);
-			if (approvedOnCard) approved.add(event.toolCallId);
-			if (refused) slot?.refuse(event.toolCallId, refused);
-			return reason ? { block: true, reason } : undefined;
-		});
-	};
-}