mixdog 0.7.1

package/src/agent/orchestrator/tools/builtin/notebook-edit-tool.mjs

@@ -0,0 +1,300 @@
+// notebook_edit — structural Jupyter notebook (.ipynb) cell editor.
+//
+// Mixdog can READ rendered notebooks (extractIpynbText) but had no
+// structural editor: a generic text `edit` against the raw .ipynb JSON is
+// fragile (source is line-split arrays, outputs/execution_count are
+// machine state). This tool parses the notebook JSON, resolves a cell by
+// its real `cell.id` or a numeric `cell-N` index, then replaces / inserts /
+// deletes a cell and writes the JSON back — preserving the on-disk BOM
+// encoding and line endings, and gated behind the same read-before-write
+// snapshot guard as edit/write. Mirrors Claude Code's NotebookEditTool.
+import { readFileSync, statSync } from 'fs';
+import { extname } from 'path';
+import { markCodeGraphDirtyPaths } from '../code-graph.mjs';
+import {
+    normalizeInputPath,
+    normalizeOutputPath,
+    resolveAgainstCwd,
+} from './path-utils.mjs';
+import { normalizeErrorMessage } from './path-diagnostics.mjs';
+import { withPathLock } from './path-locks.mjs';
+import { withAdvisoryLocks } from './advisory-lock.mjs';
+import { hashText } from './hash-utils.mjs';
+import {
+    getReadSnapshot,
+    isSnapshotStale,
+    readContentIfSnapshotHashMatches,
+    recordReadSnapshot,
+} from './read-snapshot-runtime.mjs';
+import {
+    invalidateBuiltinResultCache,
+    seedRawContentCacheAfterWrite,
+} from './cache-layers.mjs';
+import { atomicWrite } from './atomic-write.mjs';
+import { detectExistingEncoding, toWriteBuffer } from './write-tool.mjs';
+import {
+    hasUnsafeWin32Component,
+    isWindowsDevicePath,
+} from './device-paths.mjs';
+
+// Jupyter serialises notebooks with a single-space indent.
+const IPYNB_INDENT = 1;
+
+// Parse a "cell-N" synthetic id (the addressing scheme the read renderer
+// exposes for notebooks without real cell ids) into its 0-based index.
+// Returns undefined for anything that is not exactly that shape.
+function parseCellId(cellId) {
+    if (typeof cellId !== 'string') return undefined;
+    const m = cellId.match(/^cell-(\d+)$/);
+    if (!m) return undefined;
+    const n = Number.parseInt(m[1], 10);
+    return Number.isFinite(n) ? n : undefined;
+}
+
+// Decode the raw notebook bytes honouring the leading BOM (same invariant
+// the write path re-applies), and report the dominant line ending so the
+// re-serialised JSON round-trips the file's CRLF/LF convention.
+function readNotebookSource(fullPath) {
+    const raw = readFileSync(fullPath);
+    let text;
+    if (raw.length >= 2 && raw[0] === 0xff && raw[1] === 0xfe) {
+        text = raw.subarray(2).toString('utf16le');
+    } else if (raw.length >= 3 && raw[0] === 0xef && raw[1] === 0xbb && raw[2] === 0xbf) {
+        text = raw.subarray(3).toString('utf-8');
+    } else {
+        text = raw.toString('utf-8');
+    }
+    const crlf = (text.match(/\r\n/g) || []).length;
+    const lf = (text.match(/\n/g) || []).length;
+    const lineEnding = crlf > 0 && crlf >= lf - crlf ? '\r\n' : '\n';
+    return { text, lineEnding };
+}
+
+export async function executeNotebookEditTool(args, workDir, readStateScope, options = {}) {
+    if (typeof args.file_path === 'string' && !args.notebook_path) args.notebook_path = args.file_path;
+    if (typeof args.path === 'string' && !args.notebook_path) args.notebook_path = args.path;
+
+    let notebookPath = args.notebook_path;
+    if (typeof notebookPath === 'string') notebookPath = normalizeInputPath(notebookPath);
+    if (!notebookPath) return 'Error: notebook_path is required';
+
+    const newSource = args.new_source;
+    const cellId = args.cell_id;
+    let cellType = args.cell_type;
+    const editMode = args.edit_mode === undefined || args.edit_mode === null ? 'replace' : args.edit_mode;
+
+    if (editMode !== 'replace' && editMode !== 'insert' && editMode !== 'delete') {
+        return `Error: edit_mode must be replace, insert, or delete (got ${JSON.stringify(args.edit_mode)})`;
+    }
+    if (cellType !== undefined && cellType !== 'code' && cellType !== 'markdown') {
+        return `Error: cell_type must be code or markdown (got ${JSON.stringify(cellType)})`;
+    }
+    if (editMode !== 'delete' && typeof newSource !== 'string') {
+        return `Error: new_source must be a string for edit_mode=${editMode}`;
+    }
+    if (editMode === 'insert' && !cellType) {
+        return 'Error: cell_type is required when using edit_mode=insert';
+    }
+    if (editMode !== 'insert' && !cellId) {
+        return 'Error: cell_id must be specified when not inserting a new cell';
+    }
+
+    // R12: Win32 component / device-name guard before path resolution so a
+    // relative path can't be coerced into a device alias or NTFS ADS suffix.
+    if (typeof isWindowsDevicePath === 'function' && isWindowsDevicePath(notebookPath)) {
+        return `Error: cannot edit Windows device path (reserved name or raw-device namespace): ${normalizeOutputPath(notebookPath)}`;
+    }
+    if (typeof hasUnsafeWin32Component === 'function' && hasUnsafeWin32Component(notebookPath)) {
+        return `Error: cannot edit Windows path with trailing dot/space or NTFS ADS suffix (bypasses device guard): ${normalizeOutputPath(notebookPath)}`;
+    }
+
+    const fullPath = resolveAgainstCwd(notebookPath, workDir);
+    // R1: short-circuit UNC/SMB paths before any fs probe to prevent NTLM
+    // credential leakage via implicit network auth.
+    if (fullPath.startsWith('\\\\') || fullPath.startsWith('//')) {
+        return `Error: UNC/SMB paths are not supported (R1: NTLM-leak prevention): ${notebookPath}`;
+    }
+    if (typeof isWindowsDevicePath === 'function' && isWindowsDevicePath(fullPath)) {
+        return `Error: cannot edit Windows device path (reserved name or raw-device namespace): ${normalizeOutputPath(notebookPath)}`;
+    }
+    if (typeof hasUnsafeWin32Component === 'function' && hasUnsafeWin32Component(fullPath)) {
+        return `Error: cannot edit Windows path with trailing dot/space or NTFS ADS suffix (bypasses device guard): ${normalizeOutputPath(notebookPath)}`;
+    }
+
+    if (extname(fullPath).toLowerCase() !== '.ipynb') {
+        return `Error: file must be a Jupyter notebook (.ipynb). For other file types use edit/write: ${normalizeOutputPath(notebookPath)}`;
+    }
+
+    return withPathLock(fullPath, () =>
+        withAdvisoryLocks([fullPath], async () => {
+            let existing;
+            try {
+                existing = statSync(fullPath);
+            } catch (err) {
+                if (err && err.code === 'ENOENT') {
+                    return `Error: notebook file does not exist: ${normalizeOutputPath(notebookPath)}`;
+                }
+                return `Error: stat failed before edit: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}: ${notebookPath}`;
+            }
+            if (!existing.isFile()) {
+                return `Error: notebook path is not a regular file: ${normalizeOutputPath(notebookPath)}`;
+            }
+
+            // Read-before-write guard (parity with edit/write): the notebook
+            // must have been read this session, and not changed since, or a
+            // structural edit could clobber an unseen / externally-modified file.
+            const snapshot = getReadSnapshot(fullPath, readStateScope);
+            if (!snapshot) {
+                return `Error [code 6]: notebook has not been read yet — read it first before editing: ${normalizeOutputPath(notebookPath)}`;
+            }
+            if (isSnapshotStale(existing, snapshot, fullPath)) {
+                const hashOk = readContentIfSnapshotHashMatches(fullPath, snapshot, null, existing);
+                if (hashOk === null) {
+                    return `Error [code 7]: notebook modified since read — read it again before editing: ${normalizeOutputPath(notebookPath)}`;
+                }
+            }
+
+            let originalText;
+            let lineEnding;
+            try {
+                ({ text: originalText, lineEnding } = readNotebookSource(fullPath));
+            } catch (err) {
+                return `Error: failed to read notebook: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}: ${notebookPath}`;
+            }
+
+            let notebook;
+            try {
+                notebook = JSON.parse(originalText);
+            } catch {
+                return `Error: notebook is not valid JSON: ${normalizeOutputPath(notebookPath)}`;
+            }
+            if (!notebook || !Array.isArray(notebook.cells)) {
+                return `Error: notebook JSON has no "cells" array: ${normalizeOutputPath(notebookPath)}`;
+            }
+
+            // Resolve target cell index: real cell.id first, then cell-N index.
+            let cellIndex;
+            if (!cellId) {
+                cellIndex = 0; // insert-at-start default
+            } else {
+                cellIndex = notebook.cells.findIndex((cell) => cell && cell.id === cellId);
+                if (cellIndex === -1) {
+                    const parsed = parseCellId(cellId);
+                    if (parsed !== undefined) {
+                        // Mode-aware bound (matches NotebookEditTool semantics):
+                        // insert may address the append slot (index ===
+                        // cells.length) to add a cell at the very end;
+                        // replace/delete require an EXISTING cell
+                        // [0 .. cells.length-1], so a past-end index errors.
+                        const maxIndex = editMode === 'insert'
+                            ? notebook.cells.length
+                            : notebook.cells.length - 1;
+                        if (parsed < 0 || parsed > maxIndex) {
+                            return `Error: cell with index ${parsed} does not exist in notebook (${notebook.cells.length} cells)`;
+                        }
+                        cellIndex = parsed;
+                    } else {
+                        return `Error: cell with ID "${cellId}" not found in notebook`;
+                    }
+                }
+                // Insert lands AFTER the referenced cell. When the index is the
+                // append slot (=== cells.length) there is no referenced cell to
+                // sit after, so leave it as-is to append at the very end.
+                if (editMode === 'insert' && cellIndex < notebook.cells.length) {
+                    cellIndex += 1;
+                }
+            }
+
+            // Insert at the append slot (index === cells.length) adds a cell at
+            // the very end — this is the reachable "add a cell at the end" path.
+            // replace/delete past-end already errored at the bound check above.
+            let effectiveMode = editMode;
+
+            // Only mint a real cell id when the notebook format supports it
+            // (nbformat 4.5+ / >4), matching how Jupyter assigns cell ids.
+            const supportsCellId =
+                notebook.nbformat > 4 ||
+                (notebook.nbformat === 4 && (notebook.nbformat_minor ?? 0) >= 5);
+            let resultCellId;
+            if (supportsCellId) {
+                resultCellId = effectiveMode === 'insert'
+                    ? Math.random().toString(36).substring(2, 15)
+                    : cellId;
+            }
+
+            if (effectiveMode === 'delete') {
+                notebook.cells.splice(cellIndex, 1);
+            } else if (effectiveMode === 'insert') {
+                const newCell = cellType === 'markdown'
+                    ? { cell_type: 'markdown', metadata: {}, source: newSource }
+                    : { cell_type: 'code', metadata: {}, execution_count: null, outputs: [], source: newSource };
+                if (supportsCellId) newCell.id = resultCellId;
+                notebook.cells.splice(cellIndex, 0, newCell);
+            } else {
+                const targetCell = notebook.cells[cellIndex];
+                if (!targetCell) {
+                    return `Error: cell at index ${cellIndex} does not exist in notebook`;
+                }
+                targetCell.source = newSource;
+                // A MODIFIED code cell's prior run state is invalid: reset
+                // execution_count and clear THIS cell's outputs only; every
+                // other cell's structure/outputs is left untouched.
+                if (targetCell.cell_type === 'code') {
+                    targetCell.execution_count = null;
+                    targetCell.outputs = [];
+                }
+                if (cellType && cellType !== targetCell.cell_type) {
+                    targetCell.cell_type = cellType;
+                    // Switching to code requires the code-cell machine fields;
+                    // switching to markdown drops them.
+                    if (cellType === 'code') {
+                        if (targetCell.execution_count === undefined) targetCell.execution_count = null;
+                        if (!Array.isArray(targetCell.outputs)) targetCell.outputs = [];
+                    } else {
+                        delete targetCell.execution_count;
+                        delete targetCell.outputs;
+                    }
+                }
+            }
+
+            let updatedText = JSON.stringify(notebook, null, IPYNB_INDENT);
+            // Preserve the file's line-ending convention. JSON.stringify only
+            // emits \n; re-apply CRLF when the original used it.
+            if (lineEnding === '\r\n') updatedText = updatedText.replace(/\n/g, '\r\n');
+
+            // Re-encode honouring the on-disk BOM (utf16le / utf8+BOM / utf8).
+            const writeContent = toWriteBuffer(updatedText, detectExistingEncoding(fullPath));
+
+            try {
+                await atomicWrite(fullPath, writeContent, { sessionId: options?.sessionId });
+            } catch (err) {
+                return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+            }
+
+            let writtenStat = null;
+            try { writtenStat = statSync(fullPath); } catch {}
+            // Refresh the read snapshot post-write (matches edit/write) so a
+            // follow-up read/edit in the same instant isn't blocked or stale.
+            recordReadSnapshot(fullPath, writtenStat || undefined, readStateScope, {
+                source: 'write',
+                contentHash: hashText(writeContent),
+                replaceExisting: true,
+            });
+            invalidateBuiltinResultCache([fullPath]);
+            seedRawContentCacheAfterWrite(fullPath, writeContent, writtenStat);
+            markCodeGraphDirtyPaths([fullPath]);
+
+            const cellLabel = resultCellId || (cellId ?? `cell-${cellIndex}`);
+            switch (effectiveMode) {
+                case 'insert':
+                    return `Inserted ${cellType || 'code'} cell ${cellLabel} in ${normalizeOutputPath(notebookPath)}`;
+                case 'delete':
+                    return `Deleted cell ${cellId} in ${normalizeOutputPath(notebookPath)}`;
+                default:
+                    return `Updated cell ${cellLabel} in ${normalizeOutputPath(notebookPath)}`;
+            }
+        })
+    );
+}
+
+export default executeNotebookEditTool;

package/src/agent/orchestrator/tools/builtin/open-config-tool.mjs

@@ -0,0 +1,26 @@
+// open_config builtin tool.
+//
+// Lives in the always-on `builtin` module (not the gated `agent` module) so
+// the config UI stays reachable even when modules.agent.enabled === false —
+// otherwise a user who disabled the agent module would lose every way to open
+// the settings UI (the old `bun launch.mjs` slash shell-out is gone).
+//
+// Launches the config UI through the resident MCP server. Because this server
+// is a long-lived background process, its spawn of setup-server
+// (windowsHide:true inside launch-core) creates NO console window — unlike the
+// old `!bun launch.mjs` slash-command shell-out, which flashed a conhost. The
+// launch-core import is lazy so its child_process/http deps stay off the hot
+// builtin path until the tool is actually called.
+
+export async function executeOpenConfigTool() {
+    const { launchConfigUi, LaunchError } = await import(
+        new URL('../../../../../setup/launch-core.mjs', import.meta.url).href
+    );
+    try {
+        const url = await launchConfigUi();
+        return `Config UI opened at ${url}`;
+    } catch (err) {
+        if (err instanceof LaunchError) return `Error: ${err.message.trim()}`;
+        throw err;
+    }
+}

package/src/agent/orchestrator/tools/builtin/path-diagnostics.mjs

@@ -0,0 +1,152 @@
+import { readdirSync } from 'fs';
+import { basename, dirname, extname, isAbsolute, join, relative } from 'path';
+import { homedir } from 'os';
+
+// Suggest a sibling file the caller may have meant when the requested
+// path is missing: same stem with a different extension, or a same-name
+// sibling differing only in case. Pure best-effort; any fs error returns
+// null so the caller falls back to the bare "not found" message.
+export function findSimilarFile(fullPath) {
+    try {
+        const dir = dirname(fullPath);
+        const base = basename(fullPath);
+        const stem = basename(fullPath, extname(fullPath));
+        const entries = readdirSync(dir);
+        const sameStem = entries.find((e) => e !== base && basename(e, extname(e)) === stem);
+        if (sameStem) return join(dir, sameStem);
+        const caseMatch = entries.find((e) => e !== base && e.toLowerCase() === base.toLowerCase());
+        if (caseMatch) return join(dir, caseMatch);
+        return null;
+    } catch { return null; }
+}
+
+// Sibling listing for ENOENT diagnostics. Pure information extension —
+// callers always receive the directory's existing entries (capped) inline
+// in the error hint, removing the recovery cost of a follow-up list/glob
+// call. Measurement showed ENOENT recovery consistently runs read→glob/
+// list→read (4-call); siblings inline collapses that to read→read.
+export function listSiblings(dir, limit = 12) {
+    try {
+        return readdirSync(dir).filter((n) => !n.startsWith('.')).slice(0, limit);
+    } catch { return []; }
+}
+
+// Locate a missing file's basename ELSEWHERE under the search root. The most
+// common ENOENT cause is a right-name / wrong-directory path (e.g. asking for
+// `webhook.mjs` when the file lives at `src/channels/lib/webhook.mjs`).
+// findSimilarFile only inspects the same directory, so a wrong-directory miss
+// gets no hint and the caller reconstructs the real path with a grep/glob
+// storm. This walks the root (BFS — shallow hits first), skipping noise dirs
+// and hard-capped on directories scanned, and returns up to `limit` real
+// locations so the error can name them directly. Pure best-effort; any error
+// returns [].
+const BASENAME_SCAN_SKIP_DIRS = new Set([
+    'node_modules', '.git', '.hg', '.svn', 'dist', 'build', 'out',
+    'coverage', '.next', '.nuxt', '.turbo', '.cache', 'vendor',
+    'target', '.venv', 'venv', '__pycache__', '.idea', '.vscode',
+]);
+export function findFileByBasename(searchRoot, fullPath, { limit = 3, maxDirs = 6000 } = {}) {
+    try {
+        if (typeof searchRoot !== 'string' || !searchRoot) return [];
+        const target = basename(fullPath).toLowerCase();
+        if (!target) return [];
+        const matches = [];
+        const queue = [searchRoot];
+        let scanned = 0;
+        while (queue.length && matches.length < limit && scanned < maxDirs) {
+            const dir = queue.shift();
+            scanned++;
+            let entries;
+            try { entries = readdirSync(dir, { withFileTypes: true }); }
+            catch { continue; }
+            for (const ent of entries) {
+                const name = ent.name;
+                if (ent.isDirectory()) {
+                    if (name.startsWith('.') || BASENAME_SCAN_SKIP_DIRS.has(name)) continue;
+                    queue.push(join(dir, name));
+                } else if (ent.isFile() && name.toLowerCase() === target) {
+                    const hit = join(dir, name);
+                    if (hit !== fullPath) {
+                        // Return search-root-relative so the hint stays leak-safe
+                        // (no home / cache absolute) and is directly read-usable.
+                        matches.push(relative(searchRoot, hit));
+                        if (matches.length >= limit) break;
+                    }
+                }
+            }
+        }
+        return matches;
+    } catch { return []; }
+}
+
+// Node's native fs errors embed the failing path wrapped in single quotes
+// using OS-native separators ('C:\\Users\\foo\\bar.mjs' on Windows). Without
+// this pass, read error bodies surface backslash paths that
+// break the forward-slash convention the rest of the tool output keeps.
+// Accepts an optional workDir to produce cwd-relative paths. This pass also
+// closes the R14 tool-result info-leak boundary: home dir / plugin root /
+// plugin data / runtime dir absolutes are rewritten into stable tokens so
+// model-facing error bodies never carry environment-specific filesystem
+// segments. Full detail is retained in local logs upstream of this call.
+//
+// Replacement priority for any absolute path encountered:
+//   1. cwd-relative      (workDir set and path is inside workDir)
+//   2. <runtime>/...     (CLAUDE_PLUGIN_RUNTIME prefix)
+//   3. <plugin-data>/... (CLAUDE_PLUGIN_DATA prefix)
+//   4. <plugin-root>/... (CLAUDE_PLUGIN_ROOT prefix)
+//   5. ~/...             (OS home directory prefix)
+//   6. forward-slash normalised absolute (Windows backslash → slash, no leak)
+//
+// Two surface forms are scrubbed:
+//   * quoted drive-letter / POSIX absolute paths inside the message body
+//   * bare `file:///C:/...` or `file:///abs/...` stack-frame URIs (no quotes)
+// More-specific prefixes are checked first so plugin-data wins over the
+// containing home directory.
+export function normalizeErrorMessage(msg, workDir) {
+    if (typeof msg !== 'string') return msg;
+    const home = homedir().replace(/\\/g, '/');
+    const pluginRoot = (process.env.CLAUDE_PLUGIN_ROOT || '').replace(/\\/g, '/');
+    const pluginData = (process.env.CLAUDE_PLUGIN_DATA || '').replace(/\\/g, '/');
+    const runtimeDir = (process.env.CLAUDE_PLUGIN_RUNTIME || '').replace(/\\/g, '/');
+    const cwd = typeof workDir === 'string' && workDir ? workDir.replace(/\\/g, '/') : '';
+
+    const redact = (raw) => {
+        const fwd = raw.replace(/\\/g, '/');
+        if (cwd) {
+            try {
+                const rel = relative(cwd, fwd);
+                if (rel && !rel.startsWith('..') && !isAbsolute(rel)) {
+                    return rel.replace(/\\/g, '/');
+                }
+            } catch { /* fall through */ }
+        }
+        if (runtimeDir && (fwd === runtimeDir || fwd.startsWith(runtimeDir + '/'))) {
+            return `<runtime>${fwd.slice(runtimeDir.length)}`;
+        }
+        if (pluginData && (fwd === pluginData || fwd.startsWith(pluginData + '/'))) {
+            return `<plugin-data>${fwd.slice(pluginData.length)}`;
+        }
+        if (pluginRoot && (fwd === pluginRoot || fwd.startsWith(pluginRoot + '/'))) {
+            return `<plugin-root>${fwd.slice(pluginRoot.length)}`;
+        }
+        if (home && (fwd === home || fwd.startsWith(home + '/'))) {
+            return `~${fwd.slice(home.length)}`;
+        }
+        return fwd;
+    };
+
+    // 1. Strip bare `file:///...` stack-frame URIs first so the inner path
+    //    survives the quoted-path pass that follows (URIs aren't quoted).
+    let out = msg.replace(
+        /file:\/\/\/([A-Za-z]:\/[^\s'"<>)\]]+|\/[^\s'"<>)\]]+)/g,
+        (_m, p) => redact(p),
+    );
+
+    // 2. Redact quoted drive-letter (Windows) and POSIX absolute paths.
+    out = out.replace(
+        /(['"])([A-Za-z]:[\\\/][^'"]+|\/[^'"]+)\1/g,
+        (_m, q, p) => `${q}${redact(p)}${q}`,
+    );
+
+    return out;
+}

package/src/agent/orchestrator/tools/builtin/path-locks.mjs

@@ -0,0 +1,35 @@
+// Per-path mutex for concurrent Edit/Write operations. Maps absPath → Promise
+// chain so that overlapping calls for the same file are serialised in-process.
+const editLocks = new Map();
+
+export function pathLockKey(absPath) {
+    const text = String(absPath || '');
+    return process.platform === 'win32' ? text.toLowerCase() : text;
+}
+
+export function withPathLock(absPath, fn) {
+    const lockKey = pathLockKey(absPath);
+    const prev = editLocks.get(lockKey) ?? Promise.resolve();
+    const next = prev.then(fn, fn); // pass through errors so chain never stalls
+    editLocks.set(lockKey, next.then(
+        () => { if (editLocks.get(lockKey) === next) editLocks.delete(lockKey); },
+        () => { if (editLocks.get(lockKey) === next) editLocks.delete(lockKey); },
+    ));
+    return next;
+}
+
+export function withBuiltinPathLocks(paths, fn) {
+    const keyed = new Map();
+    for (const p of Array.isArray(paths) ? paths : [paths]) {
+        if (!p) continue;
+        keyed.set(pathLockKey(p), String(p));
+    }
+    const sorted = [...keyed.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map((entry) => entry[1]);
+    const run = (idx) => {
+        if (idx >= sorted.length) return fn();
+        return withPathLock(sorted[idx], () => run(idx + 1));
+    };
+    return run(0);
+}