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

package/src/schema.ts

@@ -0,0 +1,255 @@
+import { Type } from "typebox";
+import type { AskUserOption, AskUserQuestion, NormalizedQuestion, NormalizedRequest, QuestionKind } from "./types.ts";
+
+export const MAX_QUESTIONS = 5;
+export const MAX_OPTIONS = 5;
+export const DEFAULT_TIMEOUT_PER_QUESTION_MS = 60_000;
+
+export const LIMITS = {
+	title: 200,
+	prompt: 500,
+	label: 80,
+	description: 240,
+	preview: 4000,
+	defaultValue: 500,
+	header: 200,
+} as const;
+
+const ID_MAX_LENGTH = 64;
+const QUESTION_KINDS = ["single", "multi", "input"] as const;
+const QUESTION_FIELDS = ["id", "title", "prompt", "kind", "options", "default"] as const;
+const OPTION_FIELDS = ["label", "description", "preview"] as const;
+const REQUEST_FIELDS = ["questions", "header", "displayMode", "timeoutPerQuestionMs"] as const;
+
+/**
+ * Flat string enum. Emitted as `{ type: "string", enum: [...] }` because some
+ * provider proxies reject `anyOf`/`union` shapes.
+ */
+function StringEnum<T extends readonly string[]>(values: T, options: Record<string, unknown> = {}) {
+	return Type.Unsafe<T[number]>({ type: "string", enum: [...values], ...options });
+}
+
+const OptionSchema = Type.Object({
+	label: Type.String({ minLength: 1, maxLength: LIMITS.label }),
+	description: Type.Optional(Type.String({ maxLength: LIMITS.description })),
+	preview: Type.Optional(Type.String({ maxLength: LIMITS.preview })),
+});
+
+const QuestionSchema = Type.Object({
+	id: Type.Optional(Type.String({ minLength: 1, maxLength: ID_MAX_LENGTH })),
+	title: Type.String({ minLength: 1, maxLength: LIMITS.title }),
+	prompt: Type.Optional(Type.String({ maxLength: LIMITS.prompt })),
+	kind: Type.Optional(StringEnum(QUESTION_KINDS)),
+	options: Type.Optional(Type.Array(OptionSchema, { maxItems: MAX_OPTIONS })),
+	default: Type.Optional(Type.String({ maxLength: LIMITS.defaultValue })),
+});
+
+/**
+ * Parameter schema registered for the `ask_user` tool, and the single input
+ * contract for direct `askUser` calls too. Only these fields and types are read;
+ * anything else is rejected as `invalid_request` rather than coerced.
+ *
+ * The UI route is host configuration, resolved by the host adapter — it is never
+ * part of a request.
+ */
+export const AskUserParams = Type.Object({
+	questions: Type.Array(QuestionSchema, { minItems: 1, maxItems: MAX_QUESTIONS }),
+	header: Type.Optional(Type.String({ maxLength: LIMITS.header })),
+	displayMode: Type.Optional(StringEnum(["overlay", "inline"] as const)),
+	timeoutPerQuestionMs: Type.Optional(Type.Number({ minimum: 0 })),
+});
+
+export class AskUserValidationError extends Error {
+	readonly code = "invalid_request";
+
+	constructor(message: string) {
+		super(message);
+		this.name = "AskUserValidationError";
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Reject any field that is not part of the declared contract. */
+function assertKnownKeys(record: Record<string, unknown>, allowed: readonly string[], where: string): void {
+	for (const key of Object.keys(record)) {
+		if (!allowed.includes(key)) throw new AskUserValidationError(`${where} has an unknown field "${key}".`);
+	}
+}
+
+/** A required, non-empty, length-bounded string; returns the trimmed value. */
+function requireText(value: unknown, where: string, maxLength: number): string {
+	if (typeof value !== "string") throw new AskUserValidationError(`${where} must be a string.`);
+	const text = value.trim();
+	if (text === "") throw new AskUserValidationError(`${where} must not be empty.`);
+	if (text.length > maxLength) throw new AskUserValidationError(`${where} exceeds the ${maxLength}-character limit.`);
+	return text;
+}
+
+/** An optional, length-bounded string; absent stays absent. */
+function optionalText(value: unknown, where: string, maxLength: number): string | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") throw new AskUserValidationError(`${where} must be a string.`);
+	if (value.length > maxLength) throw new AskUserValidationError(`${where} exceeds the ${maxLength}-character limit.`);
+	return value;
+}
+
+function optionalQuestionId(value: unknown, where: string): string | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") throw new AskUserValidationError(`${where} "id" must be a string.`);
+	const id = value.trim();
+	if (id === "") throw new AskUserValidationError(`${where} "id" must not be empty.`);
+	if (id.length > ID_MAX_LENGTH) throw new AskUserValidationError(`${where} "id" exceeds the ${ID_MAX_LENGTH}-character limit.`);
+	return id;
+}
+
+/** A canonical option object: `{ label, description?, preview? }`. */
+function readOption(value: unknown, where: string, position: number): AskUserOption {
+	const at = `${where} option ${position + 1}`;
+	if (!isRecord(value)) throw new AskUserValidationError(`${at} must be an object with a "label".`);
+	assertKnownKeys(value, OPTION_FIELDS, at);
+	const label = requireText(value.label, `${at} label`, LIMITS.label);
+	const option: AskUserOption = { label };
+	const description = optionalText(value.description, `${at} description`, LIMITS.description);
+	if (description !== undefined) option.description = description;
+	const preview = optionalText(value.preview, `${at} preview`, LIMITS.preview);
+	if (preview !== undefined) option.preview = preview;
+	return option;
+}
+
+function readQuestion(value: unknown, index: number): { question: AskUserQuestion; warnings: string[] } {
+	const warnings: string[] = [];
+	const where = `Question ${index + 1}`;
+	if (!isRecord(value)) throw new AskUserValidationError(`${where} must be an object.`);
+	assertKnownKeys(value, QUESTION_FIELDS, where);
+
+	const title = requireText(value.title, `${where} title`, LIMITS.title);
+
+	let kind: QuestionKind | undefined;
+	if (value.kind !== undefined) {
+		if (typeof value.kind !== "string" || !QUESTION_KINDS.includes(value.kind as QuestionKind)) {
+			throw new AskUserValidationError(`${where} "kind" must be "single", "multi", or "input".`);
+		}
+		kind = value.kind as QuestionKind;
+	}
+
+	const rawOptions = value.options;
+	if (rawOptions !== undefined && !Array.isArray(rawOptions)) {
+		throw new AskUserValidationError(`${where} "options" must be an array.`);
+	}
+	const rawOptionList = rawOptions ?? [];
+	if (rawOptionList.length > MAX_OPTIONS) {
+		throw new AskUserValidationError(`${where} has more than ${MAX_OPTIONS} options.`);
+	}
+
+	const options: AskUserOption[] = [];
+	const seen = new Set<string>();
+	rawOptionList.forEach((rawOption, position) => {
+		const option = readOption(rawOption, where, position);
+		if (seen.has(option.label)) {
+			warnings.push(`${where} has a duplicate option "${option.label}"; de-duplicated.`);
+			return;
+		}
+		seen.add(option.label);
+		options.push(option);
+	});
+
+	// When `kind` is omitted it is inferred from `options`: present ⇒ `single`,
+	// absent ⇒ `input`. `multi` is only ever explicit.
+	if (kind === undefined) kind = options.length > 0 ? "single" : "input";
+	if (kind !== "input" && options.length === 0) {
+		throw new AskUserValidationError(`${where} is a "${kind}" question but has no options.`);
+	}
+
+	const question: AskUserQuestion = { title, kind };
+	const prompt = optionalText(value.prompt, `${where} prompt`, LIMITS.prompt);
+	if (prompt !== undefined) question.prompt = prompt;
+	if (kind === "input") {
+		delete question.options;
+	} else {
+		question.options = options;
+	}
+	const id = optionalQuestionId(value.id, where);
+	if (id) question.id = id;
+	const fallback = optionalText(value.default, `${where} default`, LIMITS.defaultValue);
+	if (fallback !== undefined) question.default = fallback;
+	return { question, warnings };
+}
+
+function readDisplayMode(value: unknown): "overlay" | "inline" {
+	if (value === undefined) return "overlay";
+	if (value !== "overlay" && value !== "inline") {
+		throw new AskUserValidationError('displayMode must be "overlay" or "inline".');
+	}
+	return value;
+}
+
+function readTimeoutPerQuestionMs(value: unknown): number {
+	if (value === undefined) return DEFAULT_TIMEOUT_PER_QUESTION_MS;
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+		throw new AskUserValidationError("timeoutPerQuestionMs must be a non-negative finite number.");
+	}
+	return Math.floor(value);
+}
+
+/** Normalize and validate a request against the {@link AskUserParams} contract. */
+export function normalizeAskUserRequest(raw: unknown): { request: NormalizedRequest; warnings: string[] } {
+	if (!isRecord(raw)) throw new AskUserValidationError("Missing the questions array.");
+	for (const key of Object.keys(raw)) {
+		if (!REQUEST_FIELDS.includes(key as (typeof REQUEST_FIELDS)[number])) {
+			throw new AskUserValidationError(`Unknown field "${key}".`);
+		}
+	}
+	const rawQuestions = raw.questions;
+	if (!Array.isArray(rawQuestions)) throw new AskUserValidationError("Missing the questions array.");
+	if (rawQuestions.length === 0) throw new AskUserValidationError("At least 1 question is required.");
+	if (rawQuestions.length > MAX_QUESTIONS) {
+		throw new AskUserValidationError(`At most ${MAX_QUESTIONS} questions; received ${rawQuestions.length}.`);
+	}
+
+	const warnings: string[] = [];
+	const usedIds = new Set<string>();
+	const questions: NormalizedQuestion[] = [];
+	rawQuestions.forEach((rawQuestion, index) => {
+		const { question, warnings: questionWarnings } = readQuestion(rawQuestion, index);
+		warnings.push(...questionWarnings);
+
+		let id = question.id ?? "";
+		if (id === "" || usedIds.has(id)) {
+			let candidate = `q${index + 1}`;
+			let suffix = 1;
+			while (usedIds.has(candidate)) {
+				candidate = `q${index + 1}_${suffix++}`;
+			}
+			id = candidate;
+		}
+		usedIds.add(id);
+
+		const normalized: NormalizedQuestion = {
+			id,
+			index,
+			title: question.title,
+			kind: question.kind,
+			options: question.options ?? [],
+			hasDefault: question.default !== undefined,
+		};
+		if (question.prompt !== undefined) normalized.prompt = question.prompt;
+		if (question.default !== undefined) normalized.default = question.default;
+		questions.push(normalized);
+	});
+
+	const header = optionalText(raw.header, "header", LIMITS.header);
+	const displayMode = readDisplayMode(raw.displayMode);
+	const timeoutPerQuestionMs = readTimeoutPerQuestionMs(raw.timeoutPerQuestionMs);
+
+	const request: NormalizedRequest = {
+		questions,
+		displayMode,
+		timeoutPerQuestionMs,
+		totalTimeoutMs: timeoutPerQuestionMs * questions.length,
+	};
+	if (header !== undefined) request.header = header;
+	return { request, warnings };
+}

package/src/types.ts

@@ -0,0 +1,345 @@
+/**
+ * Public types for AskUser.
+ *
+ * AskUser is a host-adaptive "ask the user" interaction primitive. A request is
+ * answered through one of two routes:
+ *
+ *  - `custom` — a custom terminal UI (only a real Pi TUI)
+ *  - `native` — native input dialogs (`ctx.hasUI` + callable input), one question
+ *    at a time
+ *
+ * The route is resolved **once, when the host adapter is created**, from
+ * trustworthy inputs only:
+ *
+ *  1. an explicit configured `mode`, which wins whenever it is supplied, or
+ *  2. otherwise an initialisation-time probe of the bound implementations —
+ *     `custom` when both can run, `native` when only that can run.
+ *
+ * If an explicitly configured route cannot run here, it is reported as
+ * unsupported; the probe result is never substituted for it. If nothing can
+ * run, there is no route at all. The model's tool parameters can never
+ * influence any of this.
+ *
+ * Capabilities remain bound to a concrete implementation object, so a route
+ * cannot be declared without something that actually performs it.
+ */
+
+/** The kind of question. */
+export type QuestionKind = "single" | "multi" | "input";
+
+/** Custom-UI presentation: floating overlay or inline prompt area. */
+export type AskUserDisplayMode = "overlay" | "inline";
+
+/** One selectable option. `preview` is rendered only by the custom UI. */
+export interface AskUserOption {
+	/** Short label shown in the list and returned as the answer value. */
+	label: string;
+	/** One-line explanation rendered next to the label. */
+	description?: string;
+	/** Optional Markdown preview. Custom UI only; never shown on the native route. */
+	preview?: string;
+}
+
+/** One question in a questionnaire. */
+export interface AskUserQuestion {
+	/** Stable id. Generated (`q1`, `q2`, ...) when omitted. */
+	id?: string;
+	/** Question heading (required). */
+	title: string;
+	/** Optional extra hint or context rendered under the heading. */
+	prompt?: string;
+	/** `single` = choose one, `multi` = choose several, `input` = free text only. */
+	kind: QuestionKind;
+	/** 1..5 options. Required for `single`/`multi`; ignored for `input`. */
+	options?: AskUserOption[];
+	/**
+	 * Default answer. When present the question may be skipped and the default
+	 * is used; when absent the question must be answered.
+	 */
+	default?: string;
+}
+
+/** A model-facing (or caller-facing) request. */
+export interface AskUserRequest {
+	/** 1..5 questions. */
+	questions: AskUserQuestion[];
+	/** Optional heading shown above the questionnaire. */
+	header?: string;
+	/** Custom-UI presentation. Defaults to `overlay`. */
+	displayMode?: AskUserDisplayMode;
+	/**
+	 * Base timeout per question in milliseconds. Defaults to 60000.
+	 *
+	 * The questionnaire's initial shared deadline is
+	 * `timeoutPerQuestionMs × questionCount`; the user can cancel it in the custom UI.
+	 */
+	timeoutPerQuestionMs?: number;
+}
+
+/** A single resolved answer. */
+export interface AskUserAnswer {
+	index: number;
+	id: string;
+	title: string;
+	kind: QuestionKind;
+	/** Selected option labels. Empty for free-text-only answers. */
+	selections: string[];
+	/** Trailing free-text input, when provided. */
+	freeText?: string;
+	/** True when the answer came from the question default rather than user input. */
+	usedDefault: boolean;
+}
+
+/**
+ * - `answered`  — the user answered through a custom or native UI.
+ * - `aborted`   — the user dismissed the interaction (or the caller aborted).
+ * - `timeout`   — the shared deadline expired before an answer was given.
+ * - `error`     — the renderer failed; or the forced mode is invalid
+ *                 (`invalid_config`) or unsupported here (`unsupported_mode`).
+ *                 Never a fallback to another route.
+ */
+export type AskUserStatus = "answered" | "aborted" | "timeout" | "error";
+export type AskUserRoute = "custom" | "native";
+/**
+ * The configured route a host is asked to use: the same two values as
+ * {@link AskUserRoute}. Configuration never falls back — an unsupported value is
+ * an error.
+ */
+export type AskUserMode = AskUserRoute;
+export type AskUserErrorCode =
+	| "invalid_request"
+	| "custom_ui_failed"
+	| "native_ui_failed"
+	| "empty_answer"
+	| "invalid_config"
+	| "unsupported_mode"
+	| "not_initialized"
+	| "internal";
+
+/** An actionable failure: what went wrong and what to do about it. */
+export interface AskUserError {
+	code: AskUserErrorCode;
+	message: string;
+}
+
+/** Result of {@link askUser}. */
+export interface AskUserResult {
+	status: AskUserStatus;
+	/**
+	 * Which route serviced the request. Absent when no route ran at all
+	 * (`invalid_request`, `invalid_config`, or an environment with no usable UI).
+	 * When an explicitly configured route was refused as unavailable, it names
+	 * that requested route.
+	 */
+	route?: AskUserRoute;
+	answers: AskUserAnswer[];
+	/** Populated when `status === "aborted"`. */
+	cancelledReason?: "user" | "abort";
+	/** Non-fatal normalization notes (e.g. dropped duplicate options). */
+	warnings?: string[];
+	error?: AskUserError;
+}
+
+// ---------------------------------------------------------------------------
+// Host adapter contract
+// ---------------------------------------------------------------------------
+
+/**
+ * Structural capabilities of a host: `customUI` is true only when the adapter
+ * binds a callable custom renderer, `nativeDialogs` only when it binds a
+ * callable native runner. They describe what can really run here; they never
+ * invent a route.
+ */
+export interface HostCapabilities {
+	customUI: boolean;
+	nativeDialogs: boolean;
+}
+
+/** The structural implementation surface probed to derive {@link HostCapabilities}. */
+export interface HostImplementations {
+	customUI?: CustomUIRenderer;
+	nativeDialogs?: NativeDialogRunner;
+}
+
+/**
+ * The outcome of resolving a host's route, computed once at host creation.
+ *
+ * `available` is the probe result (the modes that can really run here), in
+ * priority order with `custom` first. `route` is present only when a request
+ * will actually be serviced — never a fabricated default.
+ */
+export interface AskUserSupportAvailable {
+	status: "available";
+	/** The route a request will be serviced through. */
+	route: AskUserRoute;
+	/** `configured` when an explicit mode was supplied, else `probed`. */
+	source: "configured" | "probed";
+	capabilities: HostCapabilities;
+	available: AskUserRoute[];
+}
+
+/** An explicit mode was configured but cannot run here. No fallback is taken. */
+export interface AskUserSupportConfiguredUnavailable {
+	status: "configured_unavailable";
+	/** The explicitly configured route, which cannot run in this environment. */
+	configured: AskUserRoute;
+	capabilities: HostCapabilities;
+	available: AskUserRoute[];
+	reason: string;
+}
+
+/** Nothing can run here: neither a custom TUI nor native dialogs. */
+export interface AskUserSupportNoUI {
+	status: "no_available_ui";
+	capabilities: HostCapabilities;
+	available: [];
+	reason: string;
+}
+
+/** The configured value is not a known route. */
+export interface AskUserSupportInvalidConfig {
+	status: "invalid_config";
+	capabilities: HostCapabilities;
+	/** What could run here, had the configuration been valid. */
+	available: AskUserRoute[];
+	reason: string;
+}
+
+/**
+ * A discriminated union describing whether — and how — a host can prompt the
+ * user right now, without actually prompting. Narrow on `status`: the `route`
+ * field exists only for `"available"`.
+ */
+export type AskUserSupport =
+	| AskUserSupportAvailable
+	| AskUserSupportConfiguredUnavailable
+	| AskUserSupportNoUI
+	| AskUserSupportInvalidConfig;
+
+/** Shared input passed to custom/native renderers. */
+export interface AskUIInput {
+	request: NormalizedRequest;
+	deadline: Deadline;
+	/** Custom UI only: disable this questionnaire's timeout; false if already expired. */
+	cancelTimeout?: () => boolean;
+	signal?: AbortSignal;
+	/** Report progress such as "Waiting for user input...". */
+	onUpdate?: (text: string) => void;
+}
+
+/** Outcome of an interactive render attempt. */
+export interface AskUIOutcome {
+	kind: "submitted" | "cancelled" | "timeout" | "abort" | "error";
+	answers?: AskUserAnswer[];
+	message?: string;
+}
+
+export interface CustomUIRenderer {
+	/** Render the full questionnaire. Must not silently degrade to another route. */
+	render(input: AskUIInput): Promise<AskUIOutcome>;
+}
+
+export interface NativeDialogRunner {
+	/** Walk the questionnaire one native dialog at a time. Must not degrade. */
+	run(input: AskUIInput): Promise<AskUIOutcome>;
+}
+
+/**
+ * A trusted host adapter. Each declared capability is bound to the object that
+ * implements it: `customUI` is present iff the host really renders custom UI,
+ * `nativeDialogs` is present iff the host really shows native dialogs. There is
+ * no way to declare a capability without the implementation.
+ */
+export interface AskUserHost {
+	name: string;
+	/**
+	 * Resolved once, when this host was created, from the explicit configuration
+	 * and the bound implementations. The core honours it verbatim: it never
+	 * re-selects a route per request.
+	 */
+	support: AskUserSupport;
+	/**
+	 * User-configured UI preferences, resolved once at host creation from the
+	 * explicit options over the user config file. Absent means "nothing
+	 * configured": the request's own `displayMode`/`timeoutPerQuestionMs` then
+	 * applies over the built-in defaults.
+	 */
+	preferences?: AskUserUiPreferences;
+	/** Bound wherever the custom route can really run. */
+	customUI?: CustomUIRenderer;
+	/** Bound wherever the native route can really run. */
+	nativeDialogs?: NativeDialogRunner;
+}
+
+/**
+ * Resolved user presentation preferences (explicit option > config file).
+ *
+ * Every field is optional so the core can distinguish "the user configured
+ * this" from "fall back to the request, then the built-in default":
+ *
+ *  - `displayMode` set  → wins over the request's `displayMode`;
+ *  - `overlayToggleKey` set to `null` → the overlay toggle is disabled;
+ *    absent → the built-in `alt+o` applies;
+ *  - `timeoutPerQuestionMs` set → wins over the request's value.
+ */
+export interface AskUserUiPreferences {
+	displayMode?: AskUserDisplayMode;
+	overlayToggleKey?: string | null;
+	timeoutPerQuestionMs?: number;
+}
+
+/**
+ * Observer of the interactive wait, used for runtime events. `waitStarted` is
+ * called only when a route is actually about to render; `waitEnded` is called
+ * exactly once afterwards for every outcome (answered/aborted/timeout/error).
+ * A request that never enters the UI (invalid, refused, already aborted) emits
+ * neither. Implementations must never throw.
+ */
+export interface AskUserEventSink {
+	waitStarted(): void;
+	waitEnded(result: AskUserResult): void;
+}
+
+/** Options for {@link askUser}. */
+export interface AskUserOptions {
+	host: AskUserHost;
+	signal?: AbortSignal;
+	onUpdate?: (text: string) => void;
+	/** Injectable clock, used by tests. Defaults to `Date.now`. */
+	now?: () => number;
+	/**
+	 * Optional event observer for the interactive wait. The tool supplies a
+	 * Pi event-bus-backed sink; a direct caller may supply its own (or none).
+	 */
+	events?: AskUserEventSink;
+}
+
+// ---------------------------------------------------------------------------
+// Normalized request / deadline
+// ---------------------------------------------------------------------------
+
+export interface NormalizedQuestion {
+	id: string;
+	index: number;
+	title: string;
+	prompt?: string;
+	kind: QuestionKind;
+	options: AskUserOption[];
+	default?: string;
+	hasDefault: boolean;
+}
+
+export interface NormalizedRequest {
+	header?: string;
+	questions: NormalizedQuestion[];
+	displayMode: AskUserDisplayMode;
+	timeoutPerQuestionMs: number;
+	totalTimeoutMs: number;
+}
+
+export interface Deadline {
+	readonly startedAt: number;
+	readonly expiresAt: number;
+	remainingMs(): number;
+	expired(): boolean;
+}