@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/tools/ask-user-question.js

@@ -0,0 +1,337 @@
+/**
+ * AskUserQuestion structured tool — .
+ *
+ * Mirrors the standard structured-question convention
+ * pattern: clarifying questions go through a structured multi-choice
+ * tool, NOT free-text prose. The model dispatches the tool with a
+ * `question` + a `header` chip + 2-4 `options` (each with `label` +
+ * `description`). The UI renders the modal, auto-appends an "Other"
+ * fallback for custom text, and surfaces the operator's pick back to
+ * the model as a tool_result frame.
+ *
+ * Why P0 leverage: the structured form forecloses Pugi's recurring
+ * "agent rambles instead of dispatching" failure mode at the schema
+ * level. When the model is uncertain, the cheapest legal output is
+ * `ask_user_question` — not a prose menu, not a fake "Шипану через
+ * 8 минут" dispatch promise.
+ *
+ * Relationship to ask-user.ts (β1 T2):
+ *  - ask-user.ts is the LEGACY string-array form (`options: string[]`).
+ *    Kept for back-compat; the existing prompt envelope `<pugi-ask>`
+ *    and the persona prompts still emit that grammar.
+ *  - ask-user-question.ts is the STRUCTURED form layered on top. It
+ *    normalises a {label, description} option into the legacy string
+ *    before delegating to `askUser`, so the Ink modal does not need
+ *    two render paths and the abort/timeout race logic is shared.
+ *
+ * Hard rules (enforced by Zod):
+ *  - question: 5-500 chars, must end with "?". Plain English.
+ *  - header: 2-12 chars (short chip label, e.g. "Auth method").
+ *  - options: 2-4 strict (no more, no less). Mutually exclusive.
+ *    UI auto-adds "Other" — the model NEVER emits it.
+ *  - multiSelect: default false.
+ */
+import { z } from 'zod';
+import { askUser } from './ask-user.js';
+/** Cap matches the Ink modal layout: 12 chars fits the header chip. */
+export const ASK_USER_QUESTION_HEADER_MIN = 2;
+export const ASK_USER_QUESTION_HEADER_MAX = 12;
+/** Question must be a real question (ends with ?). 5-500 chars. */
+export const ASK_USER_QUESTION_MIN = 5;
+export const ASK_USER_QUESTION_MAX = 500;
+/** Each option label: 2-40 chars (1-5 words). */
+export const ASK_USER_QUESTION_OPTION_LABEL_MIN = 2;
+export const ASK_USER_QUESTION_OPTION_LABEL_MAX = 40;
+/** Each option description: 10-200 chars (one short sentence). */
+export const ASK_USER_QUESTION_OPTION_DESC_MIN = 10;
+export const ASK_USER_QUESTION_OPTION_DESC_MAX = 200;
+/** Option count: 2-4 strict. UI adds "Other" automatically. */
+export const ASK_USER_QUESTION_OPTIONS_MIN = 2;
+export const ASK_USER_QUESTION_OPTIONS_MAX = 4;
+/**
+ * Preview pane cap (PUGI-130). Lets the model attach a multi-line
+ * ASCII / code / diagram preview to an option. When ANY option в a
+ * single-select question carries `preview`, the UI switches к
+ * side-by-side layout (options column left, preview pane right).
+ *
+ * Capped at 5000 chars так что a single payload can stash a full
+ * component sketch / SQL migration / diagram, but не enough rope для
+ * a model to dump the entire codebase в a preview field.
+ *
+ * **multiSelect rule:** previews are REJECTED on multi-select questions.
+ * Rendering N preview panes simultaneously breaks the layout invariant
+ * (single 80-col terminal can host ONE side panel, not N). The schema
+ * validator enforces this at the tool boundary с a clear error message.
+ */
+export const ASK_USER_QUESTION_OPTION_PREVIEW_MIN = 1;
+export const ASK_USER_QUESTION_OPTION_PREVIEW_MAX = 5000;
+/** PUGI-480 short-format chip rules: ≤ 5 words / option label, ≤ 3 questions / call. */
+export const ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX = 5;
+export const ASK_USER_QUESTION_CHIPS_MAX = 3;
+/**
+ * Reusable validator for option labels rendered в chip mode.
+ * Counts whitespace-delimited words. Throws с a clear message that
+ * names the offending question + option so the model can self-correct.
+ */
+export function assertChipLabelWordCap(questionHeader, optionLabel) {
+    const words = optionLabel.trim().split(/\s+/u).filter((w) => w.length > 0);
+    if (words.length > ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX) {
+        throw new Error(`ask_user_question chip "${questionHeader}" option "${optionLabel}" ` +
+            `exceeds the ${ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX}-word label cap ` +
+            `(saw ${words.length} words). Shorten the label before dispatch.`);
+    }
+}
+/**
+ * Structured option. `label` is the display text; `description` is the
+ * implication line shown dim below it. Both are required — the model
+ * cannot ship a label-only option (forces it to think about why each
+ * choice exists).
+ */
+export const askUserQuestionOptionSchema = z.strictObject({
+    label: z
+        .string()
+        .min(ASK_USER_QUESTION_OPTION_LABEL_MIN)
+        .max(ASK_USER_QUESTION_OPTION_LABEL_MAX)
+        .describe('Display text. Concise (1-5 words).'),
+    description: z
+        .string()
+        .min(ASK_USER_QUESTION_OPTION_DESC_MIN)
+        .max(ASK_USER_QUESTION_OPTION_DESC_MAX)
+        .describe('What this option means / implications.'),
+    preview: z
+        .string()
+        .min(ASK_USER_QUESTION_OPTION_PREVIEW_MIN)
+        .max(ASK_USER_QUESTION_OPTION_PREVIEW_MAX)
+        .optional()
+        .describe('Optional ASCII / code preview (≤ 5000 chars, multi-line OK). When ' +
+        'ANY option in the set carries this field, the UI switches к ' +
+        'side-by-side layout (options column left, preview pane right). ' +
+        'Use для visual comparison of mockups, config snippets, diagram ' +
+        'variations. REJECTED on multiSelect questions (one pane fits one ' +
+        'preview).'),
+});
+export const askUserQuestionSchema = z
+    .strictObject({
+    question: z
+        .string()
+        .min(ASK_USER_QUESTION_MIN)
+        .max(ASK_USER_QUESTION_MAX)
+        .refine((q) => q.trim().endsWith('?'), {
+        message: 'question must end with "?"',
+    })
+        .describe('The complete question. Must end with "?". Plain English, no jargon.'),
+    header: z
+        .string()
+        .min(ASK_USER_QUESTION_HEADER_MIN)
+        .max(ASK_USER_QUESTION_HEADER_MAX)
+        .describe('Short chip label (max 12 chars). E.g. "Auth method".'),
+    options: z
+        .array(askUserQuestionOptionSchema)
+        .min(ASK_USER_QUESTION_OPTIONS_MIN)
+        .max(ASK_USER_QUESTION_OPTIONS_MAX)
+        .describe('2-4 mutually-exclusive options. NEVER add "Other" — UI auto-adds.'),
+    multiSelect: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Allow multiple selections. Default false.'),
+})
+    .superRefine((payload, ctx) => {
+    // PUGI-130 invariant: previews are single-pane only. Side-by-side
+    // layout can host ONE preview at a time; multiSelect implies the
+    // operator may toggle several options and each would want its own
+    // pane. Reject at the schema boundary so the model gets immediate
+    // feedback instead of a silently dropped preview field at render.
+    if (payload.multiSelect === true) {
+        payload.options.forEach((opt, idx) => {
+            if (typeof opt.preview === 'string' && opt.preview.length > 0) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['options', idx, 'preview'],
+                    message: 'preview is not allowed on multiSelect questions — ' +
+                        'side-by-side layout supports ONE preview pane at a time. ' +
+                        'Drop the preview field OR switch к single-select.',
+                });
+            }
+        });
+    }
+});
+/**
+ * PUGI-480 multi-question chip payload — a bundle of up to 3 short-format
+ * chip questions rendered side-by-side. Schema is intentionally narrow:
+ * the chip renderer relies on the ≤ 5-word label invariant и will
+ * truncate с "…" if the model ever bypasses Zod. The 3-question cap
+ * forecloses paragraph-wall prompts at the schema level — the model
+ * cannot legally ask "10 quick questions" in one shot.
+ */
+export const askUserQuestionChipsQuestionSchema = z.strictObject({
+    header: z
+        .string()
+        .min(ASK_USER_QUESTION_HEADER_MIN)
+        .max(ASK_USER_QUESTION_HEADER_MAX)
+        .describe('Short chip label (max 12 chars). E.g. "Stack".'),
+    question: z
+        .string()
+        .min(ASK_USER_QUESTION_MIN)
+        .max(ASK_USER_QUESTION_MAX)
+        .optional()
+        .describe('Optional full-prose question (shown in non-TTY fallback only).'),
+    options: z
+        .array(askUserQuestionOptionSchema)
+        .min(ASK_USER_QUESTION_OPTIONS_MIN)
+        .max(ASK_USER_QUESTION_OPTIONS_MAX + 1)
+        .superRefine((opts, ctx) => {
+        // Enforce ≤ 5-word label cap on every option. Schema-level so
+        // the model gets immediate feedback on overflow rather than a
+        // silent truncation at render time.
+        for (const opt of opts) {
+            const words = opt.label
+                .trim()
+                .split(/\s+/u)
+                .filter((w) => w.length > 0);
+            if (words.length > ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `option "${opt.label}" has ${words.length} words; chip labels must be ≤ ${ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX} words`,
+                });
+            }
+        }
+    })
+        .describe('2-5 mutually-exclusive options. Each label ≤ 5 words. UI inserts "Skip — use defaults" as a final option when defaults are present.'),
+});
+export const askUserQuestionChipsSchema = z.strictObject({
+    questions: z
+        .array(askUserQuestionChipsQuestionSchema)
+        .min(1)
+        .max(ASK_USER_QUESTION_CHIPS_MAX)
+        .describe('Bundle of 1-3 short clarifier questions rendered side-by-side as chips.'),
+});
+/**
+ * Dispatch the structured tool: validate args via Zod, then route
+ * through the shared `askUser` primitive so abort/timeout/non-TTY
+ * envelope behaviour is identical to the legacy form.
+ *
+ * The bridge surface is the same `AskUserBridge` signature — the
+ * structured form just gives the Ink modal richer metadata to render
+ * (header chip + per-option description). The bridge sees the legacy
+ * `{question, options: string[]}` shape because all production bridges
+ * (Ink modal + non-TTY envelope emitter) already consume that shape.
+ * Per-option descriptions and the header chip are surfaced separately
+ * via `enrich` — the modal layer reads them off the dispatched payload
+ * stash, NOT off the bridge input, so structured callers can layer on
+ * top of the legacy interface without touching the modal contract.
+ *
+ * Return contract:
+ *  - Interactive + bridge present + operator picks N options →
+ *    `[ask_user_question:answered] <labels joined by ", ">`.
+ *  - Interactive + bridge present + operator cancels →
+ *    `[ask_user_question:cancelled]`.
+ *  - Interactive + bridge present + timeout →
+ *    `[ask_user_question:timeout]`.
+ *  - Non-TTY or no bridge → `[user_input_required]<json>[/...]`
+ *    envelope identical to the legacy form. Includes `header` +
+ *    structured options so a scripted caller can parse the full shape.
+ */
+export async function dispatchAskUserQuestion(ctx, rawArgs) {
+    const parsed = askUserQuestionSchema.parse(rawArgs);
+    // Schema-level guard against the "Other" leak: the prompt rules tell
+    // the model NEVER to include "Other" in `options`, but we still reject
+    // it defensively in case a future model misreads the spec. The Ink
+    // modal auto-appends "Other" itself; a model-supplied duplicate would
+    // render two "Other" rows.
+    for (const opt of parsed.options) {
+        const trimmed = opt.label.trim().toLowerCase();
+        if (trimmed === 'other' || trimmed === 'другое') {
+            throw new Error('ask_user_question: do NOT include "Other" in options — UI auto-adds it');
+        }
+    }
+    const legacyOptions = parsed.options.map((opt) => opt.label);
+    const result = await askUser(ctx, {
+        question: parsed.question,
+        options: legacyOptions,
+        multiSelect: parsed.multiSelect ?? false,
+    });
+    if (result.answers && result.answers.length > 0) {
+        return {
+            answers: result.answers,
+            envelope: `[ask_user_question:answered] ${result.answers.join(', ')}`,
+        };
+    }
+    // Non-TTY / cancelled / timeout. Re-wrap the envelope so callers can
+    // grep for the structured tool name even when the underlying primitive
+    // surfaced its legacy `[user_input_required]` envelope.
+    if (result.envelope.includes('"reason":"timeout"')) {
+        return { envelope: '[ask_user_question:timeout]' };
+    }
+    if (result.envelope.includes('"reason":"cancelled"')) {
+        return { envelope: '[ask_user_question:cancelled]' };
+    }
+    // Default to the legacy envelope verbatim — it is still
+    // grep-friendly and includes the structured payload above.
+    return { envelope: result.envelope };
+}
+/**
+ * JSON-Schema fragment surfaced to the model via the tool-bridge
+ * `parameters` field. Mirrors the Zod schema 1:1 — kept hand-written
+ * because the runtime engine wires OpenAI-compatible JSON Schema and
+ * the Zod-to-JSON-Schema converter pulls in a transitive dep we have
+ * not greenlit. If the Zod schema above changes, mirror the change here.
+ */
+export const askUserQuestionJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['question', 'header', 'options'],
+    properties: {
+        question: {
+            type: 'string',
+            minLength: ASK_USER_QUESTION_MIN,
+            maxLength: ASK_USER_QUESTION_MAX,
+            description: 'The complete question. Must end with "?". Plain English, no jargon.',
+        },
+        header: {
+            type: 'string',
+            minLength: ASK_USER_QUESTION_HEADER_MIN,
+            maxLength: ASK_USER_QUESTION_HEADER_MAX,
+            description: 'Short chip label (max 12 chars). E.g. "Auth method".',
+        },
+        options: {
+            type: 'array',
+            minItems: ASK_USER_QUESTION_OPTIONS_MIN,
+            maxItems: ASK_USER_QUESTION_OPTIONS_MAX,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['label', 'description'],
+                properties: {
+                    label: {
+                        type: 'string',
+                        minLength: ASK_USER_QUESTION_OPTION_LABEL_MIN,
+                        maxLength: ASK_USER_QUESTION_OPTION_LABEL_MAX,
+                        description: 'Display text. Concise (1-5 words).',
+                    },
+                    description: {
+                        type: 'string',
+                        minLength: ASK_USER_QUESTION_OPTION_DESC_MIN,
+                        maxLength: ASK_USER_QUESTION_OPTION_DESC_MAX,
+                        description: 'What this option means / implications.',
+                    },
+                    preview: {
+                        type: 'string',
+                        minLength: ASK_USER_QUESTION_OPTION_PREVIEW_MIN,
+                        maxLength: ASK_USER_QUESTION_OPTION_PREVIEW_MAX,
+                        description: 'Optional multi-line ASCII / code / diagram preview (≤ 5000 chars). ' +
+                            'When ANY option carries this, UI switches к side-by-side layout. ' +
+                            'Single-select only — REJECTED if multiSelect is true.',
+                    },
+                },
+            },
+            description: '2-4 mutually-exclusive options. NEVER add "Other" — UI auto-adds.',
+        },
+        multiSelect: {
+            type: 'boolean',
+            description: 'Allow multiple selections. Default false. When true, option.preview ' +
+                'is forbidden (one terminal pane fits one preview at a time).',
+        },
+    },
+};
+//# sourceMappingURL=ask-user-question.js.map

package/dist/tools/ask-user.js

@@ -0,0 +1,115 @@
+export const ASK_USER_DEFAULT_TIMEOUT_MS = 5 * 60 * 1_000;
+/**
+ * Schema cap: keep the option count tight so the modal stays scannable.
+ * Mirrors `ASK_MAX_OPTIONS` in `core/repl/ask.ts` (4).
+ */
+export const ASK_USER_MAX_OPTIONS = 4;
+export const ASK_USER_MAX_QUESTION_LEN = 1_000;
+export const ASK_USER_MAX_OPTION_LEN = 200;
+export async function askUser(ctx, input) {
+    validate(input);
+    if (ctx.interactive && ctx.bridge) {
+        // β1a r1 : wrap the bridge in an abort-aware race so a
+        // pending modal cannot block the engine loop forever. Two signals
+        // can interrupt:
+        //  1. `ctx.signal` — the operator cancelled the parent task via
+        //     Ctrl-C; the engine forwards the loop's AbortSignal here.
+        //  2. `ctx.timeoutMs` (default 5 minutes) — operator walked away;
+        //     the modal stays renderable but the tool surface returns the
+        //     `cancelled` envelope so the model can make progress.
+        // The bridge receives the same `signal` so an Ink-based modal can
+        // tear down its render loop and free its keyboard handlers on
+        // abort. Bridges that ignore the signal still get pre-empted by
+        // the race — they just leak a render until the next operator
+        // keystroke.
+        const timeoutMs = ctx.timeoutMs ?? ASK_USER_DEFAULT_TIMEOUT_MS;
+        // Pre-flight: short-circuit when the caller's signal is already
+        // aborted. Avoids constructing a bridge promise that races against
+        // an already-resolved abort sentinel — the race ordering is
+        // unspecified for promises that have all settled by the time
+        // Promise.race is called, which would non-deterministically let
+        // the bridge's answer leak through after an explicit cancel.
+        if (ctx.signal?.aborted) {
+            return { envelope: formatEnvelope(input, 'cancelled') };
+        }
+        const controller = new AbortController();
+        if (ctx.signal) {
+            ctx.signal.addEventListener('abort', () => controller.abort(), { once: true });
+        }
+        let timeoutHandle;
+        const timeoutPromise = new Promise((resolve) => {
+            timeoutHandle = setTimeout(() => resolve('timeout'), timeoutMs);
+        });
+        const abortPromise = new Promise((resolve) => {
+            controller.signal.addEventListener('abort', () => resolve('aborted'), { once: true });
+        });
+        let picked;
+        try {
+            picked = await Promise.race([
+                ctx.bridge(input, { signal: controller.signal }),
+                timeoutPromise,
+                abortPromise,
+            ]);
+        }
+        finally {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+        }
+        if (picked === 'timeout') {
+            controller.abort();
+            return { envelope: formatEnvelope(input, 'timeout') };
+        }
+        if (picked === 'aborted') {
+            return { envelope: formatEnvelope(input, 'cancelled') };
+        }
+        if (!Array.isArray(picked) || picked.length === 0) {
+            // Operator declined / closed the modal — surface a structured
+            // "no answer" envelope so the model can decide whether to retry.
+            const envelope = formatEnvelope(input, 'cancelled');
+            return { envelope };
+        }
+        return {
+            answers: picked,
+            envelope: formatAnswer(picked),
+        };
+    }
+    // Non-TTY or no bridge — surface the envelope. Caller parses it and
+    // either pipes an answer back on a follow-up turn or aborts.
+    const envelope = formatEnvelope(input, 'no_tty');
+    return { envelope };
+}
+function validate(input) {
+    const question = input.question?.trim();
+    if (!question)
+        throw new Error('ask_user: question is required');
+    if (question.length > ASK_USER_MAX_QUESTION_LEN) {
+        throw new Error(`ask_user: question exceeds ${ASK_USER_MAX_QUESTION_LEN} char cap`);
+    }
+    if (!Array.isArray(input.options) || input.options.length < 2) {
+        throw new Error('ask_user: at least 2 options required');
+    }
+    if (input.options.length > ASK_USER_MAX_OPTIONS) {
+        throw new Error(`ask_user: at most ${ASK_USER_MAX_OPTIONS} options allowed`);
+    }
+    for (const opt of input.options) {
+        if (typeof opt !== 'string' || !opt.trim()) {
+            throw new Error('ask_user: every option must be a non-empty string');
+        }
+        if (opt.length > ASK_USER_MAX_OPTION_LEN) {
+            throw new Error(`ask_user: option exceeds ${ASK_USER_MAX_OPTION_LEN} char cap`);
+        }
+    }
+}
+function formatEnvelope(input, reason) {
+    const payload = {
+        question: input.question,
+        options: input.options,
+        multiSelect: input.multiSelect === true,
+        reason,
+    };
+    return `[user_input_required]${JSON.stringify(payload)}[/user_input_required]`;
+}
+function formatAnswer(answers) {
+    return answers.join(', ');
+}
+//# sourceMappingURL=ask-user.js.map