mindweave 0.0.1 → 2.1.2

package/dist/tools/askUser.js

@@ -0,0 +1,103 @@
+import { APPROVAL_DISMISSED } from "./approval.js";
+import { failQuietly } from "./results.js";
+const askUserDef = {
+    name: "ask_user",
+    /** Deferred: asking is rare by design — on most turns the prompt asks for a judgment
+     *  call to be made, not a question put back to the user. */
+    deferred: true,
+    readOnly: true,
+    // The old text promised "the user's choice is returned to you" with no account of the
+    // two ways that does not happen — dismissal, and no channel at all. Both now return a
+    // plain instruction to carry on, so the model must know they are possible or it will
+    // read either one as a choice.
+    description: "Ask the user a focused question when the task is genuinely ambiguous and you " +
+        "cannot proceed well without their input: which of two real approaches they want, " +
+        "a missing requirement, an unclear denial. Give 2-4 concrete options — only the " +
+        "first 4 are shown — and their choice comes back to you.\n" +
+        "Use it sparingly. Anything you can settle with a sensible default, or find out by " +
+        "reading the project, is not a question; asking about it spends the user's " +
+        "attention on work they delegated. Prefer acting when the answer is obvious, and " +
+        "prefer one question that decides the direction over several small ones.\n" +
+        "You may not get an answer: the user can dismiss the question, and some sessions " +
+        "have no way to ask at all. Both come back saying so, and neither is a choice — do " +
+        "not treat an option as picked. Carry on with the most reasonable default, say " +
+        "which one you assumed, and do any part of the work that does not depend on it.",
+    parameters: {
+        type: "object",
+        additionalProperties: false,
+        required: ["question", "options"],
+        properties: {
+            question: {
+                type: "string",
+                description: "The specific question to ask. Clear and self-contained.",
+            },
+            options: {
+                type: "array",
+                description: "2-4 concrete answer options for the user to choose from.",
+                items: { type: "string" },
+                minItems: 2,
+                maxItems: 4,
+            },
+        },
+    },
+    async execute(args, ctx) {
+        const question = typeof args.question === "string" ? args.question.trim() : "";
+        const options = Array.isArray(args.options)
+            ? args.options.filter((o) => typeof o === "string" && o.trim() !== "").map((o) => o.trim())
+            : [];
+        if (!question)
+            return failQuietly("`question` is required.");
+        if (options.length < 2)
+            return failQuietly("provide at least 2 concrete `options`.");
+        // No approval channel (headless run / tests): can't ask — tell the model to
+        // proceed on its best judgment rather than stall.
+        if (!ctx.requestApproval) {
+            return {
+                output: "Can't ask the user right now (no interactive channel). Proceed with your best " +
+                    "judgment using a sensible default, and note the assumption in your reply.",
+                summary: "ask_user unavailable — proceed with a default",
+            };
+        }
+        const choice = await ctx.requestApproval(question, options.slice(0, 4));
+        // Dismissing the question is not an answer, and must never be reported as one.
+        // It used to resolve as the second option, so "Postgres or SQLite?" dismissed came
+        // back as "The user chose: SQLite" — a decision attributed to someone who declined
+        // to make it, which is worse than not having asked.
+        if (choice === APPROVAL_DISMISSED) {
+            return {
+                output: "The user dismissed the question without answering, so you do not have their " +
+                    "preference. Do not treat any option as chosen. Proceed with the most " +
+                    "reasonable default and say which one you assumed, or continue with the part " +
+                    "of the work that does not depend on the answer.",
+                summary: `asked: ${clip(question)} → dismissed`,
+            };
+        }
+        return {
+            output: `The user chose: ${choice}`,
+            summary: `asked: ${clip(question)} → ${clip(choice)}`,
+        };
+    },
+};
+/**
+ * Never renders a row.
+ *
+ * The user has just been shown the question in the approval box and answered it — a
+ * row afterwards restating "asked: which database? → SQLite" tells them something they
+ * did a second ago. The model still gets the full result, which is the half that
+ * matters: it needs the answer, the user does not need the receipt.
+ *
+ * Wrapped at the export rather than flagged at each `return`, so a new return site
+ * cannot start rendering again by omission — the same shape `navigational()` uses for
+ * the code-intel lookups.
+ */
+export const askUserTool = {
+    ...askUserDef,
+    async execute(args, ctx) {
+        return { ...(await askUserDef.execute(args, ctx)), quiet: true };
+    },
+};
+function clip(s, max = 40) {
+    const flat = s.replace(/\s+/g, " ").trim();
+    return flat.length <= max ? flat : flat.slice(0, max - 1) + "…";
+}
+//# sourceMappingURL=askUser.js.map

package/dist/tools/askUser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"askUser.js","sourceRoot":"","sources":["../../src/tools/askUser.ts"],"names":[],"mappings":"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"}

package/dist/tools/atomicWrite.js

@@ -0,0 +1,151 @@
+/**
+ * atomicWrite.ts — replace a file's contents without ever leaving it torn.
+ *
+ * Every file-mutating tool used to call `fs.writeFile` straight onto the real
+ * path. That call TRUNCATES the destination and then streams the new bytes in,
+ * so between those two moments the file on disk is empty or half-written. A
+ * crash, an OOM kill, or a power loss inside that window destroys the user's
+ * file, and it destroys it SILENTLY: the tool never returned, so the agent
+ * believes the edit landed and carries on reasoning about content that no longer
+ * exists. The window is small; the loss is total and unrecoverable.
+ *
+ * The cure is the standard write-temp-then-rename dance:
+ *   1. write the complete new content to a sibling temp file,
+ *   2. fsync it, so the bytes are on the physical device and not merely in the
+ *      page cache (without this a power loss can land a renamed file full of
+ *      zeroes — the rename outlives the data it points at),
+ *   3. rename it over the destination.
+ *
+ * Rename within a directory is atomic on POSIX, and Node maps it to
+ * MoveFileEx(REPLACE_EXISTING) on Windows. So a reader of the destination at ANY
+ * instant sees either the old file, whole, or the new file, whole. There is no
+ * third state to observe and no window to lose the file in.
+ *
+ * A sibling temp file, not the system temp directory: rename is only atomic
+ * WITHIN a filesystem, and /tmp is very often a different mount. A cross-device
+ * rename fails outright (EXDEV), and "fix" it by copying and you are back to a
+ * torn destination with extra steps.
+ */
+import { promises as fs } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { basename, dirname, join } from "node:path";
+const IS_WINDOWS = process.platform === "win32";
+/**
+ * Windows lets another process hold a handle that blocks our rename: an editor
+ * with the file open, a search indexer, antivirus reading what we just wrote.
+ * The block is transient — those holders release in milliseconds — so a short
+ * retry converts a spurious hard failure into a normal write. POSIX renames over
+ * open files without complaint, so this path never engages there.
+ */
+const RENAME_ATTEMPTS = 5;
+const RENAME_BACKOFF_MS = 40;
+/** Errors that mean "someone else is holding the destination, briefly". */
+const TRANSIENT = new Set(["EPERM", "EACCES", "EBUSY"]);
+function errCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : "";
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * A temp name beside the destination, unique across concurrent writers.
+ *
+ * The pid alone is not enough: two sessions in the same repo are two processes,
+ * but one process running parallel tool calls is ONE pid writing several files at
+ * once. Random bytes make each attempt distinct regardless. Leading dot so a
+ * temp file that somehow outlives us stays out of the user's way.
+ */
+function tempPathFor(filePath) {
+    const unique = `${process.pid}.${randomBytes(6).toString("hex")}`;
+    return join(dirname(filePath), `.${basename(filePath)}.${unique}.tmp`);
+}
+/**
+ * The destination's current permission bits, or undefined if it does not exist.
+ *
+ * A fresh temp file is born with default permissions, so replacing an executable
+ * script would silently strip its execute bit and the next run of it fails with
+ * "permission denied" — a change nobody asked for, caused by a tool that was
+ * only supposed to edit text.
+ */
+async function existingMode(filePath) {
+    try {
+        return (await fs.stat(filePath)).mode;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Rename, tolerating Windows' transient holders. Throws if it never succeeds. */
+async function renameWithRetry(from, to) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            await fs.rename(from, to);
+            return;
+        }
+        catch (error) {
+            const retryable = IS_WINDOWS && TRANSIENT.has(errCode(error));
+            if (!retryable || attempt >= RENAME_ATTEMPTS)
+                throw error;
+            await sleep(RENAME_BACKOFF_MS * attempt);
+        }
+    }
+}
+/**
+ * Write `content` to `filePath` so the destination is never observed torn.
+ *
+ * Drop-in for `fs.writeFile(path, content, "utf8")`. Parent directories are NOT
+ * created here — callers that need that already do it, and doing it silently
+ * would hide a typo'd path behind a freshly invented tree.
+ *
+ * On any failure the destination is left exactly as it was and the temp file is
+ * cleaned up, so a failed write is a no-op rather than a partial one.
+ */
+export async function writeFileAtomic(filePath, content) {
+    const tempPath = tempPathFor(filePath);
+    const mode = await existingMode(filePath);
+    try {
+        // Explicit handle rather than fs.writeFile's `flush` option: that option only
+        // exists from Node 20.10, and this package allows >=20. On an older 20.x it
+        // would be accepted and ignored, leaving us with no fsync and no error — the
+        // exact silent-durability-loss this module exists to prevent.
+        const handle = await fs.open(tempPath, "w", mode);
+        try {
+            await handle.writeFile(content, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        // `open`'s mode argument is masked by the process umask, so an existing file's
+        // bits are re-applied here to survive it. Permission bits only: the type bits
+        // in stat.mode are not ours to copy.
+        if (mode !== undefined)
+            await fs.chmod(tempPath, mode & 0o777);
+        await renameWithRetry(tempPath, filePath);
+    }
+    catch (error) {
+        // Never leave litter behind: the destination still holds the old content, so
+        // the temp file is pure garbage at this point.
+        await fs.rm(tempPath, { force: true }).catch(() => { });
+        throw error;
+    }
+    // Durability of the RENAME itself (as opposed to the bytes) needs the parent
+    // directory synced too, or a power loss can resurrect the old directory entry
+    // pointing at a file we already unlinked. Best-effort: Windows cannot open a
+    // directory as a file, and some filesystems refuse the fsync. A failure here
+    // costs durability across a power cut, never correctness of the write.
+    if (!IS_WINDOWS) {
+        let dir;
+        try {
+            dir = await fs.open(dirname(filePath), "r");
+            await dir.sync();
+        }
+        catch {
+            // Nothing to do: the data is written and the rename has already happened.
+        }
+        finally {
+            await dir?.close().catch(() => { });
+        }
+    }
+}
+//# sourceMappingURL=atomicWrite.js.map

package/dist/tools/atomicWrite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomicWrite.js","sourceRoot":"","sources":["../../src/tools/atomicWrite.ts"],"names":[],"mappings":"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"}