@nexrall/code-core 1.3.0 → 1.4.0

package/dist/tools/executor.js

@@ -43,13 +43,25 @@ const dns = __importStar(require("dns"));
 const child_process_1 = require("child_process");
 const sandbox_1 = require("./sandbox");
 const auth_1 = require("../auth");
+const editCompleteness_1 = require("../agent/editCompleteness");
+const crossFile_1 = require("../agent/crossFile");
 const client_1 = require("../api/client");
 const symbols_1 = require("./symbols");
+const tsLangService_1 = require("./tsLangService");
 // ─── Constants ────────────────────────────────────────────────────────────────
 const DEFAULT_TIMEOUT_MS = 60000;
 const MAX_FETCH_BYTES = 200 * 1024; // 200 KB
 const MAX_READ_BYTES = 500 * 1024; // 500 KB
 const MAX_OUTPUT_CHARS = 100000; // bash / grep output cap (~100 KB)
+// GAP B — output spillover. The inline bash result keeps only HEAD+TAIL (~100 KB),
+// which loses the MIDDLE of a large log — often exactly where a stack trace's root
+// cause or a failing assertion lives. To make the full log recoverable WITHOUT
+// bloating the model context, we stream the complete stdout+stderr to a temp file
+// (bounded by MAX_SPILL_BYTES) and tell the model it can `read_file` that path with
+// offset/limit to inspect any section. This is the key long-debug capability: the
+// agent decides which slice of a 5 MB log it needs, instead of us guessing.
+const MAX_SPILL_BYTES = 20 * 1024 * 1024; // 20 MB cap on a single spill file
+const SPILL_DIR = path.join(os.tmpdir(), 'nexrall-code', 'bash-output');
 // ─── Blocked commands (safety) ────────────────────────────────────────────────
 // Regexes are tested against the LOWERCASED command so case variants and minor
 // spacing differences (double spaces, no-space pipes) are all caught.
@@ -59,10 +71,15 @@ const MAX_OUTPUT_CHARS = 100000; // bash / grep output cap (~100 KB)
 // hidden in a fake heredoc/quote (e.g. `echo "<<EOF"\nrm -rf /\nEOF`) is still
 // caught.
 const BLOCKED_REGEXES = [
-    // Filesystem destruction — match rm/chmod with any whitespace between flags
-    /rm\s+-rf\s+\//, // rm -rf /… (any path under /)
-    /rm\s+-rf\s+~/, // rm -rf ~
-    /rm\s+-rf\s+\*/, // rm -rf *
+    // Filesystem destruction — match rm/chmod with any whitespace between flags.
+    // Only root itself and BARE top-level system dirs are blocked; ordinary
+    // absolute subpaths (/tmp/x, /var/folders/x, /Users/me/proj/node_modules)
+    // must stay allowed — the old /rm\s+-rf\s+\// matched every absolute path.
+    // `-[a-z]*(?:rf|fr)[a-z]*` accepts -rf, -fr, -rfv, -vrf … (combined flag).
+    /rm\s+-[a-z]*(?:rf|fr)[a-z]*\s+\/(?:\*|\s|;|&|\||$)/, // rm -rf /  ·  / *  ·  root, bare
+    /rm\s+-[a-z]*(?:rf|fr)[a-z]*\s+\/(?:bin|sbin|etc|usr|var|lib|lib64|boot|sys|proc|dev|root|home|system|library|applications|opt|users)(?:\/)?(?:\*|\s|;|&|\||$)/, // rm -rf /etc … bare system dir
+    /rm\s+-[a-z]*(?:rf|fr)[a-z]*\s+~(?:\/)?(?:\*|\s|;|&|\||$)/, // rm -rf ~  ·  ~/  ·  ~/*
+    /rm\s+-[a-z]*(?:rf|fr)[a-z]*\s+\*/, // rm -rf *
     /rm\s+--no-preserve-root/,
     /chmod\s+-[rr]\s+777\s+\//,
     /chown\s+-[rr]/,
@@ -199,6 +216,59 @@ function isBinaryFile(filePath) {
         return false;
     }
 }
+/**
+ * Read a bounded line window [offset, offset+limit) from a file too large to load
+ * whole, by streaming it in chunks and keeping only the requested lines. Memory is
+ * bounded by (limit lines actually kept) + one chunk, never the whole file — so a
+ * 20MB bash-output spill file can be inspected section-by-section. (GAP B.)
+ */
+async function readLargeFileWindow(resolved, offset, limit, kb) {
+    return new Promise((resolve) => {
+        const endLine = offset + limit; // exclusive, 0-based
+        const kept = [];
+        let lineNo = 0; // 0-based index of the NEXT line to be completed
+        let carry = ''; // partial line spanning chunk boundaries
+        let stopped = false;
+        const stream = fs.createReadStream(resolved, { encoding: 'utf-8', highWaterMark: 256 * 1024 });
+        const finish = () => {
+            if (stopped)
+                return;
+            stopped = true;
+            stream.destroy();
+            const first = offset + 1;
+            const last = offset + kept.length;
+            const numbered = kept.map((l, i) => `${String(offset + i + 1).padStart(4, ' ')}\t${l}`).join('\n');
+            const note = kept.length < limit
+                ? ` (reached end of file at line ${last})`
+                : ` (more lines follow — increase offset to continue)`;
+            resolve({ output: `[File: ${resolved} — ${kb} KB, showing lines ${first}-${last}${note}]\n${numbered}` });
+        };
+        stream.on('data', (chunk) => {
+            const text = carry + (typeof chunk === 'string' ? chunk : chunk.toString('utf-8'));
+            const lines = text.split('\n');
+            carry = lines.pop() ?? ''; // last element is an incomplete line (or '')
+            for (const line of lines) {
+                if (lineNo >= offset && lineNo < endLine)
+                    kept.push(line);
+                lineNo++;
+                if (lineNo >= endLine) {
+                    finish();
+                    return;
+                }
+            }
+        });
+        stream.on('end', () => {
+            // Flush the final carry (file not ending in newline) if it's in range.
+            if (!stopped && carry !== '' && lineNo >= offset && lineNo < endLine)
+                kept.push(carry);
+            finish();
+        });
+        stream.on('error', (err) => { if (!stopped) {
+            stopped = true;
+            resolve({ error: err.message });
+        } });
+    });
+}
 async function readFile(input, workDir) {
     const filePath = typeof input.path === 'string' ? input.path : '';
     const offset = typeof input.offset === 'number' ? Math.max(0, Math.floor(input.offset)) : 0;
@@ -208,17 +278,22 @@ async function readFile(input, workDir) {
     try {
         const resolved = resolvePath(filePath, workDir);
         const stat = fs.statSync(resolved);
-        // Always enforce size cap — even with offset/limit we still readFileSync the whole
-        // file before slicing, so a 500 MB file would OOM regardless of the slice range.
-        if (stat.size > MAX_READ_BYTES) {
-            const kb = (stat.size / 1024).toFixed(0);
-            return { error: `File too large (${kb} KB, max ${MAX_READ_BYTES / 1024} KB). Use offset+limit to read sections, or search_files to locate the relevant part first.` };
-        }
         // Reject binary files early — reading them as UTF-8 produces garbage.
         if (isBinaryFile(resolved)) {
             const ext = path.extname(resolved).toLowerCase();
             return { error: `Cannot read binary file: ${resolved} (${ext || 'no extension'}). Use a text-based tool or convert it first.` };
         }
+        // Large-file path: when the file exceeds the in-memory cap, a full readFileSync
+        // would OOM — but we must still be able to inspect SECTIONS (this is what makes a
+        // 20MB bash-output spill file usable, GAP B). If offset+limit are given we stream
+        // line-by-line and materialise only the requested window; otherwise we require it.
+        if (stat.size > MAX_READ_BYTES) {
+            const kb = (stat.size / 1024).toFixed(0);
+            if (limit <= 0) {
+                return { error: `File too large (${kb} KB, max ${MAX_READ_BYTES / 1024} KB). Pass offset + limit to read a section (e.g. {offset:0, limit:500}), or search_files to locate the relevant part first.` };
+            }
+            return await readLargeFileWindow(resolved, offset, limit, kb);
+        }
         const content = fs.readFileSync(resolved, 'utf-8');
         const allLines = content.split('\n');
         const totalLines = allLines.length;
@@ -255,14 +330,32 @@ async function writeFile(input, workDir) {
         if (!isNew && content === '') {
             return { error: `Refusing to overwrite ${resolved} with empty content. Provide the full file content or use edit_file for targeted changes.` };
         }
+        // Edit-completeness guard: refuse writes that elide code with a placeholder
+        // ("// ... rest of the code unchanged") — a silent, irreversible data loss —
+        // or that still contain unresolved merge-conflict markers. Opt-out with
+        // NEXRALL_ALLOW_ELIDED_WRITE=1 for the rare intentional case.
+        if (process.env.NEXRALL_ALLOW_ELIDED_WRITE !== '1') {
+            const problem = (0, editCompleteness_1.checkEditCompleteness)(content, !isNew);
+            if (problem) {
+                if (problem.kind === 'elision-placeholder') {
+                    return { error: `Refusing to write ${resolved}: ${problem.reason}.\nOffending line: ${problem.sample}\nwrite_file must contain the COMPLETE file — never a "rest unchanged" placeholder. Send the full content, or use edit_file/multi_edit for a targeted change so surrounding code is preserved.` };
+                }
+                return { error: `Refusing to write ${resolved}: ${problem.reason}.\nOffending line: ${problem.sample}\nResolve the conflict (remove <<<<<<< / ======= / >>>>>>> markers and keep the intended code) before writing.` };
+            }
+        }
         // Preserve file permissions (mode bits) when overwriting an existing file.
         // writeFileSync creates new files with umask-default mode, stripping +x etc.
         let existingMode;
+        let priorContent = '';
         if (!isNew) {
             try {
                 existingMode = fs.statSync(resolved).mode;
             }
             catch { /* ignore */ }
+            try {
+                priorContent = fs.readFileSync(resolved, 'utf-8');
+            }
+            catch { /* ignore */ }
         }
         fs.writeFileSync(resolved, content, 'utf-8');
         if (existingMode !== undefined) {
@@ -276,7 +369,8 @@ async function writeFile(input, workDir) {
         if (isNew) {
             return { output: `Created ${resolved} (${lines} lines, ${bytes} bytes)` };
         }
-        return { output: `Overwrote ${resolved} (${lines} lines, ${bytes} bytes)` };
+        const xfile = crossFileBreakageWarning(resolved, normalizeLF(priorContent), normalizeLF(content), workDir ?? process.cwd());
+        return { output: `Overwrote ${resolved} (${lines} lines, ${bytes} bytes)${xfile}` };
     }
     catch (err) {
         return { error: err.message };
@@ -335,11 +429,44 @@ function startBackgroundShell(command, displayCommand, workDir, note) {
     const shell = {
         id, command: displayCommand, child, output: '', readCursor: 0, truncated: false,
         status: 'running', exitCode: null,
+        spillPath: null, spillFd: null, spillBytes: 0, spillFull: false,
     };
     // Rolling buffer: keep the LAST MAX_OUTPUT_CHARS instead of the first, so a
     // long-lived watcher/dev-server's recent output (the useful part) is never
-    // permanently lost behind an early cap.
+    // permanently lost behind an early cap. In parallel, once output exceeds the
+    // inline cap we mirror the FULL stream to a bounded spill file (GAP B) so the
+    // discarded earlier output is still recoverable via read_file.
     const append = (chunk) => {
+        if (shell.spillPath || shell.output.length + chunk.length > MAX_OUTPUT_CHARS) {
+            if (!shell.spillPath && !shell.spillFull) {
+                try {
+                    fs.mkdirSync(SPILL_DIR, { recursive: true });
+                    shell.spillPath = path.join(SPILL_DIR, `${id}-${Date.now()}.log`);
+                    shell.spillFd = fs.openSync(shell.spillPath, 'w');
+                    fs.writeSync(shell.spillFd, shell.output); // backfill what we already have
+                }
+                catch {
+                    shell.spillPath = null;
+                    shell.spillFd = null;
+                }
+            }
+            if (shell.spillFd !== null && !shell.spillFull) {
+                const buf = Buffer.from(chunk, 'utf-8');
+                const room = MAX_SPILL_BYTES - shell.spillBytes;
+                if (room <= 0) {
+                    shell.spillFull = true;
+                }
+                else {
+                    try {
+                        fs.writeSync(shell.spillFd, room >= buf.length ? buf : buf.subarray(0, room));
+                        shell.spillBytes += Math.min(room, buf.length);
+                        if (buf.length > room)
+                            shell.spillFull = true;
+                    }
+                    catch { /* degrade to inline-only */ }
+                }
+            }
+        }
         shell.output += chunk;
         if (shell.output.length > MAX_OUTPUT_CHARS) {
             // Drop from the front but never behind the read cursor's logical position;
@@ -355,6 +482,13 @@ function startBackgroundShell(command, displayCommand, workDir, note) {
     child.on('close', (code) => {
         shell.status = shell.status === 'killed' ? 'killed' : 'exited';
         shell.exitCode = code;
+        if (shell.spillFd !== null) {
+            try {
+                fs.closeSync(shell.spillFd);
+            }
+            catch { /* ignore */ }
+            shell.spillFd = null;
+        }
         // Evict oldest exited shell once map grows past 50 to prevent session-long leak
         if (_bgShells.size > 50) {
             for (const [k, v] of _bgShells) {
@@ -382,7 +516,9 @@ async function bashOutput(input) {
     const statusLine = shell.status === 'running'
         ? '[still running]'
         : `[${shell.status}${shell.exitCode != null ? `, exit ${shell.exitCode}` : ''}]`;
-    const trunc = shell.truncated ? '\n[output truncated at 100KB]' : '';
+    const trunc = shell.truncated
+        ? `\n[output truncated at 100KB${shell.spillPath ? `; full log at ${shell.spillPath} — read_file with offset/limit` : ''}]`
+        : '';
     return { output: `Shell ${id} ${statusLine}\n${fresh || '(no new output)'}${trunc}` };
 }
 async function killShell(input) {
@@ -491,8 +627,66 @@ async function bash(input, abortSignal, sandbox, workDir) {
         let totalLen = 0;
         let truncated = false;
         let settled = false;
+        // GAP B — full-output spill. We lazily open a temp file the FIRST time output
+        // exceeds the inline budget and stream everything to it (bounded), so the
+        // complete log survives even though the inline result is HEAD+TAIL only. The
+        // model is told the path and can read_file it with offset/limit.
+        let spillPath = null;
+        let spillFd = null;
+        let spillBytes = 0;
+        let spillFull = false;
+        const openSpill = () => {
+            if (spillPath || spillFull)
+                return;
+            try {
+                fs.mkdirSync(SPILL_DIR, { recursive: true });
+                spillPath = path.join(SPILL_DIR, `bash-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.log`);
+                spillFd = fs.openSync(spillPath, 'w');
+            }
+            catch {
+                spillPath = null;
+                spillFd = null;
+            } // spill is best-effort; never break the command
+        };
+        const writeSpill = (chunk) => {
+            if (spillFull || spillFd === null)
+                return;
+            const buf = Buffer.from(chunk, 'utf-8');
+            const room = MAX_SPILL_BYTES - spillBytes;
+            if (room <= 0) {
+                spillFull = true;
+                return;
+            }
+            try {
+                fs.writeSync(spillFd, room >= buf.length ? buf : buf.subarray(0, room));
+                spillBytes += Math.min(room, buf.length);
+                if (buf.length > room)
+                    spillFull = true;
+            }
+            catch { /* disk full / closed — degrade to inline-only */ }
+        };
+        const closeSpill = () => {
+            if (spillFd !== null) {
+                try {
+                    fs.closeSync(spillFd);
+                }
+                catch { /* ignore */ }
+                spillFd = null;
+            }
+        };
         const appendOutput = (chunk) => {
             totalLen += chunk.length;
+            // Mirror the full stream to the spill file once we know output is large.
+            if (spillPath || totalLen > MAX_OUTPUT_CHARS) {
+                if (!spillPath) {
+                    openSpill();
+                    if (spillPath) {
+                        writeSpill(head);
+                        writeSpill(tail);
+                    }
+                }
+                writeSpill(chunk);
+            }
             if (head.length < HEAD_CHARS) {
                 const room = HEAD_CHARS - head.length;
                 head += chunk.slice(0, room);
@@ -508,10 +702,14 @@ async function bash(input, abortSignal, sandbox, workDir) {
             }
         };
         const collect = () => {
+            closeSpill();
             if (!truncated)
                 return head + tail;
             const omitted = totalLen - head.length - tail.length;
-            return `${head}\n\n[… ${omitted} chars omitted (kept first ${HEAD_CHARS / 1024}KB + last ${Math.round(TAIL_CHARS / 1024)}KB) …]\n\n${tail}`;
+            const spillNote = spillPath
+                ? ` Full output (${(totalLen / 1024).toFixed(0)}KB${spillFull ? '+, truncated at 20MB' : ''}) saved to ${spillPath} — read_file that path with offset/limit to inspect the omitted middle.`
+                : '';
+            return `${head}\n\n[… ${omitted} chars omitted (kept first ${HEAD_CHARS / 1024}KB + last ${Math.round(TAIL_CHARS / 1024)}KB).${spillNote} …]\n\n${tail}`;
         };
         const done = (code, signal, timedOut = false) => {
             if (settled)
@@ -574,6 +772,90 @@ function ripgrepAvailable() {
     }
     return _rgAvailable;
 }
+// ── Cross-file breakage warning ──────────────────────────────────────────────
+// After an edit removes/renames an exported symbol, scan the rest of the repo for
+// surviving references. Returns a short warning string (or '' when clean). Best-
+// effort, time-boxed, and never throws — a scan failure must not fail the edit.
+function crossFileBreakageWarning(editedAbsPath, oldContent, newContent, workDir) {
+    if (process.env.NEXRALL_CROSSFILE_CHECK === '0')
+        return '';
+    let removed;
+    try {
+        removed = (0, crossFile_1.findRemovedExports)(editedAbsPath, oldContent, newContent)
+            .filter((s) => (0, crossFile_1.isCheckableSymbol)(s.name));
+    }
+    catch {
+        return '';
+    }
+    if (!removed.length)
+        return '';
+    const editedReal = (() => { try {
+        return fs.realpathSync(editedAbsPath);
+    }
+    catch {
+        return editedAbsPath;
+    } })();
+    const hits = [];
+    const MAX_SYMBOLS = 8;
+    for (const sym of removed.slice(0, MAX_SYMBOLS)) {
+        const refs = scanReferences(sym.name, workDir, editedReal);
+        if (refs.length) {
+            const shown = refs.slice(0, 3).map((r) => `      ${r}`).join('\n');
+            const more = refs.length > 3 ? `\n      … and ${refs.length - 3} more` : '';
+            hits.push(`  • ${sym.kind} "${sym.name}" (removed/renamed) still referenced in:\n${shown}${more}`);
+        }
+    }
+    if (!hits.length)
+        return '';
+    return (`\n\n⚠ CROSS-FILE BREAKAGE: you removed/renamed exported symbol(s) still used elsewhere.\n` +
+        hits.join('\n') +
+        `\nUpdate these call-sites (or restore the symbol), then run a build/typecheck to confirm nothing is broken.`);
+}
+// Find files (other than the edited one) that reference `name` as a whole word.
+// Uses ripgrep when available (fast, .gitignore-aware), else a bounded grep -r.
+function scanReferences(name, workDir, excludeRealPath) {
+    const pattern = `\\b${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`;
+    const files = new Set();
+    try {
+        if (ripgrepAvailable()) {
+            const r = (0, child_process_1.spawnSync)('rg', ['-l', '--no-messages', '-e', pattern, '.'], {
+                cwd: workDir, encoding: 'utf-8', timeout: 8000, maxBuffer: 8 * 1024 * 1024,
+            });
+            if (r.stdout)
+                for (const line of r.stdout.split('\n')) {
+                    if (line.trim())
+                        files.add(line.trim());
+                }
+        }
+        else {
+            const r = (0, child_process_1.spawnSync)('grep', ['-rlI', '--exclude-dir=node_modules', '--exclude-dir=.git',
+                '--exclude-dir=dist', '--exclude-dir=.next', '-E', pattern, '.'], {
+                cwd: workDir, encoding: 'utf-8', timeout: 8000, maxBuffer: 8 * 1024 * 1024,
+            });
+            if (r.stdout)
+                for (const line of r.stdout.split('\n')) {
+                    if (line.trim())
+                        files.add(line.trim());
+                }
+        }
+    }
+    catch {
+        return [];
+    }
+    const rel = [];
+    for (const f of files) {
+        const abs = path.isAbsolute(f) ? f : path.join(workDir, f);
+        let real = abs;
+        try {
+            real = fs.realpathSync(abs);
+        }
+        catch { /* keep abs */ }
+        if (real === excludeRealPath)
+            continue; // the file we just edited
+        rel.push(path.relative(workDir, abs) || f);
+    }
+    return rel;
+}
 async function searchFiles(input, workDir) {
     const pattern = typeof input.pattern === 'string' ? input.pattern : '';
     const searchPath = typeof input.path === 'string' ? input.path : '.';
@@ -891,7 +1173,8 @@ async function editFile(input, workDir) {
         const diff = buildDiff(filePath, oldNorm, newNorm, origNorm);
         const linesBefore = origNorm.split('\n').length;
         const linesAfter = updated.split('\n').length;
-        return { output: `Edited ${resolved} (${linesBefore} → ${linesAfter} lines)\n\n${diff}` };
+        const xfile = crossFileBreakageWarning(resolved, origNorm, normalizeLF(updated), workDir ?? process.cwd());
+        return { output: `Edited ${resolved} (${linesBefore} → ${linesAfter} lines)\n\n${diff}${xfile}` };
     }
     catch (err) {
         return { error: err.message };
@@ -1140,7 +1423,11 @@ async function fetchUrl(input, _workDir, _redirectCount = 0) {
                 if (isHtml)
                     body = stripHtml(body);
                 const truncNote = truncated ? `\n\n[Truncated at ${MAX_FETCH_BYTES / 1024}KB]` : '';
-                resolve({ output: `HTTP ${status}\n\n${body}${truncNote}` });
+                // Prompt-injection mitigation: fetched web content is fully attacker-controlled
+                // (anyone can put "ignore previous instructions..." on a page). Wrap it in an
+                // explicit untrusted-data delimiter so the model treats it as DATA to read, not
+                // as instructions to follow — defense-in-depth alongside the system-prompt rule.
+                resolve({ output: `HTTP ${status}\n\n<untrusted_web_content url="${url}">\n${body}${truncNote}\n</untrusted_web_content>` });
             });
             res.on('error', (err) => resolve({ error: err.message }));
         });
@@ -1197,6 +1484,7 @@ async function multiEdit(input, workDir) {
         // Work in LF-normalised space so CRLF files match LF old_strings
         const wasCRLF = rawFile.includes('\r\n');
         let content = normalizeLF(rawFile);
+        const originalNorm = content; // captured before edits mutate `content`
         const diffs = [];
         for (let i = 0; i < edits.length; i++) {
             const edit = edits[i];
@@ -1223,9 +1511,10 @@ async function multiEdit(input, workDir) {
         // preserving the original mode bits (+x on scripts etc.).
         const finalContent = wasCRLF ? content.replace(/\n/g, '\r\n') : content;
         atomicWritePreservingMode(resolved, finalContent, pre.mode);
+        const xfile = crossFileBreakageWarning(resolved, originalNorm, content, workDir ?? process.cwd());
         return {
             output: `Applied ${edits.length} edit(s) to ${resolved}:\n` +
-                diffs.map((d, i) => `\n--- edit #${i + 1} ---\n${d}`).join('\n'),
+                diffs.map((d, i) => `\n--- edit #${i + 1} ---\n${d}`).join('\n') + xfile,
         };
     }
     catch (err) {
@@ -1665,7 +1954,46 @@ async function memoryRead(_input) {
         return { error: err.message };
     }
 }
-// ─── Tool Dispatch ────────────────────────────────────────────────────────────
+function semanticPreamble(input, workDir) {
+    const p = typeof input.path === 'string' ? input.path : '';
+    const line = typeof input.line === 'number' ? Math.floor(input.line) : 0;
+    const character = typeof input.character === 'number' ? Math.floor(input.character) : 0;
+    if (!p)
+        return { ok: false, err: { error: 'Missing required parameter: path' } };
+    if (line < 1 || character < 1)
+        return { ok: false, err: { error: 'line and character are 1-based and required' } };
+    let resolved;
+    try {
+        resolved = resolvePath(p, workDir);
+    }
+    catch (e) {
+        return { ok: false, err: { error: e.message } };
+    }
+    if (!(0, tsLangService_1.isTsLike)(resolved)) {
+        return { ok: false, err: { error: `Semantic navigation currently supports TypeScript/JavaScript only. For ${path.extname(resolved) || 'this file type'} use get_symbols / get_workspace_symbols (regex-based).` } };
+    }
+    return { ok: true, args: { workDir: workDir ?? process.cwd(), filePath: resolved, line, character } };
+}
+const NO_TS_SERVICE = 'No TypeScript language service available (install `typescript` in the project). Use get_workspace_symbols / get_symbols instead.';
+async function goToDefinition(input, workDir) {
+    const pre = semanticPreamble(input, workDir);
+    if (!pre.ok)
+        return pre.err;
+    return (0, tsLangService_1.tsGoToDefinition)(pre.args) ?? { error: NO_TS_SERVICE };
+}
+async function findReferences(input, workDir) {
+    const pre = semanticPreamble(input, workDir);
+    if (!pre.ok)
+        return pre.err;
+    const includeDeclaration = input.include_declaration !== false;
+    return (0, tsLangService_1.tsFindReferences)({ ...pre.args, includeDeclaration }) ?? { error: NO_TS_SERVICE };
+}
+async function getHover(input, workDir) {
+    const pre = semanticPreamble(input, workDir);
+    if (!pre.ok)
+        return pre.err;
+    return (0, tsLangService_1.tsGetHover)(pre.args) ?? { error: NO_TS_SERVICE };
+}
 const TOOL_MAP = {
     read_file: readFile,
     write_file: writeFile,
@@ -1695,6 +2023,10 @@ const TOOL_MAP = {
     // so this fallback only serves the CLI / headless environments.
     get_symbols: symbols_1.getSymbols,
     get_workspace_symbols: symbols_1.getWorkspaceSymbols,
+    // Real semantic navigation (TS/JS) for the CLI — see GAP A above.
+    go_to_definition: goToDefinition,
+    find_references: findReferences,
+    get_hover: getHover,
 };
 // Tools that accept a workDir for correct relative-path resolution.
 // TOOL_MAP stores the base signatures; executeTool injects workDir at call time.
@@ -1704,6 +2036,7 @@ const WORKDIR_TOOLS = new Set([
     'delete_file', 'notebook_read', 'notebook_edit',
     'generate_image', 'stock_photo',
     'get_symbols', 'get_workspace_symbols',
+    'go_to_definition', 'find_references', 'get_hover',
 ]);
 async function executeTool(name, input, abortSignal, sandbox, workDir, agentScope) {
     if (!TOOL_MAP[name])

package/dist/tools/tsLangService.d.ts

@@ -0,0 +1,21 @@
+import type { ToolResult } from '../types';
+export declare function isTsLike(filePath: string): boolean;
+export interface SemanticDeps {
+    workDir: string;
+    filePath: string;
+    line: number;
+    character: number;
+}
+/** go_to_definition — resolve the symbol at (line, character) to its declaration(s). */
+export declare function tsGoToDefinition(deps: SemanticDeps): ToolResult | null;
+/** find_references — every usage of the symbol at (line, character) across the project. */
+export declare function tsFindReferences(deps: SemanticDeps & {
+    includeDeclaration?: boolean;
+}): ToolResult | null;
+/** get_hover — the inferred type + doc for the symbol at (line, character). */
+export declare function tsGetHover(deps: SemanticDeps): ToolResult | null;
+/** Test/diagnostic helper: is a real TS language service available for this workspace? */
+export declare function tsServiceAvailable(workDir: string): boolean;
+/** Reset cached services + module resolution (tests only). */
+export declare function _resetTsServiceCache(): void;
+//# sourceMappingURL=tsLangService.d.ts.map

package/dist/tools/tsLangService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsLangService.d.ts","sourceRoot":"","sources":["../../src/tools/tsLangService.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAsB3C,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAElD;AAsID,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wFAAwF;AACxF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU,GAAG,IAAI,CAgBtE;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG;IAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,UAAU,GAAG,IAAI,CAmBzG;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU,GAAG,IAAI,CAchE;AAED,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,8DAA8D;AAC9D,wBAAgB,oBAAoB,IAAI,IAAI,CAI3C"}