pi-roundtable 0.9.12 → 0.10.0

package/src/core/identity/principal-types.ts

@@ -0,0 +1,146 @@
+import type { Pronouns } from "../config/config.ts";
+import type { Tier } from "../speakers.ts";
+
+export type { Pronouns };
+
+/** A person the host serves, whichever surface they reach it through. */
+export interface Principal {
+	/** Opaque: a speaker id carried over from 0.8, or `p_<ulid>` for one made since. */
+	id: string;
+	displayName: string;
+	pronouns?: Pronouns;
+	disabled: boolean;
+}
+
+/** A principal as stored, with when it was made and when it was last seen. */
+export interface PrincipalRecord extends Principal {
+	locale?: string;
+	timeZone?: string;
+	createdAt: Date;
+	lastSeenAt?: Date;
+	/** The tier it was last seen at; it only ever lowers what a background turn may do, never grants. */
+	lastTier?: Tier;
+	/** Whether the person of its 0.8 speaker id may still claim it: only one the backfill made, until any identity is linked to it. */
+	claimable: boolean;
+}
+
+/** An identity on one provider: `discord` and a user id, `oidc:<issuer>` and a subject, `token` and a name. */
+export interface IdentityRef {
+	provider: string;
+	subject: string;
+}
+
+/**
+ * How an identity came to be linked: by the configuration, a plugin declaring it
+ * (`RoundtablePlugin.identities`), the CLI, admission on first contact, a 0.8 speaker id claimed,
+ * or the person themself through `IDENTITY_LINKS` (`self`).
+ */
+export type LinkSource =
+	| "config"
+	| "plugin"
+	| "cli"
+	| "jit"
+	| "legacy"
+	| "self";
+
+export interface IdentityLink extends IdentityRef {
+	principalId: string;
+	source: LinkSource;
+	linkedAt: Date;
+}
+
+/** Where a role came from. The configuration's are synced at every boot; a CLI grant stays until the CLI revokes it. */
+export type RoleSource = "config" | "cli";
+
+export interface RoleGrant {
+	role: Tier;
+	source: RoleSource;
+	grantedAt: Date;
+}
+
+/** A principal holding a role, and where the role came from. */
+export interface RoleHolder {
+	principalId: string;
+	source: RoleSource;
+}
+
+export interface NewPrincipal {
+	/** The id to keep, for a principal carried over from 0.8; otherwise a new `p_` id is made. */
+	id?: string;
+	displayName: string;
+	pronouns?: Pronouns;
+}
+
+/** The principals, their linked identities, and their lasting roles. */
+export interface PrincipalStore {
+	get(id: string): Promise<PrincipalRecord | undefined>;
+	list(): Promise<PrincipalRecord[]>;
+	/** Refuses an id already taken, and the system principal's. */
+	create(input: NewPrincipal): Promise<PrincipalRecord>;
+	/** Changes the name or the pronouns; `pronouns: null` clears them. */
+	update(
+		id: string,
+		change: { displayName?: string; pronouns?: Pronouns | null },
+	): Promise<PrincipalRecord | undefined>;
+	/**
+	 * Links the identity to the principal; linking it again to the same one changes nothing, but
+	 * that the configuration linking it makes the link the configuration's, and a plugin linking it
+	 * makes one the CLI, a first contact, or a claim made the plugin's; to another one is refused. A
+	 * principal with any identity linked is no longer claimable, even after the identity is
+	 * unlinked, except by a plugin's link: a plugin's credential is not the person's own identity,
+	 * so it leaves their 0.8 claim to them.
+	 */
+	link(
+		principalId: string,
+		identity: IdentityRef,
+		source: LinkSource,
+	): Promise<IdentityLink>;
+	/**
+	 * The identity's link, claiming the principal for it when the identity is still unlinked and
+	 * the principal claimable and not an owner; undefined when it may not be claimed. A principal
+	 * is claimed at most once. A claim names the principal `displayName`, when given, while its
+	 * name is still its id, as the backfill names someone it knows no name of; a real name stays.
+	 */
+	claim(
+		principalId: string,
+		identity: IdentityRef,
+		displayName?: string,
+	): Promise<IdentityLink | undefined>;
+	/**
+	 * The identity's link, making a new `p_` principal for it, of `id` when given, when it is still
+	 * unlinked; however many contacts admit it at once, one principal is made.
+	 */
+	admit(
+		identity: IdentityRef,
+		displayName: string,
+		id?: string,
+	): Promise<IdentityLink>;
+	/** Whether there was a link to remove; with `source`, only a link made by it is removed. */
+	unlink(
+		provider: string,
+		subject: string,
+		source?: LinkSource,
+	): Promise<boolean>;
+	identity(
+		provider: string,
+		subject: string,
+	): Promise<IdentityLink | undefined>;
+	identitiesOf(principalId: string): Promise<IdentityLink[]>;
+	/** Every link made by `source`, such as the configuration's. */
+	linksFrom(source: LinkSource): Promise<IdentityLink[]>;
+	/** Grants a lasting role. A CLI grant is kept as the CLI's even when the configuration grants the same role. */
+	grant(principalId: string, role: Tier, source: RoleSource): Promise<void>;
+	/** Revokes the role, or only the grant from `source`; whether there was one to revoke. */
+	revoke(
+		principalId: string,
+		role: Tier,
+		source?: RoleSource,
+	): Promise<boolean>;
+	rolesOf(principalId: string): Promise<RoleGrant[]>;
+	/** Every principal holding the role. */
+	holders(role: Tier): Promise<RoleHolder[]>;
+	disable(id: string): Promise<void>;
+	enable(id: string): Promise<void>;
+	/** Records that the principal was seen at `at` (default now), at this tier, or null when refused. */
+	touch(id: string, tier: Tier | null, at?: Date): Promise<void>;
+}

package/src/core/interactions/prompts.ts

@@ -37,9 +37,51 @@ export interface ApprovalDetails {
 	files?: ApprovalFile[];
 }
 
-/** An answer given on a prompt after its turn stopped waiting; `by` names who gave it. */
+/**
+ * Who approved a held call: the principal, the identity they answered with as `Speaker.id`, and
+ * the name that identity goes by. A surface reports it when it knows it; a held call's `run`
+ * reads it as `ToolTurn.approvedBy`.
+ */
+export interface ApprovedBy {
+	principalId: string;
+	speakerId: string;
+	name: string;
+	/**
+	 * True when they approved as a core owner. A surface sets it when the approver is one; a call
+	 * that named approvers is released only by an approver it names or by an `owner`, so an
+	 * approval without it, from anyone else, is not accepted.
+	 */
+	owner?: true;
+}
+
+/**
+ * What a held call's approval is asked with besides its text: who may approve it, and where to
+ * hear who did.
+ */
+export interface ApprovalOptions {
+	/**
+	 * The principal ids that may approve this call instead of the scope's speaker. Given in a
+	 * conversation that escalates to the owners, the speaker may not approve it unless named, and
+	 * each named principal needs the call's tier when they answer; the owners may still approve it.
+	 * An empty list leaves the owners alone. In a private conversation, whose person is the only one
+	 * who answers, the person may approve it only when named or an owner; otherwise it comes back
+	 * `unavailable` at once. A surface must report who approved through `approvedBy`: in a shared
+	 * conversation an approval it does not name is not accepted for a call that names approvers.
+	 */
+	approvers?: readonly string[];
+	/**
+	 * Called with who approved the call, before the approval resolves `approved`; not called for a
+	 * refusal, or by a surface that does not know who answered.
+	 */
+	approvedBy?(by: ApprovedBy): void;
+}
+
+/**
+ * An answer given on a prompt after its turn stopped waiting; `by` names who gave it. An approval
+ * names the approver too, where the surface knows them.
+ */
 export type LateAnswer = { by: string } & (
-	| { kind: "approval"; approved: boolean }
+	| { kind: "approval"; approved: boolean; approvedBy?: ApprovedBy }
 	| { kind: "question"; answer: OwnerAnswer }
 );
 
@@ -119,7 +161,8 @@ export interface Prompts {
 	 * tier the scope's speaker needs to approve it themselves, `owner` when absent; below it the
 	 * prompt goes to the owners, or, when the scope escalates to no one, resolves `expired` at once.
 	 * `pending` comes only with a `wait`. `details` is the approval as data beside `message`, its
-	 * text; a surface that shows text only ignores it.
+	 * text; a surface that shows text only ignores it. `options` says who else may approve it and
+	 * hears who did; see `ApprovalOptions`.
 	 */
 	confirm(
 		title: string,
@@ -128,6 +171,7 @@ export interface Prompts {
 		minTier?: Tier,
 		wait?: PromptWait,
 		details?: ApprovalDetails,
+		options?: ApprovalOptions,
 	): Promise<Approval>;
 	/**
 	 * Asks a question; undefined when no one answered it or it was cancelled, and `pending`, only

package/src/core/modules/schedules/precheck-tools.ts

@@ -292,30 +292,61 @@ export function precheckScriptTools(
 	},
 ): PrecheckTool[] {
 	const tools = new Map<string, PrecheckTool>();
-	for (const call of readPrecheckScript(script).calls) {
-		const name = options.toolName(call.server, call.tool);
-		const context = options.context ?? {};
-		let held: string | undefined;
-		if (call.args) held = options.holds(name, call.args, context);
-		else {
-			held = options.holds(name, {}, context);
-			const rule =
-				held === undefined ? options.holds.mayHold?.(name) : undefined;
-			if (rule !== undefined) held = messages().precheckToolMayHold(name, rule);
-		}
+	for (const call of judgedScriptCalls(script, options)) {
 		const key = `${call.server}\u0000${call.tool}`;
 		const known = tools.get(key);
 		if (!known)
 			tools.set(key, {
 				server: call.server,
 				tool: call.tool,
-				...(held ? { held } : {}),
+				...(call.held ? { held: call.held } : {}),
 			});
-		else if (held && !known.held) known.held = held;
+		else if (call.held && !known.held) known.held = call.held;
 	}
 	return [...tools.values()];
 }
 
+/** A call in a precheck script, judged: the name its rules know it by, its input, and what they say it would do. */
+interface JudgedScriptCall {
+	server: string;
+	tool: string;
+	name: string;
+	/** The arguments written out in the script; empty when it computes them. */
+	input: Record<string, unknown>;
+	/** Whether the script writes its arguments out, so `input` is what the call will be made with. */
+	literal: boolean;
+	held?: string;
+}
+
+/** Each call of the script, judged by the host's hold rules, one entry per call. */
+function judgedScriptCalls(
+	script: unknown,
+	options: {
+		toolName: (server: string, tool: string) => string;
+		holds: HoldCheck;
+		context?: HoldContext;
+	},
+): JudgedScriptCall[] {
+	const context = options.context ?? {};
+	return readPrecheckScript(script).calls.map((call) => {
+		const name = options.toolName(call.server, call.tool);
+		const input = call.args ?? {};
+		let held = options.holds(name, input, context);
+		if (!call.args && held === undefined) {
+			const rule = options.holds.mayHold?.(name);
+			if (rule !== undefined) held = messages().precheckToolMayHold(name, rule);
+		}
+		return {
+			server: call.server,
+			tool: call.tool,
+			name,
+			input,
+			literal: call.args !== undefined,
+			...(held ? { held } : {}),
+		};
+	});
+}
+
 const SCHEDULE_TOOLS = new Set(["schedule_create", "schedule_update"]);
 
 /**
@@ -330,12 +361,17 @@ export function precheckScriptHoldRule(options: {
 	tiers?: () => ToolTiers;
 }): HoldRule {
 	let judging = false;
-	/** The held tools a script being saved calls, by the names the hold rules know them by. */
-	const heldCalls = (
+	/** The held calls a script being saved makes, each with the name the hold rules know its tool by and its input. */
+	const scriptCalls = (
 		tool: string,
 		input: Record<string, unknown>,
 		context: HoldContext,
-	): { name: string; held: string }[] => {
+	): {
+		name: string;
+		input: Record<string, unknown>;
+		literal: boolean;
+		held: string;
+	}[] => {
 		const script = input.precheck_script;
 		if (!SCHEDULE_TOOLS.has(tool) || typeof script !== "string" || judging)
 			return [];
@@ -343,13 +379,20 @@ export function precheckScriptHoldRule(options: {
 		if (!runner) return [];
 		judging = true;
 		try {
-			return precheckScriptTools(script, {
+			return judgedScriptCalls(script, {
 				toolName: (server, name) => runner.toolName(server, name),
 				holds: options.holds(),
 				context,
-			}).flatMap((t) =>
-				t.held
-					? [{ name: runner.toolName(t.server, t.tool), held: t.held }]
+			}).flatMap((call) =>
+				call.held
+					? [
+							{
+								name: call.name,
+								input: call.input,
+								literal: call.literal,
+								held: call.held,
+							},
+						]
 					: [],
 			);
 		} catch {
@@ -359,6 +402,19 @@ export function precheckScriptHoldRule(options: {
 			judging = false;
 		}
 	};
+	/** The held tools a script being saved calls, once each, by the names the hold rules know them by. */
+	const heldCalls = (
+		tool: string,
+		input: Record<string, unknown>,
+		context: HoldContext,
+	): { name: string; held: string }[] => {
+		const seen = new Set<string>();
+		return scriptCalls(tool, input, context).filter((call) => {
+			if (seen.has(call.name)) return false;
+			seen.add(call.name);
+			return true;
+		});
+	};
 	return {
 		name: "precheck-scripts",
 		describe(tool, input, context) {
@@ -383,5 +439,44 @@ export function precheckScriptHoldRule(options: {
 				undefined,
 			);
 		},
+		mayName: (tool) => SCHEDULE_TOOLS.has(tool),
+		// Whoever approves must also be named for each held call the script makes: the principals
+		// every call names, and, where a call's approvers cannot be read, the owners alone.
+		approversInTurn(tool, input, context, turn) {
+			const calls = scriptCalls(tool, input, context);
+			const holds = options.holds();
+			const lookup = holds.approversInTurn;
+			if (calls.length === 0 || !lookup) return undefined;
+			return Promise.all(
+				calls.map(async (call) => {
+					try {
+						// A script's computed arguments are not known now, so its call is judged by none.
+						const named = await lookup.call(
+							holds,
+							call.name,
+							call.input,
+							context,
+							turn,
+						);
+						// A rule that answers by the arguments may name approvers once they are known:
+						// until then only the owners can stand for them.
+						return named === undefined &&
+							!call.literal &&
+							holds.mayName?.(call.name) !== undefined
+							? []
+							: named;
+					} catch {
+						return [];
+					}
+				}),
+			).then((lists) => {
+				const named = lists.filter(
+					(list): list is readonly string[] => list !== undefined,
+				);
+				const [first, ...rest] = named;
+				if (!first) return undefined;
+				return first.filter((id) => rest.every((list) => list.includes(id)));
+			});
+		},
 	};
 }

package/src/core/routing/conversation-turns.ts

@@ -49,7 +49,10 @@ export interface ConversationTurnInput {
 	steerable?: boolean;
 	/** The turn may ask the owner on the surface's prompts, such as approvals of held actions. */
 	interactive?: boolean;
-	/** The owner confirmed the channel's held actions, so they may run in this turn. */
+	/**
+	 * The speaker confirmed the channel's held actions, so they may run in this turn, except those
+	 * that named approvers the speaker is neither among nor an owner of, which stay held.
+	 */
 	confirmed?: boolean;
 	/**
 	 * Posts the turn's outcome in place of the default reply (the text, or a failure or stopped

package/src/core/runtime/conversation-sessions.ts

@@ -109,6 +109,14 @@ export class ConversationSessions {
 				this.#tiers,
 				// Owner sessions have no shell workspace but still send files from their own directory.
 				agents ? agents.workDir : this.#factory.cwd(undefined),
+				undefined,
+				// A disabled principal cannot approve, so it is not named as one who can.
+				async (id) => {
+					const principal = await this.#options.principalOf?.(id);
+					return principal && !principal.disabled
+						? principal.displayName
+						: undefined;
+				},
 			);
 			this.#gates.set(key, gate);
 			this.#restored.delete(key);

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

@@ -0,0 +1,50 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { ToolTurn } from "../../define.ts";
+import type { PromptSlot } from "../prompt-slot.ts";
+import type { ConfirmationGate, HoldTurn } from "./confirmation-gate.ts";
+
+/**
+ * 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) => {
+			gate.finish(event.toolCallId);
+			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, approvedBy, refused } = await gate.decide(
+				event.toolName,
+				event.input as Record<string, unknown>,
+				ask,
+				turn,
+			);
+			if (approvedOnCard) approved.add(event.toolCallId);
+			if (approvedBy && !reason) gate.grant(event.toolCallId, approvedBy);
+			if (refused) slot?.refuse(event.toolCallId, refused);
+			return reason ? { block: true, reason } : undefined;
+		});
+	};
+}