pi-roundtable 0.9.7 → 0.9.9

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

@@ -1,10 +1,17 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { ToolTurn } from "../../define.ts";
 import type {
 	HeldCall,
 	PendingConfirmation,
 } from "../../domain/conversation.ts";
 import type { HoldRefusal } from "../../domain/progress.ts";
-import { type HoldCheck, type HoldContext, higherTier } from "../../holds.ts";
+import {
+	HOLD_DESCRIBE_TIMEOUT_MS,
+	type HoldCheck,
+	type HoldContext,
+	higherTier,
+	isPromise,
+} from "../../holds.ts";
 import { messages } from "../../i18n/index.ts";
 import { type OwnerIdentity, ownerWords } from "../../identity.ts";
 import type { LateAnswer, Prompts } from "../../interactions/prompts.ts";
@@ -27,6 +34,20 @@ export function unexpired(
 		: pending;
 }
 
+/** 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. */
+const STOPPED = Symbol("stopped");
+
+/** What waiting for a call's description comes to: its text, or the turn stopped first. */
+type Described = string | undefined | typeof STOPPED;
+
 /** 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 {
@@ -79,12 +100,18 @@ export class ConfirmationGate {
 	readonly #tiers: ToolTiers | undefined;
 	/** Where the session's relative file paths resolve, for the sizes a card shows. */
 	readonly #fileRoot: string | undefined;
+	readonly #describeTimeoutMs: number;
+	/** Settles when the descriptions asked for so far have all been used, in the order they were asked. */
+	#describing: Promise<void> = Promise.resolve();
+	/** Descriptions asked for and not used yet. */
+	#undescribed = 0;
 
 	/**
 	 * `holds` decides which calls wait for the owner. With a workspace, the session has a shell,
 	 * and its writes outside the workspace and the context's scratch dir are held too.
 	 * `fileRoot` is the session's working directory, where a card resolves relative file paths;
-	 * it defaults to the workspace.
+	 * it defaults to the workspace. A hold that looks things up gets `describeTimeoutMs` to answer
+	 * (`HOLD_DESCRIBE_TIMEOUT_MS` by default) before its call is held under a generic description.
 	 */
 	constructor(
 		holds: HoldCheck,
@@ -93,7 +120,9 @@ export class ConfirmationGate {
 		context: HoldContext = {},
 		tiers?: ToolTiers,
 		fileRoot?: string,
+		describeTimeoutMs = HOLD_DESCRIBE_TIMEOUT_MS,
 	) {
+		this.#describeTimeoutMs = describeTimeoutMs;
 		this.#tiers = tiers;
 		this.#fileRoot = fileRoot ?? context.workspace;
 		this.#holds = holds;
@@ -144,26 +173,32 @@ export class ConfirmationGate {
 		tool: string,
 		input: Record<string, unknown>,
 		ask?: { prompts: Prompts; asker: string; signal?: AbortSignal },
+		turn?: HoldTurn,
 	): Promise<string | undefined> {
-		return (await this.decide(tool, input, ask)).reason;
+		return (await this.decide(tool, input, ask, turn)).reason;
 	}
 
 	/**
 	 * `review`, plus whether a card's approval released the call, so its result can say so:
 	 * the card's own message is shown to the person, never to the model. When a hold refuses the
 	 * call, `refused` says how, for the turn's progress to report beside the failed result.
+	 * With `turn`, a hold that looks things up as the turn's speaker is waited for before any card
+	 * opens, and a turn that stops meanwhile opens none.
 	 */
 	async decide(
 		tool: string,
 		input: Record<string, unknown>,
 		ask?: { prompts: Prompts; asker: string; signal?: AbortSignal },
+		turn?: HoldTurn,
 	): Promise<{
 		reason?: string;
 		approvedOnCard?: true;
 		/** Why a hold refused the call, for a surface that tells that from a failure; absent when it ran or the turn stopped. */
 		refused?: HoldRefusal;
 	}> {
-		const call = this.#needing(tool, input);
+		const found = this.#needingIn(tool, input, turn);
+		const call = isPromise(found) ? await found : found;
+		if (call === STOPPED) return { reason: "The turn was stopped." };
 		if (!call) return {};
 		if (!ask) return { reason: this.#record(call), refused: "held" };
 		const answer = await ask.prompts.confirm(
@@ -210,10 +245,112 @@ export class ConfirmationGate {
 
 	/** The call when it needs the owner's confirmation and no approval releases it. */
 	#needing(tool: string, input: Record<string, unknown>): HeldCall | undefined {
-		const context = this.#context;
-		const action = this.#holds(tool, input, context);
-		if (!action) return undefined;
-		const minTier = this.#holds.approvalTier?.(tool, input, context);
+		const action = this.#holds(tool, input, this.#context);
+		return action ? this.#unlessApproved(tool, input, action) : undefined;
+	}
+
+	/**
+	 * `#needing` inside a turn, where a hold may look things up first: the call when it needs the
+	 * owner's confirmation, or `STOPPED` when the turn stopped while its description was awaited.
+	 * It answers at once when every hold asked does and no earlier call is still being described.
+	 */
+	#needingIn(
+		tool: string,
+		input: Record<string, unknown>,
+		turn: HoldTurn | undefined,
+	):
+		| HeldCall
+		| undefined
+		| typeof STOPPED
+		| Promise<HeldCall | undefined | typeof STOPPED> {
+		const inTurn = this.#holds.inTurn;
+		if (!turn || !inTurn) return this.#needing(tool, input);
+		const controller = new AbortController();
+		if (turn.signal?.aborted) controller.abort();
+		let answer: string | undefined | Promise<string | undefined>;
+		try {
+			answer = inTurn.call(
+				this.#holds,
+				tool,
+				input,
+				this.#context,
+				turn.toolTurn(controller.signal),
+			);
+		} catch {
+			answer = messages().holdGeneric(tool);
+		}
+		const described: Described | Promise<Described> = isPromise(answer)
+			? this.#awaited(answer, tool, controller, turn.signal)
+			: answer;
+		return this.#inOrder(described, (action) => {
+			if (action === STOPPED) return STOPPED;
+			return action ? this.#unlessApproved(tool, input, action) : undefined;
+		});
+	}
+
+	/**
+	 * What a hold that answers later comes to: its text; the generic description when it rejects or
+	 * outlasts the timeout, so the call is still held; `STOPPED` when the turn stops first. Whatever
+	 * the hold is still doing is aborted when the wait ends.
+	 */
+	#awaited(
+		answer: Promise<string | undefined>,
+		tool: string,
+		hold: AbortController,
+		stop: AbortSignal | undefined,
+	): Promise<Described> {
+		return new Promise<Described>((resolve) => {
+			const onStop = () => end(STOPPED);
+			const timer = setTimeout(
+				() => end(messages().holdGeneric(tool)),
+				this.#describeTimeoutMs,
+			);
+			let ended = false;
+			const end = (described: Described) => {
+				if (ended) return;
+				ended = true;
+				clearTimeout(timer);
+				stop?.removeEventListener("abort", onStop);
+				hold.abort();
+				resolve(described);
+			};
+			// Handled first, so a rejection after the wait ended is never left unhandled.
+			answer.then(end, () => end(messages().holdGeneric(tool)));
+			if (stop?.aborted) return end(STOPPED);
+			stop?.addEventListener("abort", onStop, { once: true });
+		});
+	}
+
+	/**
+	 * Hands `described` to `use` after every description asked for before it has been used, so
+	 * calls made together are held, and their cards opened, in the order they were made whichever
+	 * description comes back first.
+	 */
+	#inOrder<T, R>(
+		described: T | Promise<T>,
+		use: (described: T) => R,
+	): R | Promise<R> {
+		if (this.#undescribed === 0 && !isPromise(described)) return use(described);
+		this.#undescribed++;
+		const used = this.#describing.then(() => described).then(use);
+		this.#describing = used.then(
+			() => {
+				this.#undescribed--;
+			},
+			() => {
+				this.#undescribed--;
+			},
+		);
+		return used;
+	}
+
+	/** The call for `action`, unless an approval releases it, which that approval then spends. */
+	#unlessApproved(
+		tool: string,
+		input: Record<string, unknown>,
+		action: string,
+	): HeldCall | undefined {
+		const minTier = this.#holds.approvalTier?.(tool, input, this.#context);
 		const call: HeldCall = {
 			tool,
 			input: canonicalJson(input),
@@ -269,10 +406,14 @@ export function confirmedTurnText(
 	return `(${owner.name} approved the held actions below with this message. Make each call now with exactly this input.)\n${calls}\n\n${text}`;
 }
 
-/** Without a slot, or with an empty one, every call that needs confirmation is held. */
+/**
+ * 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. */
@@ -293,10 +434,14 @@ export function confirmationGateExtension(
 				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, refused } = await gate.decide(
 				event.toolName,
 				event.input as Record<string, unknown>,
 				ask,
+				turn,
 			);
 			if (approvedOnCard) approved.add(event.toolCallId);
 			if (refused) slot?.refuse(event.toolCallId, refused);

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

@@ -31,6 +31,7 @@ import { packageDir } from "../shared/package-dir.ts";
 import { readAttachmentExtension } from "../shared/read-attachment-tool.ts";
 import { type Speaker, THE_SPEAKER } from "../speakers.ts";
 import { currentToolNames } from "../tool-tiers.ts";
+import { toolTurn } from "../tool-turn.ts";
 import {
 	CompactionTiers,
 	compactionEngine,
@@ -373,7 +374,9 @@ export class SessionFactory {
 				...(context.workspace
 					? { attachFile: attachFileExtension(context.workspace) }
 					: {}),
-				confirmationGate: confirmationGateExtension(gate, slot),
+				confirmationGate: confirmationGateExtension(gate, slot, (signal) =>
+					toolTurn(context, signal),
+				),
 				askUser: askUserExtension(slot, addressee, () =>
 					turnAddressee(
 						this.#deps.speaker(turnKey),

package/src/core/shared/attachment-reader.ts

@@ -1,6 +1,8 @@
 import { join } from "node:path";
 import { extractText, getDocumentProxy } from "unpdf";
+import { wasExpired } from "../attachments/attachment-expiry.ts";
 import { isAttachmentName, plainText } from "../attachments/attachment-name.ts";
+import { AttachmentExpiredError } from "../attachments/tool-attachment.ts";
 
 /** Characters returned per read; the model can ask for a later offset. */
 export const READ_LIMIT = 60_000;
@@ -72,6 +74,8 @@ export async function readAttachment(
 	}
 	const handle = Bun.file(join(dir, file));
 	if (!(await handle.exists())) {
+		if (await wasExpired(dir, file))
+			throw new AttachmentExpiredError(plainText(file));
 		throw new Error(`no attachment named "${file}" in this channel`);
 	}
 	let bytes: Uint8Array;

package/src/core/tool-turn.ts

@@ -0,0 +1,37 @@
+import {
+	AttachmentLookupError,
+	openAttachment,
+} from "./attachments/tool-attachment.ts";
+import type { ToolTurn } from "./define.ts";
+import { ToolRefusal } from "./define.ts";
+import { attachReplyFile } from "./reply-files.ts";
+import type { SessionContext } from "./sessions.ts";
+
+/**
+ * The turn a tool's `run` and `hold` receive, built from the session that makes the call and the
+ * signal that stops it.
+ */
+export function toolTurn(
+	context: SessionContext,
+	signal: AbortSignal | undefined,
+): ToolTurn {
+	return {
+		speaker: context.speaker(),
+		channel: context.turnChannel,
+		agent: context.agent,
+		signal,
+		...(context.workspace ? { workspace: context.workspace } : {}),
+		attachFile: attachReplyFile,
+		attachment: async (file) => {
+			if (context.attachmentDir === undefined)
+				throw new ToolRefusal("this session keeps no attachments");
+			try {
+				return await openAttachment(context.attachmentDir, file);
+			} catch (error) {
+				if (error instanceof AttachmentLookupError)
+					throw new ToolRefusal(error.message);
+				throw error;
+			}
+		},
+	};
+}

package/src/index.ts

@@ -16,6 +16,7 @@ export type {
 	GroupStatus,
 	TeamStatus,
 } from "./core/agents/team-status.ts";
+export type { AttachmentRetention } from "./core/attachments/attachment-retention.ts";
 export type { ToolAttachment } from "./core/attachments/tool-attachment.ts";
 export {
 	AGENT_SERVER_PLUGIN,
@@ -26,6 +27,7 @@ export type {
 	AccessOwnerConfig,
 	AccessTierConfig,
 } from "./core/config/access.ts";
+export type { AttachmentsConfig } from "./core/config/attachments.ts";
 export type {
 	AdapterConfig,
 	BackgroundConfig,
@@ -38,6 +40,8 @@ export type {
 	AttachmentPort,
 	AttachmentRefusalCode,
 	AttachmentUpload,
+	ExpiredAttachments,
+	ExpireUsedOptions,
 	TurnAttachmentOptions,
 } from "./core/contract/attachments.ts";
 export { AttachmentRefusal } from "./core/contract/attachments.ts";

package/src/kit/holds.ts

@@ -1,4 +1,5 @@
 // Plugin helpers, versioned like the main entry; see the plugin guide.
-// The chain a host links from every plugin's hold rules, to test a rule set as the host runs it.
+// The chain a host links from every plugin's hold rules, to test a rule set as the host runs it,
+// and how long a hold that looks things up may take.
 
-export { holdChain } from "../core/holds.ts";
+export { HOLD_DESCRIBE_TIMEOUT_MS, holdChain } from "../core/holds.ts";

package/src/kit/index.ts

@@ -52,7 +52,7 @@ export {
 	THINKING_LEVELS,
 	thinkingLabel,
 } from "./domain.ts";
-export { holdChain } from "./holds.ts";
+export { HOLD_DESCRIBE_TIMEOUT_MS, holdChain } from "./holds.ts";
 export type {
 	JevCompactInput,
 	JevCompactOptions,

package/src/testing.ts

@@ -249,7 +249,7 @@ export interface RecordedEvent {
 
 export interface TestPluginResult {
 	contribution: Contribution;
-	/** The hold rules the plugin contributed, chained as the host links them: the description of a call that must be approved first, or undefined. */
+	/** The hold rules the plugin contributed, chained as the host links them: the description of a call that must be approved first, or undefined. `holds.inTurn(tool, input, context, turn)` asks them as a turn does, so a hold that looks things up (and may return a promise) is called with the turn; the plain call has no turn, and counts a hold that declares `turn` as held under `run <tool>`. */
 	holds: HoldCheck;
 	/** What the plugin sees as `context.conversations`, for a test to drive its claims. */
 	conversations: ConversationPort;