@black942026/pi-ask-user 0.0.0-stage → 0.1.1

package/src/core.ts

@@ -0,0 +1,322 @@
+import { combineSignals, createDeadline, safeTimeoutMs } from "./deadline.ts";
+import { AskUserValidationError, normalizeAskUserRequest } from "./schema.ts";
+import type {
+	AskUIInput,
+	AskUIOutcome,
+	AskUserResult,
+	AskUserSupport,
+	AskUserOptions,
+	AskUserUiPreferences,
+	NormalizedRequest,
+} from "./types.ts";
+
+function messageOf(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Apply the host's user-configured UI preferences over a normalized request.
+ *
+ * Precedence, per knob: explicit user preference > request value > built-in
+ * default (the latter already baked into the normalized request by the schema).
+ * The timeout is recomputed from the effective per-question value so the single
+ * shared deadline stays `timeoutPerQuestionMs × questionCount`.
+ */
+function applyPreferences(request: NormalizedRequest, preferences: AskUserUiPreferences | undefined): NormalizedRequest {
+	if (!preferences) return request;
+	const displayMode = preferences.displayMode ?? request.displayMode;
+	const timeoutPerQuestionMs = preferences.timeoutPerQuestionMs ?? request.timeoutPerQuestionMs;
+	if (displayMode === request.displayMode && timeoutPerQuestionMs === request.timeoutPerQuestionMs) return request;
+	return {
+		...request,
+		displayMode,
+		timeoutPerQuestionMs,
+		totalTimeoutMs: timeoutPerQuestionMs * request.questions.length,
+	};
+}
+
+/**
+ * The single reusable entry point. Accepts raw (usually model-produced) input,
+ * normalizes it, then runs it through the route the host resolved at creation.
+ *
+ * Import this from another extension to reuse the interaction without going
+ * through the model:
+ *
+ * ```ts
+ * const result = await askUser({ questions: [...] }, { host: createPiHost(ctx) });
+ * ```
+ */
+export async function askUser(raw: unknown, options: AskUserOptions): Promise<AskUserResult> {
+	let request: NormalizedRequest;
+	let warnings: string[] = [];
+	try {
+		const normalized = normalizeAskUserRequest(raw);
+		request = normalized.request;
+		warnings = normalized.warnings;
+	} catch (error) {
+		const message =
+			error instanceof AskUserValidationError ? error.message : `Invalid request: ${messageOf(error)}`;
+		return {
+			status: "error",
+			answers: [],
+			error: { code: "invalid_request", message },
+		};
+	}
+	return askUserNormalized(request, options, warnings);
+}
+
+/** Like {@link askUser}, but for an already-normalized request. */
+export async function askUserNormalized(
+	request: NormalizedRequest,
+	options: AskUserOptions,
+	warnings: string[] = [],
+): Promise<AskUserResult> {
+	const { host, signal, onUpdate, now, events } = options;
+	// The route was resolved once, when the host was created; the core never
+	// re-selects it. A host that cannot prompt here is refused before any
+	// rendering, and never in favour of a different route.
+	const support = host.support;
+	if (support.status !== "available") {
+		return finish(supportErrorResult(support), warnings);
+	}
+	const route = support.route;
+	// Cancellation is checked before any route branch, so an already-aborted call
+	// never renders an interactive UI.
+	if (signal?.aborted) {
+		return finish({ status: "aborted", route, answers: [], cancelledReason: "abort" }, warnings);
+	}
+
+	// User preferences (explicit option over the user config file) win over the
+	// request's own displayMode/timeout; the request wins over the built-in
+	// defaults already applied by the schema.
+	const effectiveRequest = applyPreferences(request, host.preferences);
+	const deadline = createDeadline(effectiveRequest.totalTimeoutMs, now);
+	const deadlineController = new AbortController();
+	const timeoutCancelled = new AbortController();
+	const linked = combineSignals(signal, deadlineController.signal);
+
+	const input: AskUIInput = { request: effectiveRequest, deadline, signal: linked.signal };
+	if (route === "custom") {
+		input.cancelTimeout = () => {
+			if (!deadline.cancel()) return false;
+			timeoutCancelled.abort();
+			return true;
+		};
+	}
+	if (onUpdate) input.onUpdate = onUpdate;
+
+	// Wait events are emitted exactly around a real UI attempt: `waitStarted`
+	// immediately before the renderer is invoked, and `waitEnded` once on the
+	// single settle path. Requests refused before this point emit nothing.
+	let waitStarted = false;
+	const notifyStart = (): void => {
+		if (!events) return;
+		try {
+			events.waitStarted();
+		} catch {
+			// An observer must never break the interaction.
+		}
+		waitStarted = true;
+	};
+	const settle = (result: AskUserResult): AskUserResult => {
+		const finalized = finish(result, warnings);
+		if (waitStarted && events) {
+			try {
+				events.waitEnded(finalized);
+			} catch {
+				// An observer must never break the interaction.
+			}
+		}
+		return finalized;
+	};
+
+	let renderPromise: Promise<AskUIOutcome>;
+	notifyStart();
+	try {
+		if (route === "custom") {
+			if (!host.customUI) throw new Error("customUI capability declared without a renderer");
+			renderPromise = host.customUI.render(input);
+		} else {
+			if (!host.nativeDialogs) throw new Error("nativeDialogs capability declared without a runner");
+			renderPromise = host.nativeDialogs.run(input);
+		}
+	} catch (error) {
+		linked.dispose();
+		return settle(mapOutcome({ kind: "error", message: messageOf(error) }, route, effectiveRequest));
+	}
+
+	// The core owns the guarantee: even a renderer that ignores its AbortSignal
+	// cannot hang the call unless the user explicitly disables the timeout.
+	// The deadline and caller's cancellation are raced independently against
+	// the renderer; a late renderer result is ignored.
+	let race: DeadlineRace;
+	try {
+		race = await raceWithDeadline(
+			renderPromise, deadline.remainingMs(), signal,
+			() => deadlineController.abort(), timeoutCancelled.signal,
+		);
+	} finally {
+		// Always release the listeners installed on the caller's signal.
+		linked.dispose();
+	}
+
+	if (race.kind === "timeout") {
+		deadlineController.abort();
+		return settle({ status: "timeout", route, answers: [] });
+	}
+	if (race.kind === "abort") {
+		deadlineController.abort();
+		return settle({ status: "aborted", route, answers: [], cancelledReason: "abort" });
+	}
+
+	let outcome = race.outcome;
+	// A dismissal that coincides with the shared deadline is a timeout.
+	if ((outcome.kind === "cancelled" || outcome.kind === "abort") && deadline.expired()) {
+		outcome = { kind: "timeout" };
+	}
+
+	return settle(mapOutcome(outcome, route, effectiveRequest));
+}
+
+type DeadlineRace =
+	| { kind: "outcome"; outcome: AskUIOutcome }
+	| { kind: "timeout" }
+	| { kind: "abort" };
+
+/**
+ * Race a renderer against the deadline and the caller's abort signal.
+ *
+ * This is what makes the timeout guarantee independent of renderer behaviour: a
+ * renderer that never resolves (or that ignores its signal) still yields
+ * `timeout`, unless the user explicitly cancels the timeout. Late results are
+ * discarded, and the rejection path is always
+ * handled so a late failure cannot become an unhandled rejection.
+ */
+function raceWithDeadline(
+	render: Promise<AskUIOutcome>,
+	remainingMs: number,
+	callerSignal: AbortSignal | undefined,
+	onDeadline: () => void,
+	timeoutCancelled: AbortSignal,
+): Promise<DeadlineRace> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let abortHandler: (() => void) | undefined;
+	const clearDeadlineTimer = (): void => {
+		if (timer !== undefined) clearTimeout(timer);
+		timer = undefined;
+	};
+	const racers: Array<Promise<DeadlineRace>> = [
+		render.then(
+			(outcome): DeadlineRace => ({ kind: "outcome", outcome }),
+			(error): DeadlineRace => ({ kind: "outcome", outcome: { kind: "error", message: messageOf(error) } }),
+		),
+		new Promise<DeadlineRace>((resolve) => {
+			// Cancellation may happen synchronously during renderer construction.
+			if (timeoutCancelled.aborted) return;
+			timeoutCancelled.addEventListener("abort", clearDeadlineTimer, { once: true });
+			// `safeTimeoutMs` prevents a >32-bit delay from firing immediately.
+			timer = setTimeout(() => {
+				onDeadline();
+				resolve({ kind: "timeout" });
+			}, safeTimeoutMs(remainingMs));
+		}),
+	];
+	if (callerSignal) {
+		racers.push(
+			new Promise<DeadlineRace>((resolve) => {
+				if (callerSignal.aborted) {
+					resolve({ kind: "abort" });
+					return;
+				}
+				abortHandler = () => resolve({ kind: "abort" });
+				callerSignal.addEventListener("abort", abortHandler, { once: true });
+			}),
+		);
+	}
+	return Promise.race(racers).finally(() => {
+		clearDeadlineTimer();
+		timeoutCancelled.removeEventListener("abort", clearDeadlineTimer);
+		// Remove the listener when the render settled first, so repeated calls do
+		// not accumulate listeners on a long-lived caller signal.
+		if (abortHandler && callerSignal) callerSignal.removeEventListener("abort", abortHandler);
+	});
+}
+
+/**
+ * Turn a non-`available` support status into the matching error result.
+ *
+ * Nothing is rendered and no question is asked. An explicitly configured route
+ * that cannot run is reported as `unsupported_mode` and names that requested
+ * route; an environment with no usable UI reports `unsupported_mode` with no
+ * route at all, so no default is ever fabricated.
+ */
+function supportErrorResult(support: Exclude<AskUserSupport, { status: "available" }>): AskUserResult {
+	if (support.status === "invalid_config") {
+		return { status: "error", answers: [], error: { code: "invalid_config", message: support.reason } };
+	}
+	if (support.status === "configured_unavailable") {
+		return {
+			status: "error",
+			route: support.configured,
+			answers: [],
+			error: { code: "unsupported_mode", message: support.reason },
+		};
+	}
+	return { status: "error", answers: [], error: { code: "unsupported_mode", message: support.reason } };
+}
+
+function mapOutcome(
+	outcome: AskUIOutcome,
+	route: "custom" | "native",
+	request: NormalizedRequest,
+): AskUserResult {
+	switch (outcome.kind) {
+		case "submitted": {
+			const answers = outcome.answers ?? [];
+			if (answers.length !== request.questions.length) {
+				return {
+					status: "error",
+					route,
+					answers,
+					error: {
+						code: "internal",
+						message: `${route} UI returned ${answers.length} answers, expected ${request.questions.length}.`,
+					},
+				};
+			}
+			const empty = answers.find(
+				(answer) => answer.selections.length === 0 && (answer.freeText ?? "").trim() === "",
+			);
+			if (empty) {
+				return {
+					status: "error",
+					route,
+					answers,
+					error: { code: "empty_answer", message: `The answer to question "${empty.title}" is empty.` },
+				};
+			}
+			return { status: "answered", route, answers };
+		}
+		case "cancelled":
+			return { status: "aborted", route, answers: [], cancelledReason: "user" };
+		case "abort":
+			return { status: "aborted", route, answers: [], cancelledReason: "abort" };
+		case "timeout":
+			return { status: "timeout", route, answers: [] };
+		case "error":
+			return {
+				status: "error",
+				route,
+				answers: [],
+				error: {
+					code: route === "custom" ? "custom_ui_failed" : "native_ui_failed",
+					message: outcome.message ?? `${route} UI failed.`,
+				},
+			};
+	}
+}
+
+function finish(result: AskUserResult, warnings: string[]): AskUserResult {
+	if (warnings.length > 0) result.warnings = warnings;
+	return result;
+}

package/src/deadline.ts

@@ -0,0 +1,94 @@
+import type { Deadline } from "./types.ts";
+
+/**
+ * Largest delay Node's `setTimeout` accepts (a 32-bit signed integer). Larger
+ * values are clamped by Node to ~1 ms, which would fire a timer immediately and
+ * turn a huge timeout into an instant one. We clamp instead.
+ */
+export const MAX_SAFE_TIMEOUT_MS = 2_147_483_647;
+
+/** Clamp a requested timeout to a value `setTimeout` can honour. */
+export function safeTimeoutMs(ms: number): number {
+	if (!Number.isFinite(ms) || ms <= 0) return 0;
+	return Math.min(Math.floor(ms), MAX_SAFE_TIMEOUT_MS);
+}
+
+/** A shared deadline that the user can disable for the current questionnaire. */
+export interface CancellableDeadline extends Deadline {
+	/** Disable expiry. Returns false if the deadline has already expired. */
+	cancel(): boolean;
+}
+
+/**
+ * Create a single overall deadline for a questionnaire.
+ *
+ * The initial deadline is `totalMs` (which callers compute as
+ * `timeoutPerQuestionMs × questionCount`). It is clamped to
+ * {@link MAX_SAFE_TIMEOUT_MS} so `setTimeout` never overflows. Every interaction
+ * for the questionnaire shares this one deadline; native dialogs receive only
+ * the remaining time. `cancel()` disables expiry but does not clear any timers;
+ * the core and custom UI clear their timers separately. A deadline never
+ * degrades to another route.
+ */
+export function createDeadline(totalMs: number, now: () => number = Date.now): CancellableDeadline {
+	const startedAt = now();
+	const safeTotal = safeTimeoutMs(totalMs);
+	const expiresAt = safeTotal === 0 ? startedAt : startedAt + safeTotal;
+	let cancelled = false;
+	return {
+		startedAt,
+		get expiresAt(): number {
+			return cancelled ? Infinity : expiresAt;
+		},
+		remainingMs(): number {
+			return cancelled ? Infinity : Math.max(0, expiresAt - now());
+		},
+		expired(): boolean {
+			return !cancelled && now() >= expiresAt;
+		},
+		cancel(): boolean {
+			if (!cancelled && now() >= expiresAt) return false;
+			cancelled = true;
+			return true;
+		},
+	};
+}
+
+/** A signal plus the cleanup for the listeners it installed on its sources. */
+export interface LinkedSignal {
+	signal: AbortSignal;
+	/** Remove listeners from the source signals. Idempotent. */
+	dispose(): void;
+}
+
+/**
+ * Combine the caller's abort signal with a deadline-driven abort signal.
+ *
+ * Unlike `AbortSignal.any`, this returns an explicit `dispose()` so listeners
+ * installed on the caller's signal are removed once the interaction settles and
+ * do not accumulate across repeated calls.
+ */
+export function combineSignals(caller: AbortSignal | undefined, deadlineSignal: AbortSignal): LinkedSignal {
+	const controller = new AbortController();
+	const onDeadline = () => controller.abort(deadlineSignal.reason);
+	const onCaller = () => controller.abort(caller?.reason);
+	let disposed = false;
+
+	if (deadlineSignal.aborted) controller.abort(deadlineSignal.reason);
+	else deadlineSignal.addEventListener("abort", onDeadline, { once: true });
+
+	if (caller) {
+		if (caller.aborted) controller.abort(caller.reason);
+		else caller.addEventListener("abort", onCaller, { once: true });
+	}
+
+	return {
+		signal: controller.signal,
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			deadlineSignal.removeEventListener("abort", onDeadline);
+			if (caller) caller.removeEventListener("abort", onCaller);
+		},
+	};
+}

package/src/events.ts

@@ -0,0 +1,96 @@
+/**
+ * Runtime event emission for the registered `ask_user` tool.
+ *
+ * These events carry *result semantics* that Pi's generic `ui_prompt_start` /
+ * `ui_prompt_end` do not: whether the wait ended with an answer, a dismissal, a
+ * timeout, or an error — and through which route.
+ *
+ * Two families are emitted:
+ *
+ *  1. `herdr:blocked` — `{ active: true, label, callId? }` only when the tool is
+ *     actually entering the interactive wait, and exactly one matching
+ *     `{ active: false, callId? }` afterwards, for every outcome (answered,
+ *     aborted, timeout, error). Invalid or unavailable requests never emit it,
+ *     because no UI is attempted.
+ *  2. `ask:answered` / `ask:aborted` / `ask:timeout` / `ask:error` — exactly once
+ *     per UI attempt, carrying the correlation id and the route/status. By
+ *     default the full question, answers, and free text are **never** broadcast;
+ *     only non-sensitive metadata leaves the extension.
+ *
+ * A direct {@link createAskUser} caller has no Pi event bus; it may inject an
+ * {@link AskUserEventSink} instead (or accept the deliberate absence). This
+ * module never fabricates access to a bus.
+ */
+import type { AskUserEventSink, AskUserResult, AskUserRoute } from "./types.ts";
+
+/** The minimal event-bus surface used here (structurally matches Pi's EventBus). */
+export interface AskEventBus {
+	emit(channel: string, data: unknown): void;
+}
+
+export const HERDR_BLOCKED = "herdr:blocked";
+export const ASK_ANSWERED = "ask:answered";
+export const ASK_ABORTED = "ask:aborted";
+export const ASK_TIMEOUT = "ask:timeout";
+export const ASK_ERROR = "ask:error";
+
+/** Fixed label for the blocked/idle indicator. */
+export const WAITING_LABEL = "Waiting for user response";
+
+function optionalCallId(callId: string | undefined): { callId?: string } {
+	return callId === undefined || callId === "" ? {} : { callId };
+}
+
+/**
+ * Build the Pi event-bus sink for one tool call. Returns `undefined` when no
+ * usable bus is present, so the caller emits nothing rather than faking it.
+ * Emission failures are swallowed: events must never break the interaction.
+ */
+export function createAskEventSink(bus: AskEventBus | undefined, callId?: string): AskUserEventSink | undefined {
+	if (!bus || typeof bus.emit !== "function") return undefined;
+	const emit = (channel: string, data: unknown): void => {
+		try {
+			bus.emit(channel, data);
+		} catch {
+			// An observer must never break the interaction.
+		}
+	};
+	return {
+		waitStarted(): void {
+			emit(HERDR_BLOCKED, { active: true, label: WAITING_LABEL, ...optionalCallId(callId) });
+		},
+		waitEnded(result: AskUserResult): void {
+			emit(HERDR_BLOCKED, { active: false, ...optionalCallId(callId) });
+			const correlation: { callId?: string; route?: AskUserRoute } = { ...optionalCallId(callId) };
+			if (result.route !== undefined) correlation.route = result.route;
+			switch (result.status) {
+				case "answered":
+					emit(ASK_ANSWERED, { ...correlation, status: "answered" });
+					break;
+				case "aborted":
+					emit(ASK_ABORTED, { ...correlation, status: "aborted", cancelledReason: result.cancelledReason ?? "user" });
+					break;
+				case "timeout":
+					emit(ASK_TIMEOUT, { ...correlation, status: "timeout" });
+					break;
+				case "error":
+					emit(ASK_ERROR, { ...correlation, status: "error", errorCode: result.error?.code });
+					break;
+			}
+		},
+	};
+}
+
+/** The outcome-event channel for a status, exposed for documentation/tests. */
+export function outcomeChannel(status: AskUserResult["status"]): string {
+	switch (status) {
+		case "answered":
+			return ASK_ANSWERED;
+		case "aborted":
+			return ASK_ABORTED;
+		case "timeout":
+			return ASK_TIMEOUT;
+		case "error":
+			return ASK_ERROR;
+	}
+}