ast-mcp-server 0.12.0 → 0.13.1

package/dist/services/agent-targets.js

@@ -1,6 +1,9 @@
 import { toolCatalog } from "../tools/catalog.js";
 export const MCP_SERVER_NAME = "ast";
 const EXPECTED_TOOLS = toolCatalog.compatibility.required;
+const APPLY_TOOL = "ast_apply_operation";
+/** Ambient agent surfaces opt into the apply-effect tool (fail-closed guard default is deny). */
+const APPLY_GUARD_ALLOW_ENV = "AST_MCP_APPLY_GUARD=allow";
 function semver(value) {
     const match = value.match(/(?:^|\s|v)(\d+)\.(\d+)\.(\d+)(?=\s|$|[-+()]|\.(?:\s|$))/);
     return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : undefined;
@@ -28,6 +31,32 @@ function expected(context, command, args) {
         args.length === 1 &&
         args[0] === context.serverEntryPath);
 }
+function structuredGuardStatus(...values) {
+    const provided = values.filter((value) => value !== undefined);
+    if (provided.length === 0)
+        return "repairable";
+    const records = provided.filter((value) => value !== null && typeof value === "object" && !Array.isArray(value));
+    return records.length === provided.length &&
+        records.length === 1 &&
+        Object.keys(records[0]).length === 1 &&
+        records[0].AST_MCP_APPLY_GUARD === "allow"
+        ? "current"
+        : "conflict";
+}
+function matchingRegistration(hasExpectedCommand, guardStatus) {
+    if (!hasExpectedCommand) {
+        return {
+            status: "conflict",
+            detail: "The existing 'ast' registration does not match this package.",
+        };
+    }
+    return guardStatus === "conflict"
+        ? {
+            status: "conflict",
+            detail: "The existing 'ast' registration has unsupported environment settings.",
+        }
+        : { status: guardStatus };
+}
 function parseJson(result) {
     try {
         return JSON.parse(result.stdout);
@@ -46,12 +75,7 @@ function structuredInspection(result, context) {
     if (!value || value.name !== MCP_SERVER_NAME)
         return { status: "error", operation: "MCP inspection", result };
     const transport = (value.transport ?? value);
-    return expected(context, transport.command, transport.args)
-        ? { status: "current" }
-        : {
-            status: "conflict",
-            detail: "The existing 'ast' registration does not match this package.",
-        };
+    return matchingRegistration(transport.type === "stdio" && expected(context, transport.command, transport.args), structuredGuardStatus(transport.env, transport.environment));
 }
 function copilotStructuredInspection(result, context) {
     if (result.exitCode !== 0) {
@@ -65,18 +89,35 @@ function copilotStructuredInspection(result, context) {
         return { status: "error", operation: "MCP inspection", result };
     }
     const configuration = server;
-    return configuration.type === "local" &&
+    const matches = configuration.type === "local" &&
         configuration.source === "user" &&
         configuration.enabled === true &&
         Array.isArray(configuration.tools) &&
         configuration.tools.length === 1 &&
         configuration.tools[0] === "*" &&
-        expected(context, configuration.command, configuration.args)
-        ? { status: "current" }
-        : {
-            status: "conflict",
+        expected(context, configuration.command, configuration.args);
+    const inspection = matchingRegistration(matches, structuredGuardStatus(configuration.env, configuration.environment));
+    return inspection.status === "conflict"
+        ? {
+            ...inspection,
             detail: "The existing user-scoped 'ast' registration does not match this package.",
-        };
+        }
+        : inspection;
+}
+function claudeRegister(runtime, context, guarded) {
+    return runtime.run([
+        "mcp",
+        "add",
+        "--scope",
+        "user",
+        ...(guarded ? ["--env", APPLY_GUARD_ALLOW_ENV] : []),
+        "--transport",
+        "stdio",
+        MCP_SERVER_NAME,
+        "--",
+        context.nodeExecutable,
+        context.serverEntryPath,
+    ]);
 }
 const claudeMcp = {
     async inspect(runtime, context) {
@@ -88,87 +129,140 @@ const claudeMcp = {
                 : { status: "error", operation: "MCP inspection", result };
         const fields = new Map();
         for (const line of result.stdout.split(/\r?\n/)) {
-            const match = line.match(/^\s*(Status|Type|Command|Args):\s*(.*)$/i);
+            const match = line.match(/^\s*(Scope|Status|Type|Command|Args):\s*(.*)$/i);
             if (match)
                 fields.set(match[1].toLowerCase(), match[2].trim());
         }
-        return /connected/i.test(fields.get("status") ?? "") &&
+        const matches = /^user config\b/i.test(fields.get("scope") ?? "") &&
+            /connected/i.test(fields.get("status") ?? "") &&
             fields.get("type")?.toLowerCase() === "stdio" &&
-            expected(context, fields.get("command"), [fields.get("args")])
-            ? { status: "current" }
-            : {
-                status: "conflict",
+            expected(context, fields.get("command"), [fields.get("args")]);
+        const hasEnvironment = /^\s*Environment:\s*$/im.test(result.stdout);
+        const inspection = matchingRegistration(matches, /(?:^|\s)AST_MCP_APPLY_GUARD\s*=\s*allow(?:\s|$)/m.test(result.stdout)
+            ? "current"
+            : hasEnvironment
+                ? "conflict"
+                : "repairable");
+        return inspection.status === "conflict"
+            ? {
+                ...inspection,
                 detail: "The existing user-scoped 'ast' registration does not match this package.",
-            };
+            }
+            : inspection;
     },
-    register: (runtime, context) => runtime.run([
+    register: (runtime, context) => claudeRegister(runtime, context, true),
+    unregister: (runtime) => runtime.run(["mcp", "remove", MCP_SERVER_NAME, "--scope", "user"]),
+    registerLegacy: (runtime, context) => claudeRegister(runtime, context, false),
+    registrationAccepted: (result) => result.exitCode === 0,
+    removalAccepted: (result) => result.exitCode === 0,
+};
+function hermesRegister(runtime, context, guarded) {
+    return runtime.run([
         "mcp",
         "add",
-        "--scope",
-        "user",
-        "--transport",
-        "stdio",
         MCP_SERVER_NAME,
-        "--",
+        "--command",
         context.nodeExecutable,
+        ...(guarded ? ["--env", APPLY_GUARD_ALLOW_ENV] : []),
+        "--args",
         context.serverEntryPath,
-    ]),
-    registrationAccepted: (result) => result.exitCode === 0,
-};
+    ], "\n");
+}
 const hermesMcp = {
-    async inspect(runtime) {
+    async inspect(runtime, context) {
         const listed = await runtime.run(["mcp", "list"]);
         if (listed.exitCode !== 0)
             return { status: "error", operation: "MCP list", result: listed };
         if (!/^\s*ast(?:\s|$)/im.test(listed.stdout))
             return { status: "missing" };
-        const tested = await runtime.run(["mcp", "test", MCP_SERVER_NAME]);
-        return tested.exitCode === 0 && EXPECTED_TOOLS.every((tool) => tested.stdout.includes(tool))
-            ? { status: "current" }
-            : {
+        const configured = await runtime.run(["config", "get", "mcp_servers.ast", "--json"]);
+        const registration = parseJson(configured);
+        if (configured.exitCode !== 0 ||
+            !registration ||
+            Array.isArray(registration) ||
+            !expected(context, registration.command, registration.args)) {
+            return {
                 status: "conflict",
-                detail: "The existing 'ast' registration does not expose the expected structural tools.",
+                detail: "The existing 'ast' registration cannot be authenticated as this package.",
             };
+        }
+        const guardStatus = structuredGuardStatus(registration.env);
+        const admittedKeys = guardStatus === "repairable" ? ["args", "command"] : ["args", "command", "env"];
+        if (guardStatus === "conflict" ||
+            Object.keys(registration).sort().join(",") !== admittedKeys.join(",")) {
+            return {
+                status: "conflict",
+                detail: "The existing 'ast' registration has unsupported configuration.",
+            };
+        }
+        const tested = await runtime.run(["mcp", "test", MCP_SERVER_NAME]);
+        const expectedWithoutApply = EXPECTED_TOOLS.filter((tool) => tool !== APPLY_TOOL);
+        if (tested.exitCode === 0 &&
+            expectedWithoutApply.every((tool) => tested.stdout.includes(tool))) {
+            const applyPresent = !EXPECTED_TOOLS.includes(APPLY_TOOL) || tested.stdout.includes(APPLY_TOOL);
+            return guardStatus === "current" && applyPresent
+                ? { status: "current" }
+                : guardStatus === "repairable" && !tested.stdout.includes(APPLY_TOOL)
+                    ? { status: "repairable" }
+                    : {
+                        status: "conflict",
+                        detail: "The existing 'ast' registration tool surface contradicts its configuration.",
+                    };
+        }
+        return {
+            status: "conflict",
+            detail: "The existing 'ast' registration does not expose the expected structural tools.",
+        };
     },
-    register: (runtime, context) => runtime.run([
+    register: (runtime, context) => hermesRegister(runtime, context, true),
+    unregister: (runtime) => runtime.run(["mcp", "remove", MCP_SERVER_NAME]),
+    registerLegacy: (runtime, context) => hermesRegister(runtime, context, false),
+    registrationAccepted: (result) => result.exitCode === 0 && /saved\s+'ast'/i.test(result.stdout),
+    removalAccepted: (result) => result.exitCode === 0,
+};
+function separatorRegister(runtime, context, guarded) {
+    return runtime.run([
         "mcp",
         "add",
         MCP_SERVER_NAME,
-        "--command",
+        ...(guarded ? ["--env", APPLY_GUARD_ALLOW_ENV] : []),
+        "--",
         context.nodeExecutable,
-        "--args",
         context.serverEntryPath,
-    ], "\n"),
-    registrationAccepted: (result) => result.exitCode === 0 && /saved\s+'ast'/i.test(result.stdout),
-};
+    ]);
+}
 const codexMcp = {
     async inspect(runtime, context) {
         return structuredInspection(await runtime.run(["mcp", "get", MCP_SERVER_NAME, "--json"]), context);
     },
-    register: (runtime, context) => runtime.run([
-        "mcp",
-        "add",
-        MCP_SERVER_NAME,
-        "--",
-        context.nodeExecutable,
-        context.serverEntryPath,
-    ]),
+    register: (runtime, context) => separatorRegister(runtime, context, true),
+    unregister: (runtime) => runtime.run(["mcp", "remove", MCP_SERVER_NAME]),
+    registerLegacy: (runtime, context) => separatorRegister(runtime, context, false),
     registrationAccepted: (result) => result.exitCode === 0,
+    removalAccepted: (result) => result.exitCode === 0,
 };
 const copilotMcp = {
     async inspect(runtime, context) {
         return copilotStructuredInspection(await runtime.run(["mcp", "get", MCP_SERVER_NAME, "--json"]), context);
     },
-    register: (runtime, context) => runtime.run([
+    register: (runtime, context) => separatorRegister(runtime, context, true),
+    unregister: (runtime) => runtime.run(["mcp", "remove", MCP_SERVER_NAME]),
+    registerLegacy: (runtime, context) => separatorRegister(runtime, context, false),
+    registrationAccepted: (result) => result.exitCode === 0,
+    removalAccepted: (result) => result.exitCode === 0,
+};
+function geminiRegister(runtime, context, guarded) {
+    return runtime.run([
         "mcp",
         "add",
         MCP_SERVER_NAME,
-        "--",
+        ...(guarded ? ["--env", APPLY_GUARD_ALLOW_ENV] : []),
         context.nodeExecutable,
         context.serverEntryPath,
-    ]),
-    registrationAccepted: (result) => result.exitCode === 0,
-};
+        "--scope",
+        "user",
+    ]);
+}
 const geminiMcp = {
     async inspect(runtime, context) {
         const result = await runtime.run(["mcp", "list"]);
@@ -187,23 +281,24 @@ const geminiMcp = {
         const match = result.stdout.match(pattern);
         if (!match)
             return { status: "error", operation: "MCP inspection", result };
-        return expected(context, match[1]?.trim(), match[2]?.split(",").map((item) => item.trim()))
-            ? { status: "current" }
-            : {
+        const matches = expected(context, match[1]?.trim(), match[2]?.split(",").map((item) => item.trim()));
+        const inspection = matchingRegistration(matches, /(?:^|\s|,)AST_MCP_APPLY_GUARD\s*=\s*allow(?:\s|$|,)/m.test(result.stdout)
+            ? "current"
+            : /\benv(?:ironment)?\s*:/i.test(result.stdout)
+                ? "conflict"
+                : "repairable");
+        return inspection.status === "conflict"
+            ? {
                 status: "conflict",
                 detail: "The existing Gemini 'ast' registration does not match this package.",
-            };
+            }
+            : inspection;
     },
-    register: (runtime, context) => runtime.run([
-        "mcp",
-        "add",
-        MCP_SERVER_NAME,
-        context.nodeExecutable,
-        context.serverEntryPath,
-        "--scope",
-        "user",
-    ]),
+    register: (runtime, context) => geminiRegister(runtime, context, true),
+    unregister: (runtime) => runtime.run(["mcp", "remove", MCP_SERVER_NAME, "--scope", "user"]),
+    registerLegacy: (runtime, context) => geminiRegister(runtime, context, false),
     registrationAccepted: (result) => result.exitCode === 0,
+    removalAccepted: (result) => result.exitCode === 0,
 };
 const opencodeMcp = {
     async inspect() {
@@ -220,7 +315,14 @@ const opencodeMcp = {
     async register() {
         return { exitCode: 1, stdout: "", stderr: "OpenCode CLI registration is disabled." };
     },
+    async unregister() {
+        return { exitCode: 1, stdout: "", stderr: "OpenCode CLI removal is disabled." };
+    },
+    async registerLegacy() {
+        return { exitCode: 1, stdout: "", stderr: "OpenCode CLI registration is disabled." };
+    },
     registrationAccepted: () => false,
+    removalAccepted: () => false,
 };
 export const AGENT_TARGETS = [
     { id: "claude", label: "Claude Code", command: "claude", skillTarget: "claude", mcp: claudeMcp },

package/dist/services/compiler-worker-host.js

@@ -4,8 +4,9 @@ import { randomUUID } from "node:crypto";
 import { createInterface } from "node:readline";
 import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
-import { decodeCompilerWorkerEnvelope, startCompilerWorker } from "./compiler-worker-protocol.js";
-import { createCompilerWorkerSpawnSpec, readRuntimePolicy, } from "./runtime-policy.js";
+import { COMPILER_WORKER_MAX_FRAME_BYTES, decodeCompilerWorkerEnvelope, decodeCompilerWorkerResponse, isCompilerWorkerRequestIdWithinBudget, startCompilerWorker, } from "./compiler-worker-protocol.js";
+import { emitConfiguredH03HostEvent } from "./h03-timeout-fixture.js";
+import { createCompilerWorkerSpawnSpec, parseH03FixtureDescriptor, parseH05FixtureDescriptor, readRuntimePolicy, } from "./runtime-policy.js";
 import { emitCompilerWorkerEvent } from "./runtime-logger.js";
 import { PublicOperationalError, renderPublicError } from "./public-errors.js";
 export class CompilerWorkerHostError extends Error {
@@ -17,7 +18,7 @@ export class CompilerWorkerHostError extends Error {
         this.recovery = recovery;
     }
 }
-const bounded = (value) => Buffer.byteLength(JSON.stringify(value)) <= 256 * 1024;
+const bounded = (value) => Buffer.byteLength(JSON.stringify(value)) <= COMPILER_WORKER_MAX_FRAME_BYTES;
 const within = (promise, ms) => Promise.race([
     promise,
     delay(ms, undefined, { ref: false }).then(() => {
@@ -34,7 +35,11 @@ function deferred() {
     return { promise, resolve, reject };
 }
 export function spawnCompilerWorkerProcess(options) {
-    const spec = createCompilerWorkerSpawnSpec(options.workerEntryPath, options.environment);
+    const fixture = parseH03FixtureDescriptor(options.environment.AST_H03_FIXTURE);
+    const lifecycleFixture = parseH05FixtureDescriptor(options.environment.AST_H05_FIXTURE);
+    // prettier-ignore
+    const environment = fixture || lifecycleFixture ? { ...options.environment, ...(fixture ? { AST_H03_FIXTURE: JSON.stringify({ ...fixture, generation: options.generation }) } : {}), ...(lifecycleFixture ? { AST_H05_FIXTURE: JSON.stringify({ ...lifecycleFixture, generation: options.generation }) } : {}) } : options.environment;
+    const spec = createCompilerWorkerSpawnSpec(options.workerEntryPath, environment);
     if (!spec.ok || !spec.command)
         throw new CompilerWorkerHostError("startup");
     const child = spawn(spec.command, spec.args, {
@@ -86,17 +91,12 @@ export function spawnCompilerWorkerProcess(options) {
             snapshots.shift()?.resolve(decoded.value);
     });
     createInterface({ input: child.stdout }).on("line", (line) => {
-        if (Buffer.byteLength(line) > 256 * 1024)
+        const decoded = decodeCompilerWorkerResponse(line);
+        if (!decoded.ok)
             return fail(new CompilerWorkerHostError("protocol"));
-        let message;
-        try {
-            message = JSON.parse(line);
-        }
-        catch {
-            return fail(new CompilerWorkerHostError("protocol"));
-        }
-        if (!("id" in message) || message.id === undefined)
+        if (decoded.kind === "notification")
             return;
+        const message = decoded.value;
         const request = pending.get(message.id);
         if (!request)
             return;
@@ -108,7 +108,10 @@ export function spawnCompilerWorkerProcess(options) {
         });
     });
     const write = (message, acknowledge = false) => {
-        if (!bounded(message) || !child.stdin?.writable)
+        const requestIdWithinBudget = !("id" in message) ||
+            message.id === undefined ||
+            isCompilerWorkerRequestIdWithinBudget(message.id);
+        if (!requestIdWithinBudget || !bounded(message) || !child.stdin?.writable)
             return Promise.reject(new CompilerWorkerHostError("protocol"));
         options.beforeWrite?.(message);
         const writeSequence = ++writes, processed = acknowledge ? deferred() : undefined;
@@ -217,7 +220,7 @@ export class CompilerWorkerHost {
         return this.scheduleIdle(); this.parentAdmission = "closed"; const second = await child.snapshot(); if (child !== this.child || generation !== this.generation || sequence !== this.sequence || activity !== this.activity || !CompilerWorkerHost.quiescent(second)) {
         this.parentAdmission = "open";
         return this.scheduleIdle();
-    } await this.stopChild(child, "requested"); emitCompilerWorkerEvent({ kind: "idle", generation }); this.parentAdmission = "open"; }
+    } await this.stopChild(child, "requested"); emitCompilerWorkerEvent({ kind: "idle", generation }); emitConfiguredH03HostEvent("recycled", generation); this.parentAdmission = "open"; }
     // prettier-ignore
     async stopChild(child, trigger) { const completion = child.shutdown(trigger); try {
         await within(completion, this.timeoutMs);
@@ -412,7 +415,24 @@ export async function runSupervisedStdioServer() {
                 const rendered = ambiguous
                     ? renderPublicError(new PublicOperationalError("AMBIGUOUS_APPLY", "The apply outcome is ambiguous."), ambiguous.correlation_id).envelope.error
                     : undefined;
-                process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, error: { code: -32603, message: rendered?.message ?? "Compiler worker request failed.", ...(ambiguous ? { data: { code: "AMBIGUOUS_APPLY", ...ambiguous } } : {}) } })}\n`);
+                const responseId = isCompilerWorkerRequestIdWithinBudget(message.id) ? message.id : null;
+                const candidate = {
+                    jsonrpc: "2.0",
+                    id: responseId,
+                    error: {
+                        code: -32603,
+                        message: rendered?.message ?? "Compiler worker request failed.",
+                        ...(ambiguous ? { data: { code: "AMBIGUOUS_APPLY", ...ambiguous } } : {}),
+                    },
+                };
+                const response = bounded(candidate)
+                    ? candidate
+                    : {
+                        jsonrpc: "2.0",
+                        id: null,
+                        error: { code: -32603, message: "Compiler worker request failed." },
+                    };
+                process.stdout.write(`${JSON.stringify(response)}\n`);
             }
         }
     };

package/dist/services/compiler-worker-protocol.js

@@ -1,11 +1,79 @@
 import { Buffer } from "node:buffer";
+export const COMPILER_WORKER_MAX_FRAME_BYTES = 256 * 1024;
+export const COMPILER_WORKER_MAX_REQUEST_ID_BYTES = 8 * 1024;
+export const COMPILER_WORKER_JSONRPC_ENVELOPE_RESERVE_BYTES = 16 * 1024;
+export const COMPILER_WORKER_MAX_RESULT_BYTES = COMPILER_WORKER_MAX_FRAME_BYTES - COMPILER_WORKER_JSONRPC_ENVELOPE_RESERVE_BYTES;
 const FIELDS = new Set(["v", "generation", "sequence", "type", "payload"]);
 const TYPES = new Set(["handshake", "snapshot", "shutdown", "ready", "settled", "lease", "exit"]);
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+export function isCompilerWorkerRequestIdWithinBudget(id) {
+    try {
+        return Buffer.byteLength(JSON.stringify(id)) <= COMPILER_WORKER_MAX_REQUEST_ID_BYTES;
+    }
+    catch {
+        return false;
+    }
+}
+export function fitsCompilerWorkerResponseResult(result) {
+    try {
+        const frame = JSON.stringify({
+            jsonrpc: "2.0",
+            id: "x".repeat(COMPILER_WORKER_MAX_REQUEST_ID_BYTES - 2),
+            result,
+        });
+        return Buffer.byteLength(frame) <= COMPILER_WORKER_MAX_FRAME_BYTES;
+    }
+    catch {
+        return false;
+    }
+}
+export function decodeCompilerWorkerResponse(frame) {
+    if (Buffer.byteLength(frame) > COMPILER_WORKER_MAX_FRAME_BYTES) {
+        return { ok: false, reason: "oversized" };
+    }
+    let value;
+    try {
+        value = JSON.parse(frame);
+    }
+    catch {
+        return { ok: false, reason: "malformed" };
+    }
+    if (!isRecord(value) || value.jsonrpc !== "2.0") {
+        return { ok: false, reason: "invalid_response" };
+    }
+    if (Object.hasOwn(value, "method") && !Object.hasOwn(value, "id")) {
+        if (typeof value.method !== "string" ||
+            Object.keys(value).some((key) => !["jsonrpc", "method", "params"].includes(key))) {
+            return { ok: false, reason: "invalid_notification" };
+        }
+        return { ok: true, kind: "notification", value };
+    }
+    if (Object.keys(value).some((key) => !["jsonrpc", "id", "result", "error"].includes(key))) {
+        return { ok: false, reason: "unknown_field" };
+    }
+    if (!(typeof value.id === "string" || typeof value.id === "number") ||
+        !isCompilerWorkerRequestIdWithinBudget(value.id)) {
+        return { ok: false, reason: "invalid_id" };
+    }
+    const hasResult = Object.hasOwn(value, "result");
+    const hasError = Object.hasOwn(value, "error");
+    if (hasResult === hasError)
+        return { ok: false, reason: "invalid_response" };
+    if (hasError) {
+        const error = value.error;
+        if (!isRecord(error) ||
+            typeof error.code !== "number" ||
+            !Number.isSafeInteger(error.code) ||
+            typeof error.message !== "string") {
+            return { ok: false, reason: "invalid_error" };
+        }
+    }
+    return { ok: true, kind: "response", value };
+}
 export function decodeCompilerWorkerEnvelope(frame) {
-    if (Buffer.byteLength(frame) > 256 * 1024) {
+    if (Buffer.byteLength(frame) > COMPILER_WORKER_MAX_FRAME_BYTES) {
         return { ok: false, reason: "oversized" };
     }
     let value;
@@ -47,7 +115,7 @@ export function validateInitializationReplay(frames) {
         "id" in notification) {
         return { ok: false, reason: "missing_replay" };
     }
-    if (Buffer.byteLength(JSON.stringify(frames)) > 256 * 1024) {
+    if (Buffer.byteLength(JSON.stringify(frames)) > COMPILER_WORKER_MAX_FRAME_BYTES) {
         return { ok: false, reason: "oversized_replay" };
     }
     return { ok: true, frames: [request, notification] };