mixdog 0.7.18 → 0.8.0

package/src/runtime/agent/orchestrator/tools/builtin/builtin-tools.mjs

@@ -0,0 +1,165 @@
+// --- Tool definitions for external models ---
+//
+// Ordered to match the previous hand-maintained tools.json entries so
+// build-tools-manifest reproduces the legacy ordering.
+// CANONICAL SOURCE for all tool annotations (compressible, readOnlyHint,
+// destructiveHint, etc.). tools.json is GENERATED from this array by
+// dev/scripts/build-tools-manifest.mjs — do not edit annotations in tools.json
+// directly. To verify sync: node dev/scripts/check-tools-sync.mjs
+import {
+    TOOL_ASYNC_EXECUTION_CONTRACT,
+    TOOL_MANUAL_CONTROL_CONTRACT,
+    executionModeSchemaDescription,
+} from '../../../../shared/background-tasks.mjs';
+
+export const BUILTIN_TOOLS = [
+    {
+        name: 'read',
+        title: 'Mixdog Read',
+        annotations: { title: 'Mixdog Read', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false },
+        description: 'Read a specific file window or symbol body after narrowing the target. Do not reread content already shown by code_graph or grep.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path only; dirs use list.' },
+                line: { type: 'number', minimum: 1, description: 'Anchor line. Do not combine with offset/limit.' },
+                context: { type: 'number', minimum: 0, maximum: 200, description: 'Lines around line. Use only with line; max 200.' },
+                symbol: { type: 'string', description: 'Symbol body via code graph.' },
+            },
+        },
+    },
+    {
+        name: 'diagnostics',
+        title: 'Mixdog Diagnostics',
+        annotations: { title: 'Mixdog Diagnostics', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true, compressible: true },
+        description: 'Run the matching type/lint checker under a file or directory (tsc/eslint/ruff/etc.). Default cwd; no LSP.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File or directory to diagnose. Defaults to cwd.' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'open_config',
+        title: 'Open Config UI',
+        annotations: { title: 'Open Config UI', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: 'Open the mixdog settings UI (Providers + Presets) in the browser. Starts the resident config server if needed and returns the UI URL. No params.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'shell',
+        title: 'Mixdog Shell',
+        annotations: { title: 'Mixdog Shell', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, compressible: true },
+        description: `Run an OS shell command for git/build/test/run only. Do NOT use shell grep/cat/head for source; use code_graph/grep/read/list/glob. Set shell explicitly: 'powershell' for PowerShell or 'bash' for Git Bash/POSIX. Use cwd; omit empty workdir. Windows native shell does not support persistent/session_id. mode=async uses the shared background task system and returns task_id. ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                command: { type: 'string', description: 'Shell command to run.' },
+                cwd: { type: 'string', description: 'Working directory for the command; omit when using current cwd.' },
+                workdir: { type: 'string', description: 'Alias for cwd; omit if empty.' },
+                timeout: { type: 'number', description: 'Timeout in milliseconds.' },
+                merge_stderr: { type: 'boolean', description: 'Merge stderr into stdout in the returned output.' },
+                mode: { type: 'string', enum: ['sync', 'async'], description: executionModeSchemaDescription('sync') },
+                run_in_background: { type: 'boolean', description: `Legacy alias for mode=async. ${TOOL_ASYNC_EXECUTION_CONTRACT}` },
+                persistent: { type: 'boolean', description: 'Persistent shell mode; unsupported on Windows native shell.' },
+                session_id: { type: 'string', description: 'Persistent shell id; omit on Windows native shell.' },
+                create: { type: 'boolean', description: 'Allow creating a new persistent session for an explicit session_id.' },
+                close: { type: 'boolean', description: 'Close the persistent session after this command when supported.' },
+                shell: { type: 'string', enum: ['bash', 'powershell'], description: "Force the shell. On Windows: 'bash' runs the command through Git Bash (POSIX syntax), 'powershell' forces PowerShell. On POSIX: 'powershell' resolves pwsh if installed (errors if absent); 'bash' is /bin/sh (already the default). Always set this explicitly; omitting uses the OS default (PowerShell on Windows), where POSIX syntax fails to parse." },
+            },
+            required: ['command'],
+        },
+    },
+    {
+        name: 'task',
+        title: 'Background Task Control',
+        annotations: { title: 'Background Task Control', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        description: `Manual control for an async background task by task_id. action: list | status | read | wait | cancel. ${TOOL_MANUAL_CONTROL_CONTRACT} Not for bridge_*/sess_* ids.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: { type: 'string', description: 'task_id from shell mode=async. Use only for manual control; normal completion arrives as a notification.' },
+                action: { type: 'string', enum: ['list', 'status', 'read', 'wait', 'cancel'], description: 'Manual control only: list all visible tasks; status is non-blocking; read includes available result/output; wait blocks inside this one call until done/timeout; cancel terminates when the task supports it. Do not call repeatedly as a polling loop.' },
+                timeout_ms: { type: 'number', description: 'Maximum time for a single manual wait call. Prefer the completion notification instead of repeated waits.' },
+                poll_ms: { type: 'number', description: 'Internal polling interval used only inside one manual wait call.' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'grep',
+        title: 'Mixdog Grep',
+        annotations: { title: 'Mixdog Grep', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
+        description: 'Search text or regex within a known file or directory.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pattern: {
+                    anyOf: [
+                        { type: 'string' },
+                        { type: 'array', items: { type: 'string' }, minItems: 1 },
+                    ],
+                    description: 'Literal/substring or ripgrep regex. Array = OR terms. Legacy `\\|` in a single string is accepted as OR.',
+                },
+                path: { type: 'string', description: 'One file or directory only; for many paths use common parent + glob.' },
+                glob: {
+                    anyOf: [
+                        { type: 'string' },
+                        { type: 'array', items: { type: 'string' }, minItems: 1 },
+                    ],
+                    description: 'Glob filter(s).',
+                },
+                output_mode: { type: 'string', enum: ['files_with_matches', 'content', 'count'], description: 'Default content.' },
+                head_limit: { type: 'number', description: 'Max result lines.' },
+                offset: { type: 'number', description: 'Skip N result lines for paging.' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'glob',
+        title: 'Mixdog Glob',
+        annotations: { title: 'Mixdog Glob', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
+        description: 'Find files by glob pattern. Use for broad file-space narrowing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pattern: {
+                    anyOf: [
+                        { type: 'string' },
+                        { type: 'array', items: { type: 'string' }, minItems: 1 },
+                    ],
+                    description: 'Glob pattern, or array of patterns.',
+                },
+                path: {
+                    anyOf: [
+                        { type: 'string' },
+                        { type: 'array', items: { type: 'string' }, minItems: 1 },
+                    ],
+                    description: 'Base directory, or array of base directories.',
+                },
+                head_limit: { type: 'number', description: 'Max entries.' },
+                offset: { type: 'number', description: 'Skip N entries for paging.' },
+            },
+            required: ['pattern'],
+        },
+    },
+    {
+        name: 'list',
+        title: 'Mixdog List Directory',
+        annotations: { title: 'Mixdog List Directory', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
+        description: 'List directory entries or fuzzy-rank filenames. Use for broad directory/file discovery.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Directory to list; omit for current cwd.' },
+                head_limit: { type: 'number', description: 'Max entries.' },
+                offset: { type: 'number', description: 'Skip N entries for paging.' },
+                fuzzy: { type: 'string', description: 'Rank files by partial name.' },
+            },
+            required: [],
+        },
+    },
+];

package/src/runtime/agent/orchestrator/tools/builtin/fuzzy-match.mjs

@@ -0,0 +1,104 @@
+// fuzzy-match.mjs — lightweight subsequence fuzzy scorer for filename / path
+// search (codex file-search / nucleo style, in JS). Returns a score where a
+// higher value is a better match, or null when the query is not a subsequence
+// of the candidate.
+//
+// Scoring favors, in rough order of weight:
+//   - matches at the START of the basename (last path segment)
+//   - matches at a word boundary (/, \, _, -, ., space, or camelCase hump)
+//   - contiguous runs of matched characters
+//   - exact-case hits (small tie-break)
+//   - shorter / earlier candidates (mild brevity + earliness pull)
+//
+// Matching is case-insensitive. The query is matched as an ordered subsequence
+// (the chars must appear in order but need not be contiguous), which is what
+// lets partial names surface matching files.
+
+function isBoundaryChar(ch) {
+    return ch === '/' || ch === '\\' || ch === '_' || ch === '-' || ch === '.' || ch === ' ';
+}
+
+// A camelCase hump (lower/digit followed by upper) is also a word boundary.
+function isHump(prevCh, ch) {
+    return prevCh !== undefined
+        && /[a-z0-9]/.test(prevCh)
+        && /[A-Z]/.test(ch);
+}
+
+/**
+ * @param {string} query   user query (partial name)
+ * @param {string} str     candidate path (relative)
+ * @returns {number|null}  score, or null if `query` is not a subsequence
+ */
+export function fuzzyScore(query, str) {
+    if (!query) return 0;
+    const normalizedQuery = String(query).replace(/[\/\\_.\-\s]+/g, '');
+    if (!normalizedQuery) return 0;
+    const q = normalizedQuery.toLowerCase();
+    const s = str.toLowerCase();
+    const qlen = q.length;
+    const slen = s.length;
+    if (qlen === 0) return 0;
+    if (qlen > slen) return null;
+
+    const lastSep = Math.max(str.lastIndexOf('/'), str.lastIndexOf('\\'));
+
+    let score = 0;
+    let si = 0;
+    let prevMatch = -2;
+    let firstMatchIdx = -1;
+
+    for (let qi = 0; qi < qlen; qi++) {
+        const qc = q[qi];
+        let found = -1;
+        for (let k = si; k < slen; k++) {
+            if (s[k] === qc) { found = k; break; }
+        }
+        if (found === -1) return null;
+        if (firstMatchIdx === -1) firstMatchIdx = found;
+
+        score += 1; // base point per matched char
+
+        if (found === prevMatch + 1) score += 5; // contiguous run
+
+        const prevCh = found > 0 ? str[found - 1] : undefined;
+        if (prevCh === undefined || isBoundaryChar(prevCh) || isHump(prevCh, str[found])) {
+            score += 8; // word-boundary start
+        }
+
+        if (str[found] === normalizedQuery[qi]) score += 1; // exact-case tie-break
+
+        prevMatch = found;
+        si = found + 1;
+    }
+
+    // Matches that begin inside the basename (after the last separator) are far
+    // more relevant than ones buried in directory components.
+    if (firstMatchIdx > lastSep) score += 10;
+
+    // Mild pulls: shorter candidates and earlier first matches rank higher.
+    score -= Math.floor(slen / 16);
+    score -= Math.floor(firstMatchIdx / 8);
+
+    return score;
+}
+
+/**
+ * Rank candidates by fuzzy score against `query`, dropping non-matches.
+ * @param {string} query
+ * @param {Array<{path:string}>} items  each must expose a `path` string
+ * @param {number} [limit]
+ * @returns {Array<{item:object, score:number}>}  sorted desc, then path asc
+ */
+export function fuzzyRank(query, items, limit = 0) {
+    const scored = [];
+    for (const item of items) {
+        const pathScore = fuzzyScore(query, item.path);
+        const base = String(item.path || '').split(/[\\/]/).pop() || '';
+        const baseScore = fuzzyScore(query, base);
+        const sc = Math.max(pathScore ?? -Infinity, baseScore === null ? -Infinity : baseScore + 40);
+        if (Number.isFinite(sc)) scored.push({ item, score: sc });
+    }
+    scored.sort((a, b) => (b.score - a.score) || (a.item.path < b.item.path ? -1 : a.item.path > b.item.path ? 1 : 0));
+    return limit > 0 ? scored.slice(0, limit) : scored;
+}

package/src/runtime/agent/orchestrator/tools/builtin/glob-walk.mjs

@@ -0,0 +1,194 @@
+import { readdir } from 'fs/promises';
+import { join } from 'path';
+
+// Glob-to-RegExp compiler for name filters used by find_files and the
+// list-tool family. Supported syntax:
+//   *        — matches any run of non-separator chars within one segment
+//   **       — matches across `/` boundaries (any depth)
+//   ?        — matches one non-separator char
+//   {a,b,c}  — brace alternation (no nesting)
+// Regex metacharacters in literal positions are escaped per-char. The
+// per-character loop replaces an older .replace-based pipeline whose
+// substitution-string form silently corrupted patterns containing `$`
+// sequences (see B35, v0.6.216); the loop avoids substitution entirely.
+// DoS caps for brace expansion + compiled regex. A crafted pattern
+// such as `{a,b}` repeated 25 times would Cartesian-multiply to ~33M
+// variants and produce a multi-megabyte regex; both the recursive
+// expansion and the `new RegExp` call would burn CPU/memory before
+// any caller-side check. These ceilings are well above realistic user
+// globs. Limits are surfaced as Error strings so the tool layer can
+// convert them to a tool error instead of crashing the worker.
+const MAX_BRACE_VARIANTS = 256;
+const MAX_PATTERN_LENGTH = 1024;
+const MAX_REGEX_BODY_LENGTH = 16384;
+function expandBraces(pattern) {
+    const m = pattern.match(/\{([^{}]*)\}/);
+    if (!m) return [pattern];
+    const before = pattern.slice(0, m.index);
+    const after = pattern.slice(m.index + m[0].length);
+    const parts = m[1].split(',');
+    const out = [];
+    for (const p of parts) {
+        for (const rest of expandBraces(after)) {
+            if (out.length >= MAX_BRACE_VARIANTS) {
+                throw new Error(`glob brace expansion exceeds ${MAX_BRACE_VARIANTS} variants`);
+            }
+            out.push(before + p + rest);
+        }
+    }
+    return out;
+}
+const REGEX_META = /[.+^${}()|[\]\\]/;
+function compileVariant(variant) {
+    let body = '';
+    for (let i = 0; i < variant.length; i++) {
+        const ch = variant[i];
+        if (ch === '*') {
+            // `**/` (at any position, including leading) means "zero-or-more
+            // directory segments" so `src/**/foo` matches both `src/foo` and
+            // `src/a/b/foo`. The older compile emitted `.*/` which forced at
+            // least one path char between, breaking the zero-dir case.
+            if (variant[i + 1] === '*' && variant[i + 2] === '/') {
+                body += '(?:.*/)?';
+                i += 2;
+            } else if (variant[i + 1] === '*') {
+                body += '.*';
+                i++;
+            } else {
+                body += '[^/]*';
+            }
+        } else if (ch === '?') {
+            body += '[^/]';
+        } else if (ch === '[') {
+            // Glob bracket class: [abc], [!abc], [a-z]. Parse forward to the
+            // closing `]`; only when a well-formed class is found do we emit
+            // a regex character class. Malformed/unclosed `[` falls back to
+            // a literal escape so REGEX_META semantics still hold.
+            let j = i + 1;
+            let negate = false;
+            if (variant[j] === '!' || variant[j] === '^') { negate = true; j++; }
+            // POSIX-style: a `]` as the first class char is a literal.
+            const innerStart = j;
+            if (variant[j] === ']') j++;
+            while (j < variant.length && variant[j] !== ']') j++;
+            if (j < variant.length && j > innerStart) {
+                // Escape backslashes inside the class; hyphens and other
+                // chars are passed through so `[a-z]` ranges still work.
+                const inner = variant.slice(innerStart, j).replace(/\\/g, '\\\\');
+                body += '[' + (negate ? '^' : '') + inner + ']';
+                i = j;
+            } else {
+                body += '\\[';
+            }
+        } else if (REGEX_META.test(ch)) {
+            body += '\\' + ch;
+        } else {
+            body += ch;
+        }
+    }
+    return body;
+}
+export function compileSimpleGlob(pattern) {
+    if (!pattern) return null;
+    // On Windows, treat backslashes as path separators — candidate paths are
+    // forward-slash normalized, so a literal-escaped `\` (REGEX_META) in e.g.
+    // `**\*.mjs` would never match a `/`-joined path. Mirrors the win32 `\`->`/`
+    // canonicalization the grep tool already applies.
+    if (process.platform === 'win32') pattern = pattern.replace(/\\/g, '/');
+    if (pattern.length > MAX_PATTERN_LENGTH) {
+        throw new Error(`glob pattern length ${pattern.length} exceeds limit ${MAX_PATTERN_LENGTH}`);
+    }
+    const variants = expandBraces(pattern).map(compileVariant);
+    const DOLLAR = '\x24';
+    const body = variants.length === 1 ? variants[0] : `(?:${variants.join('|')})`;
+    if (body.length > MAX_REGEX_BODY_LENGTH) {
+        throw new Error(`glob regex body length ${body.length} exceeds limit ${MAX_REGEX_BODY_LENGTH}`);
+    }
+    return new RegExp('^' + body + DOLLAR, 'i');
+}
+
+// Directory names that are dependency / build / cache artifacts. Skipped
+// by default in list / tree / find_files traversal so the response shape
+// reflects user code, not transitive tooling output. Pass
+// `include_noise:true` on the tool call to traverse them.
+// Policy note: exclusion is basename-only at every depth — a directory
+// literally named e.g. `dist` is skipped regardless of where in the tree
+// it appears. Context-aware exclusion (e.g. only skip `dist` adjacent to
+// a package.json) is intentionally not implemented; the basename rule is
+// simpler and matches the noise patterns developers actually create.
+export const NOISE_DIR_NAMES = new Set([
+    'node_modules', '.git',
+    'dist', 'build', 'out', 'target',
+    '.next', '.nuxt', '.svelte-kit',
+    '.cache', '.parcel-cache', '.turbo',
+    'venv', '.venv', '__pycache__', '.pytest_cache',
+    '.gradle', 'coverage',
+    'refs',
+]);
+
+export const MAX_WALK_ENTRIES = 200_000;
+
+// Unified directory walk used by list / tree / find_files. The visitor
+// callback owns the "should I record this entry?" decision; returning
+// literal false aborts the whole walk.
+// `onWarn(dir, err)` (optional) is invoked for any readdir failure so
+// callers can surface skipped paths instead of silently dropping them.
+export async function walkDir(root, { hidden = false, maxDepth = Infinity, visit, sort, excludeDirNames, onWarn, maxEntries = MAX_WALK_ENTRIES, signal } = {}) {
+    // Windows filesystems are case-insensitive — match exclusion names the
+    // same way so e.g. Node_Modules is pruned like node_modules.
+    const _exclCI = process.platform === 'win32' && excludeDirNames && excludeDirNames.size > 0
+        ? new Set([...excludeDirNames].map((n) => n.toLowerCase()))
+        : null;
+    let truncated = false;
+    const cap = maxEntries;
+    let entriesVisited = 0;
+    const _walk = async (dir, depth) => {
+        if (signal?.aborted) {
+            truncated = true;
+            return false;
+        }
+        if (entriesVisited >= cap) {
+            truncated = true;
+            return false;
+        }
+        if (depth > maxDepth) return true;
+        let entries;
+        try { entries = await readdir(dir, { withFileTypes: true }); }
+        catch (err) {
+            if (typeof onWarn === 'function') {
+                try { onWarn(dir, err); } catch { /* warning sink must not abort */ }
+            }
+            return true;
+        }
+        if (!hidden) entries = entries.filter(e => !e.name.startsWith('.'));
+        if (excludeDirNames && excludeDirNames.size > 0) {
+            entries = entries.filter(e => !(e.isDirectory() && (_exclCI
+                ? _exclCI.has(e.name.toLowerCase())
+                : excludeDirNames.has(e.name))));
+        }
+        if (sort) entries.sort(sort);
+        const total = entries.length;
+        for (let i = 0; i < total; i++) {
+            if (signal?.aborted) {
+                truncated = true;
+                return false;
+            }
+            if (entriesVisited >= cap) {
+                truncated = true;
+                return false;
+            }
+            entriesVisited += 1;
+            const ent = entries[i];
+            const entPath = join(dir, ent.name);
+            const ctx = { depth, index: i, total, isLast: i === total - 1 };
+            const cont = visit(ent, entPath, ctx);
+            if (cont === false) return false;
+            if (ent.isDirectory()) {
+                if ((await _walk(entPath, depth + 1)) === false) return false;
+            }
+        }
+        return true;
+    };
+    await _walk(root, 1);
+    return { truncated, entriesVisited };
+}