@aragon-agent/cli 0.6.47 → 0.6.48

package/dist/tools/human-input.js

@@ -1,265 +0,0 @@
-/**
- * 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/tools/patch.d.ts

@@ -1,115 +0,0 @@
-/**
- * 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;