@rse/ase 1.0.6 → 2.0.0

package/dst/ase-mcp.js

@@ -7,7 +7,10 @@ import { fileURLToPath } from "node:url";
 import { execa } from "execa";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { SERVICE_HOST as HOST, probe, loadServiceContext } from "./ase-service.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { sessionState } from "./ase-config-core.js";
+import ServiceCommand from "./ase-service.js";
+import { SERVICE_HOST as HOST, probe, isConnRefused, loadServiceContext } from "./ase-service.js";
 /*  CLI command "ase mcp"  */
 export default class MCPCommand {
     log;
@@ -42,14 +45,60 @@ export default class MCPCommand {
             throw new Error(`mcp: service not responding on port ${ctx.port} after start`);
         return { projectId: ctx.projectId, port: ctx.port };
     }
+    /*  determine the GitHub Copilot CLI session id from the environment: unlike
+        the hook handlers, which receive it in their event payload, the bridge can
+        only learn it from the environment of its MCP server process, where GitHub
+        Copilot CLI (and only it) exports both COPILOT_PLUGIN_ROOT and the session id
+        in COPILOT_AGENT_SESSION_ID; an empty result (always the case under the
+        other tools) disables the project directory lookup  */
+    sessionIdFromEnv() {
+        if ((process.env.COPILOT_PLUGIN_ROOT ?? "") === "")
+            return "";
+        const value = process.env.COPILOT_AGENT_SESSION_ID ?? "";
+        return /^[A-Za-z0-9._-]+$/.test(value) ? value : "";
+    }
+    /*  read the project directory which the session-start hook recorded for a
+        session; the session scope resolves below the home directory and hence
+        does not itself depend on the working directory to be correct already  */
+    readSessionProjectDir(sessionId) {
+        try {
+            /*  read without locking: this is polled until the session-start
+                hook has recorded the directory, and locking would both create
+                the session files prematurely and contend with that very hook --
+                writers use atomic replacement, so a plain read can never
+                observe a partial file  */
+            const state = sessionState(this.log, sessionId);
+            state.read();
+            const value = state.getExplicit("basedir");
+            return typeof value === "string" && value !== "" ? value : null;
+        }
+        catch (_e) {
+            /*  best-effort: an unreadable session config just defers the lookup  */
+            return null;
+        }
+    }
     /*  coerce an unknown thrown value into an Error  */
     asError(e) {
         return e instanceof Error ? e : new Error(String(e));
     }
     /*  bridge stdio to a Streamable HTTP MCP endpoint on the local service  */
     async runBridge() {
-        /*  ensure the service is running  */
-        let { projectId, port } = await this.ensureService();
+        /*  determine whether the service has to be deferred: GitHub Copilot CLI
+            starts the MCP server in the plugin installation directory and reveals
+            the project only to its hooks, so the service of the project can be
+            started only once the session-start hook recorded the project directory
+            (GitHub Copilot CLI only -- the other tools already start the bridge
+            inside the project, so their service is started right away)  */
+        const sessionId = this.sessionIdFromEnv();
+        const deferred = sessionId !== "";
+        /*  ensure the service is running (unless deferred)  */
+        let projectId = "";
+        let port = null;
+        if (!deferred) {
+            const ctx = await this.ensureService();
+            projectId = ctx.projectId;
+            port = ctx.port;
+        }
         /*  create MCP STDIO server (lives for the entire bridge lifetime)  */
         const server = new StdioServerTransport();
         /*  track active client and bridge-level closed state  */
@@ -78,6 +127,8 @@ export default class MCPCommand {
         };
         /*  (re-)connect the HTTP client to the service  */
         const connectClient = async () => {
+            if (port === null)
+                throw new Error("mcp: no service port known");
             const url = new URL(`http://${HOST}:${port}/mcp`);
             const next = new StreamableHTTPClientTransport(url);
             next.onmessage = (msg) => {
@@ -149,31 +200,133 @@ export default class MCPCommand {
                 pending.push(msg);
                 return;
             }
-            client.send(msg).catch((err) => {
-                this.log.write("error", `mcp: http send: ${this.asError(err).message}`);
+            const target = client;
+            target.send(msg).catch((err) => {
+                if (!isConnRefused(err)) {
+                    this.log.write("error", `mcp: http send: ${this.asError(err).message}`);
+                    return;
+                }
+                /*  service is gone: detach the dead client, recover, and re-send  */
+                if (client === target) {
+                    closedByUs.add(target);
+                    client = null;
+                    target.close().catch(() => { });
+                    triggerReconnect("http connection refused");
+                }
+                sendToClient(msg);
             });
         };
+        /*  while deferred, answer all messages in-process through the same MCP
+            server the service would use -- this covers the MCP handshake and
+            the tool listing, which GitHub Copilot CLI insists on before it even
+            runs the session-start hook -- except the tool calls, which are held
+            back in the pending buffer until the service is connected  */
+        let local = null;
+        if (deferred) {
+            const [localClient, localServer] = InMemoryTransport.createLinkedPair();
+            await ServiceCommand.buildMcpServer(this.log, { projectId: "", port: 0 }, Date.now()).connect(localServer);
+            localClient.onmessage = (msg) => {
+                server.send(msg).catch((err) => {
+                    this.log.write("error", `mcp: stdout send: ${this.asError(err).message}`);
+                });
+            };
+            await localClient.start();
+            local = localClient;
+        }
+        /*  stop deferring: switch into the recorded project directory (if any),
+            so the service is looked up -- and if needed started -- inside the
+            project, then connect to it and flush the held tool calls  */
+        const POLL_INTERVAL_MS = 250;
+        const FALLBACK_MS = 30_000;
+        let pollTimer = null;
+        let fallbackTimer = null;
+        const undefer = (dir) => {
+            if (local === null)
+                return;
+            local.close().catch(() => { });
+            local = null;
+            if (pollTimer !== null)
+                clearInterval(pollTimer);
+            if (fallbackTimer !== null)
+                clearTimeout(fallbackTimer);
+            if (dir === null)
+                this.log.write("warning", "mcp: no project directory recorded by session-start hook " +
+                    `-- falling back to the current directory "${process.cwd()}"`);
+            else {
+                try {
+                    process.chdir(dir);
+                }
+                catch (err) {
+                    this.log.write("warning", `mcp: cannot switch to recorded project directory "${dir}": ` +
+                        `${this.asError(err).message} -- falling back to the current directory`);
+                }
+            }
+            server.onmessage = sendToClient;
+            const run = async () => {
+                const ctx = await this.ensureService();
+                port = ctx.port;
+                projectId = ctx.projectId;
+                await connectClient();
+                this.log.write("info", `mcp: connected to service of project "${projectId}" on port ${port}`);
+            };
+            run().catch((err) => {
+                triggerReconnect(`deferred connect failed: ${this.asError(err).message}`);
+            });
+        };
+        /*  look for the recorded project directory  */
+        const checkProjectDir = () => {
+            const dir = this.readSessionProjectDir(sessionId);
+            if (dir !== null)
+                undefer(dir);
+        };
         /*  wire stdio server  */
-        server.onmessage = sendToClient;
+        if (!deferred)
+            server.onmessage = sendToClient;
+        else
+            server.onmessage = (msg) => {
+                if (local === null)
+                    sendToClient(msg);
+                else if ("method" in msg && msg.method === "tools/call") {
+                    /*  hold back tool calls, and in case the session-start hook
+                        never records a project directory, do not hold them back
+                        forever (measured from the first held call and not from
+                        the start, as an interactive session can idle arbitrarily
+                        long before the hook runs with its first prompt)  */
+                    sendToClient(msg);
+                    if (fallbackTimer === null)
+                        fallbackTimer = setTimeout(() => { undefer(null); }, FALLBACK_MS);
+                    checkProjectDir();
+                }
+                else
+                    local.send(msg).catch((err) => {
+                        this.log.write("error", `mcp: local send: ${this.asError(err).message}`);
+                    });
+            };
         server.onerror = (err) => {
             this.log.write("error", `mcp: stdio: ${err.message}`);
         };
         server.onclose = () => {
             shutdown().catch(() => { });
         };
-        /*  start server and initial client  */
+        /*  start server and initial client (or the polling for the recorded project directory)  */
         await server.start();
-        try {
-            await connectClient();
+        if (!deferred) {
+            try {
+                await connectClient();
+            }
+            catch (err) {
+                /*  service vanished between probe and connect — recover instead of crashing  */
+                triggerReconnect(`initial connect failed: ${this.asError(err).message}`);
+            }
         }
-        catch (err) {
-            /*  service vanished between probe and connect — recover instead of crashing  */
-            triggerReconnect(`initial connect failed: ${this.asError(err).message}`);
+        else {
+            pollTimer = setInterval(checkProjectDir, POLL_INTERVAL_MS);
+            pollTimer.unref();
         }
         /*  periodically probe the service; trigger reconnect if it is gone  */
         const HEALTH_INTERVAL_MS = 30_000;
         const healthTimer = setInterval(async () => {
-            if (bridgeDone || reconnecting)
+            if (bridgeDone || reconnecting || port === null)
                 return;
             try {
                 const match = await probe(port, projectId);

package/dst/{ase-getopt.js → ase-service-getopt.js}

@@ -72,6 +72,75 @@ const unquote = (s) => {
     }
     return out;
 };
+/*  slice the verbatim trailing arguments from the raw input by skipping all
+    leading option tokens (and the separate value tokens they take), mirroring
+    the pass-through semantics of commander on the verbatim text  */
+const verbatimArgs = (input, flagTakesValue) => {
+    const ranges = tokenizeRanges(input);
+    let idx = 0;
+    while (idx < ranges.length) {
+        const tok = unquote(input.slice(ranges[idx].start, ranges[idx].end));
+        if (tok === "--") {
+            idx++;
+            break;
+        }
+        if (!tok.startsWith("-") || tok === "-")
+            break;
+        idx++;
+        if (flagTakesValue.get(tok) === true && idx < ranges.length)
+            idx++;
+    }
+    return idx < ranges.length ? input.slice(ranges[idx].start) : "";
+};
+/*  convert a dashed long option name into its camel-cased commander key  */
+const camelKey = (long) => long.replace(/-(.)/g, (_, c) => c.toUpperCase());
+/*  parse the options specification into commander options, plus the
+    information needed for list validation and verbatim argument slicing  */
+const parseSpec = (spec) => {
+    const tokens = spec.split(/\s+/).filter((e) => e.length > 0);
+    const re = /^--([A-Za-z][A-Za-z0-9-]*)(?:\|-([A-Za-z]))?(?:=(\((.*)\)(\.\.\.)?|.*))?$/;
+    const internals = new Set();
+    const flagTakesValue = new Map();
+    const options = [];
+    const listOpts = [];
+    for (const tok of tokens) {
+        const m = re.exec(tok);
+        if (m === null)
+            throw new Error(`invalid spec token "${tok}"`);
+        const long = m[1];
+        const short = m[2] ?? null;
+        const valuePart = m[3] ?? null;
+        const choicePart = m[4] ?? null;
+        const listMarker = m[5] ?? null;
+        const takesValue = valuePart !== null;
+        const choices = choicePart !== null ? choicePart.split("|") : null;
+        const isList = listMarker !== null;
+        const dflt = choices !== null ? choices[0] : valuePart;
+        flagTakesValue.set(`--${long}`, takesValue);
+        if (short !== null)
+            flagTakesValue.set(`-${short}`, takesValue);
+        const head = short !== null ? `-${short}, --${long}` : `--${long}`;
+        const flags = takesValue ? `${head} <value>` : head;
+        const opt = new Option(flags);
+        if (takesValue) {
+            if (choices !== null && !isList)
+                opt.choices(choices);
+            opt.default(dflt);
+        }
+        else
+            opt.default(false);
+        if (choices !== null && isList)
+            listOpts.push({ long, choices });
+        if (long.startsWith("int-")) {
+            /*  internal option: hide from usage help and remember
+                its camel-cased key for the info rendering  */
+            opt.hideHelp();
+            internals.add(camelKey(long));
+        }
+        options.push(opt);
+    }
+    return { options, internals, flagTakesValue, listOpts };
+};
 /*  MCP registration entry point for the option-parser tool  */
 export class GetoptMCP {
     register(mcp) {
@@ -92,9 +161,9 @@ export class GetoptMCP {
                 name: z.string()
                     .describe("Name of the caller (e.g. skill name), used in error messages"),
                 spec: z.string()
-                    .describe("Whitespace-separated option spec, e.g. `--foo/-f --bar --baz/-b=BAZ`"),
+                    .describe("Whitespace-separated option spec, e.g. `--foo|-f --bar --baz|-b=BAZ`"),
                 args: z.union([z.string(), z.array(z.string())])
-                    .describe("Arguments to parse (string is split on whitespace)")
+                    .describe("Arguments to parse (string is split shell-like, honoring quotes)")
             }
         }, async (args) => {
             let helpText = "";
@@ -102,11 +171,11 @@ export class GetoptMCP {
                 /*  normalize args  */
                 const argsRaw = typeof args.args === "string" ? args.args : null;
                 const argsVec = typeof args.args === "string" ?
-                    shParse(args.args)
-                        .map((e) => typeof e === "string" ? e :
-                        (e !== null && typeof e === "object" && "op" in e && e.op === "glob" ?
-                            e.pattern : null))
-                        .filter((e) => e !== null) :
+                    shParse(args.args, (key) => `$${key}`)
+                        .flatMap((e) => typeof e === "string" ? [e] :
+                        "pattern" in e ? [e.pattern] :
+                            "op" in e ? [e.op] :
+                                `#${e.comment}`.split(/\s+/).filter((s) => s.length > 0)) :
                     args.args;
                 /*  build a fresh commander program  */
                 const cmd = new Command(args.name)
@@ -118,49 +187,10 @@ export class GetoptMCP {
                     writeOut: (str) => { helpText += str; },
                     writeErr: () => { }
                 });
-                /*  tokenize spec and add one option per token  */
-                const tokens = args.spec.split(/\s+/).filter((e) => e.length > 0);
-                const re = /^--([A-Za-z][A-Za-z0-9-]*)(?:\|-([A-Za-z]))?(?:=(\((.*)\)(\.\.\.)?|.*))?$/;
-                const camelKey = (long) => long.replace(/-(.)/g, (_, c) => c.toUpperCase());
-                const internals = new Set();
-                const flagTakesValue = new Map();
-                const listOpts = [];
-                for (const tok of tokens) {
-                    const m = re.exec(tok);
-                    if (m === null)
-                        throw new Error(`invalid spec token "${tok}"`);
-                    const long = m[1];
-                    const short = m[2] ?? null;
-                    const valuePart = m[3] ?? null;
-                    const choicePart = m[4] ?? null;
-                    const listMarker = m[5] ?? null;
-                    const takesValue = valuePart !== null;
-                    const choices = choicePart !== null ? choicePart.split("|") : null;
-                    const isList = listMarker !== null;
-                    const dflt = choices !== null ? choices[0] : valuePart;
-                    flagTakesValue.set(`--${long}`, takesValue);
-                    if (short !== null)
-                        flagTakesValue.set(`-${short}`, takesValue);
-                    const head = short !== null ? `-${short}, --${long}` : `--${long}`;
-                    const flags = takesValue ? `${head} <value>` : head;
-                    const opt = new Option(flags);
-                    if (takesValue) {
-                        if (choices !== null && !isList)
-                            opt.choices(choices);
-                        opt.default(dflt);
-                    }
-                    else
-                        opt.default(false);
-                    if (choices !== null && isList)
-                        listOpts.push({ long, choices });
-                    if (long.startsWith("int-")) {
-                        /*  internal option: hide from usage help and remember
-                            its camel-cased key for the info rendering below  */
-                        opt.hideHelp();
-                        internals.add(camelKey(long));
-                    }
+                /*  parse spec and add its options  */
+                const { options, internals, flagTakesValue, listOpts } = parseSpec(args.spec);
+                for (const opt of options)
                     cmd.addOption(opt);
-                }
                 /*  parse args  */
                 cmd.parse(argsVec, { from: "user" });
                 /*  validate comma-separated list-of-choices options (only
@@ -180,37 +210,9 @@ export class GetoptMCP {
                     }
                 }
                 /*  compute verbatim trailing argument string  */
-                let argsVerbatim = "";
-                if (argsRaw !== null) {
-                    /*  tokenize raw input into [start,end) ranges, preserving quotes  */
-                    const ranges = tokenizeRanges(argsRaw);
-                    /*  walk the raw ranges, consuming leading option tokens (and any
-                        separate value tokens they take) until the first positional
-                        is reached, then slice the original input from there -- this
-                        mirrors commander's pass-through semantics while staying on
-                        the verbatim text and is robust against value-consuming
-                        options and shell-operator characters in the input  */
-                    let idx = 0;
-                    while (idx < ranges.length) {
-                        const tok = unquote(argsRaw.slice(ranges[idx].start, ranges[idx].end));
-                        if (tok === "--") {
-                            idx++;
-                            break;
-                        }
-                        if (!tok.startsWith("-") || tok === "-")
-                            break;
-                        let consumesNext = false;
-                        if (/^--[^=]+$/.test(tok) || /^-[^-]$/.test(tok))
-                            consumesNext = flagTakesValue.get(tok) === true;
-                        idx++;
-                        if (consumesNext && idx < ranges.length)
-                            idx++;
-                    }
-                    if (idx < ranges.length)
-                        argsVerbatim = argsRaw.slice(ranges[idx].start);
-                }
-                else
-                    argsVerbatim = shQuote(cmd.args);
+                const argsVerbatim = argsRaw !== null ?
+                    verbatimArgs(argsRaw, flagTakesValue) :
+                    shQuote(cmd.args);
                 /*  build markdown info rendering of parsed options  */
                 const opts = cmd.opts();
                 const info = Object.entries(opts)

package/dst/{ase-markdown.js → ase-service-markdown.js}

@@ -6,13 +6,9 @@
 import { z } from "zod";
 /*  the reusable functionality  */
 export class Markdown {
-    /*  prepare Markdown for improved rendering by rewriting
-        unordered bullet paragraphs -- replacing the "-"/"*" bullet marker with
-        "◯" and splitting multi-line inline code spans into per-line single-line
-        spans (so each physical line carries its own closed backtick span).
-        Fenced code blocks (``` / ~~~) are detected line-wise and passed
-        through entirely verbatim, so neither the inline-span splitting nor the
-        bullet-marker rewriting ever touches their contents.  */
+    /*  prepare Markdown for improved rendering: rewrite escaped-backtick code
+        spans, split multi-line code spans into per-line spans, and replace
+        "-"/"*" bullet markers with "◯", passing fenced code blocks verbatim  */
     static prepare(text) {
         if (typeof text !== "string")
             throw new Error("markdown: text must be a string");
@@ -89,9 +85,14 @@ export class Markdown {
         let j = 0;
         while (j < text.length) {
             const ch = text[j];
-            if (ch !== "`") {
+            if (ch === "\\" && text[j + 1] === "`") {
                 /*  literal backslash-escaped backtick *outside* any span
                     is left verbatim for later scanning  */
+                pre += "\\`";
+                j += 2;
+                continue;
+            }
+            if (ch !== "`") {
                 pre += ch;
                 j++;
                 continue;
@@ -137,9 +138,15 @@ export class Markdown {
                 inner += c;
                 k++;
             }
-            if (!closed || !escaped) {
-                /*  not an escaped-backtick span: emit the opening run
-                    verbatim and continue scanning from just after it  */
+            if (closed && !escaped) {
+                /*  regular span: emit it verbatim and continue after it  */
+                pre += text.slice(j, k + open);
+                j = k + open;
+                continue;
+            }
+            if (!closed) {
+                /*  unmatched opening run: emit it verbatim and continue
+                    scanning from just after it  */
                 pre += "`".repeat(open);
                 j += open;
                 continue;