repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/ask/src/interaction.ts
Rawimport { randomUUID } from "node:crypto";
import type {
EventBus,
ExtensionContext,
} from "@earendil-works/pi-coding-agent";
import type { AskAnswer, AskFlowResult, AskQuestion } from "../ask-tool.js";
const VERSION = 1;
const CLAIM_WINDOW_MS = 150;
const PENDING_LIFETIME_MS = 10 * 60 * 1000;
const MAX_PROVIDER_ID_LENGTH = 128;
const MAX_ANSWER_LENGTH = 4_096;
const MAX_NOTES_LENGTH = 4_096;
const POLLUTION_KEYS = new Set(["__proto__", "constructor", "prototype"]);
type InteractionIds = {
version: typeof VERSION;
id: string;
sessionId: string;
toolCallId: string;
};
export type AskRequest = InteractionIds & { questions: AskQuestion[] };
type CloseStatus = "answered" | "cancelled" | "released" | "expired";
export type AskInteractionResult = AskFlowResult | { status: "expired" };
type InteractionOptions = {
events: EventBus;
questions: AskQuestion[];
ctx: ExtensionContext;
toolCallId: string;
signal?: AbortSignal | undefined;
};
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function matchesIds(value: unknown, ids: InteractionIds): boolean {
return (
isRecord(value) &&
value["version"] === VERSION &&
value["id"] === ids.id &&
value["sessionId"] === ids.sessionId &&
value["toolCallId"] === ids.toolCallId
);
}
function providerId(value: unknown): string | undefined {
if (!isRecord(value) || typeof value["providerId"] !== "string")
return undefined;
const id = value["providerId"].trim();
return id.length > 0 && id.length <= MAX_PROVIDER_ID_LENGTH ? id : undefined;
}
function isPollutionKey(key: string): boolean {
return POLLUTION_KEYS.has(key);
}
function validateAnswers(
value: unknown,
questions: AskQuestion[],
): Record<string, AskAnswer> | undefined {
if (!isRecord(value)) return undefined;
const expected = new Set(questions.map((question) => question.key));
const keys = Object.keys(value);
if (keys.length !== expected.size) return undefined;
for (const key of keys) {
if (isPollutionKey(key) || !expected.has(key)) return undefined;
}
const result = Object.create(null) as Record<string, AskAnswer>;
for (const question of questions) {
const answer = value[question.key];
if (!isRecord(answer) || !Array.isArray(answer["answers"]))
return undefined;
const maximum = question.multiSelect ? question.options.length + 1 : 1;
if (
answer["answers"].length > maximum ||
(!question.multiSelect && answer["answers"].length !== 1)
)
return undefined;
const answers: string[] = [];
const seen = new Set<string>();
for (const candidate of answer["answers"]) {
if (typeof candidate !== "string") return undefined;
const normalized = candidate.trim();
if (normalized.length === 0 || normalized.length > MAX_ANSWER_LENGTH)
return undefined;
if (seen.has(normalized)) return undefined;
seen.add(normalized);
answers.push(normalized);
}
let notes: string | undefined;
if ("notes" in answer) {
if (typeof answer["notes"] !== "string") return undefined;
notes = answer["notes"].trim();
if (notes.length === 0 || notes.length > MAX_NOTES_LENGTH)
return undefined;
}
result[question.key] = notes ? { answers, notes } : { answers };
}
return result;
}
export async function requestAskInteraction(
options: InteractionOptions,
): Promise<AskInteractionResult | undefined> {
const { events, questions, ctx, toolCallId, signal } = options;
if (signal?.aborted) return { status: "cancelled" };
let sessionId: string;
try {
sessionId = ctx.sessionManager.getSessionId();
} catch {
return undefined;
}
const ids: InteractionIds = {
version: VERSION,
id: randomUUID(),
sessionId,
toolCallId,
};
const deadline = Date.now() + PENDING_LIFETIME_MS;
let claimant: string | undefined;
let state: "claiming" | "awaiting" | "done" = "claiming";
let claimTimer: ReturnType<typeof setTimeout> | undefined;
let lifetimeTimer: ReturnType<typeof setTimeout> | undefined;
let settle: ((result: AskInteractionResult | undefined) => void) | undefined;
const unsubscribe = new Set<() => void>();
const cleanup = (): void => {
if (claimTimer) clearTimeout(claimTimer);
if (lifetimeTimer) clearTimeout(lifetimeTimer);
claimTimer = undefined;
lifetimeTimer = undefined;
for (const remove of unsubscribe) remove();
unsubscribe.clear();
};
const emit = (channel: string, value: unknown): void => {
try {
events.emit(channel, value);
} catch {
// A peer failure must not strand this tool call.
}
};
const close = (status: CloseStatus): void => {
if (claimant)
emit("pi-ext:ask:closed", { ...ids, providerId: claimant, status });
};
const finish = (
result: AskInteractionResult | undefined,
status?: CloseStatus,
): void => {
if (state === "done") return;
state = "done";
cleanup();
if (status) close(status);
settle?.(result);
};
unsubscribe.add(
events.on("pi-ext:ask:claim", (value) => {
if (state !== "claiming" || claimant || !matchesIds(value, ids)) return;
const candidate = providerId(value);
if (candidate) claimant = candidate;
}),
);
unsubscribe.add(
events.on("pi-ext:ask:answer", (value) => {
if (state !== "awaiting" || !matchesIds(value, ids)) return;
if (providerId(value) !== claimant || !isRecord(value)) return;
if (Date.now() >= deadline) {
finish({ status: "expired" }, "expired");
return;
}
if (value["status"] === "cancelled") {
finish({ status: "cancelled" }, "cancelled");
return;
}
if (value["status"] !== "answered") return;
const answers = validateAnswers(value["answers"], questions);
if (answers) finish({ status: "answered", answers }, "answered");
}),
);
unsubscribe.add(
events.on("pi-ext:ask:release", (value) => {
if (
(state === "claiming" || state === "awaiting") &&
matchesIds(value, ids) &&
providerId(value) === claimant
)
finish(undefined, "released");
}),
);
const abort = (): void =>
finish({ status: "cancelled" }, claimant ? "cancelled" : undefined);
signal?.addEventListener("abort", abort, { once: true });
unsubscribe.add(() => signal?.removeEventListener("abort", abort));
const outcome = new Promise<AskInteractionResult | undefined>((resolve) => {
settle = resolve;
});
claimTimer = setTimeout(() => {
claimTimer = undefined;
if (state !== "claiming") return;
if (!claimant) {
finish(undefined);
return;
}
state = "awaiting";
emit("pi-ext:ask:claimed", { ...ids, providerId: claimant });
}, CLAIM_WINDOW_MS);
lifetimeTimer = setTimeout(
() =>
finish(
claimant ? { status: "expired" } : undefined,
claimant ? "expired" : undefined,
),
PENDING_LIFETIME_MS,
);
emit("pi-ext:ask:request", { ...ids, questions } satisfies AskRequest);
return await outcome;
}