@turri-dev/cli 0.0.0-stage → 0.1.1

package/dist/regenerate/masking.js

@@ -0,0 +1,95 @@
+/**
+ * The values of the credentials a project passes to its agents (`agent-env:`) never appear in what an agent is shown
+ * or what turri writes: each is replaced by its name, `[D365_CLIENT_SECRET]` - whole, URL-encoded, or split over the
+ * chunks of a stream. A value is registered when the agents' environment is worked out (`agentEnvironment`), and masked
+ * from then on everywhere in this process: a command's output as it streams, every tool result an agent is given and
+ * every refusal, the kept whole outputs, the job and debug logs - and so the session transcripts, which hold only what
+ * the tools returned.
+ */
+/** Shorter values are not masked: `1`, `eu`, `true` are everywhere in ordinary output. */
+const MIN_LENGTH = 4;
+/** Each form a value is masked in, to its name - longest first, so a value inside another is not cut in two. */
+let forms = [];
+/** Mask these values, by name, from now on. */
+export function registerSecrets(values) {
+    const all = new Map(forms);
+    for (const [name, value] of Object.entries(values)) {
+        if (value.length < MIN_LENGTH)
+            continue;
+        for (const form of [value, encodeURIComponent(value), encodeURIComponent(value).replace(/%20/g, "+")])
+            all.set(form, name);
+    }
+    forms = [...all].sort(([a], [b]) => b.length - a.length);
+}
+/** For tests: mask nothing. */
+export function forgetSecretsForTests() {
+    forms = [];
+}
+/** The longest form registered: how much of a stream has to be held back to catch one split over chunks. */
+function longest() {
+    return forms[0]?.[0].length ?? 0;
+}
+/** `text` with every registered value replaced by its name. */
+export function maskSecrets(text) {
+    if (forms.length === 0)
+        return text;
+    let masked = text;
+    for (const [form, name] of forms)
+        if (masked.includes(form))
+            masked = masked.split(form).join(`[${name}]`);
+    return masked;
+}
+/**
+ * A stream that masks what passes through it before `onData` sees it: the end of each chunk is held back - as long as
+ * the longest value, less one - until the next shows whether a value runs across them. `end` lets the rest out.
+ */
+export function maskingStream(onData) {
+    let held = "";
+    return {
+        write(data) {
+            if (forms.length === 0 && held === "") {
+                onData(data);
+                return;
+            }
+            const text = maskSecrets(held + data.toString("utf8"));
+            const keep = Math.max(0, longest() - 1);
+            const cut = Math.max(0, text.length - keep);
+            held = text.slice(cut);
+            if (cut > 0)
+                onData(Buffer.from(text.slice(0, cut)));
+        },
+        end() {
+            if (held !== "")
+                onData(Buffer.from(maskSecrets(held)));
+            held = "";
+        },
+    };
+}
+/** The tools, each result they return - and each error they throw, a refusal - masked before the agent sees it. */
+export function maskToolResults(tools) {
+    return tools.map((tool) => ({
+        ...tool,
+        async execute(toolCallId, params, signal, onUpdate, ctx) {
+            const update = onUpdate === undefined ? undefined : (partial) => onUpdate(maskResult(partial));
+            try {
+                return maskResult(await tool.execute(toolCallId, params, signal, update, ctx));
+            }
+            catch (error) {
+                if (error instanceof Error)
+                    error.message = maskSecrets(error.message);
+                throw error;
+            }
+        },
+    }));
+}
+function maskResult(result) {
+    if (forms.length === 0 || result === null || typeof result !== "object")
+        return result;
+    const content = result.content;
+    if (!Array.isArray(content))
+        return result;
+    return {
+        ...result,
+        content: content.map((part) => (part?.type === "text" && typeof part.text === "string" ? { ...part, text: maskSecrets(part.text) } : part)),
+    };
+}

package/dist/regenerate/notes.js

@@ -0,0 +1,397 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { reportActivity } from "./activity.js";
+/**
+ * Working notes: what one agent on a codebase leaves the next.
+ *
+ * Every agent the harness starts is a fresh session. Without notes, each one spends its first
+ * turns finding its bearings - where the entry point is, how the tests run, what was installed,
+ * which approach already failed. The notes carry that forward: each agent on a codebase gets
+ * them the moment it starts, and updates them - a line added, changed or removed - before it
+ * finishes, so they get longer with the codebase instead of being rewritten by whoever came last.
+ *
+ * Stubborn on the specs, flexible on the assumptions. What the software must do is in the spec,
+ * and the notes never repeat or override it. Where the spec is silent, an agent has to assume
+ * something, and the assumptions it made are written down - so the next agent builds on the
+ * same ones instead of guessing afresh, and changes one the moment the code or the spec shows
+ * it to be wrong.
+ *
+ * Every line says when and where it came from - `[2026-09-24 16:49 · backend 3]` for
+ * functionality 3 of backend, `backend 3 conformance`, `backend spec change` - stamped by the
+ * harness, not written by the agent, so a line read two modules later can still be traced to the
+ * step that wrote it. A line that is changed is stamped again: an assumption one agent revised
+ * shows as newer than the ones around it, and where two lines disagree the later one is right. And every line
+ * has to say something: "none", "N/A", "nothing new" are refused - a section with nothing to add
+ * is left alone.
+ *
+ * Leaving them is not optional, and neither is how: only update_notes writes the file. The file
+ * tools refuse it, a change made any other way - a shell, a script - is undone, and an agent
+ * that finishes without calling update_notes is asked again until it does.
+ *
+ * The notes are disposable: delete the file and nothing breaks, the next agent just explores a
+ * little more. They live beside the code, so they travel with it - copied up with it to a module
+ * that requires this one, committed with it, and reset with it when a run is interrupted.
+ */
+export const NOTES_FILE = ".turri-notes.md";
+/** The sections, in order, and what each is for - shown to the agent as the heading. */
+export const SECTIONS = {
+    where: "Where things are",
+    run: "How to build, run and test",
+    assumptions: "Assumptions",
+    gaps: "Spec gaps",
+    pitfalls: "Pitfalls",
+    pulses: "Pulses",
+};
+/** The sections only the harness writes: what each pulse did, as it ended. update_notes refuses them. */
+const HARNESS_ONLY = ["pulses"];
+/** How many pulses the notes keep: the last ones - the module's history has every one. */
+export const PULSES_KEPT = 10;
+const ORDER = Object.keys(SECTIONS);
+export function notesPath(buildDir) {
+    return join(buildDir, NOTES_FILE);
+}
+function empty() {
+    return { where: [], run: [], assumptions: [], gaps: [], pitfalls: [], pulses: [] };
+}
+/** The notes, as lines per section. Lines under no known heading go to pitfalls, not lost. */
+export function parseNotes(text) {
+    const notes = empty();
+    let section = "pitfalls";
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        const heading = /^##\s+(.+)$/.exec(line);
+        if (heading) {
+            section = ORDER.find((key) => SECTIONS[key].toLowerCase() === heading[1].trim().toLowerCase()) ?? section;
+            continue;
+        }
+        const item = /^[-*]\s+(.+)$/.exec(line);
+        if (item)
+            notes[section].push(item[1].trim());
+    }
+    return notes;
+}
+export function formatNotes(notes) {
+    const parts = ["# Working notes", ""];
+    for (const key of ORDER) {
+        parts.push(`## ${SECTIONS[key]}`, "", ...(notes[key].length > 0 ? notes[key].map((line) => `- ${line}`) : ["(nothing yet)"]), "");
+    }
+    return parts.join("\n").trimEnd() + "\n";
+}
+export function readNotes(buildDir) {
+    const path = notesPath(buildDir);
+    return existsSync(path) ? parseNotes(readFileSync(path, "utf8")) : empty();
+}
+function isEmpty(notes) {
+    return ORDER.every((key) => notes[key].length === 0);
+}
+const GUIDANCE = [
+    "Before you finish, call update_notes to leave the next agent on this codebase what you learned - a fresh",
+    "session that knows nothing of your work. Update them, do not rewrite them: add a line, change one that is",
+    "no longer true, remove one that is wrong. In short lines, per section:",
+    `- ${SECTIONS.where}: entry points, layout, where each functionality and its tests live.`,
+    `- ${SECTIONS.run}: the commands that build, run and test it, and what had to be installed for them.`,
+    `- ${SECTIONS.assumptions}: what you assumed where the specification is silent - a format, a default, a`,
+    "  choice it leaves open. Build on the assumptions already there; change or remove one the moment the code",
+    "  or the specification shows it wrong.",
+    `- ${SECTIONS.gaps}: what the specification should say and does not - a behaviour you had to decide that the`,
+    "  person would want to decide, not a detail of how. Each is put to the person, to be written into the",
+    "  specification. One a line, as the question it leaves: \"What happens to a contact archived in HubSpot after it",
+    "  was synced?\"",
+    `- ${SECTIONS.pitfalls}: what went wrong and what fixed it, approaches that did not work.`,
+    `- ${SECTIONS.pulses}: written by turri as each pulse ends - read them, never write them.`,
+    "Each line stands on its own, for someone who never saw your work. When and where it came from is added",
+    "to it for you - do not write it. Where two lines disagree, the later one is right: change the older one",
+    'rather than add a contradicting line. Leave a section with nothing new alone: "none" is not a note.',
+    "Stubborn on the specification, flexible on the assumptions: the specification is never an assumption, and",
+    "never copied here. Where an assumption and the specification disagree, the specification is right.",
+].join("\n");
+/** A prompt, led by the notes earlier agents left - and told to update them for the next. */
+export function withNotes(prompt, buildDir) {
+    const notes = readNotes(buildDir);
+    const earlier = isEmpty(notes)
+        ? "No earlier agent has left notes on this codebase yet."
+        : [
+            "<notes from earlier agents>",
+            formatNotes(notes).trimEnd(),
+            "</notes from earlier agents>",
+            "",
+            "Earlier agents on this codebase wrote these down, to spare you exploring from scratch; they may be out of",
+            "date - how to weigh them is below. The pitfalls include what earlier reviews sent tests back for: write your",
+            "tests so they would pass those reviews the first time.",
+        ].join("\n");
+    return `${earlier}\n\n${prompt}\n\n${GUIDANCE}`;
+}
+/**
+ * What an agent a review sent tests back to is asked to leave: the lesson, not the fix - the kind of
+ * test the review found weak or missing, and how to write it instead - so every later agent on the
+ * codebase writes it right from its first test, and the first reviews have less to send back.
+ */
+export const REVIEW_LESSON = [
+    "",
+    "Then leave the lesson for the agents after you: call update_notes and add to the pitfalls what this review taught",
+    "you - the kind of test it found weak or missing, and how to write it instead - as a rule the next agent can follow",
+    "from its first test, not a record of this one fix: e.g. \"Tests assert the exact response body and status, never only",
+    "that one came back\". One short line per lesson; skip one the notes already have, and sharpen one that was not enough.",
+];
+/**
+ * After an agent worked on what a review found: when it left no new pitfall - no lesson - it is asked
+ * once more, so the next agent does not make the same tests the review has to send back again.
+ */
+export async function reflectOnReview(buildDir, pitfallsBefore, send) {
+    const known = new Set(pitfallsBefore);
+    if (readNotes(buildDir).pitfalls.some((line) => !known.has(line)))
+        return;
+    await send([
+        "You worked on what the review found, but left no lesson in the notes. Call update_notes now and add to the pitfalls",
+        "the kind of test the review found weak or missing, and how to write it instead - a rule the next agent on this",
+        "codebase can follow from its first test, so the review does not have to send the same back again. Change nothing else.",
+    ].join("\n"));
+}
+const SOURCE = /^\[[^\]\n]+\]\s+/;
+/** A line without the `[where it came from]` in front. */
+function body(line) {
+    return line.trim().replace(/^[-*]\s+/, "").replace(SOURCE, "");
+}
+/**
+ * What says nothing: a line whose whole point is that there is nothing to say. Kept narrow, so
+ * "None of the endpoints need auth" is still a note.
+ */
+const FILLER = [
+    /^(none|n\/a|na|nothing|not applicable)( (specifically|so far|yet|found|noted|new|here|at all|for (this|now|the)|to (add|note|report))\b.*)?[.!]?$/i,
+    /^no (new |other |specific )?(pitfalls?|assumptions?|notes?|issues?|problems?)( (so far|yet|found|noted|here|for (this|now|the))\b.*)?[.!]?$/i,
+];
+export function isFiller(text) {
+    const line = body(text);
+    return line === "" || FILLER.some((pattern) => pattern.test(line));
+}
+/** A line in a section that is, or starts with, what the agent quoted - where it came from aside. */
+function find(lines, quoted) {
+    const wanted = body(quoted);
+    const exact = lines.findIndex((line) => body(line) === wanted);
+    return exact !== -1 ? exact : lines.findIndex((line) => body(line).startsWith(wanted));
+}
+/** A note about running the project's testing scripts by hand. */
+const RUNS_TESTING_SCRIPTS = /test_scripts\/|\brun_(unittests|unit_tests|conformance_tests)\w*\.sh\b/;
+/**
+ * Apply the changes; the notes that result, or what could not be applied. A line added or
+ * changed is stamped with `stamp` - when, and which step wrote it.
+ */
+export function applyNotesChanges(notes, changes, stamp) {
+    const next = Object.fromEntries(ORDER.map((key) => [key, [...(notes[key] ?? [])]]));
+    const problems = [];
+    for (const change of changes) {
+        const lines = next[change.section];
+        const said = body(change.text.replace(/\s*\n\s*/g, " "));
+        const text = stamp ? `[${stamp}] ${said}` : said;
+        // How the tests are run is the harness's: a note telling the next agent to run the project's
+        // testing scripts itself sends it looking for files it cannot reach, and writing its own.
+        if (change.action !== "remove" && RUNS_TESTING_SCRIPTS.test(said)) {
+            problems.push(`"${change.text.trim()}" tells the next agent to run the testing scripts itself. It cannot: they are not in the ` +
+                "codebase, and run_unit_tests and run_conformance_tests are how the tests are run. Leave that out.");
+            continue;
+        }
+        if (change.action !== "remove" && isFiller(said)) {
+            problems.push(`"${change.text.trim()}" in ${SECTIONS[change.section]} is not a note. Leave a section with nothing new alone.`);
+            continue;
+        }
+        if (change.action === "add") {
+            if (!lines.some((line) => body(line) === said))
+                lines.push(text);
+            continue;
+        }
+        const target = change.action === "change" ? change.replaces ?? "" : text;
+        if (target.trim() === "") {
+            problems.push(`A ${change.action} in ${SECTIONS[change.section]} has to name the line it ${change.action === "change" ? "replaces, in `replaces`" : "removes"}.`);
+            continue;
+        }
+        const at = find(lines, target);
+        if (at === -1) {
+            problems.push(`${SECTIONS[change.section]} has no line "${target}". Its lines now:\n` +
+                (lines.length > 0 ? lines.map((line) => `  - ${line}`).join("\n") : "  (none)"));
+            continue;
+        }
+        if (change.action === "remove")
+            lines.splice(at, 1);
+        else
+            lines[at] = text;
+    }
+    return { notes: next, problems };
+}
+/** The local time, to the minute: `2026-09-24 16:49`. */
+function now() {
+    const d = new Date();
+    const two = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())} ${two(d.getHours())}:${two(d.getMinutes())}`;
+}
+/** `update_notes`: lines added, changed or removed, never the notes rewritten. */
+export function createNotesTool(buildDir, onWrite, before = () => { }, source) {
+    return defineTool({
+        name: "update_notes",
+        label: "Update notes",
+        description: "Update the working notes on this codebase for the next agent - add a line, change one that is no longer " +
+            "true, remove one that is wrong - in its sections: where things are, how to build, run and test, " +
+            "assumptions made where the specification is silent, spec gaps the person should decide, and pitfalls. Never " +
+            "requirements: the specification is never an assumption.",
+        promptSnippet: "leave the next agent what you learned and assumed about this codebase",
+        parameters: Type.Object({
+            changes: Type.Array(Type.Object({
+                // Any wording of a section is taken - "where", "Where things are" - rather than failing the whole call.
+                section: Type.String({
+                    description: `One of: ${ORDER.map((key) => `${key} (${SECTIONS[key]})`).join(", ")}`,
+                }),
+                action: Type.Union([Type.Literal("add"), Type.Literal("change"), Type.Literal("remove")]),
+                text: Type.String({
+                    description: "The line to add, the new line for a change, or the line to remove - one short line that stands on its " +
+                        "own. When and where it came from is added for you.",
+                }),
+                replaces: Type.Optional(Type.String({ description: "For a change: the line it replaces, as it reads now" })),
+            }), { minItems: 1 }),
+        }),
+        async execute(_id, params) {
+            before();
+            const unknown = params.changes.filter((change) => sectionNamed(change.section) === undefined);
+            if (unknown.length > 0) {
+                throw new Error(`Nothing saved - ${unknown.map((change) => `"${change.section}"`).join(", ")} is not a section. ` +
+                    `The sections are: ${ORDER.map((key) => `${key} (${SECTIONS[key]})`).join(", ")}.`);
+            }
+            const changes = params.changes.map((change) => ({ ...change, section: sectionNamed(change.section) }));
+            const theirs = changes.filter((change) => HARNESS_ONLY.includes(change.section));
+            if (theirs.length > 0) {
+                throw new Error(`Nothing saved - ${theirs.map((change) => SECTIONS[change.section]).join(", ")} is written by turri as each pulse ends, not by you.`);
+            }
+            const { notes, problems } = applyNotesChanges(readNotes(buildDir), changes, source === undefined ? undefined : `${now()} · ${source}`);
+            if (problems.length > 0) {
+                throw new Error(`Nothing saved - fix these and call update_notes again:\n\n${problems.join("\n\n")}`);
+            }
+            const text = formatNotes(notes);
+            writeFileSync(notesPath(buildDir), text);
+            onWrite(text);
+            return { content: [{ type: "text", text: "Notes updated." }], details: { characters: text.length } };
+        },
+    });
+}
+/** The section a name means - its key or its heading, in any case, or the heading's first words. */
+export function sectionNamed(name) {
+    const wanted = name.trim().toLowerCase().replace(/[^a-z, ]+/g, " ").replace(/\s+/g, " ").trim();
+    if (wanted === "")
+        return undefined;
+    return (ORDER.find((key) => key === wanted || SECTIONS[key].toLowerCase() === wanted) ??
+        ORDER.find((key) => SECTIONS[key].toLowerCase().startsWith(wanted) || wanted.startsWith(key)));
+}
+/** How many times an agent that finishes without update_notes is asked to call it. */
+export const NOTES_ASKS = 3;
+/** The turn that asks for the notes: update_notes is the only tool it may use - the work it follows is done. */
+export const NOTES_TURN = { onlyTools: ["update_notes"] };
+/** What the notes turn says first, once the harness's own run of `script` has passed on the work. */
+export function passedOutcome(script) {
+    return (`The harness ran the project's ${script} on your work itself, and it passed: your work is done and accepted. ` +
+        "Write the notes as of work that succeeded - never that the tests could not be made to pass.");
+}
+function current(buildDir) {
+    const path = notesPath(buildDir);
+    return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+}
+/**
+ * A line the harness itself writes into the notes - an attempt at a failing conformance run, what
+ * was judged wrong and what was done about it - stamped like an agent's, and kept as update_notes
+ * would keep it, so no session takes it for a direct write. Never fails the work it records.
+ */
+export function recordNote(buildDir, section, text, source) {
+    try {
+        const { notes, problems } = applyNotesChanges(readNotes(buildDir), [{ section, action: "add", text }], `${now()} · ${source}`);
+        if (problems.length > 0)
+            return;
+        const formatted = formatNotes(notes);
+        writeFileSync(notesPath(buildDir), formatted);
+        knownNotes.set(notesPath(buildDir), formatted);
+    }
+    catch {
+        // The notes are a help, not the work.
+    }
+}
+/**
+ * A pulse's line, written by the harness as the pulse ends - landed or not: what it regenerated, how it went, where its
+ * log is. The last PULSES_KEPT stay; the module's history has every pulse.
+ */
+export function recordPulse(buildDir, text, source) {
+    try {
+        const notes = readNotes(buildDir);
+        notes.pulses = [...notes.pulses, `[${now()} · ${source}] ${text.replace(/\s+/g, " ").trim()}`].slice(-PULSES_KEPT);
+        const formatted = formatNotes(notes);
+        writeFileSync(notesPath(buildDir), formatted);
+        knownNotes.set(notesPath(buildDir), formatted);
+    }
+    catch {
+        // The notes are a help, not the work.
+    }
+}
+/** The lines of a section added since `before` - a pulse's new spec gaps, say - without when and where they came from. */
+export function linesAddedSince(before, buildDir, section) {
+    const known = new Set(before[section]);
+    return readNotes(buildDir)[section].filter((line) => !known.has(line)).map((line) => line.replace(/^\[[^\]]*\]\s*/, ""));
+}
+/** The notes, for an agent that reads them but leaves none - a judge. Empty when there are none. */
+export function notesToRead(buildDir) {
+    const notes = readNotes(buildDir);
+    return isEmpty(notes) ? "" : `<notes from earlier agents>\n${formatNotes(notes).trimEnd()}\n</notes from earlier agents>`;
+}
+/**
+ * The notes tool for one agent's session, and the check that it was used. The notes as they
+ * were when the agent started, or as update_notes last left them, are the only notes: a change
+ * made to the file any other way is undone. An agent that finishes without calling update_notes
+ * is asked to, until it has. `source` is the step it is - `backend 3`, `backend 3 conformance` -
+ * and every line it writes says so, with the time.
+ */
+/**
+ * The notes as update_notes last left them, by file - shared by every session on the codebase, so
+ * one agent's update is not taken for another's direct write. Two agents can work one codebase in
+ * the same run: the conformance agent, and the coding agent it sends the code to.
+ */
+const knownNotes = new Map();
+export function notesForSession(buildDir, source) {
+    let written = false;
+    const file = notesPath(buildDir);
+    // What is there when the session starts is what it starts from; after that, update_notes says.
+    knownNotes.set(file, current(buildDir));
+    /** Put back what update_notes did not write; whether there was anything to put back. */
+    const undoDirectWrites = () => {
+        const known = knownNotes.get(file);
+        if (current(buildDir) === known)
+            return false;
+        if (known === undefined)
+            rmSync(file, { force: true });
+        else
+            writeFileSync(file, known);
+        return true;
+    };
+    return {
+        tool: createNotesTool(buildDir, (text) => {
+            written = true;
+            knownNotes.set(file, text);
+        }, undoDirectWrites, source),
+        /**
+         * Ask for the notes until this agent has updated them; whether it has. `outcome`: how the harness's own check of the
+         * work went, said first - so the notes tell the next agent the work passed, never that it could not be made to.
+         */
+        async ensureWritten(ask, outcome) {
+            for (let round = 0; round < NOTES_ASKS && !written; round++) {
+                const undone = undoDirectWrites();
+                await ask((outcome !== undefined ? `${outcome} ` : "") +
+                    (undone
+                        ? `You changed ${NOTES_FILE} directly, and that was undone: the notes are written only through update_notes. `
+                        : "") +
+                    "Before you finish: call update_notes - add what you learned about this codebase, change what is no longer " +
+                    "true, and record the assumptions you made where the specification is silent. Call the tool itself; " +
+                    "writing the file does not count. Your work is done: this turn is for the notes alone - every other tool is " +
+                    "refused, so change nothing else.");
+            }
+            undoDirectWrites();
+            if (!written) {
+                reportActivity(`${basename(dirname(buildDir))}: its agent left no notes, though asked ${NOTES_ASKS} times`);
+            }
+            return written;
+        },
+    };
+}