@turri-dev/cli 0.1.19-next.ee6bc61 → 0.1.20-next.3ae4a0b

package/dist/sentinel-chat.js

@@ -0,0 +1,178 @@
+import { Box, Text } from "@earendil-works/pi-tui";
+import { readProjectConfig, roleModel } from "./config.js";
+import { concludedNote, concludeTool, keepGuidanceTool, notifyTool, sentinelFileTools } from "./sentinel.js";
+/**
+ * The sentinel in a chat: its tools in place of the chat's - the project to read, its shell behind the walls, notices,
+ * its guidance, a host's own - its model, and, in every chat, the notices it puts to the person: a card in the chat and,
+ * in the terminal, a dialog once the chat is idle (docs/sentinel.md).
+ */
+/** A notice in the transcript: the card. */
+const NOTICE_ENTRY = "turri_notice";
+/** A notice's end, under its card: answered, dismissed, superseded by a newer one about its module. */
+const NOTICE_OVER_ENTRY = "turri_notice_over";
+/** The sentinel done with a pulse, in the chat the person is in. */
+const CONCLUDED_ENTRY = "turri_sentinel_concluded";
+const STEER = "Say what to do instead…";
+const DISMISS = "Dismiss";
+/** The sentinel's tools and model, built into its chat. */
+export function registerSentinel(pi, session, cwd, hostTools, allowed) {
+    // pi's own file tools and shell, replaced by fenced ones of the same names: the whole project to read, nothing to write.
+    for (const tool of sentinelFileTools(cwd))
+        pi.registerTool(tool);
+    pi.registerTool(notifyTool((input) => {
+        const job = input.job !== undefined ? session.jobs.get(input.job) : undefined;
+        const module = input.module ?? job?.module;
+        return session.notice({ ...input, ...(module !== undefined ? { module } : {}), ...(job?.pulse !== undefined ? { pulse: job.pulse } : {}) });
+    }));
+    pi.registerTool(concludeTool((conclusion) => session.concluded(conclusion)));
+    pi.registerTool(keepGuidanceTool(cwd));
+    for (const tool of hostTools)
+        pi.registerTool(tool);
+    // Only its tools are offered to its model; what it calls besides is refused (extension.ts, tool_call).
+    let modelSet = false;
+    pi.on("session_start", async (_event, ctx) => {
+        try {
+            pi.setActiveTools(pi.getAllTools().map((tool) => tool.name).filter((name) => allowed.has(name)));
+        }
+        catch {
+            /* a session let go has no tools to set */
+        }
+        // Its model, once: the `sentinel` role's, else the chat's - what the person then picks in its chat stands.
+        if (modelSet)
+            return;
+        modelSet = true;
+        const choice = roleModel(readProjectConfig(cwd), "sentinel");
+        if (choice?.model !== undefined) {
+            const slash = choice.model.indexOf("/");
+            const found = slash === -1 ? undefined : ctx.modelRegistry.find(choice.model.slice(0, slash), choice.model.slice(slash + 1));
+            if (found !== undefined)
+                await pi.setModel(found);
+        }
+        if (choice?.thinking !== undefined)
+            pi.setThinkingLevel(choice.thinking);
+    });
+}
+/**
+ * A chat's notices: each drawn as a card, and - with no host to answer it - put to the person as a dialog once the chat
+ * is idle, one at a time: an action accepted, their own words, or dismissed. A notice that is over closes its dialog.
+ */
+export function noticeDialogs(pi, session, link, context) {
+    const waiting = [];
+    const asking = new Map();
+    let open = false;
+    pi.registerEntryRenderer(NOTICE_ENTRY, (entry, _options, theme) => {
+        const notice = entry.data;
+        if (notice === undefined)
+            return undefined;
+        const mark = notice.severity === "error" ? theme.fg("error", "✗") : notice.severity === "warning" ? theme.fg("warning", "!") : theme.fg("accent", "·");
+        const about = notice.module !== undefined ? `${notice.module}${notice.pulse !== undefined ? ` · pulse ${notice.pulse}` : ""}` : "";
+        const lines = [
+            `${mark} ${theme.fg("muted", `sentinel${about !== "" ? ` · ${about}` : ""}`)}`,
+            `  ${theme.fg("text", notice.summary)}`,
+            ...notice.evidence.map((line) => theme.fg("muted", `    ${line}`)),
+            ...notice.actions.map((action, index) => `  ${theme.fg("accent", `${index + 1}.`)} ${action.label}`),
+        ];
+        const box = new Box(1, 0);
+        box.addChild(new Text(lines.join("\n"), 0, 0));
+        return box;
+    });
+    pi.registerEntryRenderer(CONCLUDED_ENTRY, (entry, _options, theme) => {
+        const data = entry.data;
+        if (data === undefined)
+            return undefined;
+        const about = data.module !== undefined ? `${data.module}${data.pulse !== undefined ? ` · pulse ${data.pulse}` : ""}` : data.job;
+        const mark = data.verdict === "holds" ? theme.fg("success", "✓") : theme.fg("error", "✗");
+        const box = new Box(1, 0);
+        box.addChild(new Text(`${mark} ${theme.fg("muted", `sentinel · ${about} · ${data.verdict === "holds" ? "checked, it holds" : "found something wrong"}`)}\n  ${theme.fg("text", data.summary)}`, 0, 0));
+        return box;
+    });
+    pi.registerEntryRenderer(NOTICE_OVER_ENTRY, (entry, _options, theme) => {
+        const data = entry.data;
+        if (data === undefined)
+            return undefined;
+        const said = data.state === "superseded" ? "superseded by a newer notice" : data.state === "dismissed" ? "dismissed" : data.state === "steered" ? "answered in your words" : "accepted";
+        const box = new Box(1, 0);
+        box.addChild(new Text(theme.fg("muted", `  ${said}: ${data.summary}`), 0, 0));
+        return box;
+    });
+    const ask = async () => {
+        if (open || link.session()?.isStreaming === true)
+            return;
+        const notice = waiting.shift();
+        if (notice === undefined)
+            return;
+        if (notice.state !== "open")
+            return ask();
+        const ctx = context();
+        if (ctx === undefined || !ctx.hasUI) {
+            waiting.unshift(notice);
+            return;
+        }
+        open = true;
+        const controller = new AbortController();
+        asking.set(notice.id, controller);
+        try {
+            const options = [...notice.actions.map((action, index) => `${index + 1}. ${action.label}`), STEER, DISMISS];
+            const picked = await ctx.ui.select(`sentinel: ${notice.summary}`, options, { signal: controller.signal });
+            if (controller.signal.aborted || notice.state !== "open")
+                return;
+            if (picked === STEER) {
+                const words = await ctx.ui.input("What should be done about it?", "", { signal: controller.signal });
+                if (controller.signal.aborted || notice.state !== "open")
+                    return;
+                if (words === undefined || words.trim() === "")
+                    waiting.unshift(notice);
+                else
+                    session.answer(notice.id, { steer: words });
+                return;
+            }
+            const index = options.indexOf(picked ?? DISMISS);
+            session.answer(notice.id, index >= 0 && index < notice.actions.length ? { action: index } : { dismiss: true });
+        }
+        catch {
+            /* a dialog the chat lost - let go, or rebuilt - leaves the notice for the next */
+        }
+        finally {
+            asking.delete(notice.id);
+            open = false;
+            void ask();
+        }
+    };
+    pi.on("agent_settled", () => void ask());
+    return {
+        put(notice) {
+            try {
+                pi.appendEntry(NOTICE_ENTRY, notice);
+            }
+            catch {
+                /* the host still hears of it */
+            }
+            // A host answers it itself: its card, its buttons.
+            if (session.host.onNotice !== undefined)
+                return;
+            waiting.push(notice);
+            void ask();
+        },
+        concluded(conclusion) {
+            try {
+                pi.appendEntry(CONCLUDED_ENTRY, conclusion);
+            }
+            catch {
+                /* the agent is still told */
+            }
+            void pi.sendMessage({ customType: "turri_sentinel_concluded", content: concludedNote(conclusion), display: false, details: { jobId: conclusion.job, verdict: conclusion.verdict } }, { triggerTurn: true, deliverAs: "followUp" });
+        },
+        over(notice) {
+            asking.get(notice.id)?.abort();
+            const at = waiting.indexOf(notice);
+            if (at !== -1)
+                waiting.splice(at, 1);
+            try {
+                pi.appendEntry(NOTICE_OVER_ENTRY, { state: notice.state, summary: notice.summary });
+            }
+            catch {
+                /* a chat let go says nothing */
+            }
+        },
+    };
+}

package/dist/sentinel.d.ts

@@ -0,0 +1,55 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Job } from "./regenerate/jobs.ts";
+import type { DeployedProcess } from "./regenerate/release.ts";
+import { type Conclusion, type Notice, type NoticeInput } from "./notice.ts";
+export * from "./notice.ts";
+/**
+ * The sentinel: a chat of the session's own that every finished pulse goes to (docs/sentinel.md). It checks how each
+ * pulse went - and, with `release-after-pulse` on, tests what was released - finds out why when something is wrong, and
+ * puts it to the person as a notice in the chat they look at, with what they can do about it. It changes nothing: its
+ * file tools only read, its shell runs with the project read only, and it has none of the tools that change ***plain or
+ * start work. The chat the person talks to is never interrupted for a pulse that went well.
+ */
+/** Whether the project wants a sentinel: `sentinel:` in config.turri.yaml, true unset. */
+export declare function sentinelOn(cwd: string): boolean;
+/** A pulse that stopped on ***plain that contradicts itself: put to the person by turri itself, the way out the chat's to work out. */
+export declare function specConflictNotice(job: Job, task: string): NoticeInput;
+export declare function guidanceFile(cwd: string): string;
+export declare function readGuidance(cwd: string): string;
+export declare function keepGuidance(cwd: string, text: string): void;
+/**
+ * What a chat of the person's is told of the pulses that end: told itself, of those asked for in it - or, with the
+ * sentinel on, nothing, the sentinel telling the person what needs them.
+ */
+export declare function pulseEndsBlock(sentinel: boolean): string;
+/**
+ * What the chat the person is in is told of a pulse that landed, with the sentinel on: that it landed, what the sentinel
+ * does with it - and to tell the person so, and do nothing else about it.
+ */
+export declare function landedNote(job: Job, released: DeployedProcess[]): string;
+/** Its identity and its task, in its system prompt in place of the conversation's. */
+export declare function sentinelPrompt(cwd: string, options?: {
+    extraTools?: string[];
+}): string;
+/** What the sentinel is told of one finished pulse: the ledger's facts, the chats, and what was released. */
+export declare function sentinelBrief(job: Job, context: {
+    project: string;
+    asked?: string;
+    focused?: string;
+    released: DeployedProcess[];
+    releaseAfterPulse: boolean;
+    reaction: string;
+}): string;
+/** The tools the sentinel's agent may call: what reads, its notices and its guidance - and what a host gives it. */
+export declare const SENTINEL_TOOLS: string[];
+/**
+ * Its file tools and shell: the whole project to read and nothing to write - the shell behind the command check, the OS
+ * sandbox where one is up, and the audit, with the network open. Its home and temporary folder are its own, in the
+ * modules' scratch.
+ */
+export declare function sentinelFileTools(cwd: string): ToolDefinition[];
+export declare function notifyTool(notify: (input: NoticeInput) => Notice | undefined): ToolDefinition;
+export declare function concludeTool(conclude: (conclusion: Conclusion) => string | undefined): ToolDefinition;
+/** What the chat the person is in is told when the sentinel is done with a pulse: to say so, and do nothing more. */
+export declare function concludedNote(conclusion: Conclusion): string;
+export declare function keepGuidanceTool(cwd: string): ToolDefinition;

package/dist/sentinel.js

@@ -0,0 +1,279 @@
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { readProjectConfig } from "./config.js";
+import { confinedTools } from "./regenerate/confine.js";
+import { describeSpecConflict } from "./regenerate/stop-report.js";
+import { didNotPass } from "./regenerate/job-panel.js";
+import { formatDuration, pulseName } from "./regenerate/jobs.js";
+import { readLedger } from "./regenerate/ledger.js";
+import { describePulseView, pulseView } from "./regenerate/ledger-view.js";
+import { MODULES_DIR, ensureInScratch } from "./regenerate/paths.js";
+import { SENTINEL, wentWrong } from "./notice.js";
+export * from "./notice.js";
+/**
+ * The sentinel: a chat of the session's own that every finished pulse goes to (docs/sentinel.md). It checks how each
+ * pulse went - and, with `release-after-pulse` on, tests what was released - finds out why when something is wrong, and
+ * puts it to the person as a notice in the chat they look at, with what they can do about it. It changes nothing: its
+ * file tools only read, its shell runs with the project read only, and it has none of the tools that change ***plain or
+ * start work. The chat the person talks to is never interrupted for a pulse that went well.
+ */
+/** Whether the project wants a sentinel: `sentinel:` in config.turri.yaml, true unset. */
+export function sentinelOn(cwd) {
+    try {
+        return readProjectConfig(cwd).sentinel !== false;
+    }
+    catch {
+        return true;
+    }
+}
+/** A pulse that stopped on ***plain that contradicts itself: put to the person by turri itself, the way out the chat's to work out. */
+export function specConflictNotice(job, task) {
+    return {
+        severity: "warning",
+        summary: `${pulseName(job)} stopped: two functional specs contradict each other`,
+        evidence: describeSpecConflict(job.specConflict).split("\n").filter((line) => line.trim() !== ""),
+        actions: [{ label: "Work out the conflict with me", task }],
+        ...(job.module !== undefined ? { module: job.module } : {}),
+        job: job.id,
+        ...(job.pulse !== undefined ? { pulse: job.pulse } : {}),
+    };
+}
+// ---------------------------------------------------------------------------------------------
+// The person's guidance: what they told the sentinel, kept apart from its conversation.
+export function guidanceFile(cwd) {
+    const scratch = join(cwd, ".turri");
+    ensureInScratch(scratch, scratch);
+    return join(scratch, "sentinel.md");
+}
+export function readGuidance(cwd) {
+    try {
+        const file = join(cwd, ".turri", "sentinel.md");
+        return existsSync(file) ? readFileSync(file, "utf8").trim() : "";
+    }
+    catch {
+        return "";
+    }
+}
+export function keepGuidance(cwd, text) {
+    const line = text.replace(/\s+/g, " ").trim();
+    if (line === "")
+        return;
+    appendFileSync(guidanceFile(cwd), `- ${line} (${new Date().toISOString().slice(0, 16).replace("T", " ")})\n`);
+}
+// ---------------------------------------------------------------------------------------------
+// What the sentinel is told.
+/**
+ * What a chat of the person's is told of the pulses that end: told itself, of those asked for in it - or, with the
+ * sentinel on, nothing, the sentinel telling the person what needs them.
+ */
+export function pulseEndsBlock(sentinel) {
+    return sentinel
+        ? [
+            "<pulse-ends>",
+            "The sentinel - a chat of my own, beside this one - checks every pulse that finishes and tests what was released.",
+            "When a pulse lands, the chat the person is in is told, to tell them it landed and what the sentinel does with it -",
+            "and nothing more: the pulse is the sentinel's. A pulse that went wrong you are not told of. What needs the person, the",
+            "sentinel puts to them as a notice in the chat they are in: what is wrong, and what can be done. When they accept",
+            "one, you are given it, and what they chose: do it.",
+            "</pulse-ends>",
+        ].join("\n")
+        : "<pulse-ends>\nWhen a pulse asked for in this chat ends, you are told, and react to it.\n</pulse-ends>";
+}
+/**
+ * What the chat the person is in is told of a pulse that landed, with the sentinel on: that it landed, what the sentinel
+ * does with it - and to tell the person so, and do nothing else about it.
+ */
+export function landedNote(job, released) {
+    const wasReleased = job.details?.released === true;
+    const where = released.map((item) => `${item.name} at ${item.url ?? item.command}`).join(", ");
+    return [
+        `Pulse ${job.id} - ${pulseName(job)} - landed, after ${formatDuration(job)}.`,
+        "",
+        (job.report ?? "").trim(),
+        "",
+        `The sentinel - a chat of my own beside this one - is checking it now${wasReleased ? `, and testing what was released${where !== "" ? ` (${where})` : ""}` : ""}. If it finds something wrong, it puts it to the person in the chat they are in, with what can be done; when it is done, you are told.`,
+        "",
+        `Tell the person, in a line or two, what landed and that the sentinel is checking it${wasReleased ? " and testing the release" : ""}. Do nothing else about it: the pulse is the sentinel's now. Do not test it, release it, open it, run anything for it, or start other work because of it - whatever the project's guidance says to do when a pulse finishes.`,
+    ].join("\n");
+}
+/** Its identity and its task, in its system prompt in place of the conversation's. */
+export function sentinelPrompt(cwd, options = {}) {
+    const guidance = readGuidance(cwd);
+    return [
+        "<sentinel>",
+        "You are turri's sentinel: a chat of turri's own, beside the chats the person talks to while they build their software",
+        "with turri. Every pulse that finishes comes to you, as a message turri writes - what the pulse was, how it ended,",
+        "its ***plain diff, its log, and what was released. The person does not watch you: they are in another chat, and",
+        "hear from you only through notify_person.",
+        "",
+        "For each pulse:",
+        "1. Check how it went, from what turri tells you - and, when that is not enough, its log, the ledger (ledger, pulses),",
+        "   diagnose, and the code and the ***plain, which you read.",
+        "2. When it was released (the message says so - release-after-pulse is on), test what was released: it is running",
+        "   where the message says. How far you test is yours to judge, from what the pulse changed and what the ***plain says",
+        "   it should do: that it came up, answers, and does what its ***plain diff says it now does.",
+        "3. When something is wrong - the pulse failed or stopped, it did not pass, the release did not come up, the software",
+        "   does not do what its ***plain says - find out why, and call notify_person once: what is wrong, what shows it,",
+        "   and what the person can do about it, each a task the agent of their chat can carry out once they accept it - a",
+        "   change to the ***plain, a setting, a credential to provide, a pulse to regenerate again. Be exact: the task is",
+        "   all that agent is given.",
+        "4. When all is well, notify no one.",
+        "5. Last, call conclude once for the pulse - holds or wrong, and in a line or two what you checked and what you found:",
+        "   the chat the person is in is told, whether all is well or not. Then say the same here, in a line or two.",
+        "",
+        "You change nothing. Your file tools read the whole project and write nothing; your shell runs with the project",
+        "read only. You never regenerate, steer, release or change ***plain yourself, and never ask the person questions -",
+        "a notice is how you reach them. A newer message about the same module can arrive while you check an older pulse",
+        "that went well: leave the older one and check the newer.",
+        "",
+        "The person can talk to you here. When they tell you how to check - what to test, what to leave alone, where things",
+        "run - keep it with keep_guidance, in their words, so it holds from now on.",
+        ...(options.extraTools !== undefined && options.extraTools.length > 0 ? ["", `The host gives you ${options.extraTools.join(", ")} to test with as well.`] : []),
+        "</sentinel>",
+        ...(guidance !== "" ? ["", "<guidance>", "What the person told you to keep in mind:", guidance, "</guidance>"] : []),
+    ].join("\n");
+}
+/** What the sentinel is told of one finished pulse: the ledger's facts, the chats, and what was released. */
+export function sentinelBrief(job, context) {
+    const view = (() => {
+        try {
+            const entries = readLedger(context.project, { job: job.id });
+            const found = pulseView(job.id, entries);
+            return found !== undefined ? describePulseView(found) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    const ended = job.status === "succeeded"
+        ? didNotPass(job)
+            ? "ran to its end, and what it built did not pass"
+            : "finished, and landed what it built"
+        : job.status === "stopped"
+            ? "was stopped"
+            : "failed";
+    const lines = [`Pulse ${job.id} - ${pulseName(job)} - ${ended}, after ${formatDuration(job)}.`];
+    if (context.asked !== undefined)
+        lines.push(`It was asked for in the chat "${context.asked}".`);
+    if (context.focused !== undefined)
+        lines.push(`The person is in the chat "${context.focused}": a notice goes there.`);
+    lines.push("", job.status === "succeeded" ? (job.report ?? "").trim() : (job.error ?? job.note ?? "").trim());
+    if (view !== undefined)
+        lines.push("", "What the ledger has of it:", view);
+    else if (job.diff !== undefined && job.diff.trim() !== "")
+        lines.push("", "Its ***plain diff:", job.diff.trimEnd());
+    if (job.logFile !== undefined)
+        lines.push("", `Its log: ${job.logFile}`);
+    const released = job.details?.released === true;
+    if (released) {
+        lines.push("", "It was released, as its last stage (release-after-pulse). What runs now:");
+        if (context.released.length === 0)
+            lines.push("  nothing is running for it: the release did not leave anything running.");
+        for (const item of context.released)
+            lines.push(`  ${item.name}: ${item.url ?? item.command} - in ${item.dir}, its output in ${item.log}`);
+        lines.push("Test it.");
+    }
+    else if (job.status === "succeeded" && !didNotPass(job)) {
+        lines.push("", context.releaseAfterPulse ? "Nothing was released after it." : "release-after-pulse is off: nothing was released, and you test nothing running - check the pulse alone.");
+    }
+    if (job.specConflict !== undefined) {
+        lines.push("", "It stopped on two functional specs that contradict each other: turri has put that to the person itself. Notify no one about it.");
+    }
+    else if (wentWrong(job)) {
+        lines.push("", "It went wrong: find out why, and notify the person. What the chat would have been told to do about it - each step of it", "that changes or installs something is a task for a notice's action, not yours:", context.reaction);
+    }
+    lines.push("", `When you are done with it, call conclude for ${job.id} - whether all is well or not.`);
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------------------------
+// Its tools.
+/** The tools the sentinel's agent may call: what reads, its notices and its guidance - and what a host gives it. */
+export const SENTINEL_TOOLS = ["read", "ls", "grep", "find", "bash", "read_output", "ledger", "pulses", "diagnose", "validate", "doctor", "web_search", "web_fetch", "notify_person", "conclude", "keep_guidance"];
+/**
+ * Its file tools and shell: the whole project to read and nothing to write - the shell behind the command check, the OS
+ * sandbox where one is up, and the audit, with the network open. Its home and temporary folder are its own, in the
+ * modules' scratch.
+ */
+export function sentinelFileTools(cwd) {
+    return confinedTools({ workdir: cwd, read: [cwd], write: [], shellHome: join(cwd, MODULES_DIR, `.${SENTINEL}`) }).tools;
+}
+export function notifyTool(notify) {
+    return defineTool({
+        name: "notify_person",
+        label: "Notify",
+        description: "Put what is wrong with a finished pulse to the person, in the chat they are in: what is wrong, what shows it, and what " +
+            "they can do about it. Each action is a task the agent of their chat carries out once they accept it. Only when they " +
+            "need to act - never for a pulse that went well.",
+        parameters: Type.Object({
+            severity: Type.Union([Type.Literal("error"), Type.Literal("warning"), Type.Literal("info")], { description: "error: it is broken; warning: it works but not as its ***plain says, or something is missing; info: worth their knowing" }),
+            summary: Type.String({ description: "What is wrong, in one line" }),
+            evidence: Type.Array(Type.String(), { description: "What shows it, a line each: a step that failed, a log's lines, a request and its answer" }),
+            actions: Type.Array(Type.Object({
+                label: Type.String({ description: "What the person accepts, in a few words: \"Change the ***plain to …\", \"Regenerate fs 3 again\"" }),
+                task: Type.String({ description: "Exactly what their chat's agent does once they accept it - all it is given" }),
+            }), { description: "What can be done, the best first" }),
+            module: Type.Optional(Type.String({ description: "The module it is about" })),
+            pulse: Type.Optional(Type.String({ description: "The pulse's id" })),
+        }),
+        async execute(_id, params) {
+            const notice = notify({
+                severity: params.severity,
+                summary: params.summary,
+                evidence: params.evidence,
+                actions: params.actions,
+                ...(params.module !== undefined ? { module: params.module } : {}),
+                ...(params.pulse !== undefined ? { job: params.pulse } : {}),
+            });
+            return {
+                content: [{ type: "text", text: notice !== undefined ? `Put to the person, in the chat they are in (notice ${notice.id}).` : "There is no chat to put it in: say it here." }],
+                details: { notice: notice?.id },
+            };
+        },
+    });
+}
+export function concludeTool(conclude) {
+    return defineTool({
+        name: "conclude",
+        label: "Conclude",
+        description: "Say you are done with a pulse - whether what you checked holds, and in a line or two what you checked and found. The chat " +
+            "the person is in is told, whether all is well or not. Once a pulse, last - after notify_person, when something is wrong.",
+        parameters: Type.Object({
+            pulse: Type.String({ description: "The pulse's id" }),
+            verdict: Type.Union([Type.Literal("holds"), Type.Literal("wrong")], { description: "holds: it does what its ***plain says; wrong: it does not, or it went wrong" }),
+            summary: Type.String({ description: "What you checked and what you found, in a line or two: \"GET /api/ping answers pong; the new alias route redirects\"" }),
+        }),
+        async execute(_id, params) {
+            const chat = conclude({ job: params.pulse, verdict: params.verdict, summary: params.summary });
+            return {
+                content: [{ type: "text", text: chat !== undefined ? "The chat the person is in is told." : "There is no chat to tell: say it here." }],
+                details: {},
+            };
+        },
+    });
+}
+/** What the chat the person is in is told when the sentinel is done with a pulse: to say so, and do nothing more. */
+export function concludedNote(conclusion) {
+    const about = conclusion.module !== undefined ? `${conclusion.module}${conclusion.pulse !== undefined ? ` pulse ${conclusion.pulse}` : ""}` : `pulse ${conclusion.job}`;
+    return [
+        `The sentinel is done with ${about} (${conclusion.job}): ${conclusion.verdict === "holds" ? "it holds" : "something is wrong"}.`,
+        conclusion.summary.trim(),
+        "",
+        conclusion.verdict === "holds"
+            ? "Tell the person, in a line, that the sentinel checked it and it holds - and what it checked. Do nothing else about it."
+            : "Tell the person, in a line, that the sentinel found something wrong, and that its notice in this chat says what and what can be done. Do nothing else about it until they answer the notice.",
+    ].join("\n");
+}
+export function keepGuidanceTool(cwd) {
+    return defineTool({
+        name: "keep_guidance",
+        label: "Keep guidance",
+        description: "Keep what the person told you about how to check their software, in their words: it is in your prompt from now on, after you are closed and opened again too.",
+        parameters: Type.Object({ text: Type.String({ description: "What to keep in mind, as they said it" }) }),
+        async execute(_id, params) {
+            keepGuidance(cwd, params.text);
+            return { content: [{ type: "text", text: "Kept." }], details: {} };
+        },
+    });
+}

package/docs/README.md

@@ -17,6 +17,7 @@ turri is the first coding agent with the power of regenerative software: [\*\*\*
 | what turri needs of this machine, and what `turri doctor` checks | [installation](installation.md#what-turri-doctor-checks) |
 | how to start a project, or add a feature, in a conversation | [using](using.md#in-a-conversation) |
 | how to have several chats open at once, and reopen them | [chats](chats.md) |
+| what checks each pulse as it finishes, and tells me what needs me | [the sentinel](sentinel.md) |
 | which model codes, and how to change it | [using](using.md#choosing-a-model), [the project config](config.md#models) |
 | what `config.turri.yaml` can set, and what happens without it | [the project config](config.md) |
 | how a backend and a frontend on different stacks share one project | [the project config](config.md#stacks) |
@@ -42,6 +43,7 @@ turri is the first coding agent with the power of regenerative software: [\*\*\*
 | [Installation](installation.md) | doctor, what turri needs of this machine, turri and `pi`, environment variables |
 | [Using turri](using.md) | the conversation, the tools, background jobs, choosing a model, module history, the command line |
 | [Chats](chats.md) | several chats in one session: what each keeps and what they share, `/chat` and its keys, `turri --continue` and `.turri/chats.json` |
+| [The sentinel](sentinel.md) | the chat every finished pulse goes to: what it checks and tests, its notices and how to answer them, what it may do, closing it, its model, in a host |
 | [The project config](config.md) | `config.turri.yaml` and each stack's `config.turri.<stack>.yaml`: where they are read from, every key, models and their inheritance, conformance, the testing scripts, stacks and choosing one, the old `config.yaml` |
 | [Deploy](deploy.md) | trying what is built: dist/<module>, the last commit, starting it on your machine, `turri release` |
 | [Running unattended](headless.md) | regenerating overnight or in CI: before you leave it, the command, the results, resuming, rebuilding one functionality |

package/docs/chats.md

@@ -21,7 +21,7 @@ The session's, shared by every chat:
 - **what `activate` started** - it runs until turri ends or `/halt activated <name>`, whatever chats are opened or closed;
 - **the ledger** - one run, each event with the id of the chat its work was asked for in (`chat`), and `chat.opened` and `chat.closed` as they happen.
 
-A pulse's end is told to the chat that asked for it, shown or not - its agent reacts to it there; the chat's mark in the strip says it has something new. When that chat has been closed, the chat shown is told. Closing a chat stops its turn, never its pulses.
+A pulse's end goes to the [sentinel](sentinel.md) - a chat of turri's own, opened in the background with the first pulse that finishes - which checks it, tests what was released, and puts what needs you as a notice in the chat you are in. That chat shows the pulse's end; its agent is told of a pulse that landed, to tell you so and what the sentinel is doing with it - and when the sentinel is done with any pulse, what it found - and nothing more - and not of one that went wrong: the sentinel's notice is what it hears of that. With `sentinel: false`, a pulse's end is told to the chat that asked for it instead, shown or not - its agent reacts to it there; the chat's mark in the strip says it has something new. When that chat has been closed, the chat shown is told. Closing a chat stops its turn, never its pulses.
 
 ## In the terminal
 
@@ -45,13 +45,14 @@ On macOS, `alt` is Option (⌥), and reaches turri only when the terminal sends
 - **The side panel** (`ctrl+h`) is the session's, not a chat's: docked beside the chat or over it, it stays as another chat is shown, and opening it from any chat finds it as it was left.
 - **A long command** - `/regenerate`, planning a module from scratch - does its work in the background once it is under way: the chat, and switching to another, stay free while the planner plans.
 - **`ctrl+c`** reaches the chat shown and nothing else: another chat's turn and skill go on, and so do the pulses - `/halt` stops one. A skill stopped keeps its run, for the model to continue with `resume`. At a question - the chat's `ask_user`, a skill's interview - `ctrl+c` declines it, and the asker is told so and goes on - each question it is pressed at, however many in a row. A skill is stopped by `ctrl+c` with no question open. A second press straight after one that stopped something does nothing, so pressing twice to be sure does not leave turri; once the chat is doing nothing, the next one does - with what every other chat is doing. A host has the same as `interrupt(id)`, and `decline(id)` for a question ([hosting](hosting.md)).
-- **The last chat** is not closed: `/quit` leaves turri. Leaving turri leaves the terminal as it was: the conversation is not written out to it, nor a line on how to resume - the command run is all that stays. `turri --continue` opens the chats again.
+- **The sentinel** is a chat in the strip like the others, `sentinel`, and never shown by itself: it closes like any chat, and the next pulse that finishes opens it again. With it on, you open up to eight chats - the ninth slot is its. See [the sentinel](sentinel.md).
+- **The last chat** of yours is not closed: `/quit` leaves turri. Leaving turri leaves the terminal as it was: the conversation is not written out to it, nor a line on how to resume - the command run is all that stays. `turri --continue` opens the chats again.
 - **`/fork`** and **`/reload`** work on the chat shown, as [pi](https://pi.dev)'s do: the chat's history forked, or turri's extension rebuilt in it.
 - **A chat shown mid-turn** draws its reply as far as it is written, and follows it from there.
 
 ## Coming back
 
-`turri --continue` (`-c`) opens every chat of the last session here again, in their order - the first shown, the others beside it. A plain `turri` starts with one fresh chat and deletes nothing: the chats of the sessions before stay on disk, and `--continue` opens the most recent one's - the last session that recorded a chat.
+`turri --continue` (`-c`) opens every chat of the last session here again, in their order - the first of yours shown, the others beside it, the sentinel among them. A plain `turri` starts with one fresh chat and deletes nothing: the chats of the sessions before stay on disk, and `--continue` opens the most recent one's - the last session that recorded a chat.
 
 turri records which chats are open in `.turri/chats.json` - a run a session, each chat with its title and [pi](https://pi.dev)'s saved conversation - and keeps it from piling up:
 

package/docs/config.md

@@ -47,7 +47,7 @@ Each change says when it takes effect. None needs turri started again - what tur
 | the next pulse - one running keeps what it started with | `coding-model`, `judge-model`, every other `models.<role>`, `review`, `mutation-testing`, `turn-limit`, `compact-at`, `agent-env`, `toolchains`, `debug` |
 | the next time the work is planned | `conformance-tests`, `conformance-budget`, `max-specs-per-pulse`, `max-lines-per-pulse` |
 | the next test run - the running pulse's too | the testing scripts, `testing-scripts-run-on` |
-| the next pulse that lands - the running one too | `release-after-pulse` |
+| the next pulse that lands - the running one too | `release-after-pulse`, `sentinel` |
 | the next regeneration that names no `.plain` file | `module` |
 | the next time turri starts here | `ledger-keep`, `cache-keep` |
 
@@ -90,6 +90,7 @@ models:                              # each agent role's model, thinking and tur
 | `rules-off` | a list of rule names - `integrations`, `concise-specs`, the files of `genome/rules/` without `.md` - left out of the conversation's prompt and every \*\*\*plain-writing agent's: a rule this project's own skills or AGENTS.md replace, such as one that says to probe a live API before any \*\*\*plain is written. `turri init-config` writes it with `integration-embedded`, `integration-embedded-testing` and `integration-standalone` - take them out when the project writes an integration against a REST API. The project's alone | none |
 | `allow-to-stop-jobs` | `true` or `false`: whether turri stops a running job \*\*\*plain has moved on from - a functional spec it regenerates changed, or a file one links was edited - rolls it back and regenerates \*\*\*plain as it now is. `false`: the job runs to its end and lands, and what changed since is regenerated on top of it by the next job - see [regenerating the code](regenerating.md). Your own `halt` stops a job either way | `true` |
 | `release-after-pulse` | `true` or `false`: whether every pulse that lands code releases it, in the chat, as its last stage - before the module's next pulse starts, whatever the chat is doing: an agent on the coding model releases it, following the project's release guidance as the chat finds it (what was passed to `release` this conversation, AGENTS.md, the project's skills) for how, or to `dist/<module>` without any - see [deploy](deploy.md#after-every-pulse). One release a pulse that lands; a release that fails is said in the pulse's report, and what it landed stays. `turri init-config` writes `true` | `false` |
+| `sentinel` | `true` or `false`: whether a chat of turri's own, the sentinel, gets every pulse that finishes - checks it, tests what was released under `release-after-pulse`, and puts what needs you as a notice in the chat you are in - instead of the chat that asked for it. See [the sentinel](sentinel.md). `turri init-config` writes `true` | `true` |
 | `unittests-script` | the unit testing script, by path from the project root - it runs the code's static checks too, exiting 80 when only they fail (see [the static checks](regenerating.md#the-static-checks)) | looked for - see below |
 | `conformance-tests-script` | the conformance testing script, by path from the project root | looked for - see below |
 | `prepare-environment-script` | optional: run as `<script> <build>` before every run of the conformance testing script, which runs only once it passes - see [the testing scripts](regenerating.md#the-testing-scripts). turri never writes one | the one `prepare_environment*.sh` at the root or in `test_scripts/`, else none |
@@ -116,6 +117,7 @@ Keys are written with dashes; underscores are read the same (`conformance_tests`
 | --- | --- |
 | `default` | every role not named below - but the conversation's side |
 | `chat` | `turri`'s model - the same as `harness-model`, which it wins over |
+| `sentinel` | [the sentinel](sentinel.md): checks every finished pulse, and tests the release. Unnamed, the chat's model |
 | `chooser`, `planner` | the conversation's side: the conformance chooser of `turri regenerate`, the planner's agents. Unnamed, the chat's model |
 | `diagnosis` | the diagnosis of a job that failed for good: why it did not land, and what to do. Unnamed, the coding model the job ran on, thinking medium |
 | `release` | `turri release`'s agent and release-after-pulse's: it follows steps - a script, a start command - so it runs on the coding model, thinking low |

package/docs/deploy.md

@@ -11,7 +11,7 @@ Every release starts the same way: the module's last commit - what last landed w
 
 Guidance is whatever says it, in any words - a line in AGENTS.md such as *integrations are released with `scripts/deploy_integrations.sh`, then the app is started with `scripts/start.sh`*, or the same said in the chat.
 
-The chat reacts to every pulse that finishes as it finishes, without waiting for you to speak: guidance that says to release after a build - *release each integration once it is regenerated* - is followed then. It never has to work out whether what a pulse landed is already out: `release` does. When the module's last commit is what its last release in this conversation shipped, it does nothing - nothing exported, nothing stopped, what runs left running - and says so; `again: true` releases it anyway, for when what that release said to do was not done.
+With `sentinel: false`, the chat reacts to every pulse that finishes as it finishes, without waiting for you to speak: guidance that says to release after a build - *release each integration once it is regenerated* - is followed then. With the [sentinel](sentinel.md) on - the default - the chat is told only that a pulse landed, and does nothing about it: guidance to follow once a pulse finishes is not followed, and releasing after every pulse is `release-after-pulse`'s. It never has to work out whether what a pulse landed is already out: `release` does. When the module's last commit is what its last release in this conversation shipped, it does nothing - nothing exported, nothing stopped, what runs left running - and says so; `again: true` releases it anyway, for when what that release said to do was not done.
 
 ## What goes in dist
 
@@ -33,7 +33,7 @@ What it started is listed by the `pulses` tool and by **`/halt`**, and stopped b
 
 With `release-after-pulse: true` in `config.turri.yaml`, turri releases what each pulse lands itself, as the pulse's last stage (`releasing what this pulse landed`): the pulse ends once it is released, so the module's next pulse starts on what is out, and the chat - waiting on your answer to a question, say - has no part in it. One release a pulse that lands, in order.
 
-The release is done by an agent on the coding model, thinking low - it follows steps, and a small model does that well - the same one `turri release` runs, and it finds the guidance as the chat would: what was passed to `release` earlier in the conversation, the project's AGENTS.md and its skills. The setting is the word to release; the guidance says only how - without any, the code goes to `dist/<module>` and is started from there. Its last words go in the pulse's report - "Released after the pulse: ..." - and the chat, seeing them, does not release it again: it says in a line what was released, then does what it was told to do once something is released - a host such as a desktop app tells it, in its `surface`, to open it where the person can watch and say what to test. A release that fails is said there too; what the pulse landed stays.
+The release is done by an agent on the coding model, thinking low - it follows steps, and a small model does that well - the same one `turri release` runs, and it finds the guidance as the chat would: what was passed to `release` earlier in the conversation, the project's AGENTS.md and its skills. The setting is the word to release; the guidance says only how - without any, the code goes to `dist/<module>` and is started from there. Its last words go in the pulse's report - "Released after the pulse: ..." - and the [sentinel](sentinel.md) is told what was released and where it runs, and tests it: what needs you comes as a notice in the chat you are in, and the chat you are in says only that it landed and is being tested. With `sentinel: false`, the chat, seeing the report, does not release it again: it says in a line what was released, then does what it was told to do once something is released - a host such as a desktop app tells it, in its `surface`, to open it where the person can watch and say what to test. A release that fails is said there too; what the pulse landed stays.
 
 Off without the key: releasing after a pulse is then the chat's, when its guidance says so. `turri init-config` writes `release-after-pulse: true`.
 

package/docs/development.md

@@ -35,6 +35,7 @@ The workflow signs in to npm with npm's trusted publishing (OIDC), not a token:
 | `src/setup.ts`, `src/doctor-tool.ts`, `src/environment.ts`, `src/stack.ts` | `turri doctor` and the chat's `doctor` tool, and what they check - this machine, and in a project what its modules need of it |
 | `src/extension.ts` | the [pi](https://pi.dev) extension: every tool and command the conversation has - and `createTurriCore`, the session it is built into |
 | `src/chats.ts`, `src/chat-scope.ts`, `src/chat-records.ts` | the session's [chats](chats.md): which chat a pulse is told to, each chat's scope - its id and stack - and `.turri/chats.json` |
+| `src/sentinel.ts`, `src/sentinel-chat.ts` | [the sentinel](sentinel.md): its prompt, what it is told of a pulse, its fenced tools, its guidance; notices - their cards, the terminal's dialog, their answers |
 | `src/chat-terminal.ts`, `src/chat-ui.ts`, `src/chat-commands.ts` | the terminal's chats: [pi](https://pi.dev)'s screen switched between live sessions, a hidden chat's stand-in for it, `/chat` and its keys |
 | `src/host-session.ts` | `createTurri`, the session for a host |
 | `src/skill.ts` | parses `SKILL.md` into steps and gates |