@rse/ase 0.0.20 → 0.0.21

package/dst/ase-claude.js

@@ -0,0 +1,116 @@
+/*
+**  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 { execa, execaSync } from "execa";
+import which from "which";
+import { Config, configSchema, parseScope } from "./ase-config.js";
+/*  default statusline arguments (claudeX fallback) used when the
+    "agent.statusline" config variable is empty or unset  */
+const DEFAULT_STATUSLINE_ARGS = "-w 0 -m 2 '<blue>%u</blue> <red>%p</red> <black>%T</black> %s' '%m %e %t' '%P %c'";
+/*  CLI command "ase claude"  */
+export default class ClaudeCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  ensure a tool is available  */
+    async ensureTool(tool) {
+        return which(tool).catch(() => {
+            throw new Error(`mandatory tool "${tool}" not found in $PATH`);
+        });
+    }
+    /*  resolve the statusline command-line arguments from the layered
+        ASE configuration ("agent.statusline"), falling back to the
+        claudeX default if the value is empty or unavailable  */
+    resolveStatuslineArgs() {
+        let args = "";
+        try {
+            const cfg = new Config("config", configSchema, this.log, parseScope("project"));
+            cfg.read("lenient");
+            args = String(cfg.get("agent.statusline") ?? "").trim();
+        }
+        catch (_e) {
+            /*  cascade unavailable; keep fallback  */
+        }
+        if (args === "")
+            args = DEFAULT_STATUSLINE_ARGS;
+        return args;
+    }
+    /*  register commands  */
+    register(program) {
+        program
+            .command("claude")
+            .description("start Claude Code with bootstrapped ASE environment and settings")
+            .passThroughOptions()
+            .allowUnknownOption()
+            .argument("[args...]", "arguments forwarded verbatim to the \"claude\" CLI")
+            .action(async (args) => {
+            /*  ensure Claude Code CLI is available  */
+            await this.ensureTool("claude");
+            /*  bootstrap ASE_TERM_WIDTH from terminal columns  */
+            if (process.env.ASE_TERM_WIDTH === undefined) {
+                let width = 0;
+                if (process.stdout.isTTY) {
+                    const cols = process.stdout.columns;
+                    if (typeof cols === "number" && cols > 0)
+                        width = cols;
+                }
+                process.env.ASE_TERM_WIDTH = `${width}`;
+            }
+            /*  bootstrap ASE_TERM_HEIGHT from terminal rows  */
+            if (process.env.ASE_TERM_HEIGHT === undefined) {
+                let height = 0;
+                if (process.stdout.isTTY) {
+                    const rows = process.stdout.rows;
+                    if (typeof rows === "number" && rows > 0)
+                        height = rows;
+                }
+                process.env.ASE_TERM_HEIGHT = `${height}`;
+            }
+            /*  bootstrap ASE_TERM_COLORS from "tput colors"  */
+            if (process.env.ASE_TERM_COLORS === undefined) {
+                let colorMode = "none";
+                try {
+                    const { stdout } = execaSync("tput", ["colors"], { reject: false });
+                    const n = parseInt(stdout.trim(), 10);
+                    if (!Number.isNaN(n) && n >= 256)
+                        colorMode = "ansi256";
+                    else if (!Number.isNaN(n) && n >= 16)
+                        colorMode = "ansi16";
+                }
+                catch (_e) {
+                    /*  ignore  */
+                }
+                process.env.ASE_TERM_COLORS = colorMode;
+            }
+            /*  resolve statusline arguments (config or claudeX fallback)  */
+            const statuslineArgs = this.resolveStatuslineArgs();
+            /*  build inline Claude Code settings JSON  */
+            const settings = {
+                env: {
+                    DISABLE_TELEMETRY: "1",
+                    DISABLE_AUTOUPDATER: "1",
+                    DISABLE_BUG_COMMAND: "1",
+                    DISABLE_ERROR_REPORTING: "1"
+                },
+                statusLine: {
+                    type: "command",
+                    command: `ase statusline ${statuslineArgs}`,
+                    padding: 0
+                }
+            };
+            const settingsJSON = JSON.stringify(settings);
+            /*  exec Claude Code with the inline settings prepended
+                and any user-supplied arguments forwarded verbatim  */
+            const result = await execa("claude", ["--settings", settingsJSON, ...args], {
+                stdio: "inherit",
+                env: process.env,
+                reject: false,
+                windowsHide: false
+            });
+            process.exit(result.exitCode ?? 0);
+        });
+    }
+}

package/dst/ase-diagram.js

@@ -20,7 +20,7 @@ const parseColorMode = (name) => (value) => {
     return value;
 };
 /*  detect terminal column width  */
-const detectTermWidth = () => {
+export const detectTermWidth = () => {
     let width = 0;
     /*  attempt 1: query environment variable  */
     if (process.env.ASE_TERM_WIDTH !== undefined) {
@@ -37,7 +37,7 @@ const detectTermWidth = () => {
     return width;
 };
 /*  detect terminal row height  */
-const detectTermHeight = () => {
+export const detectTermHeight = () => {
     let height = 0;
     /*  attempt 1: query environment variable  */
     if (process.env.ASE_TERM_HEIGHT !== undefined) {
@@ -112,6 +112,29 @@ const truncateAnsiLine = (line, budget) => {
         out += "\x1b[0m";
     return out;
 };
+/*  measure visible column width of a rendered line, ignoring ANSI escape
+    sequences (CSI ...m); mirrors the visibility model of truncateAnsiLine  */
+const visibleWidth = (line) => {
+    let visible = 0;
+    let i = 0;
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === "\x1b" && line[i + 1] === "[") {
+            let j = i + 2;
+            while (j < line.length && !/[A-Za-z]/.test(line[j]))
+                j++;
+            if (j < line.length) {
+                i = j + 1;
+                continue;
+            }
+            i++;
+            continue;
+        }
+        visible++;
+        i++;
+    }
+    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) => {
@@ -146,11 +169,33 @@ export const renderDiagram = (src, opts) => {
         const maxHeight = termHeight > 0 ? termHeight - opts.diagramClipY : 0;
         const trailingNL = out.endsWith("\n");
         let lines = (trailingNL ? out.slice(0, -1) : out).split("\n");
-        if (maxWidth > 0)
+        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)
+        }
+        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;
 };

package/dst/ase-launch.js

@@ -0,0 +1,109 @@
+/*
+**  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 { execa, execaSync } from "execa";
+import which from "which";
+import { Config, configSchema, parseScope } from "./ase-config.js";
+/*  list of supported tools for "ase launch <tool>"  */
+const SUPPORTED_TOOLS = ["claude"];
+/*  default statusline arguments (used when "agent.statusline" is empty/unset)  */
+const DEFAULT_STATUSLINE_ARGS = "-w 0 -m 2 '<blue>%u</blue> <red>%p</red> <black>%T</black> %s' '%m %e %t' '%P %c'";
+/*  CLI command "ase launch"  */
+export default class LaunchCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  resolve the effective "agent.statusline" from the layered
+        configuration cascade (default < user < project)  */
+    readStatuslineConfig() {
+        let statusline = "";
+        try {
+            const cfg = new Config("config", configSchema, this.log, parseScope(undefined));
+            cfg.read("lenient");
+            statusline = String(cfg.get("agent.statusline") ?? "").trim();
+        }
+        catch (_e) {
+            /*  cascade unavailable; leave default  */
+        }
+        /*  reject shell metacharacters to prevent command injection through
+            the configured value when later interpolated into a shell command  */
+        if (statusline !== "" && /[;&|`$\n\r]/.test(statusline))
+            throw new Error("invalid \"agent.statusline\" configuration value: " +
+                "must not contain shell metacharacters (; & | ` $ newline)");
+        return statusline;
+    }
+    /*  populate ASE_TERM_* environment variables (only if unset),
+        so downstream tools (e.g. the diagram renderer) get reliable
+        terminal sizing/color information regardless of the launched tool  */
+    populateTermEnv() {
+        const tty = process.stdout.isTTY;
+        if (process.env.ASE_TERM_WIDTH === undefined) {
+            const cols = tty ? process.stdout.columns : 0;
+            process.env.ASE_TERM_WIDTH = `${typeof cols === "number" && cols > 0 ? cols : 0}`;
+        }
+        if (process.env.ASE_TERM_HEIGHT === undefined) {
+            const rows = tty ? process.stdout.rows : 0;
+            process.env.ASE_TERM_HEIGHT = `${typeof rows === "number" && rows > 0 ? rows : 0}`;
+        }
+        if (process.env.ASE_TERM_COLORS === undefined) {
+            let colorMode = "none";
+            try {
+                const { stdout } = execaSync("tput", ["colors"], { reject: false });
+                const n = parseInt(stdout.trim(), 10);
+                if (!Number.isNaN(n) && n >= 256)
+                    colorMode = "ansi256";
+                else if (!Number.isNaN(n) && n >= 16)
+                    colorMode = "ansi16";
+            }
+            catch (_e) {
+                /*  ignore  */
+            }
+            process.env.ASE_TERM_COLORS = colorMode;
+        }
+    }
+    /*  handler for "ase launch <tool> [<options>...]"  */
+    async run(tool, args) {
+        /*  populate ASE_TERM_* environment variables (always, regardless of tool)  */
+        this.populateTermEnv();
+        /*  dispatch by tool name  */
+        if (tool === "claude") {
+            await which("claude").catch(() => {
+                throw new Error("required tool \"claude\" not found in $PATH");
+            });
+            let statusline = this.readStatuslineConfig();
+            if (statusline === "")
+                statusline = DEFAULT_STATUSLINE_ARGS;
+            const settingsJson = JSON.stringify({
+                statusLine: {
+                    type: "command",
+                    command: `ase statusline ${statusline}`,
+                    padding: 0
+                }
+            });
+            const result = await execa("claude", ["--settings", settingsJson, ...args], {
+                stdio: "inherit",
+                env: process.env,
+                reject: false
+            });
+            return result.exitCode ?? 0;
+        }
+        else
+            throw new Error(`unsupported tool "${tool}" ` +
+                `(expected one of: ${SUPPORTED_TOOLS.join(", ")})`);
+    }
+    /*  register commands  */
+    register(program) {
+        program
+            .command("launch <tool> [options...]")
+            .description("launch a supported tool with bootstrapped environment and settings " +
+            `(supported tools: ${SUPPORTED_TOOLS.join(", ")})`)
+            .passThroughOptions()
+            .allowUnknownOption()
+            .action(async (tool, options) => {
+            process.exit(await this.run(tool, options));
+        });
+    }
+}

package/dst/ase-mcp.js

@@ -86,54 +86,102 @@ export default class MCPCommand {
     /*  bridge stdio to a Streamable HTTP MCP endpoint on the local service  */
     async runBridge() {
         /*  ensure the service is running  */
-        const { port } = await this.ensureService();
-        /*  create MCP HTTP client  */
-        const url = new URL(`http://${HOST}:${port}/mcp`);
-        const client = new StreamableHTTPClientTransport(url);
-        /*  create MCP STDIO server  */
+        let { port } = await this.ensureService();
+        /*  create MCP STDIO server (lives for the entire bridge lifetime)  */
         const server = new StdioServerTransport();
-        /*  handle shutdown  */
-        let closed = false;
+        /*  track active client and bridge-level closed state  */
+        let client = null;
+        let closedByUs = false; /* set when we initiated the client close */
+        let bridgeDone = false; /* set when stdio side closes             */
+        /*  cleanly shut down the whole bridge  */
         const shutdown = async () => {
-            if (closed)
+            if (bridgeDone)
                 return;
-            closed = true;
+            bridgeDone = true;
+            closedByUs = true;
             await Promise.allSettled([
                 server.close(),
-                client.close()
+                client?.close()
             ]);
         };
-        /*  connect server to client (forward transport)  */
+        /*  (re-)connect the HTTP client to the service  */
+        const connectClient = async () => {
+            const url = new URL(`http://${HOST}:${port}/mcp`);
+            const next = new StreamableHTTPClientTransport(url);
+            client = next;
+            next.onmessage = (msg) => {
+                server.send(msg).catch((_err) => {
+                    const err = _err instanceof Error ? _err : new Error(String(_err));
+                    this.log.write("error", `mcp: stdout send: ${err.message}`);
+                });
+            };
+            next.onerror = (err) => {
+                this.log.write("error", `mcp: http: ${err.message}`);
+            };
+            /*  service closed the connection — try to recover  */
+            next.onclose = () => {
+                if (closedByUs || bridgeDone)
+                    return;
+                this.log.write("warning", "mcp: http connection lost — reconnecting");
+                reconnect().catch(() => { });
+            };
+            await next.start();
+        };
+        /*  reconnect loop: restart service if needed, then reconnect client  */
+        const reconnect = async (attempt = 0) => {
+            const delay = Math.min(500 * 2 ** attempt, 10000);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            if (bridgeDone)
+                return;
+            try {
+                const ctx = await this.ensureService();
+                port = ctx.port;
+                closedByUs = true;
+                await client?.close();
+                closedByUs = false;
+                await connectClient();
+                this.log.write("info", "mcp: reconnected to service");
+            }
+            catch (_err) {
+                const err = _err instanceof Error ? _err : new Error(String(_err));
+                this.log.write("error", `mcp: reconnect failed: ${err.message}`);
+                reconnect(attempt + 1).catch(() => { });
+            }
+        };
+        /*  wire stdio server  */
         server.onmessage = (msg) => {
-            client.send(msg).catch((_err) => {
+            client?.send(msg).catch((_err) => {
                 const err = _err instanceof Error ? _err : new Error(String(_err));
                 this.log.write("error", `mcp: http send: ${err.message}`);
             });
         };
-        server.onerror = (_err) => {
-            const err = _err instanceof Error ? _err : new Error(String(_err));
+        server.onerror = (err) => {
             this.log.write("error", `mcp: stdio: ${err.message}`);
         };
         server.onclose = () => {
             shutdown().catch(() => { });
         };
-        /*  connect client to server (backward transport)  */
-        client.onmessage = (msg) => {
-            server.send(msg).catch((_err) => {
-                const err = _err instanceof Error ? _err : new Error(String(_err));
-                this.log.write("error", `mcp: stdout send: ${err.message}`);
-            });
-        };
-        client.onerror = (_err) => {
-            const err = _err instanceof Error ? _err : new Error(String(_err));
-            this.log.write("error", `mcp: http: ${err.message}`);
-        };
-        client.onclose = () => {
-            shutdown().catch(() => { });
-        };
-        /*  start server and client  */
+        /*  start server and initial client  */
         await server.start();
-        await client.start();
+        await connectClient();
+        /*  periodically probe the service; trigger reconnect if it is gone  */
+        const HEALTH_INTERVAL_MS = 30_000;
+        let reconnecting = false;
+        const healthTimer = setInterval(async () => {
+            if (bridgeDone || reconnecting)
+                return;
+            try {
+                const { projectId } = this.loadContext();
+                const match = await probe(port, projectId);
+                if (match !== true) {
+                    reconnecting = true;
+                    this.log.write("warning", "mcp: health check failed — reconnecting");
+                    reconnect().catch(() => { }).finally(() => { reconnecting = false; });
+                }
+            }
+            catch { /* ignore probe errors */ }
+        }, HEALTH_INTERVAL_MS);
+        healthTimer.unref();
         /*  await stdio to be closed  */
         await new Promise((resolve) => {
             const done = () => resolve();
@@ -141,6 +189,7 @@ export default class MCPCommand {
             process.stdin.once("close", done);
         });
         /*  shutdown services  */
+        clearInterval(healthTimer);
         await shutdown();
         return 0;
     }

package/dst/ase-service.js

@@ -17,7 +17,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { z } from "zod";
 import { Config, configSchema, parseScope } from "./ase-config.js";
-import { renderDiagram } from "./ase-diagram.js";
+import { renderDiagram, detectTermWidth, detectTermHeight } from "./ase-diagram.js";
 import { taskLoad, taskSave, taskDelete, taskList } from "./ase-task.js";
 import pkg from "../package.json" with { type: "json" };
 const SERVE_ENV = "ASE_SERVICE_SERVE";
@@ -231,10 +231,10 @@ export default class ServiceCommand {
                         .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(0)
-                        .describe("terminal width in characters; 0 disables horizontal clipping"),
-                    terminalHeight: z.number().int().min(0).default(0)
-                        .describe("terminal height in lines; 0 disables vertical clipping")
+                    terminalWidth: z.number().int().min(0).default(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(detectTermHeight())
+                        .describe("terminal height in lines; 0 disables vertical clipping; defaults to ASE_TERM_HEIGHT env var if set")
                 }
             }, async (args) => {
                 try {
@@ -326,7 +326,7 @@ export default class ServiceCommand {
                     const message = err instanceof Error ? err.message : String(err);
                     return {
                         isError: true,
-                        content: [{ type: "text", text: `task_save: FAILED: ${message}` }]
+                        content: [{ type: "text", text: `task_save: ERROR: ${message}` }]
                     };
                 }
             });
@@ -394,7 +394,7 @@ export default class ServiceCommand {
                     const val = cfg.get("agent.persona");
                     if (val === undefined)
                         return {
-                            content: [{ type: "text", text: "" }]
+                            content: [{ type: "text", text: "engineer" }]
                         };
                     const text = String(isScalar(val) ? val.value : val);
                     return {
@@ -412,7 +412,7 @@ export default class ServiceCommand {
             mcp.registerTool("task_id", {
                 title: "ASE task id get/set",
                 description: "Get or set the active ASE task `id` for a given `session`. " +
-                    "If `id` is provided, it set the task id in the given `session`, " +
+                    "If `id` is provided, it sets the task id in the given `session`, " +
                     "otherwise it returns the current task `id` of the `session`.",
                 inputSchema: {
                     id: z.string().optional()
@@ -467,6 +467,7 @@ export default class ServiceCommand {
             method: "GET",
             path: "/stop",
             handler: (_request, h) => {
+                this.log.write("info", "service: stop requested");
                 setImmediate(async () => {
                     await server.stop({ timeout: 1000 });
                     process.exit(0);
@@ -475,6 +476,21 @@ export default class ServiceCommand {
             }
         });
         const mcpHandler = async (request, h, body) => {
+            const b = body;
+            const bParams = b?.params;
+            const bMethod = typeof b?.method === "string" ? b.method : null;
+            const bName = typeof bParams?.name === "string" ? bParams.name : null;
+            const bArgs = bParams?.arguments !== undefined ? bParams.arguments : null;
+            let bodyInfo = "";
+            if (bMethod !== null) {
+                bodyInfo = ` [${bMethod}]`;
+                if (bName !== null) {
+                    bodyInfo += ` ${bName}`;
+                    if (bArgs !== null)
+                        bodyInfo += ` ${JSON.stringify(bArgs)}`;
+                }
+            }
+            this.log.write("info", `mcp: ${request.method.toUpperCase()} ${request.path}${bodyInfo}`);
             const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
             const mcp = buildMcpServer();
             request.raw.res.on("close", () => {
@@ -531,6 +547,7 @@ export default class ServiceCommand {
         try {
             await server.start();
             persistPort(ctx.svc, ctx.port);
+            this.log.write("info", `service: listening on port ${ctx.port}`);
         }
         catch (err) {
             const e = err;
@@ -552,6 +569,7 @@ export default class ServiceCommand {
                 return;
             if (Date.now() - lastActivity > IDLE_MS) {
                 stopping = true;
+                this.log.write("info", "service: idle timeout reached, stopping");
                 try {
                     await server.stop({ timeout: 1000 });
                     clearPort(ctx.svc);

package/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "http://github.com/rse/ase",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "http://github.com/rse/ase/issues" },
-    "version":                              "0.0.20",
+    "version":                              "0.0.21",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -18,9 +18,8 @@
     "devDependencies": {
         "eslint":                           "9.39.4",
         "@eslint/js":                       "9.39.4",
-        "@typescript-eslint/parser":        "8.59.1",
-        "@typescript-eslint/eslint-plugin": "8.59.1",
-        "eslint-plugin-n":                  "17.24.0",
+        "@typescript-eslint/parser":        "8.59.2",
+        "@typescript-eslint/eslint-plugin": "8.59.2",
         "eslint-plugin-promise":            "7.3.0",
         "eslint-plugin-import":             "2.32.0",
         "neostandard":                      "0.13.0",
@@ -38,18 +37,18 @@
     "dependencies": {
         "commander":                        "14.0.3",
         "yaml":                             "2.8.4",
-        "valibot":                          "1.3.1",
+        "valibot":                          "1.4.0",
         "execa":                            "9.6.1",
         "mkdirp":                           "3.0.1",
-        "@hapi/hapi":                       "21.4.8",
-        "axios":                            "1.15.2",
+        "@hapi/hapi":                       "21.4.9",
+        "axios":                            "1.16.0",
         "beautiful-mermaid":                "1.1.3",
         "cli-table3":                       "0.6.5",
         "chalk":                            "5.6.2",
         "pretty-ms":                        "9.3.0",
         "luxon":                            "3.7.2",
         "@modelcontextprotocol/sdk":        "1.29.0",
-        "zod":                              "4.4.2",
+        "zod":                              "4.4.3",
         "which":                            "6.0.1"
     },
     "engines": {