pi-roundtable 0.14.0 → 0.15.0

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

@@ -29,37 +29,52 @@ export type Described = HoldDescription | undefined | typeof STOPPED;
 export interface Judgment {
 	action: string;
 	copy?: NonNullable<ApprovalDetails["copy"]>;
+	/** Aborts when the plugin withdraws the call; see `HoldDescription`. */
+	supersede?: AbortSignal;
 	approvers?: readonly string[];
 }
 
 export type Judged = Judgment | undefined | typeof STOPPED;
 
+/** Whether `value` is an abort signal, however it was made; anything else a hold answers is ignored. */
+function isSignal(value: unknown): value is AbortSignal {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		typeof (value as AbortSignal).aborted === "boolean" &&
+		typeof (value as AbortSignal).addEventListener === "function"
+	);
+}
+
 /**
- * A hold's description as the action and the copy it carries. An answer that is neither a text
- * nor a text with a copy still holds the call, under the generic description; a copy that is not
- * a non-empty text is left out, so a hold that gets it wrong never lets the call run.
+ * A hold's description as the action, the copy and the `supersede` signal it carries. An answer
+ * that is neither a text nor a text with a copy still holds the call, under the generic
+ * description; a copy that is not a non-empty text and a `supersede` that is not a signal are
+ * left out, so a hold that gets them wrong never lets the call run.
  */
 export function described(
 	answer: HoldDescription,
 	tool: string,
-): { action: string; copy?: NonNullable<ApprovalDetails["copy"]> } {
+): Pick<Judgment, "action" | "copy" | "supersede"> {
 	if (typeof answer === "string") return { action: answer };
 	if (typeof answer !== "object" || answer === null)
 		return { action: messages().holdGeneric(tool) };
-	const { text, copy } = answer;
+	const { text, copy, supersede } = answer;
 	if (typeof text !== "string") return { action: messages().holdGeneric(tool) };
+	const withdrawal = isSignal(supersede) ? { supersede } : {};
 	if (
 		!copy ||
 		typeof copy !== "object" ||
 		typeof copy.text !== "string" ||
 		copy.text === ""
 	)
-		return { action: text };
+		return { action: text, ...withdrawal };
 	const label = typeof copy.label === "string" ? copy.label : undefined;
 	return {
 		action: text,
 		copy:
 			label === undefined ? { text: copy.text } : { label, text: copy.text },
+		...withdrawal,
 	};
 }
 
@@ -110,7 +125,7 @@ export function joinApprovers(
 	if (!lookup) return withoutApprovers(answer, tool);
 	const join = (action: Described): Judged | Promise<Judged> => {
 		if (action === STOPPED || action === undefined) return action;
-		const { action: text, copy } = described(action, tool);
+		const { action: text, copy, supersede } = described(action, tool);
 		const controller = new AbortController();
 		if (turn.signal?.aborted) controller.abort();
 		let named:
@@ -133,6 +148,7 @@ export function joinApprovers(
 			return {
 				action: text,
 				...(copy ? { copy } : {}),
+				...(supersede ? { supersede } : {}),
 				...(named ? { approvers: named } : {}),
 			};
 		}
@@ -142,6 +158,7 @@ export function joinApprovers(
 				return {
 					action: text,
 					...(copy ? { copy } : {}),
+					...(supersede ? { supersede } : {}),
 					...(approvers ? { approvers } : {}),
 				};
 			},

package/src/core/runtime/extensions/late-answer.ts

@@ -0,0 +1,36 @@
+import type { HeldCall } from "../../domain/conversation.ts";
+import type { LateAnswer } from "../../interactions/prompts.ts";
+import type { Release } from "./gate-refusals.ts";
+import { namedApprover } from "./held-calls.ts";
+import type { Watch } from "./withdrawals.ts";
+
+/**
+ * What a card answered after its turn stopped waiting comes to: the text of the turn that tells
+ * the model, and, for an approval that stands, the release that lets the identical call run once
+ * in whichever turn makes it next. Undefined when the answer changes nothing: a question's, a
+ * card its plugin withdrew, or an approval by someone the call does not name.
+ */
+export function lateOutcome(
+	call: HeldCall,
+	late: LateAnswer,
+	watch: Watch | undefined,
+): { text: string; release?: Release } | undefined {
+	// A card the plugin withdrew answers nothing, whatever a surface that kept it open reports.
+	if (watch?.withdrawn || late.kind !== "approval") return undefined;
+	if (watch) watch.card = false;
+	if (late.approved && !namedApprover(call, late.approvedBy)) return undefined;
+	if (!late.approved) {
+		watch?.end();
+		return {
+			text: `(${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.)`,
+		};
+	}
+	return {
+		text: `(${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}`,
+		release: {
+			call,
+			...(late.approvedBy ? { by: late.approvedBy } : {}),
+			...(late.prompt ? { prompt: late.prompt } : {}),
+		},
+	};
+}

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

@@ -0,0 +1,95 @@
+import type { HeldCall } from "../../domain/conversation.ts";
+
+/**
+ * One held call whose plugin may withdraw it (`HoldDescription.supersede`), for as long as the
+ * call can still run: while its card is open or answered late, while it waits for a message that
+ * confirms it, and while an approval waits for the call to be made.
+ */
+export interface Watch {
+	readonly call: HeldCall;
+	/** The plugin's signal, which the card of the call is given to close by. */
+	readonly signal: AbortSignal;
+	/** Whether the plugin withdrew the call; the call was forgotten when this turned true. */
+	readonly withdrawn: boolean;
+	/** Settles once the plugin withdraws the call, never otherwise. */
+	readonly whenWithdrawn: Promise<"withdrawn">;
+	/** Whether a card of the call can still be answered; a watch without one lasts as long as the call is kept. */
+	card: boolean;
+	/** Stops watching: the call ran, was refused, or is no longer kept. Does nothing after a withdrawal. */
+	end(): void;
+}
+
+/**
+ * The calls a conversation's gate holds that their plugins may withdraw. Withdrawing is the one
+ * transition a call makes from "may run" to "may not", taken by whichever of the plugin's abort
+ * and the call's release (an approval spending it) comes first; a watch that ended or withdrew
+ * is gone from here, so nothing is kept for a call that can no longer be withdrawn.
+ */
+export class Withdrawals {
+	readonly #watches = new Set<Watch>();
+	readonly #forget: (call: HeldCall) => void;
+
+	/** `forget` drops a withdrawn call from everything that could still run it. */
+	constructor(forget: (call: HeldCall) => void) {
+		this.#forget = forget;
+	}
+
+	/** How many calls are watched now. */
+	get size(): number {
+		return this.#watches.size;
+	}
+
+	/**
+	 * Watches `call` for `signal`. A signal that is already aborted withdraws it at once: the
+	 * returned watch is `withdrawn`, and the call is forgotten.
+	 */
+	watch(call: HeldCall, signal: AbortSignal): Watch {
+		let withdrawn = false;
+		let resolve: (value: "withdrawn") => void = () => {};
+		const whenWithdrawn = new Promise<"withdrawn">((done) => {
+			resolve = done;
+		});
+		const watches = this.#watches;
+		const forget = this.#forget;
+		const withdraw = () => {
+			if (withdrawn || !watches.delete(watch)) return;
+			withdrawn = true;
+			forget(call);
+			resolve("withdrawn");
+		};
+		const watch: Watch = {
+			call,
+			signal,
+			get withdrawn() {
+				return withdrawn;
+			},
+			whenWithdrawn,
+			card: true,
+			end() {
+				if (!watches.delete(watch)) return;
+				signal.removeEventListener("abort", withdraw);
+			},
+		};
+		watches.add(watch);
+		if (signal.aborted) withdraw();
+		else signal.addEventListener("abort", withdraw, { once: true });
+		return watch;
+	}
+
+	/** Ends the watches of `call`, which was released or refused: the same object, as the gate holds it. */
+	endCall(call: HeldCall): void {
+		for (const watch of [...this.#watches])
+			if (watch.call === call) watch.end();
+	}
+
+	/** Ends every watch, for a gate that is dropped. */
+	clear(): void {
+		for (const watch of [...this.#watches]) watch.end();
+	}
+
+	/** Ends the watches whose call is no longer kept (`kept`) and whose card is closed. */
+	sweep(kept: (call: HeldCall) => boolean): void {
+		for (const watch of [...this.#watches])
+			if (!watch.card && !kept(watch.call)) watch.end();
+	}
+}

package/src/core/runtime/session-factory.ts

@@ -371,6 +371,7 @@ export class SessionFactory {
 			speaker: () => this.#deps.speaker(turnKey),
 			origin: () => this.#deps.origin(turnKey),
 			approvedBy: (toolCallId) => gate.approvedBy(toolCallId),
+			approvedPrompt: (toolCallId) => gate.approvedPrompt(toolCallId),
 			client: () => this.#deps.client(turnKey),
 			runTask: (task) =>
 				this.#deps.runTask({ turn: turnKey, home: channel }, task),

package/src/core/sessions.ts

@@ -106,6 +106,12 @@ export interface SessionContext {
 	 * this method has none, which reads as undefined.
 	 */
 	approvedBy?(toolCallId: string): ApprovedBy | undefined;
+	/**
+	 * The id of the card whose approval released the held call whose tool call has this id, while it
+	 * runs; undefined for a call no card approved. A context built before this method has none,
+	 * which reads as undefined.
+	 */
+	approvedPrompt?(toolCallId: string): string | undefined;
 	/**
 	 * What the client that started the running turn can do for its tools, as `TurnRequest.client`
 	 * says; undefined between turns and for a turn whose transport gives none. A context built

package/src/core/testing/surface-contract.ts

@@ -264,6 +264,75 @@ const CHECKS: readonly Check[] = [
 			);
 		},
 	},
+	{
+		name: "an approval its plugin withdraws resolves cancelled and closes; one answered first stays answered",
+		applies: (subject) =>
+			subject.surface.prompts !== undefined && subject.answer !== undefined,
+		run: async (running) => {
+			const { surface, channel, answer } = running.subject;
+			const prompts = surface.prompts?.(channel, scopeOf(running.subject));
+			if (!prompts || !answer)
+				throw new ContractBroken("the surface shows no prompts");
+			const ask = (supersede: AbortSignal) =>
+				prompts.confirm(
+					"Approve?",
+					"Send it.",
+					undefined,
+					speakerOf(running.subject).tier,
+					undefined,
+					undefined,
+					{ supersede },
+				);
+			const closes = (id: string) =>
+				seen(running, "prompt_closed").filter(
+					(o) => o.kind === "prompt_closed" && o.id === id,
+				).length;
+			const withdrawn = new AbortController();
+			let before = seen(running, "prompt").length;
+			const first = ask(withdrawn.signal);
+			const firstId = await nextPrompt(running, before);
+			withdrawn.abort("replaced by a newer request");
+			const result = await Promise.race([
+				first,
+				Bun.sleep(1000).then(() => "still open" as const),
+			]);
+			expectThat(
+				result === "cancelled",
+				`a withdrawn approval answered ${result}`,
+			);
+			await until(() => closes(firstId) > 0, "the withdrawn approval closes");
+			// An answer to the closed approval changes nothing, as for any ended prompt.
+			await answer(firstId, true).catch(() => undefined);
+			expectThat(closes(firstId) === 1, "the withdrawn approval closed twice");
+			// An approval answered before the withdrawal stays answered.
+			const later = new AbortController();
+			before = seen(running, "prompt").length;
+			const second = ask(later.signal);
+			const secondId = await nextPrompt(running, before);
+			await answer(secondId, true);
+			later.abort();
+			const approved: Approval = await second;
+			expectThat(
+				approved === "approved",
+				`an answered approval came back ${approved}`,
+			);
+			await Bun.sleep(20);
+			expectThat(closes(secondId) === 1, "the answered approval closed twice");
+			// A signal that is already aborted shows nothing.
+			const gone = new AbortController();
+			gone.abort();
+			before = seen(running, "prompt").length;
+			const none: Approval = await ask(gone.signal);
+			expectThat(
+				none === "cancelled",
+				`an approval withdrawn before it opened came back ${none}`,
+			);
+			expectThat(
+				seen(running, "prompt").length === before,
+				"a withdrawn approval was shown",
+			);
+		},
+	},
 	{
 		name: "another person cannot answer the person's approval",
 		applies: (subject) =>
@@ -374,7 +443,8 @@ export async function checkSurfaceContract(
  * Registers the chat surface contract as one test per check, under `name`: the surface names a
  * prefix and owns its channel, delivers what its person writes, shows every chunk of a reply, and,
  * where it offers them, delivers files, ends typing and stop controls idempotently, shows
- * progress, resolves approvals as the person answers or as a stopped turn cancels them, ignores
+ * progress, resolves approvals as the person answers or as a stopped turn cancels them, closes
+ * one its plugin withdraws (`ApprovalOptions.supersede`) as cancelled, ignores
  * another person's answer to the person's approval, and, in a private conversation, an owner's
  * too, and lets an approval above the person's tier there come back at once, shown to no one.
  * Where it can name approvers, an approval that does is answered by them, reported as the

package/src/core/tool-turn.ts

@@ -41,6 +41,8 @@ export function toolTurn(
 	const origin = context.origin?.();
 	const approvedBy =
 		toolCallId === undefined ? undefined : context.approvedBy?.(toolCallId);
+	const approvedPrompt =
+		toolCallId === undefined ? undefined : context.approvedPrompt?.(toolCallId);
 	const client = context.client?.();
 	return {
 		speaker: context.speaker(),
@@ -49,6 +51,7 @@ export function toolTurn(
 		signal,
 		...(origin === undefined ? {} : { origin }),
 		...(approvedBy === undefined ? {} : { approvedBy }),
+		...(approvedPrompt === undefined ? {} : { approvedPrompt }),
 		...(client === undefined ? {} : { client: clientIn(client, signal) }),
 		...(context.workspace ? { workspace: context.workspace } : {}),
 		attachFile: attachReplyFile,

package/src/index.ts

@@ -202,7 +202,7 @@ export type {
 	Prompts,
 	PromptWait,
 } from "./core/interactions/prompts.ts";
-export { promptScope } from "./core/interactions/prompts.ts";
+export { promptScope, withdrawalNote } from "./core/interactions/prompts.ts";
 export type { JudgeModel } from "./core/judging/model-judge.ts";
 export type { LogEntry, LogFn, Logger } from "./core/log.ts";
 export type { ThinkingLevel, ThinkingSetting } from "./core/models.ts";