jev-agent-tools 0.1.3 → 0.2.0

package/dist/core/lexical.js

@@ -0,0 +1,132 @@
+/** A lexical pass excludes comments and keeps literals separate from identifiers. */
+export function tokenize(text, python = false) {
+    const tokens = [];
+    let i = 0;
+    let line = 1;
+    while (i < text.length) {
+        const c = text[i] ?? "";
+        if (/\s/.test(c)) {
+            if (c === "\n")
+                line++;
+            i++;
+            continue;
+        }
+        if (python ? c === "#" : text.slice(i, i + 2) === "//") {
+            while (i < text.length && text[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (!python && text.slice(i, i + 2) === "/*") {
+            i += 2;
+            while (i < text.length && text.slice(i, i + 2) !== "*/") {
+                if (text[i] === "\n")
+                    line++;
+                i++;
+            }
+            i += 2;
+            continue;
+        }
+        const start = i;
+        const firstLine = line;
+        const previous = tokens[tokens.length - 1];
+        // A slash can begin a regex only where an expression can begin, not after
+        // an operand (where it is division). Keep the entire literal opaque.
+        if (!python &&
+            c === "/" &&
+            (!previous ||
+                (!previous.string &&
+                    (/^[([{,:;=!?&|+*%~^<>-]$/.test(previous.value) ||
+                        [
+                            "return",
+                            "throw",
+                            "case",
+                            "delete",
+                            "void",
+                            "typeof",
+                            "yield",
+                            "await",
+                            "in",
+                            "of",
+                        ].includes(previous.value))))) {
+            let end = i + 1;
+            let characterClass = false;
+            while (end < text.length && text[end] !== "\n" && text[end] !== "\r") {
+                const next = text[end];
+                if (next === "\\") {
+                    end += 2;
+                    continue;
+                }
+                if (next === "[")
+                    characterClass = true;
+                else if (next === "]")
+                    characterClass = false;
+                else if (next === "/" && !characterClass)
+                    break;
+                end++;
+            }
+            if (text[end] === "/") {
+                end++;
+                while (/[a-z]/i.test(text[end] ?? ""))
+                    end++;
+                tokens.push({
+                    value: text.slice(i, end),
+                    line,
+                    offset: start,
+                    string: false,
+                });
+                i = end;
+                continue;
+            }
+        }
+        if (c === "'" || c === '"' || c === "`") {
+            const quote = python && text.slice(i, i + 3) === c.repeat(3) ? c.repeat(3) : c;
+            i += quote.length;
+            let value = "";
+            let dynamic = false;
+            while (i < text.length && text.slice(i, i + quote.length) !== quote) {
+                if (text[i] === "\n")
+                    line++;
+                if (c === "`" && text.slice(i, i + 2) === "${")
+                    dynamic = true;
+                if (text[i] === "\\") {
+                    i++;
+                    const escaped = text[i++] ?? "";
+                    value +=
+                        escaped === "n"
+                            ? "\n"
+                            : escaped === "t"
+                                ? "\t"
+                                : escaped === "r"
+                                    ? "\r"
+                                    : escaped;
+                }
+                else
+                    value += text[i++];
+            }
+            const closed = text.slice(i, i + quote.length) === quote;
+            if (closed)
+                i += quote.length;
+            tokens.push({
+                value,
+                line: firstLine,
+                offset: start,
+                string: closed && !dynamic,
+            });
+        }
+        else if (/[\w$]/.test(c)) {
+            while (i < text.length && /[\w$]/.test(text[i] ?? ""))
+                i++;
+            tokens.push({
+                value: text.slice(start, i),
+                line,
+                offset: start,
+                string: false,
+            });
+        }
+        else {
+            i++;
+            tokens.push({ value: c, line, offset: start, string: false });
+        }
+    }
+    return tokens;
+}

package/dist/core/locate.js

@@ -0,0 +1,169 @@
+import { CHOICE_MAX_OPTIONS, LOCATE_VERDICT_MIN, STATE_MAX_CHARS, } from "../constants.js";
+import { truncate } from "./truncate.js";
+export function sectionState(path, goal, sections, outline = false) {
+    return {
+        path,
+        goal,
+        sections: sections.map((section) => ({
+            id: section.id,
+            lines: `${section.start}-${section.end}`,
+            text: outline ? section.label : section.text,
+        })),
+    };
+}
+export function sectionStateFits(path, goal, sections, outline = false) {
+    return (sections.length < CHOICE_MAX_OPTIONS &&
+        JSON.stringify(sectionState(path, goal, sections, outline)).length <=
+            STATE_MAX_CHARS);
+}
+/** Every planned block has at least two sections and fits its full-text refinement budget. */
+export function sectionOutline(path, goal, sections) {
+    const base = JSON.stringify(sectionState(path, goal, [])).length;
+    const costs = new Map(sections.map((section) => [
+        section,
+        JSON.stringify({
+            id: section.id,
+            lines: `${section.start}-${section.end}`,
+            text: "",
+        }).length +
+            (section.serializedTextChars ?? JSON.stringify(section.text).length) -
+            2,
+    ]));
+    const fits = (items) => items.length < CHOICE_MAX_OPTIONS &&
+        base + items.reduce((sum, item) => sum + (costs.get(item) ?? 0) + 1, 0) <=
+            STATE_MAX_CHARS;
+    const groups = [];
+    let current = [], currentSize = base;
+    for (const section of sections) {
+        const length = (costs.get(section) ?? 0) + 1;
+        if (base + length > STATE_MAX_CHARS)
+            return [];
+        const owner = section.label.split(".")[0], previousOwner = current.at(-1)?.label.split(".")[0];
+        if (current.length &&
+            (currentSize + length > STATE_MAX_CHARS ||
+                current.length + 1 >= CHOICE_MAX_OPTIONS ||
+                (current.length >= 2 &&
+                    section.label.includes(".") &&
+                    owner !== previousOwner))) {
+            groups.push(current);
+            current = [];
+            currentSize = base;
+        }
+        current.push(section);
+        currentSize += length;
+    }
+    if (current.length)
+        groups.push(current);
+    for (let index = 0; index < groups.length; index++) {
+        const group = groups[index];
+        if (!group || group.length >= 2)
+            continue;
+        const previous = groups[index - 1], next = groups[index + 1];
+        if (previous && fits([...previous, ...group])) {
+            previous.push(...group);
+            groups.splice(index, 1);
+            index--;
+            continue;
+        }
+        if (next && fits([...group, ...next])) {
+            next.unshift(...group);
+            groups.splice(index, 1);
+            index--;
+            continue;
+        }
+        if (previous && previous.length > 2) {
+            const moved = previous.at(-1);
+            if (moved && fits([moved, ...group])) {
+                previous.pop();
+                group.unshift(moved);
+                continue;
+            }
+        }
+        if (next && next.length > 2) {
+            const moved = next[0];
+            if (moved && fits([...group, moved])) {
+                next.shift();
+                group.push(moved);
+                continue;
+            }
+        }
+        return [];
+    }
+    return groups.map((group, index) => ({
+        id: `B${index + 1}`,
+        start: group[0]?.start ?? 0,
+        end: group.at(-1)?.end ?? 0,
+        label: group.map((s) => s.label).join(" / "),
+        text: group.map((s) => s.text).join("\n"),
+    }));
+}
+/** JSON-escaped budget, allocated equally then redistributed to larger blocks. */
+export function outlineEvidence(path, goal, blocks) {
+    const overhead = JSON.stringify(sectionState(path, goal, blocks.map((block) => ({ ...block, text: "" })))).length;
+    let remaining = Math.max(0, STATE_MAX_CHARS - overhead);
+    const allocations = blocks.map(() => 0);
+    let active = blocks.map((_, index) => index);
+    while (remaining > 0 && active.length) {
+        const share = Math.max(1, Math.floor(remaining / active.length));
+        const next = [];
+        for (const index of active) {
+            const block = blocks[index];
+            if (!block)
+                continue;
+            const need = JSON.stringify(block.text).length - 2 - (allocations[index] ?? 0);
+            const granted = Math.min(need, share, remaining);
+            allocations[index] = (allocations[index] ?? 0) + granted;
+            remaining -= granted;
+            if (need > granted)
+                next.push(index);
+        }
+        active = next;
+    }
+    return blocks.map((block, index) => {
+        const budget = allocations[index] ?? 0;
+        if (JSON.stringify(block.text).length - 2 <= budget)
+            return { ...block };
+        const excerpt = (chars) => {
+            const part = Math.floor(chars / 3);
+            const slice = (start) => {
+                if (start > 0 && /[\uDC00-\uDFFF]/.test(block.text[start] ?? ""))
+                    start++;
+                return truncate(block.text.slice(start), part);
+            };
+            return `${slice(0)}\n…\n${slice(Math.max(0, Math.floor(block.text.length / 2) - Math.floor(part / 2)))}\n…\n${slice(Math.max(0, block.text.length - part))}`;
+        };
+        let low = 0, high = Math.min(block.text.length, budget), text = "";
+        while (low <= high) {
+            const middle = Math.floor((low + high) / 2), candidate = excerpt(middle);
+            if (JSON.stringify(candidate).length - 2 <= budget) {
+                text = candidate;
+                low = middle + 1;
+            }
+            else
+                high = middle - 1;
+        }
+        return { ...block, text };
+    });
+}
+export function locateDisplay(path, sections, ranked, forceUnsure) {
+    const head = ranked[0];
+    if (!head)
+        return undefined;
+    const display = (id, p) => {
+        const section = sections.find((s) => s.id === id);
+        return {
+            label: section ? `${path}:${section.start}-${section.end}` : "none",
+            value: { head: section?.label ?? "no section fits", p },
+        };
+    };
+    const band = forceUnsure || head.p < LOCATE_VERDICT_MIN
+        ? "unsure"
+        : "verdict";
+    return {
+        primary: display(head.id, head.p),
+        band,
+        candidates: band === "unsure"
+            ? ranked.slice(1, 2).map((s) => display(s.id, s.p))
+            : undefined,
+    };
+}

package/dist/core/output.js

@@ -0,0 +1,120 @@
+import { BAND_BOOL_GRAY_A, BAND_BOOL_YES_MIN, BAND_CHOICE_VERDICT_MIN, CANNOT_TELL_MIN, LIMIT_DISPLAY_MAX_PATHS, } from "../constants.js";
+export function askBand(value, input) {
+    const answer = input.answer;
+    if (answer?.type === "bool")
+        return value.p <= BAND_BOOL_GRAY_A || value.p >= BAND_BOOL_YES_MIN
+            ? "verdict"
+            : "unsure";
+    if (answer && (answer.probabilities.cannot_tell ?? 0) >= CANNOT_TELL_MIN)
+        return "abstain";
+    return value.p >= BAND_CHOICE_VERDICT_MIN ? "verdict" : "unsure";
+}
+function displayValue(input) {
+    if (input.value)
+        return input.value;
+    const answer = input.answer;
+    if (!answer)
+        throw new Error("An answer requires a typed value or a Jev answer");
+    if (answer.type === "bool")
+        return { head: answer.p >= 0.5 ? "yes" : "no (not shown)", p: answer.p };
+    const p = input.verify
+        ? Math.max(answer.probabilities.holds ?? 0, answer.probabilities.contradicted ?? 0, (answer.probabilities.not_addressed ?? 0) +
+            (answer.probabilities.cannot_tell ?? 0))
+        : Math.max(...Object.values(answer.probabilities));
+    return { head: answer.type === "choice" ? answer.choice : answer.score, p };
+}
+export function buildEnvelope(input) {
+    const lines = [];
+    if (input.budget?.kind === "session" && input.yield.calls === 0)
+        return {
+            lines: [
+                { type: "refusal", message: input.budget.message },
+                { type: "yield", value: input.yield },
+            ],
+        };
+    if (input.state)
+        lines.push({ type: "state", ...input.state });
+    const failed = (input.controls ?? [])
+        .map((control) => control.fact)
+        .join("; ");
+    for (const item of input.answers ?? []) {
+        const value = displayValue(item);
+        const initial = item.band ?? (input.policy ?? askBand)(value, item);
+        const band = initial === "verdict" && failed ? "unsure" : initial;
+        const reason = band === "abstain"
+            ? (item.reason ??
+                item.missing ??
+                "proof missing; add decisive evidence to paths or command")
+            : failed && initial === "verdict"
+                ? failed
+                : item.reason;
+        lines.push({
+            type: "answer",
+            label: item.label,
+            value,
+            band,
+            uncalibrated: item.uncalibrated ?? false,
+            ...(reason ? { reason } : {}),
+            ...(item.orderDependent !== undefined
+                ? { orderDependent: item.orderDependent }
+                : {}),
+            ...(item.candidates ? { candidates: item.candidates } : {}),
+        });
+    }
+    for (const item of input.unjudged ?? [])
+        lines.push({ type: "unjudged", ...item });
+    for (const line of input.lines ?? [])
+        lines.push(line.type === "entry" && line.band === "verdict" && failed
+            ? { ...line, band: "unsure" }
+            : line);
+    if (input.refusal)
+        lines.push({ type: "refusal", message: input.refusal });
+    if (input.budget?.kind === "session")
+        lines.push({ type: "refusal", message: input.budget.message });
+    for (const fact of input.controls ?? [])
+        lines.push({ type: "fact", ...fact });
+    const groups = new Map();
+    for (const limit of input.limitations ?? []) {
+        if (!limit.cause ||
+            !limit.path ||
+            input.limitationPriorityPaths === undefined) {
+            lines.push({ type: "fact", fact: limit.fact, next: limit.next });
+            continue;
+        }
+        const priority = input.limitationPriorityPaths?.includes(limit.path) ?? false;
+        const key = JSON.stringify([priority, limit.cause, limit.next]);
+        const group = groups.get(key) ?? {
+            type: "limit-group",
+            cause: limit.cause,
+            count: 0,
+            priority,
+            examples: [],
+            remaining: 0,
+            next: limit.next,
+        };
+        group.count += limit.count ?? 1;
+        if (priority || group.examples.length < LIMIT_DISPLAY_MAX_PATHS)
+            group.examples.push(`${limit.path}${limit.dependency ? ` (${limit.dependency})` : ""}`);
+        else
+            group.remaining++;
+        groups.set(key, group);
+    }
+    lines.push(...[...groups.values()].sort((a, b) => Number(b.priority) - Number(a.priority)));
+    if (input.budget?.kind === "max_calls")
+        lines.push({
+            type: "fact",
+            fact: input.budget.message,
+            next: "raise max_calls",
+        });
+    if (input.unchecked?.length)
+        lines.push({ type: "unchecked", items: input.unchecked });
+    const gray = lines.reduce((count, line) => count + Number(line.type === "answer" && line.band === "unsure"), 0);
+    if (gray > 0)
+        lines.push({
+            type: "fact",
+            fact: `${gray}/${input.answers?.length ?? 0} answers unsure`,
+            next: "read the decisive passage or add its file to paths",
+        });
+    lines.push({ type: "yield", value: input.yield });
+    return { lines };
+}

package/dist/core/pointer.js

@@ -0,0 +1,29 @@
+import { ORDER_DISAGREE_MIN, ORDER_REVERSE_BELOW } from "../constants.js";
+export function pointerQuestion({ instructions, noneLabel, candidates, reverse = false, }) {
+    const ordered = reverse ? [...candidates].reverse() : candidates;
+    return {
+        type: "choice",
+        instructions,
+        criteria: Object.fromEntries([
+            ...ordered.map((candidate) => [candidate.id, candidate.label]),
+            ["none", noneLabel],
+        ]),
+    };
+}
+export function needsReverse(probabilities, candidateCount) {
+    return (candidateCount > 1 &&
+        Math.max(...Object.values(probabilities)) < ORDER_REVERSE_BELOW);
+}
+export function readPointer(first, second) {
+    const ranked = Object.entries(first)
+        .map(([id, p]) => ({ id, p: second ? (p + (second[id] ?? 0)) / 2 : p }))
+        .sort((a, b) => b.p - a.p);
+    const head = ranked[0];
+    return {
+        ranked,
+        orderDependent: !!(second &&
+            head &&
+            Math.abs((first[head.id] ?? 0) - (second[head.id] ?? 0)) >
+                ORDER_DISAGREE_MIN),
+    };
+}