repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/ephemlets/runtime.ts
Rawimport 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;
}
}