@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/model/tools/human-input.js

@@ -0,0 +1,265 @@
+/**
+ * The human-input channel (plan-mode §3.5 / §5.1) — types, the fail-closed
+ * default gate, and the two pure normalizers that repair whatever the model
+ * actually sent.
+ *
+ * Everything here is pure except the type declarations: no Ink, no React, no
+ * `node:*`. `tools/` is inside the glyph scanner's scope, so every literal is
+ * ASCII.
+ *
+ * WHY THE NORMALIZERS ARE THE ONLY AUTHORITY ON THE LIMITS (P0-4). The
+ * model-facing schemas in `plan-tools.ts` declare SHAPE only — `type`,
+ * `required`, `default` — and put every bound in the `description`. They used to
+ * carry `minItems` / `maxItems` / `maxLength`, and that had two failure modes at
+ * once: `ToolExecutor` rejected a six-question call outright with `Invalid
+ * parameters: ...` before any repair could run, wasting a full research turn on
+ * a cosmetic defect; and `ajv` is an OPTIONAL dependency of core, so without it
+ * the fallback validator checks `required` plus primitive types only and the
+ * same call sailed through. One design, two behaviours, selected by whether an
+ * optional install step succeeded. Bounds live here instead, where they are
+ * deterministic and unit-tested.
+ */
+import { OTHER_OPTION_LABEL } from '../agent/agent-mode.js';
+/**
+ * Fails CLOSED. The headless default — forgetting to pass a gate must refuse,
+ * never hang and never assume yes.
+ */
+export const DENY_ALL_HUMAN_INPUT = {
+    neverPrompts: true,
+    canPrompt: () => false,
+    request: async () => null,
+};
+// ---------------------------------------------------------------------------
+// Limits (the single authority; see the module header for why not the schema)
+// ---------------------------------------------------------------------------
+export const QUESTION_LIMITS = {
+    maxQuestions: 5,
+    minOptions: 2,
+    maxOptions: 4,
+    headerChars: 12,
+    questionChars: 300,
+    labelChars: 60,
+    optionDescriptionChars: 120,
+};
+export const PLAN_LIMITS = {
+    titleChars: 80,
+    summaryChars: 600,
+    maxSteps: 20,
+    stepTitleChars: 100,
+    stepDetailChars: 400,
+    maxFiles: 30,
+    maxRisks: 10,
+    maxOpenQuestions: 10,
+};
+/**
+ * The STORAGE bound of the `ask_user` de-duplication guard — NOT a refusal
+ * condition, and the distinction is the whole point.
+ *
+ * Storage is memory hygiene: a turn that asks a thousand DISTINCT question sets
+ * is pathological, but it is still the user's turn, and Esc interrupts it. The
+ * refusal rule is semantic: "never ask the same answered questions twice". Folding
+ * the bound into the refusal rule would restore the round cap this feature
+ * deletes, with a different number written on it.
+ *
+ * Owned here rather than in `plan-tools.ts` (the caller) or `controller.ts` (the
+ * state holder) because this file is already the single authority on the
+ * structural limits of human input, beside `QUESTION_LIMITS` / `PLAN_LIMITS`.
+ */
+export const ASK_GUARD_LIMITS = { maxRemembered: 128 };
+/** How far back a truncation will look for a space before cutting hard. */
+const WORD_BOUNDARY_WINDOW = 12;
+// ---------------------------------------------------------------------------
+// Small pure helpers
+// ---------------------------------------------------------------------------
+function asString(value) {
+    return typeof value === 'string' ? value : '';
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+/**
+ * Trim to `max` characters, preferring a word boundary within the last
+ * `WORD_BOUNDARY_WINDOW` characters. Cutting a sentence mid-word reads as
+ * corruption; cutting it at a space reads as a summary.
+ */
+export function clampText(raw, max) {
+    const text = asString(raw).trim();
+    if (text.length <= max)
+        return text;
+    const head = text.slice(0, max);
+    const space = head.lastIndexOf(' ');
+    if (space >= max - WORD_BOUNDARY_WINDOW && space > 0)
+        return head.slice(0, space).trimEnd();
+    return head.trimEnd();
+}
+/**
+ * DROP FIRST, CAP SECOND, and it matters.
+ *
+ * Capping the raw array first would let blank or duplicate entries consume slots
+ * the model meant for real content: a list of 30 paths with two repeats would
+ * come back with 28 real ones and no way to tell that anything was lost.
+ */
+function nonEmptyStrings(raw, max, dedupe = false) {
+    const cleaned = asArray(raw)
+        .map((v) => asString(v).trim())
+        .filter((s) => s.length > 0);
+    return (dedupe ? [...new Set(cleaned)] : cleaned).slice(0, max);
+}
+// ---------------------------------------------------------------------------
+// normalizeQuestions
+// ---------------------------------------------------------------------------
+/**
+ * Repair whatever the model sent into something renderable.
+ *
+ * Returns `[]` when nothing survives, which the tool turns into the one hard
+ * failure this path has. Every rule below is reachable precisely BECAUSE the
+ * schema stopped declaring the bounds (P0-4); with `minItems` / `maxItems` in
+ * the schema, `ajv` rejected the call first and rules 1 and 4 were dead code.
+ */
+export function normalizeQuestions(raw) {
+    const out = [];
+    // Rule 1a: keep the first N questions.
+    for (const item of asArray(raw).slice(0, QUESTION_LIMITS.maxQuestions)) {
+        const question = normalizeOneQuestion(asRecord(item), out.length);
+        if (question)
+            out.push(question);
+    }
+    return out;
+}
+function normalizeOneQuestion(src, index) {
+    const text = clampText(src.question, QUESTION_LIMITS.questionChars);
+    if (text.length === 0)
+        return null;
+    // Rule 1b + 1c: at least 2 options, at most 4.
+    const rawOptions = asArray(src.options).slice(0, QUESTION_LIMITS.maxOptions);
+    const options = [];
+    const seen = new Set();
+    for (const rawOption of rawOptions) {
+        const record = asRecord(rawOption);
+        const label = clampText(record.label, QUESTION_LIMITS.labelChars);
+        if (label.length === 0)
+            continue;
+        // Rule 4: deduplicate labels case-insensitively. Two options the user cannot
+        // tell apart is worse than one option fewer.
+        const key = label.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        options.push({
+            label,
+            description: clampText(record.description, QUESTION_LIMITS.optionDescriptionChars),
+            recommended: record.recommended === true,
+            isOther: false,
+        });
+    }
+    if (options.length < QUESTION_LIMITS.minOptions)
+        return null;
+    // Rules 2 and 3: exactly one recommended, always. The recommended option is
+    // the wizard's initial highlight, so "none" and "several" are both unusable.
+    const firstRecommended = options.findIndex((o) => o.recommended);
+    options.forEach((option, i) => {
+        option.recommended = i === (firstRecommended === -1 ? 0 : firstRecommended);
+    });
+    // Rule 5: the synthetic free-text escape hatch, unless the model already
+    // supplied something that reads as one.
+    if (!options.some((o) => /^other/i.test(o.label))) {
+        options.push({ label: OTHER_OPTION_LABEL, description: '', recommended: false, isOther: true });
+    }
+    else {
+        const existing = options.find((o) => /^other/i.test(o.label));
+        existing.isOther = true;
+    }
+    const id = asString(src.id).trim();
+    return {
+        id: id.length > 0 ? id : `q${index + 1}`,
+        header: clampText(src.header, QUESTION_LIMITS.headerChars) || `Q${index + 1}`,
+        question: text,
+        options,
+        allowMultiple: src.allowMultiple === true,
+    };
+}
+// ---------------------------------------------------------------------------
+// normalizePlan
+// ---------------------------------------------------------------------------
+/**
+ * Repair a submitted plan. Returns `null` only when no step survives — the one
+ * hard failure, because there is then nothing left to review.
+ *
+ * A plan that is one step over the cap is still a plan, and rejecting it costs a
+ * full research turn to regain nothing. Truncation is silent to the model but
+ * VISIBLE to the user: the review overlay's position indicator counts the real
+ * rows, so a clipped plan cannot masquerade as complete.
+ */
+export function normalizePlan(raw) {
+    const src = asRecord(raw);
+    // Same drop-first, cap-second discipline as `nonEmptyStrings`: a blank-titled
+    // step is noise, and letting it consume one of the twenty slots would silently
+    // discard a real step at the other end.
+    const steps = [];
+    for (const rawStep of asArray(src.steps)) {
+        const record = asRecord(rawStep);
+        const title = clampText(record.title, PLAN_LIMITS.stepTitleChars);
+        if (title.length === 0)
+            continue;
+        steps.push({ title, detail: clampText(record.detail, PLAN_LIMITS.stepDetailChars) });
+        if (steps.length === PLAN_LIMITS.maxSteps)
+            break;
+    }
+    if (steps.length === 0)
+        return null;
+    return {
+        title: clampText(src.title, PLAN_LIMITS.titleChars) || 'Untitled plan',
+        summary: clampText(src.summary, PLAN_LIMITS.summaryChars),
+        steps,
+        // Exact deduplication, NOT case-insensitive: POSIX paths are case-sensitive
+        // and two casings are two files.
+        filesTouched: nonEmptyStrings(src.filesTouched, PLAN_LIMITS.maxFiles, true),
+        risks: nonEmptyStrings(src.risks, PLAN_LIMITS.maxRisks),
+        openQuestions: nonEmptyStrings(src.openQuestions, PLAN_LIMITS.maxOpenQuestions),
+    };
+}
+/**
+ * A question SET's identity: the question texts, trimmed, lowercased, whitespace
+ * collapsed, sorted, joined.
+ *
+ * `id` and `header` are excluded on purpose — a model that re-asks the same thing
+ * under a new id is asking the same thing, and the ids are the model's own
+ * bookkeeping rather than part of what the user reads.
+ *
+ * The fingerprint is stable because `normalizeQuestions` already ran on the TOOL
+ * side: header truncation and option trimming cannot make the same question look
+ * different here. Worst case is 5 questions x 300 chars = 1,500 chars.
+ */
+export function questionFingerprint(questions) {
+    return questions
+        .map((q) => q.question.trim().toLowerCase().replace(/\s+/g, ' '))
+        .sort()
+        .join(' | ');
+}
+/**
+ * Render the `ask_user` result: one human-readable line so the transcript
+ * preview is legible without parsing, then the JSON the model reads.
+ *
+ * CARRIES NO ROUND COUNTER, deliberately (D-4). The model used to be told
+ * `roundsUsed` / `roundsRemaining` on every call, which is a per-turn reminder
+ * that it is running out — and an agent that reads "you have 1 round left"
+ * behaves like one. There is no limit any more, so there is nothing to report.
+ *
+ * `asked` is passed separately rather than derived from `answers.length`
+ * because a cancelled wizard returns fewer answers than it asked for, and
+ * "answered 1 of 3" is the whole information content of that line.
+ */
+export function formatAnswersResult(shape, asked) {
+    const headline = shape.cancelled
+        ? 'User dismissed the questions.'
+        : `User answered ${shape.answers.length} of ${asked} questions.`;
+    const guidance = shape.cancelled
+        ? ' Proceed with your best assumptions and say what you assumed.'
+        : '';
+    return `${headline}${guidance}\n${JSON.stringify(shape, null, 2)}`;
+}

package/dist/model/tools/patch.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Structured file patches (agent-activity-presentation §3.3).
+ *
+ * PURE, NO I/O, NO REACT, ASCII-ONLY MARKERS. `glyphs.test.ts`'s static scan
+ * walks ALL of `src/` (skipping only `__tests__/` and two exempt files), so this
+ * module sits inside that guard rail directly rather than by analogy. The
+ * substantive reason is the one `reducer.ts` gives for `PREVIEW_TRUNCATION_MARK`:
+ * a string produced outside `src/ui/**` has no `TermCapabilities` in scope and
+ * must be safe on a legacy `cmd.exe`.
+ *
+ * The ladder is ANCHORED SPLIT -> BOUNDED LCS -> BLOCK REPLACE, and every
+ * recursion path terminates in one of three leaf returns. `blockReplace` is
+ * exactly what `renderUnifiedDiff` produced before this round — every old row as
+ * `del`, then every new row as `add` — kept as the explicit, bounded fallback so
+ * a pathological input degrades to today's behaviour rather than hanging.
+ *
+ * `buildPatch` is TOTAL: it never throws, for any pair of strings.
+ */
+export type PatchLineKind = 'ctx' | 'add' | 'del';
+export interface PatchLine {
+    kind: PatchLineKind;
+    /** 1-based line number in the OLD file; absent on an `add`. */
+    oldLine?: number;
+    /** 1-based line number in the NEW file; absent on a `del`. */
+    newLine?: number;
+    /** Rendered text. A trailing CR is stripped; long lines are truncated. */
+    text: string;
+}
+export interface PatchHunk {
+    oldStart: number;
+    oldCount: number;
+    newStart: number;
+    newCount: number;
+    lines: PatchLine[];
+}
+export interface FilePatch {
+    /** As the model wrote it — relative when the call was relative. */
+    path: string;
+    kind: 'create' | 'update';
+    added: number;
+    removed: number;
+    hunks: PatchHunk[];
+    /** Budget was hit; the tail of the change is not in `hunks`. */
+    truncated: boolean;
+    /**
+     * Total rendered rows across every hunk (summary and separators excluded).
+     *
+     * PRECOMPUTED so `entryRevision` stays O(1) (I-L3-1 forbids hashing, and
+     * summing `hunks[].lines.length` per entry per frame is exactly the cost the
+     * height cache exists to remove).
+     */
+    lineCount: number;
+    /** Set when the old side could not be read: too large, binary, or unreadable. */
+    degraded?: 'binary' | 'too-large' | 'unreadable';
+}
+export declare const PATCH_LIMITS: {
+    /**
+     * Context rows kept either side of a change, FOR THE UI.
+     *
+     * The text renderer does NOT use this (D-20): `renderUnifiedDiff` keeps its
+     * own `CONTEXT_LINES = 2` default so the model-facing diff does not silently
+     * widen by two rows on every single-region edit. One algorithm, two widths,
+     * chosen by the caller.
+     */
+    readonly context: 3;
+    /**
+     * Hunks separated by this many context rows or fewer are merged into one.
+     *
+     * MUST STAY `>= 2 * context` FOR EVERY CALLER'S CONTEXT WIDTH, or two adjacent
+     * hunks expanded by `context` would overlap and the same row would be rendered
+     * twice with two different line numbers. 6 covers both widths in use (3 and 2).
+     */
+    readonly mergeGap: 6;
+    /** Rendered rows a patch may carry, across all hunks. */
+    readonly maxLines: 200;
+    /** Total characters across all `PatchLine.text`. Mirrors STORED_PREVIEW_CHARS. */
+    readonly maxChars: 8000;
+    /** A single row is truncated past this, with `TRUNCATION_MARK`. */
+    readonly maxLineChars: 500;
+    /** Above this cell count the LCS leaf is refused; the segment becomes a block replace. */
+    readonly lcsCellBudget: 160000;
+    /** Recursion depth ceiling for the anchor split. */
+    readonly maxDepth: 32;
+    /** Old-side bytes above which `write_file` does not read for a diff. */
+    readonly readMaxBytes: number;
+    /** Model-facing diff text ceiling — a bound `edit_file` does not have today. */
+    readonly modelDiffMaxChars: 4000;
+};
+/**
+ * Appended to a row clipped at `maxLineChars`.
+ *
+ * SPELLED HERE RATHER THAN IMPORTED from `agent/reducer.ts`, so that `tools/`
+ * does not take a runtime dependency on the view model for one three-character
+ * string. `patch.test.ts` asserts the two spellings are equal, so the pair
+ * cannot drift silently — which is the property the import would have bought.
+ */
+export declare const TRUNCATION_MARK = "...";
+/** The note emitted when exactly one side ends with a newline. */
+export declare const NO_NEWLINE_NOTE = "(no newline at end of file)";
+export interface BuildPatchOptions {
+    /** As the model wrote it; carried onto the patch verbatim. */
+    path: string;
+    /** Context rows either side of a change. Defaults to `PATCH_LIMITS.context`. */
+    context?: number;
+    /**
+     * Why the old side is `null`.
+     *
+     * It also decides `kind`: a missing old side with no reason is a CREATE, and a
+     * missing old side WITH one is an UPDATE whose old half could not be read. The
+     * distinction matters because "created a file" and "overwrote a 5 MB file we
+     * declined to read" are different events and the card names them differently.
+     */
+    degraded?: FilePatch['degraded'];
+}
+export declare function buildPatch(oldText: string | null, newText: string, options: BuildPatchOptions): FilePatch;