pi-roundtable 0.14.1 → 0.15.0

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

@@ -11,38 +11,39 @@ import {
 	isPromise,
 } from "../../holds.ts";
 import { messages } from "../../i18n/index.ts";
-import { type OwnerIdentity, ownerWords } from "../../identity.ts";
+import type { OwnerIdentity } from "../../identity.ts";
 import type {
-	ApprovalOptions,
 	ApprovedBy,
 	LateAnswer,
 	Prompts,
 } from "../../interactions/prompts.ts";
 import type { ToolTiers } from "../../tool-tiers.ts";
 import { approvalCard, approvalDetails } from "./approval-card.ts";
+import { askOnCard } from "./card-ask.ts";
 import {
+	approverOf,
 	askSpeaker,
+	awaitingText,
+	declinedText,
 	type Needing,
 	namesOf,
 	type Release,
 	remembered,
 	type SpeakerRef,
 	unlessNamed,
+	withdrawn,
 } from "./gate-refusals.ts";
+import { type Grant, Grants } from "./grants.ts";
 import {
 	canonicalJson,
 	mayApproveNamed,
 	namedApprover,
+	sameCall,
 	unexpired,
 } from "./held-calls.ts";
-import {
-	awaited,
-	type Described,
-	type HoldTurn,
-	type Judgment,
-	joinApprovers,
-	STOPPED,
-} from "./hold-lookups.ts";
+import { HoldDescriber } from "./hold-describer.ts";
+import { type HoldTurn, type Judgment, STOPPED } from "./hold-lookups.ts";
+import { lateOutcome } from "./late-answer.ts";
 
 export { confirmationGateExtension } from "./confirmation-gate-extension.ts";
 export {
@@ -53,6 +54,9 @@ export {
 	namedApprover,
 	unexpired,
 } from "./held-calls.ts";
+
+import { type Watch, Withdrawals } from "./withdrawals.ts";
+
 export type { HoldTurn } from "./hold-lookups.ts";
 
 /**
@@ -73,8 +77,8 @@ export class ConfirmationGate {
 	#approved: Release[] = [];
 	/** Calls approved on their cards after the turn that asked stopped waiting; each runs once, in any turn. */
 	#lateApproved: Release[] = [];
-	/** Who approved each call that is running, by tool call id, until its result is back. */
-	readonly #approvers = new Map<string, ApprovedBy>();
+	/** Who approved each call that is running, and on which card, by tool call id, until its result is back. */
+	readonly #grants = new Grants();
 	readonly #holds: HoldCheck;
 	readonly #owner: OwnerIdentity;
 	/** Whom the running turn's held actions and refusals speak of: the turn's speaker. */
@@ -83,17 +87,21 @@ export class ConfirmationGate {
 	readonly #tiers: ToolTiers | undefined;
 	/** 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. */
-	#undescribed = 0;
+	/** Asks the holds to describe a call in a turn, and hands the answers on in the order they were asked. */
+	readonly #describer: HoldDescriber;
+	/** The held calls their plugins may still withdraw. */
+	readonly #withdrawals = new Withdrawals((call) => this.#forget(call));
+	/**
+	 * Called with the held actions that remain when a plugin's withdrawal removed one from them,
+	 * for whoever keeps them across a restart to keep the smaller set.
+	 */
+	onHeldChange: ((held: PendingConfirmation | undefined) => void) | undefined;
 
 	/**
 	 * `holds` decides which calls wait for the owner. With a workspace, the session has a shell,
@@ -114,7 +122,7 @@ export class ConfirmationGate {
 		describeTimeoutMs = HOLD_DESCRIBE_TIMEOUT_MS,
 		nameOf?: (principalId: string) => Promise<string | undefined>,
 	) {
-		this.#describeTimeoutMs = describeTimeoutMs;
+		this.#describer = new HoldDescriber(holds, context, describeTimeoutMs);
 		this.#nameOf = nameOf;
 		this.#tiers = tiers;
 		this.#fileRoot = fileRoot ?? context.workspace;
@@ -165,14 +173,7 @@ export class ConfirmationGate {
 		this.#speaker = speaker;
 		this.#private = isPrivate;
 		this.#addressee = addressee ?? this.#owner;
-		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 by = approverOf(speaker);
 		const held = this.pending();
 		const released = confirmed ? this.releasable(speaker) : undefined;
 		this.#approved = (released?.calls ?? []).map((call) => ({
@@ -186,38 +187,69 @@ export class ConfirmationGate {
 		this.#pending =
 			held && kept.length > 0 ? { ...held, calls: kept } : undefined;
 		this.#kept = this.#pending;
+		this.#sweep();
 	}
 
 	endTurn(): void {
 		this.#approved = [];
-		this.#approvers.clear();
+		this.#grants.clear();
+		this.#sweep();
 	}
 
-	/** 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 } : {}),
-		};
+	/** How many held calls a plugin may still withdraw. */
+	get watching(): number {
+		return this.#withdrawals.size;
+	}
+
+	/** Stops watching every call, for a gate that is dropped; a card still open is closed by its own surface. */
+	abandon(): void {
+		this.#withdrawals.clear();
+	}
+
+	/** Ends the watches of calls that nothing keeps and no card can answer. */
+	#sweep(): void {
+		const kept = (call: HeldCall) =>
+			(this.#pending?.calls.some((c) => sameCall(c, call)) ?? false) ||
+			[...this.#approved, ...this.#lateApproved].some((r) =>
+				sameCall(r.call, call),
+			);
+		this.#withdrawals.sweep(kept);
+	}
+
+	/** A plugin withdrew `call`: nothing that could run it stays, and what is held is kept anew. */
+	#forget(call: HeldCall): void {
+		const other = (r: { call: HeldCall }) => !sameCall(r.call, call);
+		this.#approved = this.#approved.filter(other);
+		this.#lateApproved = this.#lateApproved.filter(other);
+		const pending = this.#pending;
+		if (!pending?.calls.some((c) => sameCall(c, call))) return;
+		// In place, so a partial release's kept set stays the object `remembered` compares.
+		pending.calls = pending.calls.filter((c) => !sameCall(c, call));
+		if (pending.calls.length === 0) {
+			this.#pending = undefined;
+			if (this.#kept === pending) this.#kept = undefined;
+		}
+		this.onHeldChange?.(this.pending());
 	}
 
 	/** 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);
+		return this.#grants.get(toolCallId)?.by;
+	}
+
+	/** The id of the card that approved the call running under this tool call id; undefined when no card did. */
+	approvedPrompt(toolCallId: string): string | undefined {
+		return this.#grants.get(toolCallId)?.prompt;
 	}
 
-	/** 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);
+	/** Notes who approved the call running under a tool call id, and on which card, for its `run` to read. */
+	grant(toolCallId: string, grant: Grant): void {
+		this.#grants.set(toolCallId, grant);
 	}
 
 	/** Forgets who approved a tool call, once its result is back. */
 	finish(toolCallId: string): void {
-		this.#approvers.delete(toolCallId);
+		this.#grants.delete(toolCallId);
 	}
 
 	/** Returns the reason a call is held, or undefined to let it run. */
@@ -246,18 +278,22 @@ export class ConfirmationGate {
 	 * the card's own message is shown to the person, never to the model. When a hold refuses the
 	 * call, `refused` says how, for the turn's progress to report beside the failed result.
 	 * With `turn`, a hold that looks things up as the turn's speaker is waited for before any card
-	 * opens, and a turn that stops meanwhile opens none.
+	 * opens, and a turn that stops meanwhile opens none. The tool's JSON Schema, as `parameters`,
+	 * has the card show the call as fields.
 	 */
 	async decide(
 		tool: string,
 		input: Record<string, unknown>,
 		ask?: { prompts: Prompts; asker: string; signal?: AbortSignal },
 		turn?: HoldTurn,
+		parameters?: unknown,
 	): Promise<{
 		reason?: string;
 		approvedOnCard?: true;
 		/** Who approved the call, when it was held and a surface or a confirming message said who. */
 		approvedBy?: ApprovedBy;
+		/** The id of the card whose approval released the call, in this turn or answered late; absent for a call a message confirmed. */
+		approvedPrompt?: string;
 		/** 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;
 	}> {
@@ -265,77 +301,90 @@ export class ConfirmationGate {
 		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 } : {};
+		if ("released" in needing) {
+			const { by, prompt } = needing.released;
+			return {
+				...(by ? { approvedBy: by } : {}),
+				...(prompt ? { approvedPrompt: prompt } : {}),
+			};
+		}
 		const call = needing.held;
-		if (!ask) return { reason: await this.#held(call), refused: "held" };
+		const watch = needing.supersede
+			? this.#withdrawals.watch(call, needing.supersede)
+			: undefined;
+		if (watch?.withdrawn) return withdrawn(call);
+		/** Holds the call for a message, no card being open for it. */
+		const held = async (refused: "held" | "expired") => {
+			// A withdrawn call is never held again, whatever the card said last.
+			if (watch?.withdrawn) return withdrawn(call);
+			if (watch) watch.card = false;
+			return { reason: await this.#held(call), refused };
+		};
+		if (!ask) return held("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;
+			return held("held");
+		const { answer, approvedBy, approvedPrompt } = await askOnCard(
+			ask.prompts,
+			{
+				title: messages().confirmTitle(ask.asker),
+				message: approvalCard(call, this.#fileRoot, {}, parameters),
+				signal: ask.signal,
+				minTier: higherTier(this.#tiers?.minTier(call.tool), call.minTier),
+				wait: { late: (late) => this.#late(call, late, watch) },
+				details: approvalDetails(call, this.#fileRoot, needing.copy),
+				approvers: call.approverIds,
+				watch,
 			},
-		};
-		const answer = await ask.prompts.confirm(
-			messages().confirmTitle(ask.asker),
-			approvalCard(call, this.#fileRoot),
-			ask.signal,
-			higherTier(this.#tiers?.minTier(call.tool), call.minTier),
-			{ late: (late) => this.#late(call, late) },
-			approvalDetails(call, this.#fileRoot, needing.copy),
-			options,
 		);
+		// Whatever the card then reports, a call the plugin withdrew is refused, never held again.
+		if (answer === "withdrawn" || (watch?.withdrawn && answer !== "approved"))
+			return withdrawn(call);
 		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()
+					? approverOf(this.#speaker)
 					: 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 (!namedApprover(call, by)) return held("held");
+			watch?.end();
+			return {
+				approvedOnCard: true,
+				...(by ? { approvedBy: by } : {}),
+				...(approvedPrompt ? { approvedPrompt } : {}),
+			};
 		}
-		if (answer === "pending") {
-			const o = ownerWords(this.#addressee);
+		if (answer === "pending")
 			return {
-				reason: `Awaiting ${o.name}'s approval: this would ${call.action}. Its card stays open, and the call did not run. Do not retry it or ask again in this turn. End your turn now: say briefly that you are waiting for ${o.his} approval on the card. When ${o.he} answers, a new turn tells you.`,
+				reason: awaitingText(this.#addressee, call),
 				refused: "pending",
 			};
-		}
 		if (answer === "declined") {
-			const o = ownerWords(this.#addressee);
+			watch?.end();
 			return {
-				reason: `${o.name} declined this on its approval card: it would ${call.action}. Do not retry it; go on without it, or ask ${o.him} what ${o.he} wants instead.`,
+				reason: declinedText(this.#addressee, call),
 				refused: "declined",
 			};
 		}
-		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: await this.#held(call), refused: "held" };
-		return { reason: await this.#held(call), refused: "expired" };
+		if (answer === "cancelled") {
+			watch?.end();
+			return { reason: "The turn was stopped." };
+		}
+		// No card was shown, or it went unanswered: the call is held for a message, and stays withdrawable.
+		return held(answer === "unavailable" ? "held" : "expired");
 	}
 
-	/**
-	 * A late answer on a call's card: an approval lets the identical call run once, in whichever
-	 * turn makes it next; returns the text of the turn that tells the model.
-	 */
-	#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,
-			...(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}`;
+	/** A late answer on a call's card; see `lateOutcome`. Returns the text of the turn that tells the model. */
+	#late(
+		call: HeldCall,
+		late: LateAnswer,
+		watch: Watch | undefined,
+	): string | undefined {
+		const outcome = lateOutcome(call, late, watch);
+		if (outcome?.release) this.#lateApproved.push(outcome.release);
+		return outcome?.text;
 	}
 
 	/** What a call needs when a rule holds it; undefined when none does. */
@@ -358,71 +407,11 @@ export class ConfirmationGate {
 		| 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();
-		if (turn.signal?.aborted) controller.abort();
-		let answer: ReturnType<NonNullable<HoldCheck["inTurn"]>>;
-		try {
-			answer = inTurn.call(
-				this.#holds,
-				tool,
-				input,
-				this.#context,
-				turn.toolTurn(controller.signal),
-			);
-		} catch {
-			answer = messages().holdGeneric(tool);
-		}
-		const found: Described | Promise<Described> = isPromise(answer)
-			? awaited(
-					answer,
-					messages().holdGeneric(tool),
-					controller,
-					turn.signal,
-					this.#describeTimeoutMs,
-				)
-			: answer;
-		return this.#inOrder(
-			joinApprovers(
-				found,
-				{
-					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;
-			},
-		);
-	}
-
-	/**
-	 * Hands `described` to `use` after every description asked for before it has been used, so
-	 * calls made together are held, and their cards opened, in the order they were made whichever
-	 * description comes back first.
-	 */
-	#inOrder<T, R>(
-		described: T | Promise<T>,
-		use: (described: T) => R,
-	): R | Promise<R> {
-		if (this.#undescribed === 0 && !isPromise(described)) return use(described);
-		this.#undescribed++;
-		const used = this.#describing.then(() => described).then(use);
-		this.#describing = used.then(
-			() => {
-				this.#undescribed--;
-			},
-			() => {
-				this.#undescribed--;
-			},
-		);
-		return used;
+		if (!turn || !this.#holds.inTurn) return this.#needing(tool, input);
+		return this.#describer.describe(tool, input, turn, (judged) => {
+			if (judged === STOPPED) return STOPPED;
+			return judged ? this.#unlessApproved(tool, input, judged) : undefined;
+		});
 	}
 
 	/**
@@ -442,14 +431,22 @@ export class ConfirmationGate {
 			...(minTier ? { minTier } : {}),
 			...(judged.approvers ? { approverIds: [...judged.approvers] } : {}),
 		};
-		for (const released of [this.#approved, this.#lateApproved]) {
-			const approved = released.findIndex(
-				(r) => r.call.tool === call.tool && r.call.input === call.input,
-			);
+		// A plugin that already withdrew the call lets no approval of it release it.
+		for (const released of judged.supersede?.aborted
+			? []
+			: [this.#approved, this.#lateApproved]) {
+			const approved = released.findIndex((r) => sameCall(r.call, call));
 			const [spent] = approved === -1 ? [] : released.splice(approved, 1);
-			if (spent) return { released: spent.by };
+			if (spent) {
+				this.#withdrawals.endCall(spent.call);
+				return { released: spent };
+			}
 		}
-		return { held: call, ...(judged.copy ? { copy: judged.copy } : {}) };
+		return {
+			held: call,
+			...(judged.copy ? { copy: judged.copy } : {}),
+			...(judged.supersede ? { supersede: judged.supersede } : {}),
+		};
 	}
 
 	/** Records the call as held and returns what the model is told about it. */

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

@@ -23,12 +23,55 @@ export type SpeakerRef = Pick<Speaker, "id" | "principalId"> & {
 export interface Release {
 	call: HeldCall;
 	by?: ApprovedBy;
+	/** The id of the card whose approval released the call, when one did. */
+	prompt?: string;
 }
 
 /** What a call needs of the gate: nothing, a hold, or a release that spends an approval. */
 export type Needing =
-	| { held: HeldCall; copy?: NonNullable<ApprovalDetails["copy"]> }
-	| { released: ApprovedBy | undefined };
+	| {
+			held: HeldCall;
+			copy?: NonNullable<ApprovalDetails["copy"]>;
+			/** Aborts when the plugin withdraws the call; see `HoldDescription`. */
+			supersede?: AbortSignal;
+	  }
+	| { released: Release };
+
+/** A speaker as an approver; undefined without one. */
+export function approverOf(
+	speaker: SpeakerRef | undefined,
+): ApprovedBy | undefined {
+	if (!speaker) return undefined;
+	return {
+		principalId: speaker.principalId,
+		speakerId: speaker.id,
+		name: speaker.name ?? speaker.id,
+		...(speaker.tier === "owner" ? { owner: true as const } : {}),
+	};
+}
+
+/** What a turn waiting on a call its plugin withdrew is told: the call did not run and no approval will run it. */
+export function withdrawn(call: HeldCall): {
+	reason: string;
+	refused: "withdrawn";
+} {
+	return {
+		reason: `This action was withdrawn before it was approved: it would ${call.action}. It did not run, and an approval of it will not run it. Do not retry it; go on without it, or tell the owner it is no longer needed.`,
+		refused: "withdrawn",
+	};
+}
+
+/** What a turn is told when its card is left open and the call did not run. */
+export function awaitingText(addressee: OwnerIdentity, call: HeldCall): string {
+	const o = ownerWords(addressee);
+	return `Awaiting ${o.name}'s approval: this would ${call.action}. Its card stays open, and the call did not run. Do not retry it or ask again in this turn. End your turn now: say briefly that you are waiting for ${o.his} approval on the card. When ${o.he} answers, a new turn tells you.`;
+}
+
+/** What a turn is told when its call was declined on its card. */
+export function declinedText(addressee: OwnerIdentity, call: HeldCall): string {
+	const o = ownerWords(addressee);
+	return `${o.name} declined this on its approval card: it would ${call.action}. Do not retry it; go on without it, or ask ${o.him} what ${o.he} wants instead.`;
+}
 
 /** The text for a held call that the speaker's own message confirms. */
 export function askSpeaker(addressee: OwnerIdentity, call: HeldCall): string {

package/src/core/runtime/extensions/grants.ts

@@ -0,0 +1,30 @@
+import type { ApprovedBy } from "../../interactions/prompts.ts";
+
+/** What a tool's `run` is told about the approval that released its call. */
+export interface Grant {
+	/** Who approved it, when a surface or a confirming message said who. */
+	by?: ApprovedBy;
+	/** The id of the card that approved it; absent when no card did. */
+	prompt?: string;
+}
+
+/** The approvals of the calls that are running, by tool call id, until each result is back. */
+export class Grants {
+	readonly #grants = new Map<string, Grant>();
+
+	get(toolCallId: string): Grant | undefined {
+		return this.#grants.get(toolCallId);
+	}
+
+	set(toolCallId: string, grant: Grant): void {
+		this.#grants.set(toolCallId, grant);
+	}
+
+	delete(toolCallId: string): void {
+		this.#grants.delete(toolCallId);
+	}
+
+	clear(): void {
+		this.#grants.clear();
+	}
+}

package/src/core/runtime/extensions/held-calls.ts

@@ -20,6 +20,14 @@ export function unexpired(
 		: pending;
 }
 
+/** Whether two held calls are the same call: the same tool with the same canonical input. */
+export function sameCall(
+	a: Pick<HeldCall, "tool" | "input">,
+	b: Pick<HeldCall, "tool" | "input">,
+): boolean {
+	return a.tool === b.tool && a.input === b.input;
+}
+
 /** 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 {

package/src/core/runtime/extensions/hold-describer.ts

@@ -0,0 +1,99 @@
+import { type HoldCheck, type HoldContext, isPromise } from "../../holds.ts";
+import { messages } from "../../i18n/index.ts";
+import {
+	awaited,
+	type Described,
+	type HoldTurn,
+	type Judged,
+	joinApprovers,
+} from "./hold-lookups.ts";
+
+/**
+ * Asks a conversation's holds to describe a call a turn makes, and hands each description on in
+ * the order the calls were made, whichever comes back first, so calls made together are held,
+ * and their cards opened, in that order.
+ */
+export class HoldDescriber {
+	readonly #holds: HoldCheck;
+	readonly #context: HoldContext;
+	readonly #timeoutMs: number;
+	/** 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. */
+	#undescribed = 0;
+
+	/** A hold that looks things up gets `timeoutMs` to answer before its call is held under a generic description. */
+	constructor(holds: HoldCheck, context: HoldContext, timeoutMs: number) {
+		this.#holds = holds;
+		this.#context = context;
+		this.#timeoutMs = timeoutMs;
+	}
+
+	/**
+	 * The call's description with the approvers the holds name, handed to `use` when every
+	 * description asked for before it has been used; at once when none is outstanding and the
+	 * holds answered at once. The holds must have an `inTurn` check.
+	 */
+	describe<R>(
+		tool: string,
+		input: Record<string, unknown>,
+		turn: HoldTurn,
+		use: (judged: Judged) => R,
+	): R | Promise<R> {
+		const controller = new AbortController();
+		if (turn.signal?.aborted) controller.abort();
+		let answer: ReturnType<NonNullable<HoldCheck["inTurn"]>>;
+		try {
+			answer = this.#holds.inTurn?.call(
+				this.#holds,
+				tool,
+				input,
+				this.#context,
+				turn.toolTurn(controller.signal),
+			);
+		} catch {
+			answer = messages().holdGeneric(tool);
+		}
+		const found: Described | Promise<Described> = isPromise(answer)
+			? awaited(
+					answer,
+					messages().holdGeneric(tool),
+					controller,
+					turn.signal,
+					this.#timeoutMs,
+				)
+			: answer;
+		return this.#inOrder(
+			joinApprovers(
+				found,
+				{
+					holds: this.#holds,
+					context: this.#context,
+					timeoutMs: this.#timeoutMs,
+				},
+				tool,
+				input,
+				turn,
+			),
+			use,
+		);
+	}
+
+	#inOrder<T, R>(
+		described: T | Promise<T>,
+		use: (described: T) => R,
+	): R | Promise<R> {
+		if (this.#undescribed === 0 && !isPromise(described)) return use(described);
+		this.#undescribed++;
+		const used = this.#describing.then(() => described).then(use);
+		this.#describing = used.then(
+			() => {
+				this.#undescribed--;
+			},
+			() => {
+				this.#undescribed--;
+			},
+		);
+		return used;
+	}
+}