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; 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\n${JSON.stringify(selections)}\n`; } 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 { 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(); /** "next" answers given while idle; only their latest revision joins the next run. */ private readonly held = new Set(); private timer: ReturnType | undefined; private readonly notified = new Set(); private readonly waiters = new Set(); 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> { 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((resolve, reject) => { let timer: ReturnType | 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> { 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; } }