@pugi/cli 0.1.0-beta.2 → 0.1.0-beta.20

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

@@ -0,0 +1,213 @@
+/**
+ * AskUserQuestion structured tool — leak L5 (research memo §2.5).
+ *
+ * Mirrors openclaude's `src/tools/AskUserQuestionTool/prompt.ts`
+ * 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;
+/**
+ * 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.'),
+});
+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.'),
+});
+/**
+ * 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.',
+                    },
+                },
+            },
+            description: '2-4 mutually-exclusive options. NEVER add "Other" — UI auto-adds.',
+        },
+        multiSelect: {
+            type: 'boolean',
+            description: 'Allow multiple selections. Default false.',
+        },
+    },
+};
+//# 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 (2026-05-26): 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

package/dist/tools/file-tools.js

@@ -1,9 +1,37 @@
+/**
+ * file-tools - Pugi CLI file/bash/glob/grep tool surface.
+ *
+ * Workspace-binding contract (CEO red-alert 2026-05-27 follow-up):
+ *
+ *   Every tool dispatch path threads `ctx.root` from the operator's
+ *   `process.cwd()` through `EngineTask.workspaceRoot` ->
+ *   `native-pugi.run()` -> `toolCtx.root` -> here. Tools call
+ *   `resolveWorkspacePath(ctx.root, path)` for every on-disk operation
+ *   so a dispatched specialist (e.g. Hiroshi writing tic-tac-toe HTML)
+ *   produces files in the OPERATOR'S cwd, never in a server-side temp
+ *   space. The path-security gate refuses traversal (`../etc/passwd`,
+ *   URL-encoded variants, symlink escapes at the target).
+ *
+ *   Wiring chain:
+ *     1. runtime/cli.ts:    workspaceRoot = process.cwd()
+ *     2. EngineTask.workspaceRoot threads through to native-pugi.run().
+ *     3. native-pugi:       const root = task.workspaceRoot
+ *     4. tool-bridge:       passes ctx.root to file-tools / bash.
+ *     5. file-tools:        resolveWorkspacePath(ctx.root, path).
+ *
+ *   The contract is locked by `test/tools-write-to-workspace.spec.ts`
+ *   (6 cases covering relative + nested + absolute paths + traversal
+ *   refusal). If any layer of the chain regressed silently, dispatched
+ *   files would land in `/tmp` instead of the operator's repo, which
+ *   is the same failure surface as the menu-mode anti-pattern the
+ *   sibling commits close.
+ */
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, relative } from 'node:path';
 import { globSync } from 'node:fs';
 import { decidePermission } from '../core/permission.js';
-import { createReadRecord, hashContent } from '../core/file-cache.js';
+import { StaleReadError, createReadRecord, hashContent, } from '../core/file-cache.js';
 import { resolveWorkspacePath } from '../core/path-security.js';
 import { recordFileMutation, recordToolCall, recordToolResult } from '../core/session.js';
 /**
@@ -19,6 +47,11 @@ export class OperatorAbortedError extends Error {
         this.name = 'OperatorAbortedError';
     }
 }
+// Re-export StaleReadError so tool-bridge / test consumers can import
+// the typed error from a single file-tools surface alongside
+// OperatorAbortedError. Same shape as the existing OperatorAbortedError
+// re-surface pattern.
+export { StaleReadError } from '../core/file-cache.js';
 /**
  * α6.9 WriteGate: refuse the tool dispatch when the active
  * cancellation token has aborted. Idempotent (the token's `isAborted`
@@ -124,10 +157,37 @@ export function writeTool(ctx, path, content) {
         throw error;
     }
     const existed = existsSync(resolved);
-    const before = existed ? readFileSync(resolved, 'utf8') : undefined;
+    // Leak L1 stale-read gate for writeTool's update-existing path. The
+    // model uses writeTool for two distinct intents:
+    //
+    //   - create-new: path does not exist on disk. There is no prior
+    //     read to validate against; skip the gate. This is the
+    //     intentional escape hatch the leak spec also calls out.
+    //   - overwrite-existing: path exists. Without the gate the model
+    //     could blind-clobber an externally-modified file, losing the
+    //     concurrent change silently. Force the model to re-read first.
+    //
+    // We deliberately apply the SAME stale-validation primitive editTool
+    // uses so the two write surfaces stay symmetric and a future fix to
+    // either one cannot accidentally weaken the other.
+    let before;
+    if (existed) {
+        before = readFileSync(resolved, 'utf8');
+        const currentStat = statSync(resolved);
+        const validation = ctx.readCache.validate(ctx.root, path, currentStat.mtimeMs, before);
+        if (validation.stale) {
+            const reason = `stale_read: write ${path} refused — ${validation.detail}`;
+            recordToolResult(ctx.session, toolCallId, 'error', reason);
+            throw new StaleReadError(path, validation.reason, validation.detail);
+        }
+    }
     const tmp = `${resolved}.pugi-tmp-${Date.now()}`;
     writeFileSync(tmp, content, { encoding: 'utf8', mode: 0o600 });
     renameSync(tmp, resolved);
+    // Refresh the cache with the post-write content so the model can
+    // chain a follow-up read+edit on the same file without an extra
+    // round-trip. Same pattern editTool uses below.
+    ctx.readCache.set(createReadRecord(ctx.root, path, content, 'read_tool'));
     recordFileMutation(ctx.session, {
         toolCallId,
         path,
@@ -154,10 +214,6 @@ export function editTool(ctx, path, oldString, newString) {
         recordToolResult(ctx.session, toolCallId, 'error', reason);
         throw new Error(reason);
     }
-    const readRecord = ctx.readCache.get(ctx.root, path);
-    if (!readRecord) {
-        throw new Error(`Cannot edit ${path}: file must be read first`);
-    }
     let resolved;
     try {
         resolved = permissionGatedResolve(ctx, path, 'edit', 'edit');
@@ -167,16 +223,31 @@ export function editTool(ctx, path, oldString, newString) {
         recordToolResult(ctx.session, toolCallId, 'error', reason);
         throw error;
     }
+    // Leak L1 stale-read gate. Validate the model's read-time view of
+    // the file against the on-disk state BEFORE applying the mutation.
+    // We read disk content once and feed it to the validator so a single
+    // syscall covers both the gate decision AND the oldString/newString
+    // replacement below.
     const before = readFileSync(resolved, 'utf8');
-    const currentHash = hashContent(before);
-    if (currentHash !== readRecord.sha256) {
-        throw new Error(`Cannot edit ${path}: file changed since last read`);
+    const currentStat = statSync(resolved);
+    const validation = ctx.readCache.validate(ctx.root, path, currentStat.mtimeMs, before);
+    if (validation.stale) {
+        const reason = `stale_read: edit ${path} refused — ${validation.detail}`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new StaleReadError(path, validation.reason, validation.detail);
     }
+    const currentHash = hashContent(before);
     const matches = before.split(oldString).length - 1;
-    if (matches === 0)
-        throw new Error(`Cannot edit ${path}: oldString not found`);
-    if (matches > 1)
-        throw new Error(`Cannot edit ${path}: oldString is not unique`);
+    if (matches === 0) {
+        const reason = `Cannot edit ${path}: oldString not found`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new Error(reason);
+    }
+    if (matches > 1) {
+        const reason = `Cannot edit ${path}: oldString is not unique`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new Error(reason);
+    }
     const after = before.replace(oldString, newString);
     const tmp = `${resolved}.pugi-tmp-${Date.now()}`;
     writeFileSync(tmp, after, { encoding: 'utf8', mode: 0o600 });