@litterthanlit/hypher-cli 0.1.8 → 0.2.1

package/vendor/ledgerSeal.mjs

@@ -0,0 +1,283 @@
+// Generated from hypher-web/shared/ledgerSeal.ts by script/sync-hypher-shared.mjs. Do not edit.
+/**
+ * What `seal` means in a project whose decision ledger is on (M2 slice 6): the CLI's `seal` input (a goal,
+ * a next action, decisions with why, constraints, completed, unverified, open, blockers, checks, and raw
+ * ops) turned into one `record_ops` call, and the server's answer turned into the words the agent reads.
+ * Pure TypeScript with no database, network, Node, Convex, or Next.js, vendored into the CLI
+ * (`script/sync-hypher-shared.mjs`) so the hosted tests and the installed copy run the same code.
+ *
+ * Installed CLIs never update themselves, so what this sends is permanent: it sends only ops the
+ * ledger already defines (`ledgerOps.ts`), never an origin, a status, or an approval of its own, and the
+ * call is checked locally by `parseLedgerCall` (secrets, `FILL:`, lengths, 50 ops, 25,000 bytes) before
+ * anything leaves the machine.
+ *
+ * The order of the ops follows `planV1Save` in `ledgerV1.ts`: decisions and constraints first, then the
+ * `seal` (a new goal moves the branch's old tasks, blockers, and checks out of the note), then the tasks,
+ * blockers, and checks this save says stand under it, then any raw ops the agent sent.
+ *
+ * Lists are additive. A ledger holds more than one save's worth, so leaving a line out of `completed`,
+ * `unverified`, `open`, or `blockers` removes nothing. A task is closed by listing it under `completed`,
+ * a decision is replaced by naming its ID, and anything else is a raw op (`ops`), for example
+ * `decision.retire`, `blocker.resolve`, or `task.drop`.
+ */
+import { noteText } from "./handoffNote.mjs";
+import { evidenceFromSeal } from "./handoffSeal.mjs";
+import { LEDGER_MAX_TEXT, parseLedgerCall } from "./ledgerOps.mjs";
+/** A body larger than this does not fit `/api/mcp` (`MAX_BODY_BYTES` in the route). */
+export const LEDGER_CALL_MAX_BYTES = 25_000;
+/** The code of the answer a server gives for a project whose ledger is not on (`ledgerNotOnMessage` in ledgerApi.ts). */
+export const LEDGER_NOT_ON_CODE = "ledger-not-on";
+const lower = (value) => value.toLowerCase();
+function clean(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function cleanList(values) {
+    return Array.isArray(values) ? values.map(clean).filter(Boolean) : [];
+}
+/** The first words of a text, for the line that says what became of it. */
+function short(text, max = 60) {
+    const flat = noteText(text, 400);
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+const DISPLAY_ID = /^d-[1-9]\d{0,8}$/i;
+const WINDOW_NUMBER = /^D\d+$/i;
+/** The numbering of the old note (D1, D2…), which a project with a ledger no longer has. */
+export function windowNumberHint(ref) {
+    return `${ref} is a number from the old note, and decisions in this project have IDs like d-3. Use the ID shown in the note ("d-3: …"), or part of the old decision's words.`;
+}
+/**
+ * The active decision a text names: the exact text, or a unique case-insensitive part of it (three
+ * characters or more). `items` is newest first, as the read route lists them. When the list was cut at
+ * its page size, a miss says so and points at the ID.
+ */
+export function resolveDecisionText(items, reference, complete = true) {
+    const ref = reference.trim();
+    const wanted = lower(ref);
+    const exact = items.find((item) => lower(item.text.trim()) === wanted);
+    if (exact)
+        return { ok: true, id: exact.id };
+    const partial = wanted.length >= 3 ? items.filter((item) => lower(item.text).includes(wanted)) : [];
+    if (partial.length === 1)
+        return { ok: true, id: partial[0].id };
+    const list = (rows) => rows.slice(0, 8).map((item) => `${item.id} "${short(item.text, 50)}"`).join(", ") + (rows.length > 8 ? `, and ${rows.length - 8} more` : "");
+    if (partial.length > 1)
+        return { ok: false, error: `"${short(ref, 50)}" matches ${partial.length} decisions (${list(partial)}); use the decision's ID, for example ${partial[0].id}.` };
+    const cut = complete ? "" : " Only the newest decisions were checked; use the decision's ID (`hypher resume --full` lists them).";
+    return { ok: false, error: `No active decision matches "${short(ref, 50)}".${items.length ? ` Decisions: ${list(items)}.` : " There are no decisions to replace."}${cut}` };
+}
+function fail(error) {
+    return { ok: false, error };
+}
+/**
+ * The ops for one seal. Nothing is sent from here. When a decision is replaced by its words, the active
+ * decisions are needed to find its ID: the first call answers `needsDecisions`, the caller reads them
+ * once and calls again with `decisions`.
+ *
+ * @param input.prior the window this session resumed from (null when none was kept)
+ * @param input.labeled true when the resume was for a branch with no workstream yet: it was shown the most
+ *   recently active one, so its goal is carried onto the new branch when the seal gives none
+ * @param input.sessionRef the label of this session; it is the source of every decision
+ * @param input.now the time of the save; checks are stamped with it rounded down to the minute, so an
+ *   identical retry within the minute is the same call
+ */
+export function planLedgerSeal(input) {
+    const { seal, prior } = input;
+    const nextAction = clean(seal.nextAction);
+    if (!nextAction)
+        return fail("The next action is required: nextAction (in a shell, --next \"…\").");
+    const extra = seal.ops === undefined || seal.ops === null ? [] : seal.ops;
+    if (!Array.isArray(extra))
+        return fail("ops must be a list of ledger ops, each an object with a type, for example { \"type\": \"decision.retire\", \"id\": \"d-3\", \"reason\": \"…\" }.");
+    for (let index = 0; index < extra.length; index += 1) {
+        const op = extra[index];
+        if (!op || typeof op !== "object" || Array.isArray(op) || typeof op.type !== "string") {
+            return fail(`ops[${index}] must be an object with a type, for example { "type": "decision.retire", "id": "d-3", "reason": "…" }.`);
+        }
+    }
+    // First pass: everything that can be refused without reading the ledger.
+    let needsLookup = false;
+    for (const raw of seal.decisions ?? []) {
+        const text = clean(raw?.decision);
+        if (!text)
+            continue;
+        if (!clean(raw.why))
+            return fail(`Say why for "${text}" (--why "…" right after --decision).`);
+        const ref = clean(raw.replaces);
+        if (!ref || DISPLAY_ID.test(ref))
+            continue;
+        if (WINDOW_NUMBER.test(ref))
+            return fail(windowNumberHint(ref));
+        needsLookup = true;
+    }
+    if (needsLookup && !input.decisions)
+        return { ok: false, needsDecisions: true };
+    const ops = [];
+    const labels = [];
+    const push = (op, label) => {
+        ops.push(op);
+        labels.push(label);
+    };
+    // Decisions. A restatement of one the window already holds changes nothing, as in v1. The session's label is the
+    // source of each, cut to the length a source may have (v1 cuts it the same way).
+    const sessionRef = clean(input.sessionRef).slice(0, LEDGER_MAX_TEXT);
+    const known = new Set((prior?.decisions ?? []).map((item) => lower(item.decision.trim())));
+    const replaced = new Set();
+    for (const raw of seal.decisions ?? []) {
+        const text = clean(raw?.decision);
+        if (!text)
+            continue;
+        const reason = clean(raw.why);
+        const ref = clean(raw.replaces);
+        const label = `decision "${short(text)}"`;
+        if (ref) {
+            let id;
+            if (DISPLAY_ID.test(ref)) {
+                id = lower(ref);
+            }
+            else {
+                const found = resolveDecisionText(input.decisions ?? [], ref, input.decisionsComplete ?? true);
+                if (!found.ok)
+                    return found;
+                id = found.id;
+            }
+            if (replaced.has(id))
+                return fail(`${id} is replaced twice.`);
+            replaced.add(id);
+            push({ type: "decision.supersede", id, text, reason, sourceRefs: [sessionRef] }, label);
+        }
+        else {
+            if (known.has(lower(text)))
+                continue;
+            known.add(lower(text));
+            push({ type: "decision.add", text, reason, sourceRefs: [sessionRef] }, label);
+        }
+    }
+    // Constraints are only added. One the window already holds is not sent again.
+    const constraints = new Set((prior?.constraints ?? []).map((item) => lower(item.trim())));
+    for (const text of cleanList(seal.constraints)) {
+        if (constraints.has(lower(text)))
+            continue;
+        constraints.add(lower(text));
+        push({ type: "constraint.add", text }, `constraint "${short(text)}"`);
+    }
+    // The seal. On a branch with no workstream the goal of the one the note showed is carried, so the new
+    // workstream has a goal; a goal the agent gives always wins, and without either none is sent.
+    const given = clean(seal.goal);
+    const goal = given || (input.labeled ? clean(prior?.goal) : "");
+    push({ type: "seal", ...(goal ? { goal } : {}), nextAction }, given ? "goal and next action" : "next action");
+    // Tasks. The fold matches an active task by its words on this branch and sets its status, so a line
+    // under `completed` closes one that was open or unverified. A line in two lists takes the later one.
+    const tasks = new Map();
+    for (const text of cleanList(seal.open))
+        tasks.set(lower(text), { text, status: "open" });
+    for (const text of cleanList(seal.unverified))
+        tasks.set(lower(text), { text, status: "unverified" });
+    for (const text of cleanList(seal.completed))
+        tasks.set(lower(text), { text, status: "done" });
+    for (const task of tasks.values())
+        push({ type: "task.upsert", text: task.text, status: task.status }, `task "${short(task.text)}" (${task.status})`);
+    const blockers = new Set();
+    for (const text of cleanList(seal.blockers)) {
+        if (blockers.has(lower(text)))
+            continue;
+        blockers.add(lower(text));
+        push({ type: "blocker.add", text }, `blocker "${short(text)}"`);
+    }
+    // Checks, bound to the tree at the save and stamped to the minute.
+    const stamped = Math.floor(input.now / 60_000) * 60_000;
+    const reported = evidenceFromSeal(seal.evidence, input.tree, stamped);
+    if (!reported.ok)
+        return fail(reported.error);
+    for (const item of reported.items) {
+        push({ type: "evidence.record", command: item.command, exitCode: item.exitCode, tree: item.tree, capturedAt: item.capturedAt }, `check "${short(item.command)}" (exit ${item.exitCode})`);
+    }
+    // Raw ops last, as the agent wrote them.
+    extra.forEach((op, index) => push(op, `ops[${index}] ${noteText(op.type, 40)}`));
+    return { ok: true, ops, labels };
+}
+/** The words for an error `parseLedgerCall` gave about `ops[n]`, said about the item it came from. */
+export function explainCallError(error, labels) {
+    const limit = /^A call carries at most (\d+) ops; this one has (\d+)\.$/.exec(error);
+    if (limit) {
+        return `Refused: this save would send ${limit[2]} ops, and one call carries at most ${limit[1]}. Nothing was sent. Save in two parts, the most important first.`;
+    }
+    const at = /^ops\[(\d+)\]\.?(.*)$/.exec(error);
+    const rest = (at ? at[2] || "is not valid" : error).replace(/\.$/, "");
+    const subject = at ? labels[Number(at[1])] ?? `ops[${at[1]}]` : "";
+    return `Refused: ${subject ? `${subject}: ` : ""}${rest}. Nothing was sent. Fix it and seal again.`;
+}
+/**
+ * Check the call as the server will: `parseLedgerCall` (secrets, `FILL:`, lengths, at most 50 ops) and the
+ * size of the whole request. A refusal is in plain words and nothing is sent.
+ */
+export function checkLedgerCall(input) {
+    const parsed = parseLedgerCall({ baseRevision: input.baseRevision, repo: input.repo, ops: input.ops });
+    if (!parsed.ok)
+        return fail(explainCallError(parsed.error, input.labels));
+    const args = { source: input.source, projectId: input.projectId, baseRevision: input.baseRevision, repo: parsed.value.repo, ops: parsed.value.ops };
+    // The whole JSON-RPC request counts, not only the arguments.
+    const body = JSON.stringify({ jsonrpc: "2.0", id: 1_000_000, method: "tools/call", params: { name: "record_ops", arguments: args } });
+    const bytes = new TextEncoder().encode(body).length;
+    if (bytes > LEDGER_CALL_MAX_BYTES) {
+        return fail(`Refused: this save is ${bytes.toLocaleString("en-US")} bytes, and one call may carry at most ${LEDGER_CALL_MAX_BYTES.toLocaleString("en-US")}. Nothing was sent. Save in two parts, the most important first.`);
+    }
+    return { ok: true, ops: parsed.value.ops, args };
+}
+/** True for the answer a server gives when it has no such tool: an older Hypher, with no ledger. */
+export function isUnknownToolError(message, code) {
+    return code === -32601 || /\bunknown[-\s]tool\b|\btool not found\b|\bmethod not found\b/i.test(message);
+}
+const KNOWN_STATUSES = ["applied", "merged", "noop", "disputed", "refused", "unsupported"];
+function oneLine(text, max = 240) {
+    return noteText(text ?? "", max);
+}
+function resultLine(result, label) {
+    const note = result.note ? ` (${oneLine(result.note)})` : "";
+    switch (result.status) {
+        case "merged":
+            return `${label}: merged into ${result.id ?? "an existing item"}${note}`;
+        case "noop":
+            return `${label}: no change${note}`;
+        case "disputed":
+            return `${label}: disputed${result.subject ? ` on ${oneLine(result.subject, 40)}` : ""}${result.id ? `; your proposal is ${oneLine(result.id, 40)}` : ""}`;
+        case "refused":
+            return `${label}: refused${result.reason ? `. ${oneLine(result.reason)}` : ""}`;
+        case "unsupported":
+            return `${label}: not applied. This Hypher does not know the op type "${oneLine(result.type ?? "", 60)}"; it is kept in the log.`;
+        default: {
+            // A status this copy does not know: said as it came, with whatever the server attached.
+            const parts = [result.id, result.subject].filter(Boolean).map((item) => oneLine(item, 40));
+            return `${label}: ${oneLine(result.status, 40)}${parts.length ? ` ${parts.join(" ")}` : ""}${result.reason ? `. ${oneLine(result.reason)}` : ""}${note}`;
+        }
+    }
+}
+/**
+ * The answer to a saved `record_ops` call. It starts with the revision and the counts, then has one line
+ * for each op that was not simply applied, then each question for the user, then a line when other
+ * writers landed changes between the revision this session read and this save.
+ */
+export function describeLedgerSave(input) {
+    const { answer } = input;
+    const results = answer.results ?? [];
+    const counts = answer.counts && typeof answer.counts === "object"
+        ? { ...answer.counts }
+        : results.reduce((all, item) => ({ ...all, [item.status]: (all[item.status] ?? 0) + 1 }), {});
+    const order = [...KNOWN_STATUSES, ...Object.keys(counts).filter((status) => !KNOWN_STATUSES.includes(status))];
+    const summary = order.filter((status) => (counts[status] ?? 0) > 0).map((status) => `${counts[status]} ${oneLine(status, 40)}`).join(", ") || "no ops";
+    const where = `for "${oneLine(input.projectName, 80)}" (branch ${oneLine(answer.branch ?? input.branch, 120)})`;
+    const lines = [
+        `Saved ledger revision ${answer.revision} ${where}: ${summary}. Memory did not transfer code.${answer.replay ? " This save was already recorded; nothing was added." : ""}`,
+        ...(input.extraLines ?? []),
+    ];
+    for (const result of results) {
+        if (result.status === "applied")
+            continue;
+        lines.push(`- ${resultLine(result, input.labels[result.index] ?? `ops[${result.index}] ${oneLine(result.type ?? "?", 40)}`)}`);
+    }
+    for (const question of answer.ask ?? [])
+        lines.push(`Ask the user: ${oneLine(question, 600)}`);
+    if (answer.revision > input.base + 1 && !answer.replay) {
+        lines.push(`Other changes landed since this session read the ledger (revision ${input.base}; it is now ${answer.revision}). Run \`hypher resume\` to read them before you save again.`);
+    }
+    return lines.join("\n");
+}