Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/ephemlets/runtime.ts

Raw
import type { JsonValue } from "@earendil-works/pi-ai";
import type {
	AgentToolResult,
	ExtensionAPI,
	ExtensionContext,
} from "@earendil-works/pi-coding-agent";
import type { IconSet } from "./src/look.ts";
import { PanelHost } from "./src/panel.ts";
import {
	deliveryOf,
	ENTRY_TYPE,
	EphemletStore,
	isChecked,
	needsAnswer,
	optionsOf,
	retainAnswers,
	retainTexts,
	saveMessage,
	validateFields,
} from "./src/store.ts";
import type { Ephemlet, Field } from "./src/types.ts";

export type EphemletParams = {
	action: "put" | "list" | "get" | "delete" | "show" | "hide" | "wait";
	id?: string;
	expectedRevision?: number;
	title?: string;
	purpose?: string;
	source?: string;
	fields?: Field[];
	include?: ("source" | "view" | "answers")[];
	/** Wait only: field IDs to wait for; default every open question. */
	waitFor?: string[];
	timeoutMs?: number;
};

export const DEFAULT_WAIT_MS = 300_000;
export const MAX_WAIT_MS = 1_800_000;

type Waiter = {
	id: string;
	fields: Set<string>;
	answered(): void;
	cancel(error: Error): void;
};

/** Whether the human has given any answer to a field. */
function hasAnswer(record: Ephemlet, field: Field): boolean {
	return field.type === "text"
		? record.texts[field.id] !== undefined
		: record.answers[field.id] !== undefined;
}

type Logger = typeof import("./src/debug.ts").dbg;

export const ANSWER_MESSAGE = "ephemlet-answer";
/** Coalesces rapid clicks into one message so the agent is not steered per keystroke. */
const DELIVERY_DELAY_MS = 800;

function answerMessage(record: Ephemlet): string {
	const selections = record.fields.map((field) =>
		field.type === "text"
			? {
					field: field.id,
					type: field.type,
					text: record.texts[field.id] ?? null,
				}
			: {
					field: field.id,
					type: field.type,
					selected: optionsOf(field)
						.filter((option) => isChecked(record, field, option))
						.map((option) => option.id),
				},
	);
	// Pi may deliver a queued older message after a newer one; the revision orders them.
	return `The human answered in ephemlet "${record.title}" (${record.id}), answer revision ${record.answerRevision}. If several ephemlet-answer messages for it arrive, only the highest revision is current. Selections of all its fields:\n<ephemlet-answers revision="${record.answerRevision}">\n${JSON.stringify(selections)}\n</ephemlet-answers>`;
}

function required(value: string | undefined, name: string): string {
	if (!value?.trim()) throw new Error(`${name} is required`);
	return value;
}
function excerpt(value: string, limit: number): string {
	return value.length > limit ? `${value.slice(0, limit - 1)}…` : value;
}
function metadata(record: Ephemlet) {
	return {
		id: record.id,
		title: record.title,
		purpose: excerpt(record.purpose, 160),
		revision: record.revision,
		...(record.answerRevision > record.seenRevision ? { unseen: true } : {}),
	};
}
/** Effective values plus who set each one, so the agent never guesses. */
function answers(record: Ephemlet) {
	return record.fields.map((field) => ({
		id: field.id,
		type: field.type,
		...(field.label !== undefined ? { label: field.label } : {}),
		...(field.type === "text" ? { text: record.texts[field.id] ?? null } : {}),
		items: optionsOf(field).map((option) => ({
			id: option.id,
			label: option.label,
			checked: isChecked(record, field, option),
			by:
				record.answers[field.id]?.[option.id] === undefined ? "agent" : "user",
		})),
	}));
}
function result(data: unknown): AgentToolResult<unknown> {
	const text = JSON.stringify(data);
	const details: JsonValue = JSON.parse(text);
	return {
		content: [{ type: "text", text }],
		details,
		structuredContent: details,
	};
}

export class EphemletRuntime {
	readonly store: EphemletStore;
	private context: ExtensionContext | undefined;
	private sessionId: string | undefined;
	private panel: PanelHost | undefined;
	private readonly pending = new Set<string>();
	/** "next" answers given while idle; only their latest revision joins the next run. */
	private readonly held = new Set<string>();
	private timer: ReturnType<typeof setTimeout> | undefined;
	private readonly notified = new Set<string>();
	private readonly waiters = new Set<Waiter>();

	constructor(
		private readonly pi: ExtensionAPI,
		private readonly log: Logger,
		/** Resolved from settings at session start. */
		private readonly icons: () => IconSet = () => "nerd",
	) {
		this.store = new EphemletStore((event) =>
			pi.appendEntry(ENTRY_TYPE, event),
		);
	}
	setContext(ctx: ExtensionContext): void {
		this.context = ctx;
	}
	private ctx(): ExtensionContext {
		if (!this.context) throw new Error("No ephemlet session context");
		return this.context;
	}

	restore(ctx: ExtensionContext): void {
		this.dispose();
		this.context = ctx;
		this.sessionId = ctx.sessionManager.getSessionId();
		this.store.replay(ctx.sessionManager.getBranch());
		// Opening a session never restores an overlay over the user's conversation.
		this.store.visible = false;
		if (this.store.records.size) this.refresh(false);
	}

	private refresh(focus: boolean): void {
		if (this.ctx().mode !== "tui") return;
		this.panel ??= new PanelHost(
			this.store,
			() => this.ctx(),
			{
				changed: () => this.panel?.refresh(false),
				close: (id) => {
					this.close(id);
					this.panel?.refresh(true);
				},
				save: (id) => {
					this.pi.sendUserMessage(saveMessage(this.store.get(id)), {
						deliverAs: "followUp",
						expandPromptTemplates: false,
					});
				},
				hide: () => {
					this.store.view(this.store.selected, false);
					this.panel?.refresh();
				},
				answered: (id, fieldId) => this.answered(id, fieldId),
			},
			this.icons,
		);
		this.panel.refresh(focus);
	}

	show(ctx: ExtensionContext): void {
		this.prepare(ctx);
		if (!this.store.records.size) {
			ctx.ui.notify("No ephemlets in this session", "info");
			return;
		}
		this.store.view(
			this.store.selected ?? this.store.records.keys().next().value ?? null,
			true,
		);
		this.refresh(true);
	}
	hide(ctx: ExtensionContext): void {
		this.prepare(ctx);
		this.store.view(this.store.selected, false);
		this.refresh(false);
	}
	toggle(ctx: ExtensionContext): void {
		this.prepare(ctx);
		if (this.store.visible) this.hide(ctx);
		else this.show(ctx);
	}
	private prepare(ctx: ExtensionContext): void {
		if (this.sessionId !== ctx.sessionManager.getSessionId()) this.restore(ctx);
		else this.context = ctx;
	}

	private answered(id: string, fieldId: string): void {
		const field = this.store.records
			.get(id)
			?.fields.find((candidate) => candidate.id === fieldId);
		if (!field) return;
		// An agent blocked in wait gets the answer as its tool result, not as a message.
		const waiters = [...this.waiters].filter(
			(waiter) => waiter.id === id && waiter.fields.has(fieldId),
		);
		for (const waiter of waiters) waiter.answered();
		if (waiters.length || deliveryOf(field) === "ambient") return;
		this.pending.add(id);
		clearTimeout(this.timer);
		this.timer = setTimeout(() => this.deliver(), DELIVERY_DELAY_MS);
	}

	/**
	 * Sends one message per changed ephemlet: a busy agent is steered before its next model call;
	 * an idle agent gets a turn only for "now" answers, otherwise the answer waits for the next run.
	 */
	deliver(): void {
		clearTimeout(this.timer);
		this.timer = undefined;
		const ctx = this.context;
		for (const id of this.pending) {
			const record = this.store.records.get(id);
			if (!ctx || !record || !this.unsent(record)) continue;
			const now = record.fields.some(
				(field) => deliveryOf(field) === "now" && hasAnswer(record, field),
			);
			const idle = ctx.isIdle();
			if (idle && !now) {
				this.held.add(id);
				continue;
			}
			this.held.delete(id);
			this.pi.sendMessage(
				{
					customType: ANSWER_MESSAGE,
					content: answerMessage(record),
					display: true,
					details: { id, answerRevision: record.answerRevision },
				},
				idle ? { triggerTurn: true } : { deliverAs: "steer" },
			);
			this.store.sent.set(id, record.answerRevision);
		}
		this.pending.clear();
		this.panel?.refresh();
	}

	/** Latest held or still-coalescing answers, as one message for the run that is starting. */
	takeHeld():
		| {
				customType: string;
				content: string;
				display: true;
				details: { answers: { id: string; answerRevision: number }[] };
		  }
		| undefined {
		clearTimeout(this.timer);
		this.timer = undefined;
		const records = [...new Set([...this.held, ...this.pending])]
			.map((id) => this.store.records.get(id))
			.filter((record): record is Ephemlet => !!record && this.unsent(record));
		this.held.clear();
		this.pending.clear();
		if (!records.length) return undefined;
		for (const record of records)
			this.store.sent.set(record.id, record.answerRevision);
		this.panel?.refresh();
		return {
			customType: ANSWER_MESSAGE,
			content: records.map(answerMessage).join("\n\n"),
			display: true,
			details: {
				answers: records.map(({ id, answerRevision }) => ({
					id,
					answerRevision,
				})),
			},
		};
	}

	/** Answers the agent has neither been sent nor read. */
	private unsent(record: Ephemlet): boolean {
		return (
			(this.store.sent.get(record.id) ?? 0) < record.answerRevision &&
			record.seenRevision < record.answerRevision
		);
	}

	/** Called with each LLM context: delivered answers there are truly read. */
	markRead(messages: readonly unknown[]): void {
		let changed = false;
		type Answer = { id?: unknown; answerRevision?: unknown };
		for (const message of messages) {
			const m = message as {
				role?: string;
				customType?: string;
				details?: Answer & { answers?: unknown };
			};
			if (m.role !== "custom" || m.customType !== ANSWER_MESSAGE) continue;
			const entries: Answer[] = Array.isArray(m.details?.answers)
				? m.details.answers
				: m.details
					? [m.details]
					: [];
			for (const { id, answerRevision } of entries) {
				if (typeof id !== "string" || typeof answerRevision !== "number")
					continue;
				const before = this.store.records.get(id)?.seenRevision;
				this.store.seen(id, answerRevision);
				changed ||= before !== this.store.records.get(id)?.seenRevision;
			}
		}
		if (changed) this.panel?.refresh();
	}

	/** Blocks only this tool call until an awaited field is answered or time runs out. */
	private async wait(
		params: EphemletParams,
		ctx: ExtensionContext,
		signal: AbortSignal | undefined,
	): Promise<AgentToolResult<unknown>> {
		const record = this.store.get(required(params.id, "id"));
		const fields = params.waitFor
			? params.waitFor.map((fieldId) => {
					const field = record.fields.find(
						(candidate) => candidate.id === fieldId,
					);
					if (!field)
						throw new Error(
							`Unknown field ${fieldId} in ephemlet ${record.id}`,
						);
					return field;
				})
			: record.fields.filter((field) => needsAnswer(record, field));
		const ids = fields
			.filter((field) => needsAnswer(record, field))
			.map((field) => field.id);
		const finish = (timedOut: boolean) => {
			this.pending.delete(record.id);
			this.store.sent.set(record.id, record.answerRevision);
			this.store.seen(record.id);
			this.panel?.refresh();
			return result({
				...metadata(record),
				fields: answers(record),
				timedOut,
			});
		};
		if (!ids.length) return finish(false);
		signal?.throwIfAborted();
		const timeoutMs = Math.min(
			Math.max(1, params.timeoutMs ?? DEFAULT_WAIT_MS),
			MAX_WAIT_MS,
		);
		this.store.waiting.set(record.id, new Set(ids));
		this.refresh(false);
		ctx.ui.notify(
			`Ephemlet "${record.title}": the agent is waiting for your answer · alt+e`,
			"info",
		);
		const timedOut = await new Promise<boolean>((resolve, reject) => {
			let timer: ReturnType<typeof setTimeout> | undefined;
			const onAbort = () =>
				waiter.cancel(
					signal?.reason instanceof Error
						? signal.reason
						: new Error("Aborted"),
				);
			const done = () => {
				clearTimeout(timer);
				signal?.removeEventListener("abort", onAbort);
				this.waiters.delete(waiter);
				this.store.waiting.delete(record.id);
				this.panel?.refresh();
			};
			const waiter: Waiter = {
				id: record.id,
				fields: new Set(ids),
				answered: () => {
					done();
					resolve(false);
				},
				cancel: (error) => {
					done();
					reject(error);
				},
			};
			this.waiters.add(waiter);
			timer = setTimeout(() => {
				done();
				resolve(true);
			}, timeoutMs);
			signal?.addEventListener("abort", onAbort, { once: true });
		});
		return finish(timedOut);
	}

	private close(id: string): void {
		this.store.delete(id);
		this.log?.("ephemlet.delete", { count: this.store.records.size });
	}

	async execute(
		params: EphemletParams,
		ctx: ExtensionContext,
		signal?: AbortSignal,
	): Promise<AgentToolResult<unknown>> {
		this.prepare(ctx);
		if (params.action === "wait") return this.wait(params, ctx, signal);
		if (params.action === "list")
			return result({
				ephemlets: [...this.store.records.values()].map(metadata),
			});
		if (params.action === "get") {
			const record = this.store.get(required(params.id, "id"));
			const withAnswers = params.include?.includes("answers")
				? { fields: answers(record) }
				: {};
			if (params.include?.includes("answers")) {
				this.store.seen(record.id);
				this.panel?.refresh();
			}
			return result({
				...metadata(record),
				...withAnswers,
				...(params.include?.includes("source")
					? { source: record.source }
					: {}),
				...(params.include?.includes("view")
					? {
							view: this.panel?.getView(record.id) ?? {
								available: false,
								reason: "Never rendered",
							},
						}
					: {}),
			});
		}
		if (params.action === "show" || params.action === "hide") {
			if (params.id) this.store.view(params.id, params.action === "show");
			if (params.action === "show") this.show(ctx);
			else this.hide(ctx);
			return result({
				visible: this.store.visible,
				selected: this.store.selected,
			});
		}
		if (params.action === "delete") {
			this.close(required(params.id, "id"));
			this.refresh(false);
			return result({ deleted: params.id });
		}
		const previous = params.id ? this.store.get(params.id) : undefined;
		const title = required(params.title ?? previous?.title, "title");
		const fields = validateFields(params.fields ?? previous?.fields ?? []);
		const dropped = [
			...retainAnswers(previous?.answers ?? {}, fields).dropped,
			...retainTexts(previous?.texts ?? {}, fields).dropped,
		];
		const record = this.store.put({
			...(params.id ? { id: params.id } : {}),
			...(params.expectedRevision !== undefined
				? { expectedRevision: params.expectedRevision }
				: {}),
			title,
			// Purpose is metadata; a missing one must not cost the agent a retry.
			purpose: params.purpose?.trim()
				? params.purpose
				: (previous?.purpose ?? title),
			source: required(params.source ?? previous?.source, "source"),
			fields,
		});
		this.refresh(false);
		for (const field of record.fields) {
			const key = `${record.id}/${field.id}`;
			if (
				deliveryOf(field) === "now" &&
				needsAnswer(record, field) &&
				!this.notified.has(key)
			) {
				this.notified.add(key);
				ctx.ui.notify(
					`Ephemlet "${record.title}" needs your input · alt+e`,
					"info",
				);
			}
		}
		this.log?.("ephemlet.put", { count: this.store.records.size });
		// Human answers win; tell the agent which ones its update discarded.
		return result({
			...metadata(record),
			...(dropped.length ? { droppedAnswers: dropped } : {}),
		});
	}

	dispose(): void {
		for (const waiter of [...this.waiters])
			waiter.cancel(new Error("Ephemlet session ended while waiting"));
		clearTimeout(this.timer);
		this.timer = undefined;
		this.pending.clear();
		this.held.clear();
		this.panel?.dispose();
		this.panel = undefined;
		this.context = undefined;
		this.sessionId = undefined;
	}
}