@rse/ase 0.0.27 → 0.0.28

package/dst/ase-diagram.js

@@ -6,6 +6,7 @@
 import fs from "node:fs";
 import { InvalidArgumentError } from "commander";
 import { renderMermaidASCII } from "beautiful-mermaid";
+import { z } from "zod";
 /*  custom argument parser for Commander: non-negative integer  */
 const parseInteger = (name) => (value) => {
     const n = Number.parseInt(value, 10);
@@ -19,57 +20,6 @@ const parseColorMode = (name) => (value) => {
         throw new InvalidArgumentError(`${name} must be "none", "ansi16", or "ansi256"`);
     return value;
 };
-/*  detect terminal column width  */
-export const detectTermWidth = () => {
-    let width = 0;
-    /*  attempt 1: query environment variable  */
-    if (process.env.ASE_TERM_WIDTH !== undefined) {
-        const cols = Number.parseInt(process.env.ASE_TERM_WIDTH, 10);
-        if (Number.isFinite(cols) && cols > 0)
-            width = cols;
-    }
-    /*  attempt 2: query stdout  */
-    if (width === 0 && process.stdout.isTTY) {
-        const cols = process.stdout.columns;
-        if (typeof cols === "number" && cols > 0)
-            width = cols;
-    }
-    return width;
-};
-/*  detect terminal row height  */
-export const detectTermHeight = () => {
-    let height = 0;
-    /*  attempt 1: query environment variable  */
-    if (process.env.ASE_TERM_HEIGHT !== undefined) {
-        const rows = Number.parseInt(process.env.ASE_TERM_HEIGHT, 10);
-        if (Number.isFinite(rows) && rows > 0)
-            height = rows;
-    }
-    /*  attempt 2: query stdout  */
-    if (height === 0 && process.stdout.isTTY) {
-        const rows = process.stdout.rows;
-        if (typeof rows === "number" && rows > 0)
-            height = rows;
-    }
-    return height;
-};
-/*  detect terminal color capability  */
-const detectColorMode = () => {
-    let mode = "none";
-    /*  attempt 1: query environment variable (explicitly)  */
-    if (process.env.ASE_TERM_COLORS !== undefined)
-        if (process.env.ASE_TERM_COLORS.match(/^(?:none|ansi16|ansi256)$/) !== null)
-            mode = process.env.ASE_TERM_COLORS;
-    /*  attempt 2: query stdout  */
-    if (mode === "none" && process.stdout.isTTY) {
-        const depth = process.stdout.getColorDepth();
-        if (depth >= 8)
-            mode = "ansi256";
-        else if (depth >= 4)
-            mode = "ansi16";
-    }
-    return mode;
-};
 /*  truncate a single rendered line to a maximum visible column,
     preserving ANSI escape sequences (CSI ...m) and appending an ANSI
     reset sequence if any styling was active at the truncation point  */
@@ -135,70 +85,124 @@ const visibleWidth = (line) => {
     }
     return visible;
 };
-/*  pure rendering helper: turn a Mermaid source string plus options into
-    a rendered Unicode/ASCII diagram string. Throws on render failure.  */
-export const renderDiagram = (src, opts) => {
-    /*  create diagram rendering  */
-    let out = renderMermaidASCII(src, {
-        useAscii: opts.ascii,
-        paddingX: opts.nodeMarginX,
-        paddingY: opts.nodeMarginY,
-        boxBorderPadding: opts.nodePadding,
-        colorMode: opts.colorMode,
-        theme: opts.colorMode !== "none" ? {
-            fg: "#000000",
-            border: "#a0a0a0",
-            junction: "#a0a0a0",
-            arrow: "#404040",
-            line: "#707070",
-            corner: "#707070"
-        } : {
-            fg: "#000000",
-            border: "#000000",
-            junction: "#000000",
-            arrow: "#000000",
-            line: "#000000",
-            corner: "#000000"
+/*  reusable functionality: Mermaid diagram rendering as Unicode/ASCII art  */
+export class Diagram {
+    /*  detect terminal column width  */
+    static detectTermWidth() {
+        let width = 0;
+        /*  attempt 1: query environment variable  */
+        if (process.env.ASE_TERM_WIDTH !== undefined) {
+            const cols = Number.parseInt(process.env.ASE_TERM_WIDTH, 10);
+            if (Number.isFinite(cols) && cols > 0)
+                width = cols;
         }
-    });
-    /*  optionally clip diagram rendering  */
-    const termWidth = opts.terminalWidth;
-    const termHeight = opts.terminalHeight;
-    if (termWidth > 0 || termHeight > 0) {
-        const maxWidth = termWidth > 0 ? termWidth - opts.diagramClipX : 0;
-        const maxHeight = termHeight > 0 ? termHeight - opts.diagramClipY : 0;
-        const trailingNL = out.endsWith("\n");
-        let lines = (trailingNL ? out.slice(0, -1) : out).split("\n");
-        let widthWarn = "";
-        let heightWarn = "";
-        if (maxWidth > 0) {
-            const widest = lines.reduce((m, l) => Math.max(m, visibleWidth(l)), 0);
-            if (widest > maxWidth)
-                widthWarn =
-                    `ase diagram: WARNING: rendered diagram width ${widest} exceeds budget ${maxWidth}; ` +
-                        "rightmost content was clipped. Please regenerate the Mermaid source to fit " +
-                        `within ${maxWidth} chars by preferring a portrait orientation ` +
-                        "(\"flowchart TB\", top-to-bottom) over landscape (\"LR\"/\"RL\"/\"BT\"), " +
-                        "reducing siblings per row, abbreviating node labels, or restructuring " +
-                        "into nested subgraph hierarchies.";
-            lines = lines.map((l) => truncateAnsiLine(l, maxWidth));
+        /*  attempt 2: query stdout  */
+        if (width === 0 && process.stdout.isTTY) {
+            const cols = process.stdout.columns;
+            if (typeof cols === "number" && cols > 0)
+                width = cols;
         }
-        if (maxHeight > 0 && lines.length > maxHeight) {
-            const overflow = lines.length - maxHeight;
-            heightWarn =
-                `ase diagram: WARNING: rendered diagram height ${lines.length} exceeds budget ${maxHeight}; ` +
-                    `bottom ${overflow} line(s) were clipped. Please regenerate the Mermaid source to fit ` +
-                    `within ${maxHeight} lines by reducing depth or splitting into multiple diagrams.`;
-            lines = lines.slice(0, maxHeight);
+        return width;
+    }
+    /*  detect terminal row height  */
+    static detectTermHeight() {
+        let height = 0;
+        /*  attempt 1: query environment variable  */
+        if (process.env.ASE_TERM_HEIGHT !== undefined) {
+            const rows = Number.parseInt(process.env.ASE_TERM_HEIGHT, 10);
+            if (Number.isFinite(rows) && rows > 0)
+                height = rows;
+        }
+        /*  attempt 2: query stdout  */
+        if (height === 0 && process.stdout.isTTY) {
+            const rows = process.stdout.rows;
+            if (typeof rows === "number" && rows > 0)
+                height = rows;
         }
-        out = lines.join("\n") + (trailingNL ? "\n" : "");
-        if (widthWarn !== "")
-            out += "\n" + widthWarn + "\n";
-        if (heightWarn !== "")
-            out += "\n" + heightWarn + "\n";
+        return height;
     }
-    return out;
-};
+    /*  detect terminal color capability  */
+    static detectColorMode() {
+        let mode = "none";
+        /*  attempt 1: query environment variable (explicitly)  */
+        if (process.env.ASE_TERM_COLORS !== undefined)
+            if (process.env.ASE_TERM_COLORS.match(/^(?:none|ansi16|ansi256)$/) !== null)
+                mode = process.env.ASE_TERM_COLORS;
+        /*  attempt 2: query stdout  */
+        if (mode === "none" && process.stdout.isTTY) {
+            const depth = process.stdout.getColorDepth();
+            if (depth >= 8)
+                mode = "ansi256";
+            else if (depth >= 4)
+                mode = "ansi16";
+        }
+        return mode;
+    }
+    /*  pure rendering helper: turn a Mermaid source string plus options into
+        a rendered Unicode/ASCII diagram string. Throws on render failure.  */
+    static render(src, opts) {
+        /*  create diagram rendering  */
+        let out = renderMermaidASCII(src, {
+            useAscii: opts.ascii,
+            paddingX: opts.nodeMarginX,
+            paddingY: opts.nodeMarginY,
+            boxBorderPadding: opts.nodePadding,
+            colorMode: opts.colorMode,
+            theme: opts.colorMode !== "none" ? {
+                fg: "#000000",
+                border: "#a0a0a0",
+                junction: "#a0a0a0",
+                arrow: "#404040",
+                line: "#707070",
+                corner: "#707070"
+            } : {
+                fg: "#000000",
+                border: "#000000",
+                junction: "#000000",
+                arrow: "#000000",
+                line: "#000000",
+                corner: "#000000"
+            }
+        });
+        /*  optionally clip diagram rendering  */
+        const termWidth = opts.terminalWidth;
+        const termHeight = opts.terminalHeight;
+        if (termWidth > 0 || termHeight > 0) {
+            const maxWidth = termWidth > 0 ? termWidth - opts.diagramClipX : 0;
+            const maxHeight = termHeight > 0 ? termHeight - opts.diagramClipY : 0;
+            const trailingNL = out.endsWith("\n");
+            let lines = (trailingNL ? out.slice(0, -1) : out).split("\n");
+            let widthWarn = "";
+            let heightWarn = "";
+            if (maxWidth > 0) {
+                const widest = lines.reduce((m, l) => Math.max(m, visibleWidth(l)), 0);
+                if (widest > maxWidth)
+                    widthWarn =
+                        `ase diagram: WARNING: rendered diagram width ${widest} exceeds budget ${maxWidth}; ` +
+                            "rightmost content was clipped. Please regenerate the Mermaid source to fit " +
+                            `within ${maxWidth} chars by preferring a portrait orientation ` +
+                            "(\"flowchart TB\", top-to-bottom) over landscape (\"LR\"/\"RL\"/\"BT\"), " +
+                            "reducing siblings per row, abbreviating node labels, or restructuring " +
+                            "into nested subgraph hierarchies.";
+                lines = lines.map((l) => truncateAnsiLine(l, maxWidth));
+            }
+            if (maxHeight > 0 && lines.length > maxHeight) {
+                const overflow = lines.length - maxHeight;
+                heightWarn =
+                    `ase diagram: WARNING: rendered diagram height ${lines.length} exceeds budget ${maxHeight}; ` +
+                        `bottom ${overflow} line(s) were clipped. Please regenerate the Mermaid source to fit ` +
+                        `within ${maxHeight} lines by reducing depth or splitting into multiple diagrams.`;
+                lines = lines.slice(0, maxHeight);
+            }
+            out = lines.join("\n") + (trailingNL ? "\n" : "");
+            if (widthWarn !== "")
+                out += "\n" + widthWarn + "\n";
+            if (heightWarn !== "")
+                out += "\n" + heightWarn + "\n";
+        }
+        return out;
+    }
+}
 /*  read stdin into a single string  */
 const readStdin = async () => {
     const chunks = [];
@@ -219,14 +223,14 @@ export default class DiagramCommand {
             .description("Render Mermaid diagram specification as Unicode/ASCII art")
             .option("-i, --input <file>", "read Mermaid source from file instead of stdin")
             .option("-a, --ascii", "emit plain ASCII (+-|) instead of Unicode box-drawing", false)
-            .option("-c, --color-mode <mode>", "force color mode (\"none\", \"ansi16\", or \"ansi256\")", parseColorMode("--color-mode"), detectColorMode())
+            .option("-c, --color-mode <mode>", "force color mode (\"none\", \"ansi16\", or \"ansi256\")", parseColorMode("--color-mode"), Diagram.detectColorMode())
             .option("--node-margin-x <n>", "horizontal margin between nodes of <n> characters", parseInteger("--node-margin-x"), 3)
             .option("--node-margin-y <n>", "vertical margin between nodes of <n> lines", parseInteger("--node-margin-y"), 3)
             .option("--node-padding <n>", "horizontal and vertical inner node padding with <n> characters", parseInteger("--node-padding"), 1)
             .option("--diagram-clip-x <n>", "extra horizontal clipping of diagram to terminal width minus <n> characters", parseInteger("--diagram-clip-x"), 0)
             .option("--diagram-clip-y <n>", "extra vertical clipping of diagram to terminal height minus <n> lines", parseInteger("--diagram-clip-y"), 0)
-            .option("--terminal-width <n>", "width of terminal of <n> characters (for diagram clipping)", parseInteger("--terminal-width"), detectTermWidth())
-            .option("--terminal-height <n>", "height of terminal of <n> lines (for diagram clipping)", parseInteger("--terminal-height"), detectTermHeight())
+            .option("--terminal-width <n>", "width of terminal of <n> characters (for diagram clipping)", parseInteger("--terminal-width"), Diagram.detectTermWidth())
+            .option("--terminal-height <n>", "height of terminal of <n> lines (for diagram clipping)", parseInteger("--terminal-height"), Diagram.detectTermHeight())
             .action(async (opts) => {
             /*  fetch Mermaid diagram specification from stdin  */
             let src;
@@ -241,7 +245,7 @@ export default class DiagramCommand {
             /*  create diagram rendering  */
             let out;
             try {
-                out = renderDiagram(src, {
+                out = Diagram.render(src, {
                     ascii: opts.ascii ?? false,
                     colorMode: opts.colorMode,
                     nodeMarginX: opts.nodeMarginX,
@@ -265,3 +269,68 @@ export default class DiagramCommand {
         });
     }
 }
+/*  MCP registration entry point for diagram tools  */
+export class DiagramMCP {
+    register(mcp) {
+        mcp.registerTool("diagram", {
+            title: "ASE diagram render",
+            description: "Render a Mermaid diagram as Unicode/ASCII art. " +
+                "Use for visualizing " +
+                "structure/layout/components/dependencies as a Flowchart, " +
+                "control-flow/branching/concurrency as a Flowchart, " +
+                "state-machine/states/transitions as an UML State Diagram, " +
+                "data-flow/actors/messages/protocols as an UML Sequence Diagram, " +
+                "data-structure/classes/methods as an UML Class Diagram, " +
+                "data-model/entities/relationships as an ER Diagram, or " +
+                "metrics/distributions/time-series as an XY-Chart. " +
+                "Pass the Mermaid diagram specification as `diagram`. " +
+                "Returns the rendered art as `text`.",
+            inputSchema: {
+                diagram: z.string()
+                    .describe("Mermaid diagram specification"),
+                ascii: z.boolean().default(false)
+                    .describe("emit plain ASCII (+-|) instead of Unicode box-drawing characters"),
+                colorMode: z.enum(["none", "ansi16", "ansi256"]).default("none")
+                    .describe("color mode for ANSI escape sequences in the rendered output"),
+                nodeMarginX: z.number().int().min(0).default(3)
+                    .describe("horizontal margin between nodes, in characters"),
+                nodeMarginY: z.number().int().min(0).default(3)
+                    .describe("vertical margin between nodes, in lines"),
+                nodePadding: z.number().int().min(0).default(1)
+                    .describe("inner horizontal and vertical padding within each node, in characters"),
+                diagramClipX: z.number().int().min(0).default(0)
+                    .describe("extra horizontal clipping: subtract this many characters from `terminalWidth`"),
+                diagramClipY: z.number().int().min(0).default(0)
+                    .describe("extra vertical clipping: subtract this many lines from `terminalHeight`"),
+                terminalWidth: z.number().int().min(0).default(Diagram.detectTermWidth())
+                    .describe("terminal width in characters; 0 disables horizontal clipping; defaults to ASE_TERM_WIDTH env var if set"),
+                terminalHeight: z.number().int().min(0).default(Diagram.detectTermHeight())
+                    .describe("terminal height in lines; 0 disables vertical clipping; defaults to ASE_TERM_HEIGHT env var if set")
+            }
+        }, async (args) => {
+            try {
+                const out = Diagram.render(args.diagram, {
+                    ascii: args.ascii,
+                    colorMode: args.colorMode,
+                    nodeMarginX: args.nodeMarginX,
+                    nodeMarginY: args.nodeMarginY,
+                    nodePadding: args.nodePadding,
+                    diagramClipX: args.diagramClipX,
+                    diagramClipY: args.diagramClipY,
+                    terminalWidth: args.terminalWidth,
+                    terminalHeight: args.terminalHeight
+                });
+                return {
+                    content: [{ type: "text", text: out }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `diagram: render failed: ${message}` }]
+                };
+            }
+        });
+    }
+}

package/dst/ase-hook.js

@@ -5,6 +5,7 @@
 */
 import path from "node:path";
 import fs from "node:fs";
+import os from "node:os";
 import { execaSync } from "execa";
 import Version from "./ase-version.js";
 import { Config, configSchema, parseScope } from "./ase-config.js";
@@ -173,6 +174,26 @@ export default class HookCommand {
         process.stdout.write(JSON.stringify(payload));
         return 0;
     }
+    /*  handler for "ase hook session-end" (both tools)  */
+    doSessionEnd(_tool) {
+        /*  read session information (Claude Code uses snake_case fields,
+            Copilot CLI uses camelCase fields)  */
+        const stdin = fs.readFileSync(0, "utf8");
+        const input = stdin.trim() !== "" ? JSON.parse(stdin) : {};
+        /*  determine session id  */
+        const sessionId = input.session_id ?? input.sessionId ?? "";
+        /*  remove the session directory ~/.ase/session/<id> (only for a valid sessionId)  */
+        if (/^[A-Za-z0-9._-]+$/.test(sessionId)) {
+            const dir = path.join(os.homedir(), ".ase", "session", sessionId);
+            try {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+            catch (_e) {
+                /*  best-effort: ignore failures  */
+            }
+        }
+        return 0;
+    }
     /*  handler for "ase hook pre-tool-use" (both tools)  */
     doPreToolUse(tool) {
         const spec = toolSpecs[tool];
@@ -254,6 +275,14 @@ export default class HookCommand {
             .action(async (opts) => {
             process.exit(await this.doSessionStart(this.parseTool(opts.tool)));
         });
+        /*  register CLI sub-command "ase hook session-end"  */
+        hookCmd
+            .command("session-end")
+            .description("handle SessionEnd hook event")
+            .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\")", toolDflt)
+            .action((opts) => {
+            process.exit(this.doSessionEnd(this.parseTool(opts.tool)));
+        });
         /*  register CLI sub-command "ase hook pre-tool-use"  */
         hookCmd
             .command("pre-tool-use")

package/dst/ase-mcp.js

@@ -9,7 +9,7 @@ import { execa } from "execa";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { Config, configSchema } from "./ase-config.js";
-import { SERVICE_HOST as HOST, serviceSchema, probe } from "./ase-service-probe.js";
+import { SERVICE_HOST as HOST, serviceSchema, probe } from "./ase-service.js";
 /*  CLI command "ase mcp"  */
 export default class MCPCommand {
     log;

package/dst/ase-persona.js

@@ -0,0 +1,87 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+import { isScalar } from "yaml";
+import { z } from "zod";
+import { Config, configSchema, parseScope } from "./ase-config.js";
+/*  reusable functionality: ASE agent persona style get/set  */
+export class Persona {
+    /*  allowed persona style values  */
+    static styles = ["writer", "engineer", "telegrapher", "caveman"];
+    /*  get the effective persona style for an optional session;
+        returns the default "engineer" if nothing is configured  */
+    static get(log, session) {
+        const scope = session !== undefined ?
+            parseScope(`session:${session}`) :
+            parseScope(undefined);
+        const cfg = new Config("config", configSchema, log, scope);
+        cfg.read();
+        const val = cfg.get("agent.persona");
+        if (val === undefined)
+            return "engineer";
+        return String(isScalar(val) ? val.value : val);
+    }
+    /*  set the persona style on the strongest scope of an optional session  */
+    static set(log, style, session) {
+        const scope = session !== undefined ?
+            parseScope(`session:${session}`) :
+            parseScope(undefined);
+        const cfg = new Config("config", configSchema, log, scope);
+        cfg.read();
+        cfg.set("agent.persona", style);
+        cfg.write();
+    }
+}
+/*  MCP registration entry point for persona tools  */
+export default class PersonaMCP {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    register(mcp) {
+        mcp.registerTool("persona", {
+            title: "ASE persona style get/set",
+            description: "Get or set the active ASE agent persona `style`. " +
+                "If `style` is provided, it sets the persona style, " +
+                "otherwise it returns the current persona `style`. " +
+                "If `session` is provided, the operation is scoped to that session, " +
+                "otherwise it operates on the broadest scope (user/project cascade). " +
+                "Allowed styles: \"writer\" (decorative, eloquent, explaining), " +
+                "\"engineer\" (brief, factual, accurate), " +
+                "\"telegrapher\" (very brief, factual, abbreviating), " +
+                "\"caveman\" (ultra brief, rough, stuttering).",
+            inputSchema: {
+                style: z.enum(Persona.styles).optional()
+                    .describe("persona style to set; if omitted, the current persona style is returned"),
+                session: z.string().optional()
+                    .describe("session identifier (allowed characters: A-Z, a-z, 0-9, '-'); " +
+                    "if omitted, the operation is not scoped to a specific session")
+            }
+        }, async (args) => {
+            try {
+                if (args.style !== undefined) {
+                    Persona.set(this.log, args.style, args.session);
+                    const where = args.session !== undefined ?
+                        ` for session "${args.session}"` : "";
+                    const msg = `persona: OK: set agent.persona to "${args.style}"${where}`;
+                    return {
+                        content: [{ type: "text", text: msg }]
+                    };
+                }
+                const text = Persona.get(this.log, args.session);
+                return {
+                    content: [{ type: "text", text }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `persona: ERROR: ${message}` }]
+                };
+            }
+        });
+    }
+}