pi-roundtable 0.9.11 → 0.9.13

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/runtime-plugin.ts

@@ -168,6 +168,9 @@ export function runtimePlugin(
 						}),
 						confirmations: heldActions,
 						toolTiers: context.toolTiers,
+						...(providers.filled.has("images")
+							? { images: providers.images }
+							: {}),
 						stopping: () => context.queue.closed,
 						get agents() {
 							return agents();

package/src/core/runtime/runtime-types.ts

@@ -4,6 +4,7 @@ import type {
 	ExtensionFactory,
 	ModelRuntime,
 } from "@earendil-works/pi-coding-agent";
+import type { ImageDrawer } from "../contract/providers.ts";
 import type { AgentSessions, LoadedSkill } from "../contract/runtime.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
 import type { InterimTextMode } from "../domain/interim.ts";
@@ -97,6 +98,8 @@ export interface PiAgentRuntimeOptions {
 	interimPrimaryChars?: number;
 	/** How long a new session waits for its MCP tools to register. */
 	mcpConnectTimeoutMs?: number;
+	/** The host's image provider, when one fills the slot; sessions then offer `generate_image`. */
+	images?: ImageDrawer;
 	/** Defaults to true: bridge shared turns refuse raw private exchanges inaccessible to the reader. */
 	memory?: boolean;
 }
@@ -113,6 +116,8 @@ export interface CoreExtensions {
 	readAttachment: ExtensionFactory;
 	/** `attach_file`, for a session with a workspace. */
 	attachFile?: ExtensionFactory;
+	/** `generate_image`, for a host with an image provider. */
+	generateImage?: ExtensionFactory;
 	confirmationGate: ExtensionFactory;
 	askUser: ExtensionFactory;
 	selfCompactGuard: ExtensionFactory;
@@ -144,6 +149,9 @@ export function sessionExtensions(
 		...(core.attachFile
 			? [{ name: "attach-file", factory: core.attachFile }]
 			: []),
+		...(core.generateImage
+			? [{ name: "generate-image", factory: core.generateImage }]
+			: []),
 		{ name: "confirmation-gate", factory: core.confirmationGate },
 		{ name: "ask-user", factory: core.askUser },
 		{ name: "self-compact-guard", factory: core.selfCompactGuard },

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

@@ -10,6 +10,7 @@ import {
 	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { channelSegment } from "../attachments/attachment-dir.ts";
+import type { ImageDrawer } from "../contract/providers.ts";
 import type { ClientPort } from "../domain/client.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
 import { ConfigError } from "../domain/errors.ts";
@@ -28,8 +29,13 @@ import {
 	ATTACH_FILE_TOOL,
 	attachFileExtension,
 } from "../shared/attach-file-tool.ts";
+import {
+	GENERATE_IMAGE_TOOL,
+	generateImageExtension,
+} from "../shared/generate-image-tool.ts";
 import { packageDir } from "../shared/package-dir.ts";
 import { readAttachmentExtension } from "../shared/read-attachment-tool.ts";
+import type { WorkspaceRoots } from "../shared/workspace-files.ts";
 import { type Speaker, THE_SPEAKER } from "../speakers.ts";
 import { currentToolNames } from "../tool-tiers.ts";
 import { toolTurn } from "../tool-turn.ts";
@@ -56,6 +62,7 @@ import type { PromptSlot } from "./prompt-slot.ts";
 import type {
 	ChannelSession,
 	CompactionEnd,
+	CoreExtensions,
 	PiAgentRuntimeOptions,
 } from "./runtime-types.ts";
 import {
@@ -142,6 +149,8 @@ export class SessionFactory {
 			ASK_USER_TOOL,
 			// Registered only by a session with a workspace.
 			ATTACH_FILE_TOOL,
+			// Registered only with an image provider.
+			GENERATE_IMAGE_TOOL,
 			...groups
 				.filter((group) => selection.groups.includes(group.name))
 				.flatMap((group) => group.tools),
@@ -361,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),
@@ -381,6 +391,10 @@ export class SessionFactory {
 				...(context.workspace
 					? { attachFile: attachFileExtension(context.workspace) }
 					: {}),
+				...imageTools(
+					this.#options.images,
+					context.workspace ?? { workspace: cwd },
+				),
 				confirmationGate: confirmationGateExtension(gate, slot, (signal) =>
 					toolTurn(context, signal),
 				),
@@ -442,6 +456,14 @@ export class SessionFactory {
 	}
 }
 
+/** `generate_image` for a session of a host with an image provider; nothing without one. */
+export function imageTools(
+	images: ImageDrawer | undefined,
+	roots: WorkspaceRoots,
+): Pick<CoreExtensions, "generateImage"> {
+	return images ? { generateImage: generateImageExtension(images, roots) } : {};
+}
+
 /** Pi's bash tool with TMPDIR set to `scratchDir`, so `mktemp` and tools write there. */
 export function scratchBash(cwd: string, scratchDir: string): ToolDefinition {
 	// SAFETY: Pi's bash definition is a ToolDefinition typed by its own parameter schema, which the session takes as any custom tool.

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