deepclause-pi 0.1.5 → 0.2.0

package/dist/index.js

@@ -1,14 +1,22 @@
-import { readdir } from "node:fs/promises";
+import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { buildInitialMessages } from "./context.js";
 import { loadConfig, setModelToolEnabled } from "./config.js";
+import { renderDml, renderSequence } from "./diagram/extract.js";
+import { polishDiagram, resolveGrade } from "./diagram/grade.js";
+import { findChrome, validateMermaid } from "./diagram/validate.js";
+import { buildViewer, openViewerInBrowser, writeSidecar, } from "./diagram/viewer.js";
+import { collectDiagramTargets, diagramNameFor, displayPath, ensureDiagramDir, resolveDiagramSource, } from "./diagram/workspace.js";
+import { completeTextWithPiModel } from "./model.js";
 import { executeDml } from "./runtime.js";
 import { getPaths, initializeWorkspace, resolveDmlPath } from "./workspace.js";
 import { assemblePlanDml, buildPlanningPrompt, DC_PLAN_COMMIT_TOOL, isContextualPlan, PI_AGENT_STEP_TOOL, readPlanRequiredTools, validateGeneratedPlan, validatePlanSpec, writePlanNonDestructively, } from "./planner.js";
 const DC_RUN_TOOL = "dc_run";
-const AUTHORING_INSTRUCTION = `DeepClause programs live in .pi/deepclause/skills/ and executable generated plans live in .pi/deepclause/plans/. You may create and edit DML skills directly after consulting .pi/deepclause/AGENTS.md and DML_REFERENCE.md. Use /dc-plan when the user asks pi to design a contextual executable plan; finish that planning turn with dc_plan_commit. DeepClause compilation is unavailable, so generated content must already be valid DML. Users execute programs through /dc-run. If the opt-in dc_run tool is active, you may execute an ordinary skill with it, but contextual plans requiring pi_agent_step must be started by the user. Never invoke a compiler or create .deepclause/.`;
+const DC_DIAGRAM_TOOL = "dc_diagram";
+const AUTHORING_INSTRUCTION = `DeepClause programs live in .pi/deepclause/skills/ and executable generated plans live in .pi/deepclause/plans/. You may create and edit DML skills directly after consulting .pi/deepclause/AGENTS.md and DML_REFERENCE.md. Use /dc-plan when the user asks pi to design a contextual executable plan; finish that planning turn with dc_plan_commit. When the user asks for a diagram, flowchart, or visual of a .dml file, call the dc_diagram tool with the exact path and the requested grade (presentation or specification); it writes the viewer under .pi/deepclause/diagrams/ and opens it, so do not hand-write Mermaid. DeepClause compilation is unavailable, so generated content must already be valid DML. Users execute programs through /dc-run. If the opt-in dc_run tool is active, you may execute an ordinary skill with it, but contextual plans requiring pi_agent_step must be started by the user. Never invoke a compiler or create .deepclause/.`;
 const STATUS_KEY = "deepclause";
 const WIDGET_KEY = "deepclause-stream";
 export function splitArguments(input) {
@@ -170,6 +178,12 @@ async function listDmlFiles(directory, prefix = "") {
 function modelLabel(ctx) {
     return ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none selected";
 }
+async function bundledViewerTemplate() {
+    return readFile(fileURLToPath(new URL("./assets/viewer.template.html", import.meta.url)), "utf8");
+}
+function viewerVendorAssetPath() {
+    return fileURLToPath(new URL("./assets/vendor/mermaid.min.js", import.meta.url));
+}
 function publishResult(pi, content, details) {
     pi.sendMessage({ customType: "deepclause-result", content, display: true, details });
 }
@@ -177,6 +191,7 @@ export default function deepClauseExtension(pi) {
     let activeController;
     let activeDescription;
     let modelToolRegistered = false;
+    let diagramToolRegistered = false;
     let planCommitRegistered = false;
     let planningTransaction;
     let pendingAgentStep;
@@ -468,9 +483,131 @@ export default function deepClauseExtension(pi) {
                 : activeTools.filter((name) => name !== DC_RUN_TOOL));
         }
     };
+    const setDiagramToolActive = () => {
+        if (!diagramToolRegistered) {
+            pi.registerTool({
+                name: DC_DIAGRAM_TOOL,
+                label: "Create DeepClause Diagram",
+                description: "Create a presentation-grade or specification-grade Mermaid diagram from any .dml file, write a self-contained offline viewer under .pi/deepclause/diagrams/, and open it.",
+                promptSnippet: "Create a presentation- or specification-grade diagram from a DML file",
+                promptGuidelines: [
+                    "Use dc_diagram whenever the user asks for a diagram, flowchart, or visual of a .dml file; pass the exact path the user named.",
+                    "Choose grade=presentation for slides and overviews and grade=specification for engineering detail; use grade=both only when the user asks for both.",
+                    "Do not hand-write Mermaid or run diagram tools yourself; call dc_diagram and report the viewer result.",
+                ],
+                parameters: Type.Object({
+                    dml: Type.String({ description: "Path to a .dml file, relative to the workspace or absolute. A leading @ is ignored." }),
+                    grade: Type.Optional(Type.String({ description: "presentation (default), specification, or both. Synonyms such as detailed or technical map to specification." })),
+                    view: Type.Optional(StringEnum(["flow", "sequence"], { description: "Base layout used to seed the grade; default flow." })),
+                }),
+                async execute(_toolCallId, params, signal, onUpdate, ctx) {
+                    if (activeController) {
+                        return {
+                            content: [{ type: "text", text: "Another DeepClause operation is already active; wait for it to finish." }],
+                            details: { success: false, error: "execution_already_active" },
+                        };
+                    }
+                    const requested = resolveGrade(String(params.grade ?? "")) ?? "presentation";
+                    const grades = requested === "both" ? ["presentation", "specification"] : [requested];
+                    const view = params.view === "sequence" ? "sequence" : "flow";
+                    let sourcePath;
+                    try {
+                        sourcePath = await resolveDiagramSource(ctx.cwd, params.dml);
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        return { content: [{ type: "text", text: `dc_diagram failed: ${message}` }], details: { success: false, error: message } };
+                    }
+                    if (!ctx.model) {
+                        return {
+                            content: [{ type: "text", text: "dc_diagram requires an active pi model. Select one and try again." }],
+                            details: { success: false, error: "no_model" },
+                        };
+                    }
+                    const config = await loadConfig(getPaths(ctx.cwd).config);
+                    const source = await readFile(sourcePath, "utf8");
+                    const display = displayPath(ctx.cwd, sourcePath);
+                    const seed = view === "sequence"
+                        ? renderSequence(display, source)
+                        : renderDml(display, source, { hideOutput: true });
+                    const targets = await collectDiagramTargets(ctx.cwd, [sourcePath]);
+                    const name = diagramNameFor(sourcePath, targets, ctx.cwd);
+                    const { diagrams, vendor } = await ensureDiagramDir(ctx.cwd, viewerVendorAssetPath());
+                    const templateText = await bundledViewerTemplate();
+                    const controller = new AbortController();
+                    const cancel = () => controller.abort(signal?.reason ?? new Error("dc_diagram cancelled"));
+                    if (signal?.aborted)
+                        cancel();
+                    else
+                        signal?.addEventListener("abort", cancel, { once: true });
+                    activeController = controller;
+                    activeDescription = `diagram ${name} (${grades.join("+")})`;
+                    const run = (command, args, options) => pi.exec(command, args, options);
+                    let chrome;
+                    let chromeResolved = false;
+                    try {
+                        for (const grade of grades) {
+                            const result = await polishDiagram({
+                                grade,
+                                view,
+                                source,
+                                seed,
+                                maxTokens: config.maxTokens,
+                                signal: controller.signal,
+                                complete: (options) => completeTextWithPiModel(ctx, options),
+                                validate: async (code) => {
+                                    if (!chromeResolved) {
+                                        chrome = await findChrome(run);
+                                        chromeResolved = true;
+                                    }
+                                    const outcome = await validateMermaid(code, view, { run, vendorDir: vendor, chrome: chrome ?? null });
+                                    return outcome.result;
+                                },
+                                onProgress: (message) => onUpdate?.({
+                                    content: [{ type: "text", text: message }],
+                                    details: { dml: display, grades, name },
+                                }),
+                            });
+                            await writeSidecar(diagrams, name, grade, result.code);
+                        }
+                        const build = await buildViewer({
+                            cwd: ctx.cwd,
+                            templateText,
+                            vendorAssetPath: viewerVendorAssetPath(),
+                            extraPaths: [sourcePath],
+                        });
+                        const opened = ctx.hasUI
+                            ? await openViewerInBrowser(pi, build.viewerPath, name, grades[0] ?? "presentation")
+                            : false;
+                        const viewer = displayPath(ctx.cwd, build.viewerPath);
+                        const text = `Created ${grades.join(" + ")}-grade diagram for ${display}. Viewer: ${viewer}${opened ? " (opened in your browser)" : ""}`;
+                        return {
+                            content: [{ type: "text", text }],
+                            details: { success: true, dml: display, grades, name, viewer, opened, chrome: Boolean(chrome) },
+                        };
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        return { content: [{ type: "text", text: `dc_diagram failed: ${message}` }], details: { success: false, error: message } };
+                    }
+                    finally {
+                        signal?.removeEventListener("abort", cancel);
+                        activeController = undefined;
+                        activeDescription = undefined;
+                    }
+                },
+            });
+            diagramToolRegistered = true;
+        }
+        const activeTools = pi.getActiveTools();
+        if (!activeTools.includes(DC_DIAGRAM_TOOL)) {
+            pi.setActiveTools([...activeTools, DC_DIAGRAM_TOOL]);
+        }
+    };
     pi.on("session_start", async (_event, ctx) => {
         const config = await loadConfig(getPaths(ctx.cwd).config);
         setModelToolActive(config.modelToolEnabled);
+        setDiagramToolActive();
     });
     pi.on("tool_execution_start", (event) => {
         if (pendingAgentStep && !pendingAgentStep.toolsUsed.includes(event.toolName)) {
@@ -547,6 +684,9 @@ export default function deepClauseExtension(pi) {
                 `Plans: ${path.relative(ctx.cwd, paths.plans)}`,
                 `Context: ${config.contextMode} (verbose default: ${config.verbose})`,
                 `Model tool (${DC_RUN_TOOL}): ${config.modelToolEnabled && pi.getActiveTools().includes(DC_RUN_TOOL) ? "enabled" : "disabled"}`,
+                `Model tool (${DC_DIAGRAM_TOOL}): ${pi.getActiveTools().includes(DC_DIAGRAM_TOOL) ? "enabled" : "disabled"}`,
+                "Ask pi for a presentation-grade or specification-grade diagram of any .dml file;",
+                "it writes the viewer under .pi/deepclause/diagrams/ and opens it.",
                 "Commands:",
                 "  /dc-list",
                 "  /dc-plan <request> [--name=slug]   create an executable contextual DML plan",

package/dist/model.d.ts

@@ -0,0 +1,16 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Usage } from "@earendil-works/pi-ai";
+export interface TextCompletion {
+    text: string;
+    usage?: Usage;
+}
+/**
+ * One-shot text completion through pi's active model and credentials. Used by
+ * diagram grading; it never requests API keys or mutates provider state.
+ */
+export declare function completeTextWithPiModel(ctx: ExtensionContext, options: {
+    systemPrompt?: string;
+    prompt: string;
+    maxTokens: number;
+    signal?: AbortSignal;
+}): Promise<TextCompletion>;

package/dist/model.js

@@ -0,0 +1,28 @@
+/**
+ * One-shot text completion through pi's active model and credentials. Used by
+ * diagram grading; it never requests API keys or mutates provider state.
+ */
+export async function completeTextWithPiModel(ctx, options) {
+    const model = ctx.model;
+    if (!model)
+        throw new Error("Select a pi model before generating a diagram grade");
+    if (!ctx.modelRegistry.hasConfiguredAuth(model)) {
+        throw new Error(`Pi has no configured authentication for ${model.provider}/${model.id}`);
+    }
+    const response = await ctx.modelRegistry.complete(model, {
+        systemPrompt: options.systemPrompt,
+        messages: [{ role: "user", content: options.prompt, timestamp: Date.now() }],
+    }, {
+        signal: options.signal,
+        maxTokens: options.maxTokens,
+        cacheRetention: "none",
+    });
+    if (response.stopReason === "error" || response.stopReason === "aborted") {
+        throw new Error(response.errorMessage || `Pi model request ${response.stopReason}`);
+    }
+    const text = response.content
+        .filter((content) => content.type === "text")
+        .map((content) => content.text)
+        .join("");
+    return { text, usage: response.usage };
+}

package/docs/DIAGRAM_INTEGRATION_PROPOSAL.md

@@ -0,0 +1,154 @@
+# DML diagrams in `deepclause-pi` — minimal design
+
+## Goal
+
+> The user asks pi to turn a DML file into a diagram — **presentation grade** or
+> **specification grade**. When it's done, a viewer opens.
+
+That's the whole feature. No command suite, no manual build/edit/check/clean
+ritual. Pi does the work; the user just asks.
+
+## How the user experiences it
+
+```text
+User:  “Make me a presentation-grade diagram of
+        skills/deep_research.dml”
+
+pi:    (calls the dc_diagram tool)
+       Creating a presentation-grade diagram for deep_research.dml…
+       (viewer opens in the browser at the Presentation view)
+
+User:  “Now a specification-grade one for the same file”
+
+pi:    (calls dc_diagram with grade=specification)
+       (viewer opens at the Specification view)
+```
+
+The DML file can live **anywhere** — a relative path, an absolute path, or a
+path outside `.pi/deepclause/`. Pi points at it; the tool reads it.
+
+Grade is inferred from the request, or passed explicitly:
+`presentation` / `presentation-grade` → Presentation; `specification` /
+`spec` / `detailed` / `technical` → Specification. If the user says "both",
+produce both views.
+
+## What the extension exposes
+
+Exactly **one model-callable tool**:
+
+```text
+dc_diagram
+  dml   : string                      // path to any .dml file (relative or absolute)
+  grade : "presentation" | "specification" | "both"   // default: presentation
+  view  : "flow" | "sequence"         // optional, default: flow
+```
+
+- Registered on startup (it is a safe, read-and-generate operation — it does not
+  execute the DML, unlike `dc_run`, so it does not need the `/dc-tool` opt-in).
+- `promptGuidelines` tell pi to call it whenever the user asks for a diagram /
+  flowchart / visual of a DML file, to infer the grade from the wording, and not
+  to hand-write Mermaid itself.
+- A short line in `AUTHORING_INSTRUCTION` / `.pi/deepclause/AGENTS.md` mentions
+  the tool and where diagrams live.
+
+Optional, only if we want manual triggering: a single `/dc-diagram <path>
+[--grade=...]` command that does exactly the same thing. Not required.
+
+## What the tool does (one call, end to end)
+
+1. Resolve the input path: relative to the workspace or absolute; require an
+   existing `.dml` file (`realpath` + extension check). No `.pi/deepclause/`
+   restriction on input.
+2. Read the DML and compute a deterministic Mermaid **seed** in-process
+   (`renderDml` / `renderSequence`, ported from `dml_flow.mjs`). Always valid.
+3. If a grade is requested, ask the active pi model to rewrite the seed in that
+   grade (reusing pi's model backend — no `pi_bash`, no API keys), then validate
+   and retry up to ~3 rounds:
+   - **Presentation**: ~8–12 nodes, plain language, headline numbers, 1–2
+     callouts, no function names or framework jargon.
+   - **Specification**: keep function names, `task`/`tool` roles,
+     post-conditions, seed data; precise for an engineer.
+   - Validation: structural checks always; real Mermaid parser via headless
+     Chrome only if Chrome is available. A broken result never reaches the
+     viewer.
+4. Write the sidecar(s) under the active workspace's
+   `.pi/deepclause/diagrams/`: `<name>.presentation.mmd` and/or
+   `<name>.specification.mmd`.
+5. (Re)build `viewer.html` (embedded manifest + vendored Mermaid).
+6. **Open the viewer** at that diagram and view:
+   `xdg-open .pi/deepclause/diagrams/viewer.html?view=presentation#<name>`
+   (fixed argv via `pi.exec`, TUI/interactive only; otherwise just return the
+   path).
+7. Return a one-line result: file, grade, and viewer path.
+
+Progress and cancellation reuse the existing `/dc-run` UI plumbing
+(`setWidget`/`setStatus`, a local `AbortController` wired to the active
+execution so `/dc-cancel` still works).
+
+## Names and collisions
+
+The viewer is keyed by the DML **file name** (without `.dml`). If two DML files
+with the same base name are diagrammed, disambiguate with a short path hash
+(e.g. `deep_research-3f9a`) so sidecars and viewer entries never collide. The
+full source path is always shown in the viewer.
+
+## Artifacts
+
+```text
+.pi/deepclause/diagrams/              # in the active workspace, regardless
+├── viewer.html                       # of where the DML source lives
+├── index.json                        # manifest (also handy for tests/scripts)
+├── <name>.md                         # Mermaid fences for editors
+├── <name>.presentation.mmd           # presentation-grade sidecar
+└── <name>.specification.mmd          # specification-grade sidecar
+```
+
+- Created lazily on first use; `initializeWorkspace()` stays untouched.
+- Output always stays under `.pi/deepclause/`; no `.deepclause/`, no `docs/`.
+- Regenerating a grade overwrites only that sidecar (the user asked for it);
+  the other grade and other diagrams are preserved.
+
+## Viewer
+
+Reuse the handbook `viewer.template.html` nearly verbatim, with the sidebar
+list, theme picker, split pane (editable Mermaid + read-only DML), SVG/PNG
+export and hash deep-links. The view dropdown becomes:
+
+`Presentation → Specification → Flow → Sequence`
+
+Fallback order for the default view: Presentation → Specification → Flow.
+
+## Code changes
+
+```text
+src/diagram/extract.ts     # TS port of dml_flow.mjs (renderDml, renderSequence)
+src/diagram/grade.ts       # model rewrite + validation/retry loop
+src/diagram/viewer.ts      # write sidecars, build viewer.html, open browser
+src/assets/viewer.template.html   # adapted; Presentation/Specification labels
+src/assets/vendor/mermaid.min.js  # vendored, written on first build
+src/runtime.ts             # export a small completeWithPiModel() helper
+src/index.ts               # register dc_diagram + authoring note
+```
+
+## Policy
+
+- No compiler, no `.deepclause/`, no DML execution.
+- Input may be any readable `.dml` path; **output** is confined to the active
+  workspace's `.pi/deepclause/diagrams/`.
+- Does not register runtime tools and does not widen `pi_bash`/approval scope.
+- Browser opening uses a fixed command, not a shell string.
+
+## Validation
+
+- Asking pi for a diagram in natural language results in a `dc_diagram` call and
+  an opened viewer.
+- A DML file outside `.pi/deepclause/` (including an absolute path) works.
+- Presentation vs specification wording selects the right grade; "both"
+  produces both.
+- Chrome present → real-parser gate; Chrome absent → structural gate, viewer
+  still opens.
+- Invalid/partial model output is retried and never written as a final sidecar.
+- Missing file / non-`.dml` input is rejected.
+- Same-name DML files do not collide in the viewer.
+- No approval prompts are raised.
+- No files appear outside `.pi/deepclause/diagrams/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepclause-pi",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Pi-hosted runtime for DeepClause DML programs",
   "type": "module",
   "license": "MIT",

package/src/assets/AGENTS.md

@@ -375,6 +375,22 @@ DML is most valuable when an application needs more structure than a prompt and
 
 Poor fits include long-running background services, high-frequency shell automation that would require many approval prompts, workflows needing unrestricted pi tools, secret handling, or durable state without an explicit workspace storage design.
 
+## Diagrams
+
+Pi can turn any DML file into a self-contained, offline Mermaid viewer. Ask for one in plain language:
+
+> "Make a presentation-grade diagram of .pi/deepclause/skills/my_skill.dml"
+> "Give me a specification-grade diagram of src/report.dml"
+
+Pi calls the `dc_diagram` model tool with the DML path and a grade:
+
+- **presentation** — about 8-12 nodes, plain language, headline numbers (slides and overviews).
+- **specification** — function names, task/tool roles, post-conditions (engineers).
+
+The tool extracts a deterministic Mermaid seed, has pi rewrite it in the chosen grade, validates the result, writes the viewer under `.pi/deepclause/diagrams/`, and opens it. The DML file may live anywhere (workspace-relative or absolute); only the generated viewer stays under `.pi/deepclause/`.
+
+Do not hand-write Mermaid for the user, and do not copy diagram tooling into the workspace. Regenerating a grade replaces only that grade's sidecar (`<name>.presentation.mmd` / `<name>.specification.mmd`).
+
 ## Conservative editing rules
 
 When modifying an existing skill: