mcp-fs-shell-windows 0.2.20 → 0.2.29

package/dist/browser/handler.js

@@ -0,0 +1,227 @@
+import { validatePath } from "../helpers/path.js";
+import { launchBrowser, closeBrowserQuiet } from "./launcher.js";
+import { closeSession, getSession, setSession } from "./session.js";
+import { executeBrowserActions } from "./browserActions.js";
+import { rankFuzzyMatches } from "./fuzzySearch.js";
+// In-page candidate collection for fuzzy find (ported from the Beledarian
+// reference): interactive + text nodes, deduped on (text||selector), capped
+// at 400 candidates. Runs inside the page context.
+const collectFuzzyCandidates = (page) => page.evaluate(() => {
+    const dedup = new Map();
+    const nodes = document.querySelectorAll("a,button,input,textarea,select,[role='button'],[aria-label],h1,h2,h3,h4,h5,h6,p,span");
+    const clean = (value) => value.replace(/\s+/g, " ").trim();
+    const classSelector = (el) => {
+        const classes = Array.from(el.classList).slice(0, 2).map(c => c.replace(/[^a-zA-Z0-9_-]/g, ""));
+        return classes.length > 0 ? `.${classes.join(".")}` : "";
+    };
+    const buildSelector = (el) => {
+        if (el.id)
+            return `#${el.id}`;
+        const name = el.getAttribute("name");
+        if (name)
+            return `${el.tagName.toLowerCase()}[name="${name.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"]`;
+        return `${el.tagName.toLowerCase()}${classSelector(el)}`;
+    };
+    for (const node of nodes) {
+        const element = node;
+        const text = clean(element.innerText ||
+            element.value ||
+            element.getAttribute("aria-label") ||
+            "");
+        if (!text)
+            continue;
+        const selector = buildSelector(element);
+        const key = `${text}||${selector}`;
+        if (!dedup.has(key)) {
+            dedup.set(key, { text: text.substring(0, 200), selector });
+        }
+        if (dedup.size >= 400)
+            break;
+    }
+    return Array.from(dedup.values());
+});
+// browser_session_open: launch (replacing any existing session), navigate,
+// optionally wait for a selector, and optionally return full page text.
+export async function handleBrowserSessionOpen(url, waitForSelector, includePageText) {
+    try {
+        if (getSession()) {
+            await closeSession();
+        }
+        const browser = await launchBrowser();
+        const page = await browser.newPage();
+        try {
+            await page.goto(url, { waitUntil: "networkidle0", timeout: 30000 });
+            if (waitForSelector) {
+                await page.waitForSelector(waitForSelector, { timeout: 15000 });
+            }
+        }
+        catch (error) {
+            await closeBrowserQuiet(browser);
+            throw error;
+        }
+        setSession({ browser, page, currentUrl: page.url() });
+        const pageText = includePageText !== false
+            ? await page.evaluate(() => document.body.innerText || "")
+            : undefined;
+        return JSON.stringify({
+            success: true,
+            session_active: true,
+            url: page.url(),
+            title: await page.title(),
+            text_content: pageText,
+            text_length: pageText ? pageText.length : 0,
+            message: "Browser session opened.",
+        });
+    }
+    catch (error) {
+        return JSON.stringify({
+            error: `Failed to open browser session: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}
+// browser_session_control: run actions on the active page, optionally capture
+// a screenshot, return page metadata (full text only on URL change or with
+// full_read), and optionally fuzzy-find in-page text/selectors.
+export async function handleBrowserSessionControl(args, allowedDirectories) {
+    const session = getSession();
+    if (!session) {
+        return JSON.stringify({
+            error: "No active browser session. Call 'browser_session_open' first.",
+        });
+    }
+    try {
+        const beforeUrl = session.page.url();
+        const actionLog = await executeBrowserActions(session.page, args.actions || []);
+        const afterUrl = session.page.url();
+        const urlChanged = beforeUrl !== afterUrl;
+        session.currentUrl = afterUrl;
+        let screenshotSaved = false;
+        if (args.screenshot_path) {
+            const screenshotFilePath = await validatePath(args.screenshot_path, allowedDirectories);
+            await session.page.screenshot({ path: screenshotFilePath, fullPage: args.full_page_screenshot ?? false });
+            screenshotSaved = true;
+        }
+        let pageSnapshot = undefined;
+        if (args.read_page !== false) {
+            const title = await session.page.title();
+            if (urlChanged || args.full_read) {
+                const textContent = await session.page.evaluate(() => document.body.innerText || "");
+                pageSnapshot = {
+                    url: afterUrl,
+                    title,
+                    text_content: textContent,
+                    text_length: textContent.length,
+                };
+            }
+            else {
+                pageSnapshot = {
+                    url: afterUrl,
+                    title,
+                    note: "Full page text omitted (URL unchanged). Set full_read=true to force full output.",
+                };
+            }
+        }
+        let fuzzyResults = [];
+        if (typeof args.fuzzy_find === "string" && args.fuzzy_find.trim()) {
+            const query = args.fuzzy_find;
+            const candidates = await collectFuzzyCandidates(session.page);
+            const ranked = candidates
+                .map(candidate => ({
+                ...candidate,
+                score: Math.max(rankFuzzyMatches(query, [candidate.text], 1)[0]?.score ?? 0, rankFuzzyMatches(query, [candidate.selector], 1)[0]?.score ?? 0),
+            }))
+                .sort((a, b) => b.score - a.score)
+                .slice(0, args.max_results ?? 5);
+            fuzzyResults = ranked.map(item => ({
+                text: item.text,
+                selector: item.selector,
+                score: item.score,
+            }));
+        }
+        return JSON.stringify({
+            success: true,
+            session_active: true,
+            actions_executed: actionLog,
+            screenshot_saved: screenshotSaved,
+            url_changed: urlChanged,
+            url_change_notice: urlChanged ? `Url changed to -> [${afterUrl}]` : undefined,
+            page: pageSnapshot,
+            fuzzy_find_results: fuzzyResults,
+        });
+    }
+    catch (error) {
+        return JSON.stringify({
+            error: `Browser session control failed: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}
+// browser_session_close: tear down the active session (idempotent).
+export async function handleBrowserSessionClose() {
+    if (!getSession()) {
+        return JSON.stringify({
+            success: true,
+            session_active: false,
+            message: "No active browser session.",
+        });
+    }
+    try {
+        await closeSession();
+        return JSON.stringify({
+            success: true,
+            session_active: false,
+            message: "Browser session closed.",
+        });
+    }
+    catch (error) {
+        return JSON.stringify({
+            error: `Failed to close browser session: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}
+// browser_open_page: stateless one-shot render (own browser instance, always
+// closed on return; never touches the persistent session).
+export async function handleBrowserOpenPage(args, allowedDirectories) {
+    let browser;
+    try {
+        browser = await launchBrowser();
+        const page = await browser.newPage();
+        try {
+            await page.goto(args.url, { waitUntil: "networkidle0", timeout: 30000 });
+            if (args.wait_for_selector) {
+                await page.waitForSelector(args.wait_for_selector, { timeout: 10000 });
+            }
+            const beforeActionUrl = page.url();
+            const actionLog = await executeBrowserActions(page, args.actions || []);
+            const currentUrl = page.url();
+            const urlChanged = currentUrl !== beforeActionUrl;
+            const title = await page.title();
+            const textContent = await page.evaluate(() => document.body.innerText || "");
+            let screenshotSaved = false;
+            if (args.screenshot_path) {
+                const screenshotFilePath = await validatePath(args.screenshot_path, allowedDirectories);
+                await page.screenshot({ path: screenshotFilePath, fullPage: args.full_page_screenshot ?? false });
+                screenshotSaved = true;
+            }
+            return JSON.stringify({
+                url: currentUrl,
+                title,
+                text_content: textContent.substring(0, 5000),
+                screenshot_saved: screenshotSaved,
+                actions_executed: actionLog,
+                url_changed: urlChanged,
+                url_change_notice: urlChanged ? `Url changed to -> [${currentUrl}]` : undefined,
+            });
+        }
+        finally {
+            await closeBrowserQuiet(browser);
+        }
+    }
+    catch (error) {
+        if (browser) {
+            await closeBrowserQuiet(browser);
+        }
+        return JSON.stringify({
+            error: `Browser operation failed: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}

package/dist/browser/launcher.js

@@ -0,0 +1,103 @@
+import fs from "fs";
+import nodePath from "path";
+import os from "os";
+// Chrome-for-Testing build 142.0.7444.175, preinstalled at
+// C:\Users\Gerar\.cache\puppeteer (installed for the Beledarian browser tools;
+// pairs with puppeteer 24.31). puppeteer-core is a pure-JS dependency (no
+// browser download); ALL browser launches in this repo go through this single
+// module so web_search's browser legs (duckduckgo-html / google / bing) and
+// the browser_session_* / browser_open_page tools share one launcher:
+//
+//   * getSharedBrowser / closeSharedBrowser - the web_search shared browser
+//     (module-level; one search call reuses a single instance across legs and
+//     each leg closes it afterwards).
+//   * launchBrowser - a fresh standalone instance (used by the persistent
+//     browser session and the stateless browser_open_page one-shot).
+//
+// The persistent session (browser/session.ts) deliberately holds its OWN
+// browser instance so web_search legs can never close it mid-session.
+//
+// Executable resolution (v0.2.29 publish portability):
+//   1. env MCP_CHROME_PATH (explicit; must exist)
+//   2. the standard puppeteer cache <home>/.cache/puppeteer/chrome/<build>/,
+//      highest version wins (e.g. win64-142.0.7444.175/chrome-win64/chrome.exe)
+//   3. the legacy hardcoded path (the reference machine's preinstall)
+export const CHROME_PATH = "C:\\Users\\Gerar\\.cache\\puppeteer\\chrome\\win64-142.0.7444.175\\chrome-win64\\chrome.exe";
+// Compare two "win64-<a.b.c.d>" build dirs numerically (ascending).
+function compareBuildDirs(a, b) {
+    const pa = a.replace(/^win64-/, "").split(".").map((n) => parseInt(n, 10) || 0);
+    const pb = b.replace(/^win64-/, "").split(".").map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pb[i] || 0) - (pa[i] || 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+// Resolve the Chrome-for-Testing executable (null when nothing is found).
+export function resolveChromePath() {
+    const env = process.env.MCP_CHROME_PATH;
+    if (env && fs.existsSync(env))
+        return env;
+    const base = nodePath.join(os.homedir(), ".cache", "puppeteer", "chrome");
+    if (fs.existsSync(base)) {
+        const builds = fs
+            .readdirSync(base, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && e.name.startsWith("win64-"))
+            .map((e) => e.name)
+            .sort(compareBuildDirs);
+        for (let i = builds.length - 1; i >= 0; i--) {
+            const p = nodePath.join(base, builds[i], "chrome-win64", "chrome.exe");
+            if (fs.existsSync(p))
+                return p;
+        }
+    }
+    if (fs.existsSync(CHROME_PATH))
+        return CHROME_PATH;
+    return null;
+}
+const LAUNCH_ARGS = ["--no-sandbox", "--disable-setuid-sandbox"];
+// Launch a fresh headless browser with the standard options.
+export const launchBrowser = async () => {
+    const puppeteer = await import("puppeteer-core");
+    const chromePath = resolveChromePath();
+    if (!chromePath) {
+        throw new Error("No Chrome-for-Testing executable found. Set MCP_CHROME_PATH to the path of chrome.exe, " +
+            `or install a build under ${nodePath.join(os.homedir(), ".cache", "puppeteer", "chrome")} ` +
+            "(standard layout: win64-<version>/chrome-win64/chrome.exe).");
+    }
+    return puppeteer.launch({
+        headless: true,
+        executablePath: chromePath,
+        args: LAUNCH_ARGS,
+    });
+};
+// Close a browser, swallowing already-closed errors.
+export const closeBrowserQuiet = async (browser) => {
+    try {
+        await browser.close();
+    }
+    catch {
+        // already closed
+    }
+};
+let sharedBrowser = null;
+// Shared browser used by the web_search browser legs. Lazily launched so a
+// missing browser never breaks the non-puppeteer legs (errors surface per
+// provider and are collected, not fatal).
+export const getSharedBrowser = async () => {
+    if (!sharedBrowser) {
+        sharedBrowser = await launchBrowser();
+    }
+    return sharedBrowser;
+};
+// Close and drop the shared browser so a later provider can relaunch cleanly
+// (the reference kept a stale closed instance; nulling here is strictly safer
+// for manual multi-provider mode).
+export const closeSharedBrowser = async () => {
+    if (sharedBrowser) {
+        const browser = sharedBrowser;
+        sharedBrowser = null;
+        await closeBrowserQuiet(browser);
+    }
+};

package/dist/browser/schema.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+// Shared actions schema: scripted browser steps executed in order on a page.
+// (Ported from the Beledarian reference; per-action required fields are
+// enforced at execution time by executeBrowserActions with clear errors.)
+export const BrowserActionSchema = z.object({
+    type: z.enum(["wait_for_selector", "wait", "click", "type", "press", "select", "hover", "scroll", "evaluate"]),
+    selector: z.string().optional().describe("CSS selector used by selector-based actions."),
+    text: z.string().optional().describe("Text payload for type action."),
+    value: z.string().optional().describe("Value payload for select action."),
+    key: z.string().optional().describe("Keyboard key for press action (e.g., Enter, Tab)."),
+    milliseconds: z.number().int().min(0).max(30000).optional().describe("Delay in milliseconds for wait action."),
+    x: z.number().optional().describe("Horizontal scroll delta for scroll action."),
+    y: z.number().optional().describe("Vertical scroll delta for scroll action."),
+    script: z.string().optional().describe("JavaScript snippet for evaluate action (executed in page context)."),
+});
+export const BrowserSessionOpenArgsSchema = z.object({
+    url: z.string(),
+    wait_for_selector: z.string().optional().describe("Optional selector to wait for after navigation."),
+    include_page_text: z.boolean().optional().describe("If true (default), returns full page text content after opening."),
+});
+export const BrowserSessionControlArgsSchema = z.object({
+    actions: z.array(BrowserActionSchema).optional().describe("Optional scripted browser actions to execute on the active page."),
+    read_page: z.boolean().optional().describe("If true (default), returns page metadata. Full text is returned only on URL change or when full_read=true."),
+    full_read: z.boolean().optional().describe("If true, forces full page text output even when URL has not changed."),
+    screenshot_path: z.string().optional().describe("Optional screenshot output path (must be within an allowed directory)."),
+    full_page_screenshot: z.boolean().optional().describe("If true, captures full page screenshot."),
+    fuzzy_find: z.string().optional().describe("Optional fuzzy-find query for in-page content/selectors."),
+    max_results: z.number().int().min(1).max(20).optional().describe("Max fuzzy results to return (default: 5)."),
+});
+export const BrowserSessionCloseArgsSchema = z.object({});
+export const BrowserOpenPageArgsSchema = z.object({
+    url: z.string(),
+    screenshot_path: z.string().optional().describe("Path to save a screenshot (e.g., 'screenshot.png'); must be within an allowed directory."),
+    wait_for_selector: z.string().optional().describe("CSS selector to wait for before returning."),
+    full_page_screenshot: z.boolean().optional().describe("If true, captures the full page when taking a screenshot."),
+    actions: z.array(BrowserActionSchema).optional().describe("Optional scripted browser steps to run after navigation."),
+});

package/dist/browser/session.js

@@ -0,0 +1,14 @@
+import { closeBrowserQuiet } from "./launcher.js";
+let session = null;
+export const getSession = () => session;
+export const setSession = (s) => {
+    session = s;
+};
+// Close the active session's browser and drop the state. No-op when none.
+export const closeSession = async () => {
+    if (session) {
+        const s = session;
+        session = null;
+        await closeBrowserQuiet(s.browser);
+    }
+};

package/dist/compat/handler.js

@@ -0,0 +1,254 @@
+// compat/handler.ts — Beledarian-compatible alias handlers (MCP filesystem fork v0.2.28).
+//
+// Reference: .beledarians-llm-toolbox/dev-src/beledarians-lm-studio-tools/src/toolsProvider.ts.
+// Every handler either delegates to the fork's own tool handler (so behavior and
+// job-registry lifetime are identical) or reuses the fork's shell-layer spawn
+// machinery (runCaptured + cap) with Beledarian's 60 s timeout cap, so existing
+// prompts that pass timeout_seconds up to 60 behave exactly as under Beledarian.
+//
+// Deliberate deviations (documented per the task spec):
+//   * execute_command / run_python / run_javascript keep Beledarian's 60 s cap
+//     (the fork's native shell_* tools cap at 28 s). Same bounded synchronous
+//     semantics, same cmd.exe /d /c verbatim spawn path.
+//   * save_memory has NO enable gate (the fork has no such setting); the memory
+//     file path = env MCP_MEMORY_FILE if set, else the Beledarian workspace
+//     memory.md, created with a '# Long-Term Memory' header if missing.
+//   * run_javascript env = { ...process.env, NO_COLOR: "true" } (Beledarian's
+//     reference passed only NO_COLOR, which strips PATH; spreading process.env
+//     keeps the confined Deno spawn robust and matches run_javascript_free).
+import fsp from "fs/promises";
+import fs from "fs";
+import nodePath from "path";
+import crypto from "crypto";
+import { cap, CAP_OK, CAP_ERR, SHELL_JOBS_DIR, ensureJobsDir, resolveCwd, runCaptured, handleShellTest, handleShellStart, handleShellCheck, handleShellCancel, handleShellTerminal, } from "../shell/handler.js";
+import { resolveDenoPath } from "../run_javascript/handler.js";
+import { COMPAT_SYNC_TIMEOUT_SEC } from "./schema.js";
+// ---------------------------------------------------------------------------
+// execute_command — bounded synchronous execution (alias of shell_run, 60 s cap)
+// Mirrors handleShellRun exactly (cmd.exe /d /c, verbatim, stdin pipe) with
+// Beledarian's 60 s cap and the same result shape: {command, exitCode, stdout,
+// stderr, timedOut, duration_ms, cwd}; non-zero exit / timeout throw with the
+// captured output embedded (callTool turns that into isError content).
+// ---------------------------------------------------------------------------
+export async function handleExecuteCommand(command, input, timeoutSeconds) {
+    const abs = await resolveCwd();
+    const timeout = Math.min(Math.max(timeoutSeconds ?? 5, 0.1), COMPAT_SYNC_TIMEOUT_SEC);
+    const started = Date.now();
+    const r = await runCaptured("cmd.exe", ["/d", "/c", command], {
+        cwd: abs,
+        input,
+        timeoutMs: timeout * 1000,
+        verbatim: true,
+    });
+    const durationMs = Date.now() - started;
+    if (r.spawnError) {
+        throw new Error(`Failed to launch command: ${r.spawnError}`);
+    }
+    if (r.timedOut) {
+        throw new Error(`Process timed out after ${timeout}s.\nSTDOUT:\n${cap(r.stdout, CAP_ERR)}\nSTDERR:\n${cap(r.stderr, CAP_ERR)}`);
+    }
+    if (r.code !== 0) {
+        throw new Error(`Process exited with code ${r.code ?? "unknown"}.\nSTDOUT:\n${cap(r.stdout, CAP_ERR)}\nSTDERR:\n${cap(r.stderr, CAP_ERR)}`);
+    }
+    return JSON.stringify({
+        command,
+        exitCode: 0,
+        stdout: cap(r.stdout, CAP_OK),
+        stderr: cap(r.stderr, CAP_OK),
+        timedOut: false,
+        duration_ms: durationMs,
+        cwd: abs,
+    });
+}
+// ---------------------------------------------------------------------------
+// run_in_terminal — delegates to shell_terminal (visible cmd /k console window).
+// Returns the shell_terminal job JSON (including the job id; kill via
+// shell_cancel / cancel_background_command).
+// ---------------------------------------------------------------------------
+export async function handleRunInTerminal(command) {
+    return handleShellTerminal(command);
+}
+// ---------------------------------------------------------------------------
+// run_test_command — delegates to shell_test ({command, exit_code, stdout,
+// stderr, passed}; never errors on a failing test; CI=true).
+// ---------------------------------------------------------------------------
+export async function handleRunTestCommand(command) {
+    return handleShellTest(command);
+}
+// ---------------------------------------------------------------------------
+// run_background_command — delegates to shell_start. Job ids live in the fork's
+// per-process registry (same lifetime semantics as Beledarian's per-process
+// backgroundCommands Map). name is required (as in Beledarian); timeout_hours
+// defaults to 10 (max 10).
+// ---------------------------------------------------------------------------
+export async function handleRunBackgroundCommand(command, name, timeoutHours, cwd) {
+    return handleShellStart(command, name, timeoutHours, cwd);
+}
+// ---------------------------------------------------------------------------
+// check_background_command — delegates to shell_check.
+// ---------------------------------------------------------------------------
+export async function handleCheckBackgroundCommand(id) {
+    return handleShellCheck(id);
+}
+// ---------------------------------------------------------------------------
+// cancel_background_command — delegates to shell_cancel (kills the whole tree).
+// ---------------------------------------------------------------------------
+export async function handleCancelBackgroundCommand(id) {
+    return handleShellCancel(id);
+}
+// ---------------------------------------------------------------------------
+// run_python — temp .py + system python (alias of shell_python, 60 s cap).
+// Mirrors handleShellPython exactly (temp file in the shell-jobs dir, deleted
+// in finally) with Beledarian's 60 s cap.
+// ---------------------------------------------------------------------------
+export async function handleRunPython(code, timeoutSeconds, cwd) {
+    const abs = await resolveCwd(cwd);
+    await ensureJobsDir();
+    const file = nodePath.join(SHELL_JOBS_DIR, `py-${Date.now().toString(36)}-${crypto.randomBytes(3).toString("hex")}.py`);
+    await fsp.writeFile(file, code, "utf-8");
+    const timeout = Math.min(Math.max(timeoutSeconds ?? 5, 0.1), COMPAT_SYNC_TIMEOUT_SEC);
+    const started = Date.now();
+    try {
+        const r = await runCaptured("python", [file], {
+            cwd: abs,
+            timeoutMs: timeout * 1000,
+        });
+        const durationMs = Date.now() - started;
+        if (r.spawnError) {
+            throw new Error(`Failed to launch python: ${r.spawnError}`);
+        }
+        if (r.timedOut) {
+            throw new Error(`Process timed out after ${timeout}s.\nSTDOUT:\n${cap(r.stdout, CAP_ERR)}\nSTDERR:\n${cap(r.stderr, CAP_ERR)}`);
+        }
+        if (r.code !== 0) {
+            throw new Error(`Process exited with code ${r.code ?? "unknown"}.\nSTDOUT:\n${cap(r.stdout, CAP_ERR)}\nSTDERR:\n${cap(r.stderr, CAP_ERR)}`);
+        }
+        return JSON.stringify({
+            exitCode: 0,
+            stdout: cap(r.stdout, CAP_OK),
+            stderr: cap(r.stderr, CAP_OK),
+            timedOut: false,
+            duration_ms: durationMs,
+        });
+    }
+    finally {
+        await fsp.unlink(file).catch(() => undefined);
+    }
+}
+// ---------------------------------------------------------------------------
+// run_javascript — the CONFINED variant (replicates Beledarian reference
+// L544-610; NOT an alias of run_javascript_free).
+//
+// Temp .ts written in the working directory (Beledarian's pattern, deleted in
+// finally), Deno flags: --allow-read=. --allow-write=. --no-prompt --deny-net
+// --deny-env --deny-sys --deny-run --deny-ffi (net/env/sys/run/ffi denied;
+// no --allow-import, so external module imports are denied — "you cannot import
+// external modules"). cwd defaults to the fork's shell_cwd default. Default
+// timeout 5 s, max 60 s. Returns {stdout, stderr} (trimmed, per the reference).
+// Non-zero exit throws the reference's error text: "Process exited with code N.
+// Stderr: ...". Reuses the fork's Deno binary resolution (resolveDenoPath).
+// ---------------------------------------------------------------------------
+export async function handleRunJavascript(javascript, timeoutSeconds) {
+    const deno = resolveDenoPath();
+    if (!deno) {
+        throw new Error("No Deno runtime found. Set the DENO_PATH environment variable to a deno binary, " +
+            "install deno on PATH, or run this server from inside an LM Studio installation " +
+            "(which bundles deno at <home>/.internal/utils/deno.exe).");
+    }
+    const abs = await resolveCwd();
+    const file = nodePath.join(abs, `temp_script_${Date.now()}.ts`);
+    const timeout = Math.min(Math.max(timeoutSeconds ?? 5, 0.1), COMPAT_SYNC_TIMEOUT_SEC);
+    const started = Date.now();
+    try {
+        await fsp.writeFile(file, javascript, "utf-8");
+        const r = await runCaptured(deno, [
+            "run",
+            "--allow-read=.",
+            "--allow-write=.",
+            "--no-prompt",
+            "--deny-net",
+            "--deny-env",
+            "--deny-sys",
+            "--deny-run",
+            "--deny-ffi",
+            file,
+        ], {
+            cwd: abs,
+            timeoutMs: timeout * 1000,
+            env: { ...process.env, NO_COLOR: "true" },
+        });
+        const durationMs = Date.now() - started;
+        if (r.spawnError) {
+            throw new Error(`Failed to launch deno: ${r.spawnError}`);
+        }
+        if (r.timedOut) {
+            throw new Error(`Process timed out after ${timeout}s.\nSTDOUT:\n${cap(r.stdout, CAP_ERR)}\nSTDERR:\n${cap(r.stderr, CAP_ERR)}`);
+        }
+        if (r.code !== 0) {
+            // Reference error text (toolsProvider.ts L594).
+            throw new Error(`Process exited with code ${r.code ?? "unknown"}. Stderr: ${cap(r.stderr, CAP_ERR)}`);
+        }
+        return JSON.stringify({
+            stdout: r.stdout.trim(),
+            stderr: r.stderr.trim(),
+            duration_ms: durationMs,
+            cwd: abs,
+        });
+    }
+    finally {
+        // Always cleanup temp file, even on error (reference L606-609).
+        await fsp.unlink(file).catch(() => undefined);
+    }
+}
+// ---------------------------------------------------------------------------
+// save_memory — STANDALONE (replicates Beledarian reference L509-542, minus
+// the enable gate — the fork has no such setting).
+//
+// Appends "- [ISO timestamp] fact" to the memory file. Memory file path =
+// env MCP_MEMORY_FILE if set, else the reference machine's workspace
+// memory.md if present, else <cwd>/memory.md. If the file is missing it is
+// created with a '# Long-Term Memory' header.
+// Returns {success, message} on success, {error} on failure.
+// ---------------------------------------------------------------------------
+export function resolveMemoryFile() {
+    const env = process.env.MCP_MEMORY_FILE;
+    if (env && env.trim())
+        return env;
+    // Reference machine's workspace memory.md (kept for back-compat); on other
+    // machines the path does not exist, so fall back to the server's CWD.
+    const legacy = "C:\\Users\\Gerar\\.beledarians-llm-toolbox\\workspace\\memory.md";
+    if (fs.existsSync(legacy))
+        return legacy;
+    return nodePath.join(process.cwd(), "memory.md");
+}
+export async function handleSaveMemory(fact) {
+    const memoryFile = resolveMemoryFile();
+    const timestamp = new Date().toISOString();
+    const entry = `\n- [${timestamp}] ${fact}`;
+    try {
+        // Reference: append; on failure (e.g. missing file) create with header.
+        // On POSIX the reference's append fails for a missing file and the write
+        // path runs; on Windows appendFile would create the file headerless, so we
+        // check existence up front to keep the '# Long-Term Memory' header on all
+        // platforms.
+        let exists = false;
+        try {
+            await fsp.access(memoryFile);
+            exists = true;
+        }
+        catch {
+            exists = false;
+        }
+        if (exists) {
+            await fsp.appendFile(memoryFile, entry, "utf-8");
+            return JSON.stringify({ success: true, message: "Fact saved to memory." });
+        }
+        await fsp.writeFile(memoryFile, "# Long-Term Memory\n" + entry, "utf-8");
+        return JSON.stringify({ success: true, message: "Fact saved to memory (new file created)." });
+    }
+    catch (error) {
+        return JSON.stringify({
+            error: `Failed to save memory: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}