@alisio/core 0.1.0 → 0.2.0

package/dist/plan/diagrams.js

@@ -0,0 +1,326 @@
+/**
+ * Plan diagrams: the lightweight, render-free validation of the Mermaid diagrams the plan agent
+ * passes to `exit_plan`. Mermaid cannot render without a DOM, so the server only checks what it
+ * can see in the text: a size limit, an allowlist of diagram types, a node estimate and the
+ * constructs that would run code, open links, fetch resources or relax Mermaid's security
+ * settings. A diagram that fails is DROPPED with a reason (the plan is still published); a
+ * diagram that only fails to draw is shown as source by the web renderer.
+ *
+ * Pure functions: no I/O, no Mermaid import.
+ */
+import { createHash } from "node:crypto";
+/** Largest Mermaid source of one diagram (UTF-8 bytes). */
+export const DIAGRAM_MAX_BYTES = 8 * 1024;
+/** Most nodes (participants, entities, states, tasks...) of one diagram, estimated from the text. */
+export const DIAGRAM_MAX_NODES = 40;
+/** Hard ceiling of `plan.maxDiagrams`. */
+export const DIAGRAMS_MAX_ALLOWED = 8;
+export const DIAGRAM_ID_MAX = 40;
+export const DIAGRAM_TITLE_MAX = 80;
+export const DIAGRAM_EXPLANATION_MAX = 400;
+export const DIAGRAM_SECTION_MAX = 120;
+/** Mermaid diagram keywords a plan may use (the first statement of the source). */
+export const DIAGRAM_SYNTAXES = [
+    "flowchart",
+    "graph",
+    "sequenceDiagram",
+    "stateDiagram-v2",
+    "stateDiagram",
+    "erDiagram",
+    "classDiagram",
+    "gantt",
+    "mindmap",
+    "timeline",
+    "journey",
+];
+export const DIAGRAM_TYPES = [
+    "overview",
+    "flow",
+    "components",
+    "architecture",
+    "sequence",
+    "data",
+    "state",
+    "other",
+];
+/**
+ * The semantic classes of the style guide. The web applies the same names as a `classDef` block
+ * at render time when a diagram uses a class without defining it (colors live in the web).
+ */
+export const DIAGRAM_CLASSES = [
+    "input",
+    "process",
+    "data",
+    "system",
+    "external",
+    "decision",
+    "risk",
+];
+const ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Security settings a directive or the front matter may not touch. */
+const FORBIDDEN_CONFIG = /(securityLevel|htmlLabels|\bsecure\b|dompurify|themeCSS|maxTextSize|maxEdges|startOnLoad|callback|logLevel|deterministicIds)/i;
+/** Normalizes line endings and trims: what is stored and hashed. */
+export const normalizeMermaid = (source) => source
+    .replace(/\r\n?/g, "\n")
+    .replace(/\u0000/g, "")
+    .trim();
+const byteLength = (text) => Buffer.byteLength(text, "utf8");
+/** Removes a leading YAML front matter block (`---` ... `---`). */
+function splitFrontMatter(source) {
+    const match = /^---[ \t]*\n([\s\S]*?)\n---[ \t]*(?:\n|$)/.exec(source);
+    return match
+        ? { front: match[1] ?? "", body: source.slice(match[0].length) }
+        : { front: "", body: source };
+}
+/** Directives `%%{ ... }%%` (possibly several lines) and plain `%%` comments. */
+function directives(body) {
+    return [...body.matchAll(/%%\{[\s\S]*?\}%%/g)].map((m) => m[0]);
+}
+/** The body without directives and comments (what the statement scan reads). */
+function statements(body) {
+    return body
+        .replace(/%%\{[\s\S]*?\}%%/g, "")
+        .split("\n")
+        .map((line) => line.replace(/%%.*$/, ""))
+        .filter((line) => line.trim());
+}
+/** The diagram keyword of a source (its first statement), or undefined when it has none. */
+export function diagramSyntax(source) {
+    const { body } = splitFrontMatter(normalizeMermaid(source));
+    const first = statements(body)[0]?.trim();
+    if (!first)
+        return undefined;
+    const word = /^([A-Za-z][\w-]*)/.exec(first)?.[1];
+    return word && DIAGRAM_SYNTAXES.includes(word) ? word : (word ?? undefined);
+}
+/** The purpose a syntax implies when the model gave none. */
+export function defaultDiagramType(syntax) {
+    switch (syntax) {
+        case "sequenceDiagram":
+            return "sequence";
+        case "stateDiagram":
+        case "stateDiagram-v2":
+            return "state";
+        case "erDiagram":
+        case "classDiagram":
+            return "data";
+        default:
+            return "flow";
+    }
+}
+const uniqueCount = (items) => new Set(items).size;
+/** Words of a line without bracketed labels, quoted text and edge labels. */
+function bareLine(line) {
+    return line
+        .replace(/"[^"]*"/g, " ")
+        .replace(/\[\[[^\]]*\]\]|\[[^\]]*\]|\(\([^)]*\)\)|\([^)]*\)|\{\{[^}]*\}\}|\{[^}]*\}/g, " ")
+        .replace(/\|[^|]*\|/g, " ")
+        .replace(/:::[\w-]+/g, " ");
+}
+/**
+ * An estimate of the diagram's nodes from its text (participants, entities, states, tasks, topics
+ * or flowchart node ids). It errs on the high side: it is a guard against walls of boxes, not a
+ * parser.
+ */
+export function estimateNodes(source, syntax) {
+    const { body } = splitFrontMatter(normalizeMermaid(source));
+    const lines = statements(body).map((line) => line.trim());
+    const content = lines.slice(1);
+    switch (syntax) {
+        case "flowchart":
+        case "graph": {
+            const ids = new Set();
+            for (const line of content) {
+                if (/^(subgraph|end|classDef|class|style|linkStyle|direction|click|accTitle|accDescr)\b/.test(line))
+                    continue;
+                for (const part of bareLine(line).split(/<?[-=.~]+[ox>]?|&|;|\s+/)) {
+                    const id = /^[A-Za-z_][\w]*$/.exec(part.trim())?.[0];
+                    if (id)
+                        ids.add(id);
+                }
+            }
+            return ids.size;
+        }
+        case "sequenceDiagram": {
+            const names = new Set();
+            for (const line of content) {
+                const declared = /^(?:participant|actor)\s+(\S+)/.exec(line)?.[1];
+                if (declared) {
+                    names.add(declared);
+                    continue;
+                }
+                const message = /^([^\s:]+?)\s*(?:-->>|->>|--x|-x|--\)|-\)|-->|->)\s*[+-]?([^\s:]+)/.exec(line);
+                if (message?.[1] && message[2]) {
+                    names.add(message[1]);
+                    names.add(message[2]);
+                }
+            }
+            return names.size;
+        }
+        case "stateDiagram":
+        case "stateDiagram-v2": {
+            const states = new Set();
+            for (const line of content) {
+                const transition = /^(\S+)\s*-->\s*(\S+)/.exec(line);
+                if (transition?.[1] && transition[2])
+                    for (const state of [transition[1], transition[2]])
+                        if (state !== "[*]")
+                            states.add(state);
+                const declared = /^state\s+(?:"[^"]*"\s+as\s+)?(\w+)/.exec(line)?.[1];
+                if (declared)
+                    states.add(declared);
+            }
+            return states.size;
+        }
+        case "erDiagram": {
+            const entities = new Set();
+            for (const line of content) {
+                const relation = /^(\S+)\s+[|}o{.-]+\s*[|}o{.-]*\s+(\S+)\s*:/.exec(line);
+                if (relation?.[1] && relation[2]) {
+                    entities.add(relation[1]);
+                    entities.add(relation[2]);
+                }
+                const block = /^(\w+)\s*\{/.exec(line)?.[1];
+                if (block)
+                    entities.add(block);
+            }
+            return entities.size;
+        }
+        case "classDiagram": {
+            const classes = new Set();
+            for (const line of content) {
+                const declared = /^class\s+(\w+)/.exec(line)?.[1];
+                if (declared)
+                    classes.add(declared);
+                const relation = /^(\w+)\s+(?:"[^"]*"\s+)?[<|*o.\-\\/>]+\s+(?:"[^"]*"\s+)?(\w+)/.exec(line);
+                if (relation?.[1] && relation[2]) {
+                    classes.add(relation[1]);
+                    classes.add(relation[2]);
+                }
+            }
+            return classes.size;
+        }
+        case "gantt":
+            return content.filter((line) => line.includes(":") &&
+                !/^(title|dateFormat|axisFormat|section|excludes|includes|todayMarker|tickInterval|weekday|accTitle|accDescr|inclusiveEndDates|topAxis)\b/.test(line)).length;
+        case "journey":
+            return content.filter((line) => !/^(title|section|accTitle|accDescr)\b/.test(line)).length;
+        default:
+            // mindmap, timeline and anything else: one node per line.
+            return uniqueCount(content.filter((line) => !/^(title|section|accTitle|accDescr)\b/.test(line)));
+    }
+}
+/** The first problem that makes a Mermaid source unsafe or unsupported, or undefined when fine. */
+export function mermaidProblem(source, limits = {}) {
+    const maxBytes = limits.maxBytes ?? DIAGRAM_MAX_BYTES;
+    const maxNodes = limits.maxNodes ?? DIAGRAM_MAX_NODES;
+    const text = normalizeMermaid(source);
+    if (!text)
+        return "the diagram is empty";
+    if (byteLength(text) > maxBytes)
+        return `the diagram is larger than ${maxBytes} bytes`;
+    if (/[\u0001-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(text))
+        return "the diagram has control characters";
+    const { front, body } = splitFrontMatter(text);
+    const syntax = diagramSyntax(text);
+    if (!syntax)
+        return "the diagram does not start with a Mermaid diagram keyword";
+    if (!DIAGRAM_SYNTAXES.includes(syntax))
+        return `the diagram type "${syntax}" is not allowed (use ${DIAGRAM_SYNTAXES.join(", ")})`;
+    if (FORBIDDEN_CONFIG.test(front))
+        return "the front matter changes Mermaid security settings, which plans may not do";
+    for (const directive of directives(body))
+        if (FORBIDDEN_CONFIG.test(directive))
+            return "an init directive changes Mermaid security settings, which plans may not do";
+    // The scan below ignores comments and directives, which were checked above.
+    const code = statements(body).join("\n");
+    if (/(?:javascript|vbscript)\s*:|data\s*:\s*(?:text|image|application)\//i.test(code))
+        return "the diagram contains a javascript:, vbscript: or data: URL";
+    if (/\bhref\b/i.test(code))
+        return "the diagram contains a link (href)";
+    if (/url\s*\(|@import/i.test(code))
+        return "the diagram references an external resource (url())";
+    // `<<choice>>` and `<<interface>>` are Mermaid annotations, not tags.
+    if (/<\s*\/?\s*[A-Za-z!][^>]*>/.test(code.replace(/<<[^<>\n]*>>/g, " ")))
+        return "labels are text: HTML tags (<br/>, <b>, <script>) are not allowed";
+    const interactive = !["mindmap", "timeline", "journey"].includes(syntax);
+    if (interactive && /^\s*(?:click|links?|callback)\s/m.test(code))
+        return "click, link and callback statements are not allowed";
+    if (estimateNodes(text, syntax) > maxNodes)
+        return `the diagram has more than ${maxNodes} nodes: split it or keep only the main parts`;
+    return undefined;
+}
+/** SHA-256 of what makes a diagram "the same" across revisions. */
+export function diagramHash(diagram) {
+    return createHash("sha256")
+        .update(JSON.stringify([
+        diagram.title,
+        diagram.explanation,
+        diagram.section ?? "",
+        diagram.type,
+        normalizeMermaid(diagram.mermaid),
+    ]), "utf8")
+        .digest("hex");
+}
+const text = (value, max) => typeof value === "string" && value.trim() ? value.trim().slice(0, max) : undefined;
+/**
+ * Validates the `diagrams` argument of `exit_plan`. Never throws: every problem becomes a dropped
+ * diagram with the reason the model needs to fix it. Order is kept; the first diagram with an id
+ * wins; only `limits.max` are accepted.
+ */
+export function validateDiagrams(input, limits) {
+    const accepted = [];
+    const dropped = [];
+    if (input === undefined || input === null)
+        return { accepted, dropped };
+    if (!Array.isArray(input)) {
+        dropped.push({ id: "diagrams", reason: "`diagrams` must be an array" });
+        return { accepted, dropped };
+    }
+    const seen = new Set();
+    input.forEach((raw, index) => {
+        const item = raw && typeof raw === "object" ? raw : {};
+        const given = typeof item.id === "string" ? item.id.trim() : "";
+        const label = given || `#${index + 1}`;
+        const drop = (reason) => dropped.push({ id: label, reason });
+        if (!raw || typeof raw !== "object")
+            return drop("the diagram must be an object");
+        if (!ID.test(given) || given.length > DIAGRAM_ID_MAX)
+            return drop(`the id must be kebab-case, at most ${DIAGRAM_ID_MAX} characters (like "request-flow")`);
+        if (seen.has(given))
+            return drop("the id is already used by another diagram of this plan");
+        const title = text(item.title, DIAGRAM_TITLE_MAX);
+        if (!title)
+            return drop("the title is missing");
+        const explanation = text(item.explanation, DIAGRAM_EXPLANATION_MAX);
+        if (!explanation)
+            return drop("the explanation is missing (one short sentence)");
+        if (typeof item.mermaid !== "string")
+            return drop("the `mermaid` source is missing");
+        if (accepted.length >= limits.max)
+            return drop(limits.max === 0
+                ? "diagrams are turned off (plan.maxDiagrams is 0)"
+                : `only ${limits.max} diagrams are accepted per plan (plan.maxDiagrams)`);
+        const problem = mermaidProblem(item.mermaid, limits);
+        if (problem)
+            return drop(problem);
+        const mermaid = normalizeMermaid(item.mermaid);
+        const syntax = diagramSyntax(mermaid);
+        const type = DIAGRAM_TYPES.includes(item.type)
+            ? item.type
+            : defaultDiagramType(syntax);
+        const section = text(item.section, DIAGRAM_SECTION_MAX);
+        seen.add(given);
+        accepted.push({
+            id: given,
+            title,
+            explanation,
+            ...(section ? { section } : {}),
+            type,
+            syntax,
+            mermaid,
+            nodes: estimateNodes(mermaid, syntax),
+        });
+    });
+    return { accepted, dropped };
+}

package/dist/plan/exit-plan.d.ts

@@ -1,15 +1,3 @@
-/**
- * `exit_plan`: how the plan agent hands over its plan. The tool publishes the plan as a Markdown
- * artifact (`plan.md`, one revision per call), asks the user for a decision through the same
- * question infrastructure as `ask_user_question` and ALWAYS returns a tool result (approved,
- * skipped or feedback), so a session never keeps a dangling call. It does not switch agents or
- * start anything: an approved plan is recorded (`plan/state.ts`) and the host starts the
- * implementation turn once the plan run has ended.
- *
- * The tool is opt-in (`core/opt-in.ts`): only the plan agent's run lists it. Its effect is
- * `read`, so it is allowed under every policy; the plan agent stays read-only because its run
- * policy has no write/process/external effect, whatever the permission mode.
- */
 import type { AskQuestionsRequest, AskQuestionsResult } from "@alisio/sdk";
 import type { ToolRegistry } from "../core/registry.ts";
 import { type PlanStore } from "./state.ts";
@@ -21,5 +9,10 @@ export interface ExitPlanDeps {
     };
     /** `--read-only`: nothing can be implemented afterwards, so there is no decision to take. */
     readOnly?: boolean;
+    /** `plan.diagrams` and `plan.maxDiagrams`, read on every request (they change live). */
+    diagrams?: () => {
+        enabled: boolean;
+        max: number;
+    };
 }
 export declare function registerExitPlan(registry: ToolRegistry, deps: ExitPlanDeps): void;

package/dist/plan/exit-plan.js

@@ -1,7 +1,48 @@
+/**
+ * `exit_plan`: how the plan agent hands over its plan. The tool publishes the plan as a Markdown
+ * artifact (`plan.md`, one revision per call), asks the user for a decision through the same
+ * question infrastructure as `ask_user_question` and ALWAYS returns a tool result (approved,
+ * skipped or feedback), so a session never keeps a dangling call. It does not switch agents or
+ * start anything: an approved plan is recorded (`plan/state.ts`) and the host starts the
+ * implementation turn once the plan run has ended.
+ *
+ * The tool is opt-in (`core/opt-in.ts`): only the plan agent's run lists it. Its effect is
+ * `read`, so it is allowed under every policy; the plan agent stays read-only because its run
+ * policy has no write/process/external effect, whatever the permission mode.
+ */
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { textResult } from "@alisio/sdk";
 import { EXIT_PLAN_TOOL } from "../core/opt-in.js";
 import { objectSchema } from "../tools/standard.js";
-import { decidePlan, nextPlanRevision, PLAN_CONTEXT_MAX_CHARS, PLAN_MAX_CHARS, PLAN_OPTIONS, PLAN_QUESTION_ID, PLAN_REVIEW_TITLE, PLAN_TEXT_KEY, planHash, planTitle, proposePlan, withdrawPendingPlan, } from "./state.js";
+import { DIAGRAM_MAX_BYTES, DIAGRAM_MAX_NODES, validateDiagrams, } from "./diagrams.js";
+import { buildPlanManifest } from "./manifest.js";
+import { currentPlan, decidePlan, nextPlanRevision, PLAN_CONTEXT_MAX_CHARS, PLAN_MAX_CHARS, PLAN_OPTIONS, PLAN_QUESTION_ID, PLAN_REVIEW_TITLE, PLAN_TEXT_KEY, planHash, planTitle, proposePlan, withdrawPendingPlan, } from "./state.js";
+const DIAGRAM_SCHEMA = {
+    type: "array",
+    description: `Optional Mermaid diagrams; see the plan agent's instructions`,
+    items: {
+        type: "object",
+        properties: {
+            id: { type: "string", description: "kebab-case, stable across revisions" },
+            title: { type: "string" },
+            explanation: { type: "string", description: "One short sentence" },
+            section: { type: "string", description: "Plan heading it illustrates" },
+            type: {
+                type: "string",
+                description: "overview, flow, components, architecture, sequence, data, state or other",
+            },
+            mermaid: { type: "string", description: "Mermaid source, no html, click or %%{init}" },
+        },
+    },
+};
+const BASE_DESCRIPTION = "Finish planning: hand the complete plan, in Markdown, to the user for review. Call it once, " +
+    "when the plan is complete, instead of pasting the plan in your reply. The user can approve " +
+    "(the build agent then implements exactly this plan), skip for now, or add context (the " +
+    "result is `feedback`: revise the plan and call exit_plan again). Only the plan agent has " +
+    "this tool. If review is unavailable (headless or read-only sessions) the result says so: " +
+    "then give the complete plan as your final reply.";
 const withArtifact = (result, artifact) => artifact
     ? {
         ...result,
@@ -9,49 +50,157 @@ const withArtifact = (result, artifact) => artifact
     }
     : result;
 const answer = (decision, message, extra = {}) => JSON.stringify({ decision, ...extra, message });
+const diagramReport = (outcome) => outcome.involved
+    ? {
+        diagrams: {
+            accepted: outcome.accepted.map((d) => d.id),
+            ...(outcome.dropped.length ? { dropped: outcome.dropped } : {}),
+            ...(outcome.removed.length ? { removed: outcome.removed.map((d) => d.id) } : {}),
+        },
+    }
+    : {};
+/**
+ * Writes the plan folder (`plan.md`, `plan.json`, `diagrams/<id>.mmd`) in a scratch directory the
+ * publisher then copies, and removes the directory again.
+ */
+async function publishPlanFolder(publisher, files, title) {
+    const scratch = await mkdtemp(join(tmpdir(), "alisio-plan-"));
+    try {
+        const folder = join(scratch, "plan");
+        for (const file of files) {
+            const target = join(folder, ...file.path.split("/"));
+            await mkdir(join(target, ".."), { recursive: true });
+            await writeFile(target, file.text, { flag: "wx" });
+        }
+        const input = { source: folder, title, entry: "plan.md", fileName: "plan.md" };
+        return typeof publisher.publishDetailed === "function"
+            ? (await publisher.publishDetailed(input)).artifact
+            : await publisher.publish(input);
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
 export function registerExitPlan(registry, deps) {
-    registry.register({
+    const settings = () => deps.diagrams?.() ?? { enabled: true, max: 5 };
+    const offered = () => {
+        const current = settings();
+        return current.enabled && current.max > 0;
+    };
+    const plain = objectSchema({
+        title: { type: "string", maxLength: 120, description: "Short plan title" },
+        plan: {
+            type: "string",
+            minLength: 1,
+            maxLength: PLAN_MAX_CHARS,
+            description: "The whole plan in Markdown",
+        },
+    }, ["plan"]);
+    const withDiagrams = objectSchema({ ...plain.properties, diagrams: DIAGRAM_SCHEMA }, ["plan"]);
+    // The input is always VALIDATED with `diagrams` allowed (a call made while they were switched
+    // off must not fail), but the model is only OFFERED the field while diagrams are on: the
+    // registry compiles the schema once, while the provider reads it on every request.
+    let registering = true;
+    const tool = {
         name: EXIT_PLAN_TOOL,
         effect: "read",
-        description: "Finish planning: hand the complete plan, in Markdown, to the user for review. Call it once, " +
-            "when the plan is complete, instead of pasting the plan in your reply. The user can approve " +
-            "(the build agent then implements exactly this plan), skip for now, or add context (the " +
-            "result is `feedback`: revise the plan and call exit_plan again). Only the plan agent has " +
-            "this tool. If review is unavailable (headless or read-only sessions) the result says so: " +
-            "then give the complete plan as your final reply.",
-        inputSchema: objectSchema({
-            title: { type: "string", maxLength: 120, description: "Short plan title" },
-            plan: {
-                type: "string",
-                minLength: 1,
-                maxLength: PLAN_MAX_CHARS,
-                description: "The whole plan in Markdown",
-            },
-        }, ["plan"]),
+        get description() {
+            return offered()
+                ? `${BASE_DESCRIPTION} Optional \`diagrams\`: up to ${settings().max} small Mermaid diagrams (see your instructions).`
+                : BASE_DESCRIPTION;
+        },
+        get inputSchema() {
+            return registering || offered() ? withDiagrams : plain;
+        },
         async execute(input, context) {
             const plan = String(input.plan ?? "").trim();
             if (!plan)
                 throw new Error("exit_plan needs the whole plan in the `plan` field");
             const sessionId = context.session;
             const title = planTitle(plan, input.title);
-            const hash = planHash(plan);
             const planId = crypto.randomUUID();
             const reviewable = !!sessionId && deps.ui.interactive() && !deps.readOnly;
             const revision = sessionId ? nextPlanRevision(deps.store, sessionId) : 1;
+            const previous = sessionId
+                ? currentPlan(deps.store, sessionId)?.diagrams
+                : undefined;
+            // Diagrams: validated without rendering; a bad one is dropped and the plan still goes out.
+            const current = settings();
+            const outcome = { accepted: [], dropped: [], removed: [], involved: false };
+            if (input.diagrams !== undefined) {
+                outcome.involved = true;
+                if (!current.enabled)
+                    outcome.dropped.push({
+                        id: "diagrams",
+                        reason: "diagrams are turned off (plan.diagrams); the plan was published without them",
+                    });
+                else {
+                    const validated = validateDiagrams(input.diagrams, {
+                        max: current.max,
+                        maxBytes: DIAGRAM_MAX_BYTES,
+                        maxNodes: DIAGRAM_MAX_NODES,
+                    });
+                    outcome.accepted = validated.accepted;
+                    outcome.dropped = validated.dropped;
+                }
+            }
+            const preManifest = buildPlanManifest({
+                planId,
+                revision,
+                title,
+                hash: "",
+                markdown: plan,
+                diagrams: outcome.accepted,
+                ...(previous ? { previous } : {}),
+            });
+            outcome.removed = preManifest.removed;
+            if (outcome.removed.length)
+                outcome.involved = true;
+            const hash = planHash(plan, preManifest.diagrams.map((d) => ({ id: d.id, hash: d.hash })));
+            const manifest = { ...preManifest, hash };
+            const diagrams = manifest.diagrams.map((entry, index) => ({
+                id: entry.id,
+                title: entry.title,
+                explanation: entry.explanation,
+                ...(entry.section ? { section: entry.section } : {}),
+                type: entry.type,
+                syntax: entry.syntax,
+                status: entry.status,
+                mermaid: outcome.accepted[index]?.mermaid ?? "",
+            }));
             // The plan is saved first, so the review (and every later turn) can point at it.
             let artifact;
             let publishNote = "";
-            if (context.artifacts)
-                try {
-                    artifact = await context.artifacts.publishText({
-                        fileName: "plan.md",
-                        title: revision > 1 ? `${title} (revision ${revision})` : title,
-                        text: `${plan}\n`,
-                    });
-                }
-                catch (error) {
-                    publishNote = ` The plan could not be saved as an artifact: ${error instanceof Error ? error.message : String(error)}.`;
-                }
+            const artifactTitle = revision > 1 ? `${title} (revision ${revision})` : title;
+            const publisher = context.artifacts;
+            if (publisher) {
+                // A folder (plan.md + plan.json + diagrams) when diagrams are involved, else plan.md alone.
+                if (outcome.accepted.length || outcome.removed.length)
+                    try {
+                        artifact = await publishPlanFolder(publisher, [
+                            { path: "plan.md", text: `${plan}\n` },
+                            { path: "plan.json", text: `${JSON.stringify(manifest, null, 2)}\n` },
+                            ...outcome.accepted.map((d) => ({
+                                path: `diagrams/${d.id}.mmd`,
+                                text: `${d.mermaid}\n`,
+                            })),
+                        ], artifactTitle);
+                    }
+                    catch (error) {
+                        publishNote = ` The diagrams could not be saved with the plan: ${error instanceof Error ? error.message : String(error)}.`;
+                    }
+                if (!artifact)
+                    try {
+                        artifact = await publisher.publishText({
+                            fileName: "plan.md",
+                            title: artifactTitle,
+                            text: `${plan}\n`,
+                        });
+                    }
+                    catch (error) {
+                        publishNote += ` The plan could not be saved as an artifact: ${error instanceof Error ? error.message : String(error)}.`;
+                    }
+            }
             const record = {
                 planId,
                 revision,
@@ -59,12 +208,18 @@ export function registerExitPlan(registry, deps) {
                 title,
                 ...(context.callId ? { callId: context.callId } : {}),
                 ...(artifact ? { artifactId: artifact.id } : {}),
+                ...(manifest.diagrams.length
+                    ? {
+                        diagrams: manifest.diagrams.map((d) => ({ id: d.id, title: d.title, hash: d.hash })),
+                    }
+                    : {}),
             };
+            const report = diagramReport(outcome);
             if (!reviewable) {
                 // Nobody to ask: keep the revision count honest and tell the model what to do instead.
                 if (sessionId)
                     proposePlan(deps.store, sessionId, { ...record, status: "skipped" });
-                return withArtifact(textResult(answer("unavailable", `No plan review is possible in this session (${deps.readOnly ? "it is read-only" : "it is not interactive"}), so nothing will be implemented from here. Give the complete plan in Markdown as your final reply and stop.${publishNote}`, artifact ? { artifactId: artifact.id } : {})), artifact);
+                return withArtifact(textResult(answer("unavailable", `No plan review is possible in this session (${deps.readOnly ? "it is read-only" : "it is not interactive"}), so nothing will be implemented from here. Give the complete plan in Markdown as your final reply and stop.${publishNote}`, { ...(artifact ? { artifactId: artifact.id } : {}), ...report })), artifact);
             }
             proposePlan(deps.store, sessionId, record);
             context.emitEvent?.("plan_proposed", {
@@ -82,6 +237,7 @@ export function registerExitPlan(registry, deps) {
                 title,
                 markdown: plan,
                 ...(artifact ? { artifact } : {}),
+                ...(diagrams.length ? { diagrams } : {}),
             };
             const result = await deps.ui.askQuestions({
                 questions: [
@@ -114,17 +270,27 @@ export function registerExitPlan(registry, deps) {
                 hash,
                 decision,
             });
-            const base = { planId, revision, ...(artifact ? { artifactId: artifact.id } : {}) };
+            const base = {
+                planId,
+                revision,
+                ...(artifact ? { artifactId: artifact.id } : {}),
+                ...report,
+            };
             const body = decision === "approve"
                 ? answer("approved", "The user approved the plan. The build agent will implement exactly this plan in the " +
                     "next turn. Do not implement anything yourself: reply with one short sentence and " +
                     "call no more tools.", base)
                 : decision === "context"
                     ? answer("feedback", "The user added context instead of deciding. Revise the plan to account for it and " +
-                        "call exit_plan again with the complete updated plan.", { ...base, feedback: text })
+                        "call exit_plan again with the complete updated plan" +
+                        (outcome.involved
+                            ? ", with every diagram that still applies updated (and any dropped one fixed)."
+                            : "."), { ...base, feedback: text })
                     : answer("skipped", "The user chose to skip for now. Stay in plan mode and do not implement anything. " +
                         "Do not call exit_plan again unless the user asks; end your turn with one short sentence.", base);
             return withArtifact(textResult(body), artifact);
         },
-    });
+    };
+    registry.register(tool);
+    registering = false;
 }