pi-roundtable 0.9.11 → 0.9.13

package/src/core/shared/generate-image-tool.ts

@@ -0,0 +1,173 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { ImageDrawer, ReferenceImage } from "../contract/providers.ts";
+import {
+	attachReplyFile,
+	REPLY_FILE_LIMITS,
+	ReplyFileError,
+} from "../reply-files.ts";
+import { toolError, toolText } from "./tool-result.ts";
+import {
+	findWorkspaceFile,
+	readWorkspaceFile,
+	WorkspaceFileError,
+	type WorkspaceRoots,
+} from "./workspace-files.ts";
+
+export const GENERATE_IMAGE_TOOL = "generate_image";
+
+/** The limits on the reference images one call passes to the drawer. */
+export const REFERENCE_IMAGE_LIMITS = Object.freeze({
+	maxImages: 4,
+	maxImageBytes: 20 * 1024 * 1024,
+	maxTotalBytes: 40 * 1024 * 1024,
+});
+
+const MAX_PROMPT_CHARS = 4000;
+
+/** The image type of `data` by its content, or undefined for anything else. */
+export function imageTypeOf(
+	data: Uint8Array,
+): { mimeType: string; ext: string } | undefined {
+	const starts = (bytes: readonly number[], at = 0) =>
+		bytes.every((byte, i) => data[at + i] === byte);
+	if (starts([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
+		return { mimeType: "image/png", ext: "png" };
+	if (starts([0xff, 0xd8, 0xff])) return { mimeType: "image/jpeg", ext: "jpg" };
+	if (starts([0x47, 0x49, 0x46, 0x38]))
+		return { mimeType: "image/gif", ext: "gif" };
+	if (starts([0x52, 0x49, 0x46, 0x46]) && starts([0x57, 0x45, 0x42, 0x50], 8))
+		return { mimeType: "image/webp", ext: "webp" };
+	return undefined;
+}
+
+async function readReferences(
+	paths: readonly string[],
+	roots: WorkspaceRoots,
+): Promise<ReferenceImage[]> {
+	const { maxImages, maxImageBytes, maxTotalBytes } = REFERENCE_IMAGE_LIMITS;
+	if (paths.length > maxImages)
+		throw new WorkspaceFileError(
+			`${paths.length} reference images given; at most ${maxImages} are allowed.`,
+		);
+	const files = await Promise.all(
+		paths.map((path) => findWorkspaceFile(path, roots)),
+	);
+	let total = 0;
+	for (const file of files) {
+		if (file.size > maxImageBytes)
+			throw new WorkspaceFileError(
+				`${file.path} is ${file.size} bytes; a reference image may contain at most ${maxImageBytes} bytes.`,
+			);
+		total += file.size;
+	}
+	if (total > maxTotalBytes)
+		throw new WorkspaceFileError(
+			`the reference images total ${total} bytes; at most ${maxTotalBytes} are allowed.`,
+		);
+	const references: ReferenceImage[] = [];
+	for (const file of files) {
+		const data = await readWorkspaceFile(file, maxImageBytes);
+		const type = imageTypeOf(data);
+		if (!type)
+			throw new WorkspaceFileError(
+				`${file.path} is not a PNG, JPEG, WebP or GIF image.`,
+			);
+		references.push({
+			data: Buffer.from(data).toString("base64"),
+			mimeType: type.mimeType,
+		});
+	}
+	return references;
+}
+
+/**
+ * Registers `generate_image`, which draws a new picture with the host's image provider, saves it
+ * under `<scratch dir or workspace>/drawings`, and attaches it to the turn's reply.
+ */
+export function generateImageExtension(
+	draw: ImageDrawer,
+	roots: WorkspaceRoots,
+): ExtensionFactory {
+	return (pi) => {
+		pi.registerTool({
+			name: GENERATE_IMAGE_TOOL,
+			label: "Generate image",
+			description:
+				'Generate a new picture from a description. Describe the subject, style and composition; say "no text" when you will add text to it later. The picture is saved to a file whose path the result names, and attached to your reply.',
+			parameters: Type.Object(
+				{
+					prompt: Type.String({
+						minLength: 1,
+						maxLength: MAX_PROMPT_CHARS,
+						description:
+							"What to draw: subject, style, composition, and anything to leave out.",
+					}),
+					reference_paths: Type.Optional(
+						Type.Array(Type.String({ minLength: 1, maxLength: 4096 }), {
+							maxItems: REFERENCE_IMAGE_LIMITS.maxImages,
+							description:
+								"Paths of PNG, JPEG, WebP or GIF images inside the workspace or the scratch dir to draw from.",
+						}),
+					),
+				},
+				{ additionalProperties: false },
+			),
+			execute: async (_toolCallId, params, signal) => {
+				let references: ReferenceImage[];
+				try {
+					references = await readReferences(
+						params.reference_paths ?? [],
+						roots,
+					);
+				} catch (error) {
+					if (error instanceof WorkspaceFileError)
+						return toolError(`Not drawn: ${error.message}`);
+					throw error;
+				}
+				signal?.throwIfAborted();
+				let data: Uint8Array;
+				try {
+					data = await draw(
+						params.prompt,
+						references,
+						signal ? { signal } : {},
+					);
+				} catch (error) {
+					signal?.throwIfAborted();
+					return toolError(
+						`The image provider did not draw it: ${error instanceof Error ? error.message : String(error)}`,
+					);
+				}
+				signal?.throwIfAborted();
+				const type = imageTypeOf(data);
+				if (!type)
+					return toolError(
+						"The image provider returned something that is not a PNG, JPEG, WebP or GIF image.",
+					);
+				const dir = join(roots.scratchDir ?? roots.workspace, "drawings");
+				await mkdir(dir, { recursive: true });
+				const name = `generated-${new Date().toISOString().replace(/[:.]/g, "-")}.${type.ext}`;
+				const path = join(dir, name);
+				await writeFile(path, data);
+				try {
+					if (data.byteLength > REPLY_FILE_LIMITS.maxFileBytes)
+						throw new ReplyFileError(
+							`it is ${data.byteLength} bytes; a reply file may contain at most ${REPLY_FILE_LIMITS.maxFileBytes} bytes.`,
+						);
+					attachReplyFile({ name, data });
+				} catch (error) {
+					if (!(error instanceof ReplyFileError)) throw error;
+					return toolText(
+						`Drew the picture and saved it to ${path} (${data.byteLength} bytes), but it is not attached: ${error.message}`,
+					);
+				}
+				return toolText(
+					`Drew the picture, saved it to ${path} (${data.byteLength} bytes); it will appear with your reply.`,
+				);
+			},
+		});
+	};
+}

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}`,
+	);
+}

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

@@ -1,15 +1,23 @@
 import { describe, test } from "bun:test";
-import type { InboundMessage } from "../contract/channels.ts";
 import type { ChatSurface } from "../contract/surface.ts";
 import { parseChannelKey } from "../contract/surface.ts";
 import type { TurnProgress } from "../domain/progress.ts";
-import {
-	type Approval,
-	type PromptScope,
-	promptScope,
-} from "../interactions/prompts.ts";
+import type { Approval } from "../interactions/prompts.ts";
 import type { ChannelKey } from "../sessions.ts";
 import type { Speaker } from "../speakers.ts";
+import {
+	answeredOnlyByThem,
+	approval,
+	ContractBroken,
+	expectThat,
+	namedApproverAnswers,
+	nextPrompt,
+	type Running,
+	scopeOf,
+	seen,
+	speakerOf,
+	until,
+} from "./surface-contract-support.ts";
 
 /** What the person on a surface's network has seen, as the contract reads it. */
 export type SurfaceObservation =
@@ -55,6 +63,20 @@ export interface SurfaceContractSubject {
 	 * check is skipped.
 	 */
 	owner?: SurfaceContractAnswerer;
+	/**
+	 * Another principal, not an owner, who holds the tier of the person's approvals and whom an
+	 * approval may name in `approvers`; they know the id of the person's open prompt and answer it.
+	 * A surface must report them through `ApprovalOptions.approvedBy`, because the runtime accepts
+	 * an approval of a call that names approvers only from one it names. Without it the
+	 * named-approver checks are skipped.
+	 */
+	approver?: SurfaceContractAnswerer & { principalId: string };
+	/**
+	 * Set by a surface that serves only conversations private to one person, such as the web chat:
+	 * it has no shared conversation in which an approval is the named approvers', so it skips that
+	 * check and keeps the one that its person alone answers a private conversation's.
+	 */
+	privateOnly?: boolean;
 	close?(): Promise<void>;
 }
 
@@ -71,11 +93,6 @@ export interface SurfaceContractFailure {
 	error: unknown;
 }
 
-interface Running {
-	subject: SurfaceContractSubject;
-	delivered: InboundMessage[];
-}
-
 interface Check {
 	name: string;
 	/** Whether the check applies to this subject; a check that does not is skipped. */
@@ -83,72 +100,6 @@ interface Check {
 	run(running: Running): Promise<void>;
 }
 
-class ContractBroken extends Error {
-	override name = "ContractBroken";
-}
-
-function expectThat(condition: boolean, message: string): void {
-	if (!condition) throw new ContractBroken(message);
-}
-
-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);
-	}
-}
-
-const seen = (running: Running, kind: SurfaceObservation["kind"]) =>
-	running.subject.observations().filter((o) => o.kind === kind);
-
-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. */
-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. */
-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. */
-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;
-}
-
 const CHECKS: readonly Check[] = [
 	{
 		name: "names a surface prefix without a colon, and owns the subject's channel",
@@ -331,6 +282,28 @@ const CHECKS: readonly Check[] = [
 		run: (running) =>
 			answeredOnlyByThem(running, running.subject.owner, "private"),
 	},
+	{
+		name: "a named approver answers an approval instead of the person; the person and another person cannot",
+		applies: (subject) =>
+			subject.surface.prompts !== undefined &&
+			subject.answer !== undefined &&
+			subject.stranger !== undefined &&
+			subject.approver !== undefined &&
+			subject.privateOnly !== true,
+		run: namedApproverAnswers,
+	},
+	{
+		name: "a private conversation is answered by its person alone, whoever else a call names",
+		applies: (subject) =>
+			subject.surface.prompts !== undefined &&
+			subject.answer !== undefined &&
+			subject.approver !== undefined,
+		run: (running) =>
+			answeredOnlyByThem(running, running.subject.approver, "private", [
+				speakerOf(running.subject).principalId,
+				running.subject.approver?.principalId ?? "",
+			]),
+	},
 	{
 		name: "a private conversation's approval above the person's tier goes to no one: it comes back at once, unshown",
 		applies: (subject) =>
@@ -361,48 +334,6 @@ const CHECKS: readonly Check[] = [
 	},
 ];
 
-/**
- * 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.
- */
-async function answeredOnlyByThem(
-	running: Running,
-	other: SurfaceContractAnswerer | undefined,
-	visibility: "private" | "shared",
-): 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,
-		)
-		.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}`);
-}
-
 async function runCheck(
 	check: Check,
 	make: () => Promise<SurfaceContractSubject>,
@@ -445,7 +376,10 @@ export async function checkSurfaceContract(
  * 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
  * 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. Each
+ * 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
+ * approver, and not by the person or another person, and a private conversation's is answered by
+ * its person alone, whoever the call names besides them. Each
  * check gets a fresh subject from `make`; a check for an optional part the surface lacks passes.
  */
 export function describeSurfaceContract(

package/src/core/tool-turn.ts

@@ -31,13 +31,16 @@ function clientIn(port: ClientPort, turn: AbortSignal | undefined): ClientPort {
 
 /**
  * The turn a tool's `run` and `hold` receive, built from the session that makes the call and the
- * signal that stops it.
+ * signal that stops it. For a call being run, `toolCallId` finds who approved it.
  */
 export function toolTurn(
 	context: SessionContext,
 	signal: AbortSignal | undefined,
+	toolCallId?: string,
 ): ToolTurn {
 	const origin = context.origin?.();
+	const approvedBy =
+		toolCallId === undefined ? undefined : context.approvedBy?.(toolCallId);
 	const client = context.client?.();
 	return {
 		speaker: context.speaker(),
@@ -45,6 +48,7 @@ export function toolTurn(
 		agent: context.agent,
 		signal,
 		...(origin === undefined ? {} : { origin }),
+		...(approvedBy === undefined ? {} : { approvedBy }),
 		...(client === undefined ? {} : { client: clientIn(client, signal) }),
 		...(context.workspace ? { workspace: context.workspace } : {}),
 		attachFile: attachReplyFile,

package/src/index.ts

@@ -166,8 +166,12 @@ export type {
 	AccessOwner,
 	AccessRules,
 	AccessTier,
+	Provisioning,
+	ProvisioningRule,
+	SelfLinkRules,
 } from "./core/identity/access-policy.ts";
 export type { ActorFacts } from "./core/identity/actor-facts.ts";
+export type { IdentityLinks } from "./core/identity/identity-links.ts";
 export type { IdentityService } from "./core/identity/identity-service.ts";
 export type {
 	IdentityLink,
@@ -182,6 +186,8 @@ export type {
 	Approval,
 	ApprovalDetails,
 	ApprovalFile,
+	ApprovalOptions,
+	ApprovedBy,
 	AskOption,
 	LateAnswer,
 	OwnerAnswer,
@@ -293,6 +299,7 @@ export {
 	CONVERSATIONS,
 	DELEGATION,
 	IDENTITY,
+	IDENTITY_LINKS,
 	MEMORY,
 	PRECHECKS,
 	RUNTIME,