pi-roundtable 0.9.12 → 0.10.0

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

@@ -0,0 +1,133 @@
+import type {
+	HeldCall,
+	PendingConfirmation,
+} from "../../domain/conversation.ts";
+import { type OwnerIdentity, ownerWords } from "../../identity.ts";
+import type { ApprovedBy } from "../../interactions/prompts.ts";
+import type { Speaker } from "../../speakers.ts";
+import { mayApproveNamed } from "./held-calls.ts";
+
+/**
+ * The speaker of a turn as the gate records them; `name` is what an approval by their message is
+ * attributed to, and `tier` tells whether they approve as an owner.
+ */
+export type SpeakerRef = Pick<Speaker, "id" | "principalId"> & {
+	name?: string;
+	tier?: Speaker["tier"];
+};
+
+/** A call an approval released, and who gave it, when that is known. */
+export interface Release {
+	call: HeldCall;
+	by?: ApprovedBy;
+}
+
+/** What a call needs of the gate: nothing, a hold, or a release that spends an approval. */
+export type Needing = { held: HeldCall } | { released: ApprovedBy | undefined };
+
+/** The text for a held call that the speaker's own message confirms. */
+export function askSpeaker(addressee: OwnerIdentity, call: HeldCall): string {
+	const o = ownerWords(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.`;
+}
+
+/**
+ * For a call that names approvers the speaker is neither among nor an owner of: the text that
+ * tells the model the truth about it, from the names of those who may approve; undefined when
+ * the speaker may.
+ */
+export function unlessNamed(
+	call: HeldCall,
+	speaker: SpeakerRef | undefined,
+	addressee: OwnerIdentity,
+	isPrivate: boolean,
+): ((names: string[], missing: boolean) => string) | undefined {
+	if (!call.approverIds || mayApproveNamed(speaker, call)) return undefined;
+	const o = ownerWords(addressee);
+	const anyone = (call.approverIds?.length ?? 0) > 0;
+	return (names, missing) => {
+		// Names that could not be read still leave the people the tool named.
+		const named =
+			names.length === 0 && anyone
+				? ["the people named for it"]
+				: missing
+					? [...names, "others named for it"]
+					: names;
+		const who = orList([...named, "an owner"]);
+		const approval = `Only ${who} can approve it.`;
+		if (isPrivate)
+			return `Held, and ${o.name} cannot approve it here: this would ${call.action}. ${approval} A private conversation can only be answered by its person, so it stays held and nothing ${o.he} says here releases it. Do not retry it, and do not ask ${o.him} to confirm it or to say yes. Tell ${o.him} plainly that it was not done and needs ${who}.`;
+		return `Held, and ${o.name} cannot approve it: this would ${call.action}. ${approval} Do not retry it in this turn, and do not ask ${o.name} to confirm it. Tell ${o.him} plainly that it was not done, and ask ${who} to confirm in this channel; once one of them agrees in a message, make the same call with the same input and it runs.`;
+	};
+}
+
+/** The names of the principals, as far as they are known; ids are never shown. `missing` says some could not be read. */
+export async function namesOf(
+	nameOf: ((principalId: string) => Promise<string | undefined>) | undefined,
+	principalIds: readonly string[],
+): Promise<{ names: string[]; missing: boolean }> {
+	if (!nameOf) return { names: [], missing: principalIds.length > 0 };
+	const names = await Promise.all(
+		[...new Set(principalIds)].map(async (id) => {
+			try {
+				return await nameOf(id);
+			} catch {
+				return undefined;
+			}
+		}),
+	);
+	return {
+		names: [...new Set(names.filter((name): name is string => !!name))],
+		missing: names.some((name) => !name),
+	};
+}
+
+/**
+ * The pending hold with `call` added: a partial release kept calls that name approvers, which
+ * belong to no speaker, so what this turn holds is its speaker's from now.
+ */
+export function remembered(
+	current: PendingConfirmation | undefined,
+	kept: PendingConfirmation | undefined,
+	selectionId: string,
+	speaker: SpeakerRef | undefined,
+	call: HeldCall,
+): PendingConfirmation {
+	// A partial release kept calls that name approvers, which belong to no speaker: what this turn
+	// holds is its speaker's, from now.
+	let pending = current;
+	if (pending && pending === kept) {
+		pending = { ...pending, calls: [...pending.calls] };
+		pending.selectionId = selectionId;
+		pending.heldAt = new Date();
+		delete pending.speakerId;
+		delete pending.principalId;
+		if (speaker) {
+			pending.speakerId = speaker.id;
+			pending.principalId = speaker.principalId;
+		}
+	}
+	pending ??= {
+		selectionId,
+		heldAt: new Date(),
+		calls: [],
+		...(speaker
+			? {
+					speakerId: speaker.id,
+					principalId: speaker.principalId,
+				}
+			: {}),
+	};
+	if (
+		!pending.calls.some((c) => c.tool === call.tool && c.input === call.input)
+	)
+		pending.calls.push(call);
+	return pending;
+}
+
+/** "a", "a or b", "a, b or c". */
+function orList(items: readonly string[]): string {
+	const last = items.at(-1);
+	if (items.length < 2 || last === undefined) return items.join("");
+	return `${items.slice(0, -1).join(", ")} or ${last}`;
+}

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

@@ -0,0 +1,91 @@
+import type {
+	HeldCall,
+	PendingConfirmation,
+} from "../../domain/conversation.ts";
+import type { OwnerIdentity } from "../../identity.ts";
+import type { ApprovedBy } from "../../interactions/prompts.ts";
+import type { Speaker } from "../../speakers.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;
+}
+
+/** 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;
+}
+
+/** 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}`;
+}
+
+/**
+ * Whether a call's `approverIds` leave the person free to approve it: always, for a call that names
+ * none, since whoever asked decides who the person is; for one that does, only an owner or a named
+ * principal. Nobody known, such as a turn without a speaker, may approve a call that names approvers.
+ */
+export function mayApproveNamed(
+	person:
+		| (Pick<Speaker, "principalId"> & { tier?: Speaker["tier"] })
+		| undefined,
+	call: Pick<HeldCall, "approverIds">,
+): boolean {
+	if (!call.approverIds) return true;
+	return (
+		person !== undefined &&
+		(person.tier === "owner" || call.approverIds.includes(person.principalId))
+	);
+}
+
+/** Whether an approval reported for a call is one its `approverIds` accept: from a named principal or an owner. */
+export function namedApprover(
+	call: Pick<HeldCall, "approverIds">,
+	by: ApprovedBy | undefined,
+): boolean {
+	if (!call.approverIds) return true;
+	return (
+		by !== undefined &&
+		(by.owner === true || call.approverIds.includes(by.principalId))
+	);
+}

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

@@ -0,0 +1,108 @@
+import type { ToolTurn } from "../../define.ts";
+import { type HoldCheck, type HoldContext, isPromise } from "../../holds.ts";
+
+/** 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. */
+export const STOPPED = Symbol("stopped");
+
+/** What waiting for a call's description comes to: its text, or the turn stopped first. */
+export type Described = string | undefined | typeof STOPPED;
+
+/** A held call's description with who may approve it instead of the speaker; see `HoldRule.approversInTurn`. */
+export type Judged =
+	| { action: string; approvers?: readonly string[] }
+	| undefined
+	| typeof STOPPED;
+
+/**
+ * What a lookup that answers later comes to: its answer; `fallback` when it rejects or outlasts
+ * `timeoutMs`; `STOPPED` when the turn stops first. Whatever the lookup is still doing is
+ * aborted when the wait ends.
+ */
+export function awaited<T>(
+	answer: Promise<T>,
+	fallback: T,
+	lookup: AbortController,
+	stop: AbortSignal | undefined,
+	timeoutMs: number,
+): Promise<T | typeof STOPPED> {
+	return new Promise((resolve) => {
+		const onStop = () => end(STOPPED);
+		const timer = setTimeout(() => end(fallback), timeoutMs);
+		let ended = false;
+		const end = (found: T | typeof STOPPED) => {
+			if (ended) return;
+			ended = true;
+			clearTimeout(timer);
+			stop?.removeEventListener("abort", onStop);
+			lookup.abort();
+			resolve(found);
+		};
+		// Handled first, so a rejection after the wait ended is never left unhandled.
+		answer.then(end, () => end(fallback));
+		if (stop?.aborted) return end(STOPPED);
+		stop?.addEventListener("abort", onStop, { once: true });
+	});
+}
+
+/**
+ * A description joined by the approvers the holds name for a call they hold, looked up as the
+ * turn with the same wait as the description; a lookup that rejects or outlasts the timeout names
+ * none, so only the owners approve the call. A call no rule holds asks no one.
+ */
+export function joinApprovers(
+	described: Described | Promise<Described>,
+	from: { holds: HoldCheck; context: HoldContext; timeoutMs: number },
+	tool: string,
+	input: Record<string, unknown>,
+	turn: HoldTurn,
+): Judged | Promise<Judged> {
+	const lookup = from.holds.approversInTurn;
+	if (!lookup) return withoutApprovers(described);
+	const join = (action: Described): Judged | Promise<Judged> => {
+		if (action === STOPPED || action === undefined) return action;
+		const controller = new AbortController();
+		if (turn.signal?.aborted) controller.abort();
+		let named:
+			| readonly string[]
+			| undefined
+			| Promise<readonly string[] | undefined>;
+		try {
+			named = lookup.call(
+				from.holds,
+				tool,
+				input,
+				from.context,
+				turn.toolTurn(controller.signal),
+			);
+		} catch {
+			named = [];
+		}
+		if (!isPromise(named)) {
+			controller.abort();
+			return named ? { action, approvers: named } : { action };
+		}
+		return awaited(named, [], controller, turn.signal, from.timeoutMs).then(
+			(approvers) => {
+				if (approvers === STOPPED) return STOPPED;
+				return approvers ? { action, approvers } : { action };
+			},
+		);
+	};
+	return isPromise(described) ? described.then(join) : join(described);
+}
+
+function withoutApprovers(
+	described: Described | Promise<Described>,
+): Judged | Promise<Judged> {
+	const wrap = (action: Described): Judged =>
+		action === STOPPED || action === undefined ? action : { action };
+	return isPromise(described) ? described.then(wrap) : wrap(described);
+}

package/src/core/runtime/pi-agent-runtime.ts

@@ -160,7 +160,10 @@ export class PiAgentRuntime implements AgentRuntime {
 		);
 		if (session.thinkingLevel !== level) session.setThinkingLevel(level);
 		const gate = await this.#sessions.gate(key, request.agent !== undefined);
-		const pending = gate.pending();
+		// What this turn's message may release: a held call that named approvers is theirs alone.
+		const pending = request.confirmed
+			? gate.releasable(request.speaker)
+			: gate.pending();
 		const registered = new Set(session.getAllTools().map((tool) => tool.name));
 		// The speaker's tier limits the tools.
 		const { tier } = request.speaker;
@@ -216,8 +219,9 @@ export class PiAgentRuntime implements AgentRuntime {
 			request.confirmed === true,
 			who,
 			request.speaker,
+			conversation.visibility === "private",
 		);
-		if (request.confirmed && pending) {
+		if (request.confirmed && pending && pending.calls.length > 0) {
 			logger.info(
 				{
 					channel: request.channel,
@@ -287,7 +291,7 @@ export class PiAgentRuntime implements AgentRuntime {
 		try {
 			const attachments = request.attachments ?? NO_ATTACHMENTS;
 			const text =
-				request.confirmed && pending
+				request.confirmed && pending && pending.calls.length > 0
 					? confirmedTurnText(pending, request.text, who)
 					: request.text;
 			const prompted = running.run(() =>

package/src/core/runtime/prompt-slot.ts

@@ -61,9 +61,17 @@ export class PromptSlot {
 		const prompts = this.#prompts;
 		if (!prompts) return undefined;
 		return {
-			confirm: (title, message, signal, minTier, wait, details) =>
+			confirm: (title, message, signal, minTier, wait, details, options) =>
 				this.#waiting(() =>
-					prompts.confirm(title, message, signal, minTier, wait, details),
+					prompts.confirm(
+						title,
+						message,
+						signal,
+						minTier,
+						wait,
+						details,
+						options,
+					),
 				),
 			ask: (title, question: OwnerQuestion, signal, wait) =>
 				this.#waiting(() => prompts.ask(title, question, signal, wait)),

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

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

package/src/core/services.ts

@@ -10,6 +10,7 @@ import { type ServiceKey, serviceKey } from "./contract/services.ts";
 import type { ConversationRegistry } from "./conversations/conversation-registry.ts";
 import type { PendingConfirmation } from "./domain/conversation.ts";
 import type { HttpRoute } from "./http/listeners.ts";
+import type { IdentityLinks } from "./identity/identity-links.ts";
 import type { IdentityService } from "./identity/identity-service.ts";
 import type { ThinkingSetting } from "./models.ts";
 import type {
@@ -46,6 +47,16 @@ import type { AgentTurnScope, ChannelKey } from "./sessions.ts";
  */
 export const IDENTITY: ServiceKey<IdentityService> =
 	serviceKey<IdentityService>("roundtable.identity");
+/**
+ * Links a person's own account to their principal, which `IDENTITY` cannot. Provided by the
+ * `identity` plugin only when the configuration lists providers in `access.selfLink`; read it with
+ * `find` when your plugin works without it, and with `get` when it cannot.
+ */
+export const IDENTITY_LINKS: ServiceKey<IdentityLinks> =
+	serviceKey<IdentityLinks>("roundtable.identity-links", {
+		absent:
+			'Self-linking is switched off. List the providers people may link in the configuration, such as access: { selfLink: { providers: ["discord"] } }.',
+	});
 /**
  * The runtime every conversation turn runs on: the agent server's, and each turn run through
  * `context.turns`. The `runtime` provider slot's when a plugin fills it, Pi's otherwise. Provided

package/src/core/sessions.ts

@@ -3,6 +3,7 @@ import type { ClientPort } from "./domain/client.ts";
 import { PluginError } from "./errors.ts";
 import type { Principal } from "./identity/principal-store.ts";
 import type { OwnerIdentity } from "./identity.ts";
+import type { ApprovedBy } from "./interactions/prompts.ts";
 import type { Speaker } from "./speakers.ts";
 
 /** `<surface>:<channel id>`, for example `discord:1234`. A DM is one channel. */
@@ -99,6 +100,12 @@ export interface SessionContext {
 	 * method, which reads as undefined.
 	 */
 	origin?(): string | undefined;
+	/**
+	 * Who approved the held call whose tool call has this id, while it runs; undefined for a call
+	 * that ran without a hold or whose approver the surface did not name. A context built before
+	 * this method has none, which reads as undefined.
+	 */
+	approvedBy?(toolCallId: string): ApprovedBy | 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-support.ts

@@ -0,0 +1,194 @@
+import type { InboundMessage } from "../contract/channels.ts";
+import {
+	type Approval,
+	type ApprovedBy,
+	type PromptScope,
+	promptScope,
+} from "../interactions/prompts.ts";
+import type { Speaker } from "../speakers.ts";
+import type {
+	SurfaceContractAnswerer,
+	SurfaceContractSubject,
+	SurfaceObservation,
+} from "./surface-contract.ts";
+
+export interface Running {
+	subject: SurfaceContractSubject;
+	delivered: InboundMessage[];
+}
+
+export class ContractBroken extends Error {
+	override name = "ContractBroken";
+}
+
+export function expectThat(condition: boolean, message: string): void {
+	if (!condition) throw new ContractBroken(message);
+}
+
+export async function until(
+	done: () => boolean,
+	what: string,
+	ms = 2000,
+): Promise<void> {
+	const deadline = Date.now() + ms;
+	while (!done()) {
+		if (Date.now() > deadline)
+			throw new ContractBroken(`timed out waiting until ${what}`);
+		await Bun.sleep(5);
+	}
+}
+
+export const seen = (running: Running, kind: SurfaceObservation["kind"]) =>
+	running.subject.observations().filter((o) => o.kind === kind);
+
+export const speakerOf = (subject: SurfaceContractSubject): Speaker =>
+	subject.speaker ?? {
+		id: "contract-speaker",
+		name: "Ada",
+		tier: "owner",
+		principalId: "contract-speaker",
+	};
+
+/** The person's prompt scope in a conversation of this visibility. */
+export const scopeOf = (
+	subject: SurfaceContractSubject,
+	visibility: "private" | "shared" = "shared",
+): PromptScope => promptScope(speakerOf(subject), visibility);
+
+/** The newest prompt the person has seen, once one more than `before` is open. */
+export async function nextPrompt(
+	running: Running,
+	before: number,
+): Promise<string> {
+	await until(
+		() => seen(running, "prompt").length > before,
+		"the person sees the approval",
+	);
+	const prompt = seen(running, "prompt").at(-1);
+	if (prompt?.kind !== "prompt") throw new ContractBroken("no prompt seen");
+	return prompt.id;
+}
+
+/** Asks for one approval and answers it as the person does. */
+export async function approval(running: Running, approved: boolean) {
+	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 before = seen(running, "prompt").length;
+	const result = prompts.confirm(
+		"Approve?",
+		"Send the report.",
+		undefined,
+		speakerOf(running.subject).tier,
+	);
+	await answer(await nextPrompt(running, before), approved);
+	return result;
+}
+
+/**
+ * Opens the person's approval in a conversation of `visibility`, has `other` answer it by its id,
+ * and checks that only the person's own answer settles it.
+ */
+export async function answeredOnlyByThem(
+	running: Running,
+	other: SurfaceContractAnswerer | undefined,
+	visibility: "private" | "shared",
+	approvers?: readonly string[],
+): Promise<void> {
+	const { surface, channel, answer } = running.subject;
+	const prompts = surface.prompts?.(
+		channel,
+		scopeOf(running.subject, visibility),
+	);
+	if (!prompts || !answer || !other)
+		throw new ContractBroken("the surface shows no prompts");
+	await other.join?.();
+	const before = seen(running, "prompt").length;
+	let settled: Approval | undefined;
+	const result = prompts
+		.confirm(
+			"Approve?",
+			"Send the report.",
+			undefined,
+			speakerOf(running.subject).tier,
+			undefined,
+			undefined,
+			approvers ? { approvers } : undefined,
+		)
+		.then((value) => {
+			settled = value;
+			return value;
+		});
+	const id = await nextPrompt(running, before);
+	await other.answer(id, true);
+	await Bun.sleep(50);
+	expectThat(
+		settled === undefined,
+		`another principal's answer settled the approval as ${settled}`,
+	);
+	await answer(id, false);
+	const own = await result;
+	expectThat(own === "declined", `the person's answer came back ${own}`);
+}
+
+/**
+ * Opens the person's approval in a shared conversation naming the approver, and checks that
+ * another person and the person themselves cannot answer it, and the approver can, who is then
+ * reported as the approver.
+ */
+export async function namedApproverAnswers(running: Running): Promise<void> {
+	const { surface, channel, answer, stranger, approver } = running.subject;
+	const prompts = surface.prompts?.(channel, scopeOf(running.subject));
+	if (!prompts || !answer || !stranger || !approver)
+		throw new ContractBroken("the surface shows no prompts");
+	await stranger.join?.();
+	await approver.join?.();
+	const before = seen(running, "prompt").length;
+	let settled: Approval | undefined;
+	let reported: ApprovedBy | undefined;
+	const result = prompts
+		.confirm(
+			"Approve?",
+			"Send the report.",
+			undefined,
+			speakerOf(running.subject).tier,
+			undefined,
+			undefined,
+			{
+				approvers: [approver.principalId],
+				approvedBy: (by) => {
+					reported = by;
+				},
+			},
+		)
+		.then((value) => {
+			settled = value;
+			return value;
+		});
+	const id = await nextPrompt(running, before);
+	await stranger.answer(id, true);
+	await Bun.sleep(50);
+	expectThat(
+		settled === undefined,
+		`another person's answer settled the named approver's approval as ${settled}`,
+	);
+	await answer(id, true);
+	await Bun.sleep(50);
+	expectThat(
+		settled === undefined,
+		`the speaker's answer settled an approval that names others as ${settled}`,
+	);
+	await approver.answer(id, true);
+	const own = await result;
+	expectThat(own === "approved", `the approver's answer came back ${own}`);
+	// The runtime accepts an approval of a call that names approvers only from one it names.
+	expectThat(
+		reported !== undefined,
+		"the approval did not report who approved it through approvedBy",
+	);
+	expectThat(
+		reported?.principalId === approver.principalId,
+		`the approval reported ${reported?.principalId} as its approver, not ${approver.principalId}`,
+	);
+}