mixdog 0.9.38 → 0.9.40

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

@@ -39,7 +39,7 @@ 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 verified file path(s); guessed path → find first (same turn as other probes). Batch paths/regions as real arrays in one call. Not for directory listing.',
+        description: 'Read verified file path(s); guessed path/name → find first. Array-first: batch paths/regions as real arrays in one call; put targets in path[] or {path,offset,limit}[] and read the whole logical unit. Content_with_context is actionable; do not page or re-read returned spans. Not for directory listing.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -58,29 +58,31 @@ export const BUILTIN_TOOLS = [
                                             offset: { type: 'number', minimum: 0 },
                                             limit: { type: 'number', minimum: 1 },
                                         },
+                                        required: ['path'],
                                     },
                                 ],
                             },
                             minItems: 1,
                         },
                     ],
-                    description: 'Verified file path. Batch spans via path[] or {path,offset,limit}[] regions. Pass arrays directly; JSON strings are legacy recovery only.',
+                    description: 'Verified file path; use {path,offset,limit}[] targets. Pass arrays directly; JSON strings are legacy recovery only.',
                 },
-                offset: { type: 'number', minimum: 0, description: 'Numeric lines to skip before reading; 0 starts at line 1. Continue with offset:N.' },
-                limit: { type: 'number', minimum: 1, description: 'Numeric max lines to return after offset.' },
+                offset: { type: 'number', minimum: 0, description: 'Numeric lines to skip; 0 starts at line 1. Continue with offset:N.' },
+                limit: { type: 'number', minimum: 1, description: 'Numeric max lines after offset.' },
             },
+            required: ['path'],
         },
     },
     {
         name: 'shell',
         title: 'Mixdog Shell',
         annotations: { title: 'Mixdog Shell', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, compressible: true },
-        description: `Run programs or change system state. Set shell: powershell or bash. Not for reading, listing, or searching files. Batch independent commands: ;/&& in one call, or parallel calls in the same turn.${_shellSyntaxCheat} ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
+        description: `Run programs or change system state; set shell: powershell or bash. Not for reading, listing or searching. Shell/write calls are serial; use ;/&& only for intentional in-command sequencing.${_shellSyntaxCheat} ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
         inputSchema: {
             type: 'object',
             properties: {
                 command: { type: 'string', description: 'Command.' },
-                cwd: { type: 'string', description: 'Working directory. Persists across shell calls in a session — omit to reuse the previous command\'s directory (e.g. after cd); pass an absolute path to change it.' },
+                cwd: { type: 'string', description: 'Working directory; persists across calls. Omit to reuse; absolute path changes it.' },
                 timeout: { type: 'number', description: `Timeout ms. Default ${_shellDefaultTimeoutMs()} (${_shellDefaultTimeoutMs() / 60000} min) when omitted; an explicit value is honored uncapped — long-running commands may set it higher. On timeout the command is MOVED TO BACKGROUND (a task_id you can wait/status/read/cancel) and keeps running instead of being killed; sleep-like commands and MIXDOG_SHELL_DISABLE_BACKGROUND_TASKS opt out (killed with a [timeout] marker). async/background runs with timeout omitted have NO timeout (run until done/cancelled); an explicit timeout is still enforced.` },
                 merge_stderr: { type: 'boolean', description: 'Merge stderr.' },
                 mode: { type: 'string', enum: ['sync', 'async'], description: executionModeSchemaDescription('sync') },
@@ -93,12 +95,12 @@ export const BUILTIN_TOOLS = [
         name: 'task',
         title: 'Background Task Control',
         annotations: { title: 'Background Task Control', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-        description: `Manual control for shell async task_id. actions: list/status/read/wait/cancel. ${TOOL_MANUAL_CONTROL_CONTRACT} Not sess_* or agent ids.`,
+        description: `Control a shell async task_id: actions list/status/read/wait/cancel. ${TOOL_MANUAL_CONTROL_CONTRACT} Not sess_* or agent ids.`,
         inputSchema: {
             type: 'object',
             properties: {
                 task_id: { type: 'string', description: 'shell async task_id.' },
-                action: { type: 'string', enum: ['list', 'status', 'read', 'wait', 'cancel'], description: 'Manual action. Avoid polling loops.' },
+                action: { type: 'string', enum: ['list', 'status', 'read', 'wait', 'cancel'], description: 'Action; avoid polling loops.' },
                 timeout_ms: { type: 'number', description: 'Wait timeout ms.' },
                 poll_ms: { type: 'number', description: 'Wait poll ms.' },
             },
@@ -109,7 +111,7 @@ export const BUILTIN_TOOLS = [
         name: 'grep',
         title: 'Mixdog Grep',
         annotations: { title: 'Mixdog Grep', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Exact text/regex in verified scope (project root counts as verified — unscoped search needs no find). Only a guessed path fragment → find first, same turn. No path "." + guessed src/**. Broad: files_with_matches/count; narrow: content_with_context.',
+        description: 'Quoted/non-identifier literal or regex→grep. Search in verified scope (project root counts as verified); guessed path fragment → find first. Omitted output_mode and content_with_context are contextual; a nonzero content_with_context result resolves that search concept—act directly, without regex tweaks, narrowing or re-search. Choose files_with_matches/count for existence; Only zero/error results may change tokens or scope. No path "." + guessed src/**.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -118,14 +120,14 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Text/regex. Array = variants in one call.',
+                    description: 'Text/regex. Array = variants in one call; pattern[] batches tokens. path[] batches verified scopes only; file/span reads use read path[] regions.',
                 },
                 path: {
                     anyOf: [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Verified file/dir, or project root; guessed → find first.',
+                    description: 'Verified file/dir or project root; guessed → find first.',
                 },
                 glob: {
                     anyOf: [
@@ -134,21 +136,24 @@ export const BUILTIN_TOOLS = [
                     ],
                     description: 'Glob filter; no guessed src/** under path ".".',
                 },
-                output_mode: { type: 'string', enum: ['content_with_context', 'content', 'files_with_matches', 'count'], description: 'Broad: files_with_matches/count; narrow: content_with_context.' },
+                output_mode: { type: 'string', enum: ['content_with_context', 'files_with_matches', 'count'], description: 'Omitted/contextual content; content_with_context; files_with_matches/count are existence modes. Legacy content is runtime-compatible, not public.' },
                 head_limit: { type: 'number', minimum: 0, description: 'Max results.' },
                 offset: { type: 'number', minimum: 0, description: 'Skip results for paging.' },
                 '-A': { type: 'number', minimum: 0, description: 'Lines after each match.' },
                 '-B': { type: 'number', minimum: 0, description: 'Lines before each match.' },
                 '-C': { type: 'number', minimum: 0, description: 'Lines before/after each match.' },
             },
-            required: [],
+            anyOf: [
+                { required: ['pattern'] },
+                { required: ['glob'] },
+            ],
         },
     },
     {
         name: 'glob',
         title: 'Mixdog Glob',
         annotations: { title: 'Mixdog Glob', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Exact glob from verified roots (project root is verified). Guessed root/name → find first, same turn. No path "." + guessed src/**. Batch arrays.',
+        description: 'Exact glob from verified roots (project root is verified); guessed root/name → find first. Array-first: batch related pattern[]/path[]. No path "." + guessed src/**.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -157,14 +162,14 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Exact glob pattern(s). Batch related patterns as pattern[] in one call.',
+                    description: 'Exact glob pattern(s); batch related pattern[].',
                 },
                 path: {
                     anyOf: [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Verified base dir(s) or project root; guessed → find first. Batch path[].',
+                    description: 'Verified base dir(s)/project root; guessed → find first; batch path[].',
                 },
                 head_limit: { type: 'number', description: 'Max entries.' },
                 offset: { type: 'number', description: 'Skip entries.' },
@@ -176,7 +181,7 @@ export const BUILTIN_TOOLS = [
         name: 'find',
         title: 'Mixdog Find Files',
         annotations: { title: 'Mixdog Find Files', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Partial path/name lookup incl dot dirs; verify roots before grep/glob. Batch query[].',
+        description: 'Partial path/name lookup only for unknown partial paths/names (including dot dirs); verify roots before grep/glob. Not for the project root or already-verified roots. Output paths are verified downstream. Array-first: batch query[].',
         inputSchema: {
             type: 'object',
             properties: {
@@ -185,7 +190,7 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Partial path/name words (not file contents), or query[] to batch lookups in one call.',
+                    description: 'Partial path/name words, not contents; query[] batches lookups.',
                 },
                 path: { type: 'string', description: 'Base directory.' },
                 head_limit: { type: 'number', description: 'Max paths.' },
@@ -197,7 +202,7 @@ export const BUILTIN_TOOLS = [
         name: 'list',
         title: 'Mixdog List Directory',
         annotations: { title: 'Mixdog List Directory', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'List verified directories (project root included). Guessed dir → find first. Batch dirs as path[].',
+        description: 'List verified directories (project root included); Guessed dir → find first. Array-first: batch independent dirs as path[].',
         inputSchema: {
             type: 'object',
             properties: {
@@ -206,7 +211,7 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Verified directory, or path[] to list several directories in one call.',
+                    description: 'Verified directory; path[] batches directories.',
                 },
                 head_limit: { type: 'number', description: 'Max entries.' },
                 offset: { type: 'number', description: 'Skip N entries for paging.' },

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

@@ -19,10 +19,13 @@ export const FS_REACHABILITY_DEADLINE_MS = 5000;
 // error). Reject with EFSUNREACHABLE only when the stat itself exceeds the
 // deadline, which is the dead-mount / hung-FS signature.
 export async function assertPathReachable(path, deadlineMs = FS_REACHABILITY_DEADLINE_MS) {
-    if (typeof path !== 'string' || path.length === 0) return;
+    if (typeof path !== 'string' || path.length === 0) return null;
     const ms = Number(deadlineMs) > 0 ? Number(deadlineMs) : FS_REACHABILITY_DEADLINE_MS;
     let timer = null;
-    const probe = stat(path).then(() => true, () => true); // any answer = reachable
+    // Resolve to the Stats on success so a caller can seed its stat cache and
+    // avoid an immediate redundant synchronous re-stat of the same path; a
+    // clean FS rejection (ENOENT/EACCES) resolves to null (still "reachable").
+    const probe = stat(path).then((s) => s, () => null);
     const deadline = new Promise((resolve) => {
         timer = setTimeout(() => resolve('TIMEOUT'), ms);
     });
@@ -37,6 +40,7 @@ export async function assertPathReachable(path, deadlineMs = FS_REACHABILITY_DEA
         err.code = 'EFSUNREACHABLE';
         throw err;
     }
+    return result; // Stats on success, null on a clean FS rejection
 }
 
 // Batch variant: reject if ANY path is unreachable. Runs probes concurrently so

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

@@ -25,62 +25,69 @@ function isHump(prevCh, ch) {
         && /[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) {
+function prepareFuzzyScore(query) {
     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;
+    return (str) => {
+        const s = str.toLowerCase();
+        const slen = s.length;
+        if (qlen === 0) return 0;
+        if (qlen > slen) return null;
 
-        score += 1; // base point per matched char
+        const lastSep = Math.max(str.lastIndexOf('/'), str.lastIndexOf('\\'));
 
-        if (found === prevMatch + 1) score += 5; // contiguous run
+        let score = 0;
+        let si = 0;
+        let prevMatch = -2;
+        let firstMatchIdx = -1;
 
-        const prevCh = found > 0 ? str[found - 1] : undefined;
-        if (prevCh === undefined || isBoundaryChar(prevCh) || isHump(prevCh, str[found])) {
-            score += 8; // word-boundary start
-        }
+        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;
 
-        if (str[found] === normalizedQuery[qi]) score += 1; // exact-case tie-break
+            score += 1; // base point per matched char
 
-        prevMatch = found;
-        si = found + 1;
-    }
+            if (found === prevMatch + 1) score += 5; // contiguous run
 
-    // 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;
+            const prevCh = found > 0 ? str[found - 1] : undefined;
+            if (prevCh === undefined || isBoundaryChar(prevCh) || isHump(prevCh, str[found])) {
+                score += 8; // word-boundary start
+            }
 
-    // Mild pulls: shorter candidates and earlier first matches rank higher.
-    score -= Math.floor(slen / 16);
-    score -= Math.floor(firstMatchIdx / 8);
+            if (str[found] === normalizedQuery[qi]) score += 1; // exact-case tie-break
 
-    return score;
+            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;
+    };
+}
+
+/**
+ * @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) {
+    const scorer = prepareFuzzyScore(query);
+    return typeof scorer === 'function' ? scorer(str) : scorer;
 }
 
 // Below this per-query-char score, a subsequence-only match (query chars in
@@ -97,6 +104,53 @@ function normalizeForContains(s) {
     return String(s || '').toLowerCase().replace(/[\/\\_.\-\s]+/g, '');
 }
 
+function compareRanked(a, b) {
+    return (b.score - a.score)
+        || (a.item.path < b.item.path ? -1 : a.item.path > b.item.path ? 1 : 0);
+}
+
+function compareRankedNodes(a, b) {
+    return compareRanked(a.entry, b.entry) || (a.ordinal - b.ordinal);
+}
+
+function siftDownRankedHeap(heap, index) {
+    for (;;) {
+        const left = index * 2 + 1;
+        const right = left + 1;
+        let worst = index;
+        if (left < heap.length && compareRankedNodes(heap[left], heap[worst]) > 0) worst = left;
+        if (right < heap.length && compareRankedNodes(heap[right], heap[worst]) > 0) worst = right;
+        if (worst === index) return;
+        const node = heap[index];
+        heap[index] = heap[worst];
+        heap[worst] = node;
+        index = worst;
+    }
+}
+
+// Keep the worst retained candidate at index zero. The ordinal completes the
+// public comparator only for heap bookkeeping, preserving stable-sort behavior
+// for duplicate score/path entries.
+function retainTopRanked(heap, entry, ordinal, limit) {
+    const node = { entry, ordinal };
+    if (heap.length < limit) {
+        heap.push(node);
+        for (let index = heap.length - 1; index > 0;) {
+            const parent = Math.floor((index - 1) / 2);
+            if (compareRankedNodes(heap[index], heap[parent]) <= 0) break;
+            const parentNode = heap[parent];
+            heap[parent] = heap[index];
+            heap[index] = parentNode;
+            index = parent;
+        }
+        return;
+    }
+    if (compareRankedNodes(node, heap[0]) < 0) {
+        heap[0] = node;
+        siftDownRankedHeap(heap, 0);
+    }
+}
+
 /**
  * Rank candidates by fuzzy score against `query`, dropping non-matches.
  * @param {string} query
@@ -106,30 +160,41 @@ function normalizeForContains(s) {
  */
 export function fuzzyRank(query, items, limit = 0) {
     const normQuery = normalizeForContains(query);
+    const score = prepareFuzzyScore(query);
     // Floor scales with query length: a scattered subsequence earns ~1 point
     // per char, while any contiguous run (+5/char) or word-boundary hit
     // (+8) pushes a genuine match well past 4/char.
     const floor = normQuery.length * SUBSEQUENCE_MIN_PER_CHAR;
     const scored = [];
-    for (const item of items) {
+    // Preserve slice's legacy coercion behavior for non-integer public callers;
+    // normal tool limits are positive integers and take the bounded fast path.
+    const bounded = Number.isInteger(limit) && limit > 0;
+    for (let ordinal = 0; ordinal < items.length; ordinal++) {
+        const item = items[ordinal];
         const p = String(item.path || '');
-        const pathScore = fuzzyScore(query, p);
-        const base = p.split(/[\\/]/).pop() || '';
-        const baseScore = fuzzyScore(query, base);
+        const lastSep = Math.max(p.lastIndexOf('/'), p.lastIndexOf('\\'));
+        const base = p.slice(lastSep + 1);
+        const pathScore = typeof score === 'function' ? score(p) : score;
+        const baseScore = typeof score === 'function' ? score(base) : score;
         const sc = Math.max(pathScore ?? -Infinity, baseScore === null ? -Infinity : baseScore + 40);
         if (!Number.isFinite(sc)) continue;
         // Strong match: the query (separators stripped) is a contiguous
         // substring of the basename or the full path. These ALWAYS pass so an
         // exact substring/basename hit can never be starved out as noise.
-        const strong = normQuery.length > 0
-            && (normalizeForContains(base).includes(normQuery)
-                || normalizeForContains(p).includes(normQuery));
+        const strong = normQuery.length > 0 && normalizeForContains(p).includes(normQuery);
         // Otherwise it is subsequence-only: keep it only if it clears the
         // per-char floor. Weak scattered matches (the pgAdmin-style junk that
         // merely contains the query chars in order) fall below it and drop out.
         if (!strong && sc < floor) continue;
-        scored.push({ item, score: sc });
+        const entry = { item, score: sc };
+        if (bounded) retainTopRanked(scored, entry, ordinal, limit);
+        else scored.push(entry);
+    }
+    if (!bounded) {
+        scored.sort(compareRanked);
+        return limit > 0 ? scored.slice(0, limit) : scored;
     }
-    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;
+    return scored
+        .sort(compareRankedNodes)
+        .map(({ entry }) => entry);
 }