pi-roundtable 0.9.6 → 0.9.8

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

@@ -1,5 +1,5 @@
 import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
-import type { TurnProgress } from "../domain/progress.ts";
+import type { HoldRefusal, TurnProgress } from "../domain/progress.ts";
 
 /** How long text is joined before it is sent, so a fast stream costs a few events a second. */
 export const PROGRESS_INTERVAL_MS = 250;
@@ -19,6 +19,11 @@ export interface ProgressReporter {
 
 export interface ProgressReporterOptions {
 	intervalMs?: number;
+	/**
+	 * Why a hold refused a tool's call, asked when a failed tool ends and read once; the gate that
+	 * refused it is how a surface tells that from a failure.
+	 */
+	refusalOf?: (toolCallId: string) => HoldRefusal | undefined;
 	/** Runs `run` after `ms`; returns a cancel. Replaceable in tests. */
 	setTimer?: (run: () => void, ms: number) => () => void;
 }
@@ -104,7 +109,14 @@ export function progressReporter(
 		toolEnd(id, tool, isError) {
 			if (closed) return;
 			flush();
-			send({ type: "tool_end", id, tool, ok: !isError });
+			const refused = isError ? options.refusalOf?.(id) : undefined;
+			send({
+				type: "tool_end",
+				id,
+				tool,
+				ok: !isError,
+				...(refused ? { refused } : {}),
+			});
 		},
 		close() {
 			if (closed) return;

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

@@ -332,7 +332,7 @@ const CHECKS: readonly Check[] = [
 			answeredOnlyByThem(running, running.subject.owner, "private"),
 	},
 	{
-		name: "a private conversation's approval above the person's tier goes to no one: it expires at once",
+		name: "a private conversation's approval above the person's tier goes to no one: it comes back at once, unshown",
 		applies: (subject) =>
 			subject.surface.prompts !== undefined &&
 			speakerOf(subject).tier !== "owner",
@@ -349,7 +349,8 @@ const CHECKS: readonly Check[] = [
 				Bun.sleep(1000).then(() => "still open" as const),
 			]);
 			expectThat(
-				answer === "expired",
+				// `expired` is what surfaces answered before `unavailable` existed.
+				answer === "unavailable" || answer === "expired",
 				`an approval no one may answer came back ${answer}`,
 			);
 			expectThat(
@@ -444,7 +445,7 @@ 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 expire 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. 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

@@ -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

@@ -118,7 +118,7 @@ export type {
 	InterimTextMode,
 } from "./core/domain/interim.ts";
 export type { TurnConversation, TurnRequest } from "./core/domain/ports.ts";
-export type { TurnProgress } from "./core/domain/progress.ts";
+export type { HoldRefusal, TurnProgress } from "./core/domain/progress.ts";
 export type { DrainOptions } from "./core/drain.ts";
 export {
 	HostStoppingError,
@@ -161,6 +161,8 @@ export type {
 export { SYSTEM_PRINCIPAL } from "./core/identity/principal-store.ts";
 export type {
 	Approval,
+	ApprovalDetails,
+	ApprovalFile,
 	AskOption,
 	LateAnswer,
 	OwnerAnswer,

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,
@@ -158,6 +158,7 @@ export {
 	toolText,
 } from "./tools.ts";
 export type {
+	CardLimits,
 	InterimPosterOptions,
 	McpEndpoint,
 	PromptSlot,
@@ -165,6 +166,7 @@ export type {
 } from "./worker.ts";
 export {
 	approvalCard,
+	approvalDetails,
 	archiveSessions,
 	canonicalJson,
 	InterimPoster,

package/src/kit/worker.ts

@@ -1,10 +1,12 @@
 // Plugin helpers, versioned like the main entry; see the plugin guide.
 // Running a Pi session of your own: MCP servers for it, its work timeout, its held-action cards.
 
+export type { CardLimits } from "../core/runtime/extensions/approval-card.ts";
 export {
 	approvalCard,
-	canonicalJson,
-} from "../core/runtime/extensions/confirmation-gate.ts";
+	approvalDetails,
+} from "../core/runtime/extensions/approval-card.ts";
+export { canonicalJson } from "../core/runtime/extensions/confirmation-gate.ts";
 export type { InterimPosterOptions } from "../core/runtime/interim-text.ts";
 export { InterimPoster } from "../core/runtime/interim-text.ts";
 export type { VirtualServer } from "../core/runtime/mcp.ts";

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;