Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): stop exec reporting documents that do not exist (PRD-8375) (#4061)
tim-inkeepfcc892b24d97
diff --git a/.changeset/exec-path-honesty.md b/.changeset/exec-path-honesty.mdnew file mode 100644index 000000000..507e1ad03--- /dev/null+++ b/.changeset/exec-path-honesty.md@@ -0,0 +1,13 @@+---+"@inkeep/open-knowledge": patch+---++Agent `exec` no longer reports documents that do not exist.++`exec` returns a list of the wiki files a command touched, with frontmatter, link counts and a link to open each one. That list was assembled by reading the command's output and treating anything ending in `.md` as a document. It was checked against the disk, and when the check failed the path was kept anyway on the strength of the file extension.++`ls -l` was the clearest case. Its output puts permissions, owner and a timestamp ahead of each name, so the whole line was taken as a filename: a listing of six documents, none of which existed, each with its own preview link, while the real files went unmentioned. Output from `sort`, `uniq` and `cut` was read the same way, and ordinary prose became documents.++A path that is not on disk is no longer reported. Alongside that, each command's output is now read according to its own shape rather than scanned for anything markdown-looking: `ls -l` reads the name field, and the commands that name their files as arguments report those. `ls -l` now lists what is actually there, and `sort`, `uniq` and `cut` report the file they read, which none of them did before. `wc` already named its file and continues to.++A companion suite runs a matrix of representative command and flag shapes over a fixture project and checks that every path reported back exists, so the guarantee is verified rather than assumed. One case asserts the tool still reports the real files, so the check cannot be satisfied by reporting nothing.diff --git a/packages/server/src/bash/argv-model-agreement.test.ts b/packages/server/src/bash/argv-model-agreement.test.tsindex 4dd8ece5d..5756e2853 100644--- a/packages/server/src/bash/argv-model-agreement.test.ts+++ b/packages/server/src/bash/argv-model-agreement.test.ts@@ -12,6 +12,7 @@ function stageOf(command: string): Stage {const COMMANDS = ['grep -m 5 needle notes.md','grep -e needle notes.md',+ 'grep -f pats.txt notes.md','grep -rn needle .','grep --include=*.md needle .','grep -A 2 needle notes.md',diff --git a/packages/server/src/bash/extract-paths.test.ts b/packages/server/src/bash/extract-paths.test.tsindex 3a41b024d..f48891547 100644--- a/packages/server/src/bash/extract-paths.test.ts+++ b/packages/server/src/bash/extract-paths.test.ts@@ -152,3 +152,180 @@ describe('extractReferencedPaths — fallback regex', () => {expect(paths).toEqual(['file.md']);});});++describe('extractReferencedPaths — grep filename-only flags', () => {+ test('grep -l reports the files it named, not every file it searched', () => {+ const paths = extractReferencedPaths('specs/one.md\n', [+ stage('grep', '-l', 'alpha', 'specs/one.md', 'specs/two.md'),+ ]);+ expect(paths).toEqual(['specs/one.md']);+ });++ test('grep -L reports the files without a match', () => {+ const paths = extractReferencedPaths('specs/two.md\n', [+ stage('grep', '-L', 'alpha', 'specs/one.md', 'specs/two.md'),+ ]);+ expect(paths).toEqual(['specs/two.md']);+ });++ test('grep -l with no match reports nothing', () => {+ const paths = extractReferencedPaths('', [+ stage('grep', '-l', 'alpha', 'specs/one.md', 'specs/two.md'),+ ]);+ expect(paths).toEqual([]);+ });++ test('single-file grep reports the file it read', () => {+ const paths = extractReferencedPaths('alpha beta\n', [stage('grep', 'alpha', 'README.md')]);+ expect(paths).toEqual(['README.md']);+ });+});++describe('extractReferencedPaths — long listing', () => {+ test('ls -l reads the name field and skips the total line', () => {+ const stdout = [+ 'total 8',+ '-rw-r--r-- 1 user user 3132 Sep 1 12:47 README.md',+ 'drwxr-xr-x 2 user user 64 Sep 1 12:47 specs',+ '-rw-r--r-- 1 user user 100 Sep 1 12:47 my notes.md',+ '',+ ].join('\n');+ expect(extractReferencedPaths(stdout, [stage('ls', '-l')])).toEqual([+ 'README.md',+ 'specs',+ 'my notes.md',+ ]);+ });+});++describe('extractReferencedPaths — operand commands', () => {+ test.each(['sort', 'uniq', 'cut', 'wc'])('%s reports its operand, not its output', (cmd) => {+ const paths = extractReferencedPaths('prose with other.md inside\n', [stage(cmd, 'notes.md')]);+ expect(paths).toEqual(['notes.md']);+ });++ test('a non-wiki operand does not hijack the producer', () => {+ const paths = extractReferencedPaths('alpha beta\n', [+ stage('cat', 'README.md'),+ stage('sort', 'plain.txt'),+ ]);+ expect(paths).toEqual(['README.md']);+ });+});++describe('extractReferencedPaths — grep reads flags through the argv model', () => {+ test('a pattern supplied with -e is not read as a flag', () => {+ const paths = extractReferencedPaths('the -l flag lists files\n', [+ stage('grep', '-e', '-l', 'notes.md'),+ ]);+ expect(paths).toEqual(['notes.md']);+ });++ test('a pattern after -- is not read as a flag', () => {+ const paths = extractReferencedPaths('the -l flag lists files\n', [+ stage('grep', '--', '-l', 'notes.md'),+ ]);+ expect(paths).toEqual(['notes.md']);+ });++ test('single-file grep is not split on a colon inside a matched line', () => {+ const paths = extractReferencedPaths('specs/two.md: see also\n', [+ stage('grep', 'see also', 'README.md'),+ ]);+ expect(paths).toEqual(['README.md']);+ });++ test('an ambiguous multi-operand grep with no match reports nothing', () => {+ expect(extractReferencedPaths('', [stage('grep', 'nomatch', 'a.md', 'b.md')])).toEqual([]);+ });+});++describe('extractReferencedPaths — pins for the sibling one-liners', () => {+ test('ls -a drops the dot entries from the raw listing', () => {+ const stdout = '.\n..\n.git\nREADME.md\nspecs\n';+ expect(extractReferencedPaths(stdout, [stage('ls', '-a')])).toEqual(['README.md', 'specs']);+ });++ test('a non-wiki operand does not elect head as producer', () => {+ const paths = extractReferencedPaths('content\n', [+ stage('cat', 'auth.md'),+ stage('head', 'plain.txt'),+ ]);+ expect(paths).toEqual(['auth.md']);+ });++ test('the fallback regex matches an uppercase extension', () => {+ expect(extractReferencedPaths('see NOTES.MD for background\n', [stage('wc', '-l')])).toEqual([+ 'NOTES.MD',+ ]);+ });+});++describe('extractReferencedPaths — grep counts only the files it searches', () => {+ test('a -f pattern file is not a searched file', () => {+ const paths = extractReferencedPaths('specs/two.md: see also\n', [+ stage('grep', '-f', 'needles.md', 'notes.md'),+ ]);+ expect(paths).toEqual(['notes.md']);+ });++ test('grep -h suppresses filename prefixing even with multiple operands', () => {+ const paths = extractReferencedPaths('specs/two.md: see also\n', [+ stage('grep', '-h', 'see also', 'README.md', 'specs/two.md'),+ ]);+ expect(paths).toEqual(['README.md', 'specs/two.md']);+ });++ test('a digit-bearing bundle still counts as recursive', () => {+ const stdout = 'specs/one.md:12:alpha\nspecs/one.md-13-see other.md\n';+ expect(extractReferencedPaths(stdout, [stage('grep', '-rA3', 'alpha', '.')])).toEqual([+ 'specs/one.md',+ ]);+ });++ test('a digit-bearing bundle still suppresses filename prefixing', () => {+ const paths = extractReferencedPaths('specs/two.md: see also\n', [+ stage('grep', '-hA3', 'see also', 'README.md', 'specs/two.md'),+ ]);+ expect(paths).toEqual(['README.md', 'specs/two.md']);+ });++ test('a grep with only an output-shaping flag defers to the upstream producer', () => {+ const paths = extractReferencedPaths('specs/two.md: see also\n', [+ stage('cat', 'README.md'),+ stage('grep', '-l', 'also'),+ ]);+ expect(paths).toEqual(['README.md']);+ });++ test('a recursive grep with no search operand reads stdin and defers upstream', () => {+ const paths = extractReferencedPaths('specs/two.md: see also\n', [+ stage('cat', 'README.md'),+ stage('grep', '-r', 'also'),+ ]);+ expect(paths).toEqual(['README.md']);+ });++ test('a bare dash operand is stdin, not a searched file', () => {+ const paths = extractReferencedPaths('specs/two.md: see also\n', [+ stage('cat', 'README.md'),+ stage('grep', '-r', 'also', '-'),+ ]);+ expect(paths).toEqual(['README.md']);+ });++ test('a dash beside a real operand is not counted as a second searched file', () => {+ const paths = extractReferencedPaths('(standard input):see specs/two.md\n', [+ stage('grep', 'see', 'README.md', '-'),+ ]);+ expect(paths).toEqual(['README.md']);+ });++ test('a grep with no search operand defers to the upstream producer', () => {+ const paths = extractReferencedPaths('specs/two.md: see also\n', [+ stage('cat', 'README.md'),+ stage('grep', 'also'),+ ]);+ expect(paths).toEqual(['README.md']);+ });+});diff --git a/packages/server/src/bash/extract-paths.ts b/packages/server/src/bash/extract-paths.tsindex 2c3418ef1..ba9cfdd2d 100644--- a/packages/server/src/bash/extract-paths.ts+++ b/packages/server/src/bash/extract-paths.ts@@ -1,11 +1,17 @@-import { classifyArgs, type Stage } from './parse-command.ts';+import { classifyArgs, isRecursiveGrepFlag, type Stage } from './parse-command.ts';-const PRODUCER_COMMANDS: ReadonlySet<string> = new Set(['cat', 'ls', 'grep', 'find']);+const PRODUCER_COMMANDS: ReadonlySet<string> = new Set(['cat', 'ls', 'find']);-const PATH_FALLBACK_RE = /\b[\w./-]+\.(md|mdx)\b/g;+const OPERAND_COMMANDS: ReadonlySet<string> = new Set(['sort', 'uniq', 'cut', 'wc']);-function isWikiPath(p: string): boolean {- return /\.(md|mdx)$/.test(p);+function operandCommandActsAsProducer(stage: Stage): boolean {+ return OPERAND_COMMANDS.has(stage.command) && pathArgs(stage).some(isWikiPath);+}++const PATH_FALLBACK_RE = /\b[\w./-]+\.(md|mdx)\b/gi;++export function isWikiPath(p: string): boolean {+ return /\.(md|mdx)$/i.test(p);}function normalize(p: string): string {@@ -31,6 +37,14 @@ function extractFromCat(stage: Stage): string[] {return pathArgs(stage).filter(isWikiPath);}+const LS_LONG_RE = /^[bcdlprsw-][rwxsStT-]{9}[.+@]?\s+(?:\S+\s+){7}(.+)$/;++function lsEntryName(line: string): string {+ const trimmed = line.trim();+ const long = LS_LONG_RE.exec(trimmed);+ return long ? long[1] : trimmed;+}+function extractFromLs(stdout: string, stage: Stage): string[] {const operands = pathArgs(stage);const fileArgs = operands.filter(isWikiPath);@@ -42,8 +56,8 @@ function extractFromLs(stdout: string, stage: Stage): string[] {const out: string[] = [];if (prefix) out.push(prefix);for (const line of stdout.split('\n')) {- const name = line.trim();- if (!name) continue;+ const name = lsEntryName(line);+ if (!name || name === '.' || name === '..' || /^total \d+$/.test(name)) continue;if (name.endsWith(':')) {const dir = normalize(name.slice(0, -1));prefix = dir === '.' ? '' : dir;@@ -57,13 +71,51 @@ function extractFromLs(stdout: string, stage: Stage): string[] {return out;}-function extractFromGrep(stdout: string): string[] {+function searchOperands(stage: Stage): string[] {+ return classifyArgs(stage)+ .filter((a) => a.role === 'path' && a.flag === undefined && a.value !== '-')+ .map((a) => a.value);+}++function grepHasFlag(stage: Stage, letter: string, long: string): boolean {+ return classifyArgs(stage).some(+ (a) =>+ a.role === 'flag' &&+ (a.value === long || (/^-[a-zA-Z]+\d*$/.test(a.value) && a.value.includes(letter))),+ );+}++function grepPrintsFilenamesOnly(stage: Stage): boolean {+ return (+ grepHasFlag(stage, 'l', '--files-with-matches') ||+ grepHasFlag(stage, 'L', '--files-without-match')+ );+}++function grepIsRecursive(stage: Stage): boolean {+ return classifyArgs(stage).some((a) => a.role === 'flag' && isRecursiveGrepFlag(a.value));+}++function grepPrefixesFilenames(stage: Stage): boolean {+ if (grepHasFlag(stage, 'h', '--no-filename')) return false;+ return searchOperands(stage).length > 1 || grepIsRecursive(stage);+}++function grepActsAsProducer(stage: Stage): boolean {+ return searchOperands(stage).length > 0;+}++function extractFromGrep(stdout: string, stage: Stage): string[] {+ const filenamesOnly = grepPrintsFilenamesOnly(stage);+ if (!filenamesOnly && !grepPrefixesFilenames(stage)) {+ return searchOperands(stage).filter(isWikiPath).map(normalize);+ }const out: string[] = [];for (const line of stdout.split('\n')) {if (!line) continue;- const firstColon = line.indexOf(':');- if (firstColon < 0) continue;- const path = normalize(line.slice(0, firstColon));+ const end = filenamesOnly ? line.length : line.indexOf(':');+ if (end < 0) continue;+ const path = normalize(line.slice(0, end));if (isWikiPath(path)) out.push(path);}return out;@@ -84,7 +136,7 @@ function extractFromHeadTail(stage: Stage): string[] {}function headTailActsAsProducer(stage: Stage): boolean {- return pathArgs(stage).length > 0;+ return pathArgs(stage).some(isWikiPath);}function fallback(stdout: string): string[] {@@ -102,10 +154,18 @@ export function extractReferencedPaths(stdout: string, stages: Stage[]): string[producer = s;break;}+ if (s.command === 'grep' && grepActsAsProducer(s)) {+ producer = s;+ break;+ }if ((s.command === 'head' || s.command === 'tail') && headTailActsAsProducer(s)) {producer = s;break;}+ if (operandCommandActsAsProducer(s)) {+ producer = s;+ break;+ }}let raw: string[];@@ -114,13 +174,17 @@ export function extractReferencedPaths(stdout: string, stages: Stage[]): string[} else {switch (producer.command) {case 'cat':+ case 'sort':+ case 'uniq':+ case 'cut':+ case 'wc':raw = extractFromCat(producer);break;case 'ls':raw = extractFromLs(stdout, producer);break;case 'grep':- raw = extractFromGrep(stdout);+ raw = extractFromGrep(stdout, producer);break;case 'find':raw = extractFromFind(stdout);diff --git a/packages/server/src/bash/path-honesty-contract.test.ts b/packages/server/src/bash/path-honesty-contract.test.tsnew file mode 100644index 000000000..c420cceed--- /dev/null+++ b/packages/server/src/bash/path-honesty-contract.test.ts@@ -0,0 +1,178 @@+import { mkdirSync, mkdtempSync, rmSync, statSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join, resolve } from 'node:path';+import simpleGit from 'simple-git';+import { afterAll, describe, expect, test } from 'vitest';+import { ConfigSchema } from '../config/schema.ts';+import { buildExecResult } from '../mcp/tools/exec.ts';++const CONFIG = ConfigSchema.parse({});+const created: string[] = [];++afterAll(() => {+ for (const dir of created) rmSync(dir, { recursive: true, force: true });+});++async function corpus(): Promise<string> {+ const root = mkdtempSync(join(tmpdir(), 'path-honesty-'));+ created.push(root);+ const git = simpleGit(root);+ await git.init();+ await git.raw('config', 'user.name', 'Test');+ await git.raw('config', 'user.email', '[email protected]');+ mkdirSync(join(root, 'specs'));+ mkdirSync(join(root, 'empty-dir'));+ writeFileSync(+ join(root, 'README.md'),+ '---\ntitle: Readme\n---\nalpha beta\nspecs/two.md: see also\n',+ );+ writeFileSync(join(root, 'my notes.md'), '---\ntitle: Spaced\n---\nalpha\n');+ writeFileSync(join(root, 'plain.txt'), 'not markdown\n');+ writeFileSync(join(root, 'two spaces.md'), '---\ntitle: Spaced\n---\nalpha\n');+ writeFileSync(join(root, 'UPPER.MD'), '---\ntitle: Upper\n---\nalpha\n');+ writeFileSync(join(root, 'specs/one.md'), '---\ntitle: One\n---\nalpha ONE\n');+ writeFileSync(join(root, 'specs/two.md'), '---\ntitle: Two\n---\nTWO\n');+ await git.add('.');+ await git.commit('init');+ return root;+}++async function reported(root: string, command: string): Promise<string[]> {+ const result = (await buildExecResult(+ { command, cwd: root },+ { resolveCwd: async () => root, serverUrl: undefined, config: CONFIG },+ )) as { structuredContent?: { enrichedPaths?: Array<{ path: string }> } };+ return (result.structuredContent?.enrichedPaths ?? []).map((entry) => entry.path);+}++const COMMANDS = [+ 'ls',+ 'ls -l',+ 'ls -la',+ 'ls -A',+ 'ls -a',+ 'ls specs/',+ 'ls specs/*.md',+ 'ls README.md specs/one.md',+ 'cat README.md',+ 'cat specs/*.md',+ 'cat README.md specs/one.md',+ 'head -n 1 README.md',+ 'tail -n 1 README.md',+ 'wc -l README.md',+ 'wc -l specs/*.md',+ 'sort README.md',+ 'uniq README.md',+ 'cut -d" " -f1 README.md',+ 'grep alpha README.md',+ 'grep -rn alpha .',+ 'grep -l alpha specs/*.md',+ 'cat README.md | grep also',+ 'cat README.md | grep -l also',+ 'cat README.md | grep -r also',+ "find . -name '*.md'",+ 'find . -type f',+ 'find . -type d',+ 'grep -rn alpha . | head -3',+ 'ls | sort',+ 'cat README.md | sort -k 2',+ 'cat README.md | cut -d " " -f 1',+ 'cat README.md | uniq -f 1',+ 'cat README.md | sort plain.txt',+ 'cat plain.txt',+ 'ls empty-dir/',+];++describe('exec never reports a path that does not exist', () => {+ test.each(COMMANDS)('%s', async (command) => {+ const root = await corpus();+ for (const path of await reported(root, command)) {+ expect(+ () => statSync(resolve(root, path)),+ `${command} reported a nonexistent path: ${path}`,+ ).not.toThrow();+ }+ });++ test('the assertion can fail, so a passing run means something', async () => {+ const root = await corpus();+ expect(() => statSync(resolve(root, 'ghost.md'))).toThrow();+ });++ test.each([+ 'cat README.md',+ 'ls -l',+ 'ls -la',+ 'sort README.md',+ 'uniq README.md',+ 'wc -l README.md',+ 'cut -d" " -f1 README.md',+ 'head -n 1 README.md',+ 'tail -n 1 README.md',+ 'grep alpha README.md',+ 'grep -rn alpha .',+ 'cat README.md | sort -k 2',+ 'cat README.md | cut -d " " -f 1',+ 'cat README.md | uniq -f 1',+ ])('%s still reports the file it read, so honesty is not silence', async (command) => {+ const root = await corpus();+ expect(await reported(root, command)).toContain('README.md');+ });+});++describe('a long listing reports the name as written', () => {+ test('consecutive whitespace in a filename survives', async () => {+ const root = await corpus();+ expect(await reported(root, 'ls -l')).toContain('two spaces.md');+ });++ test('an uppercase extension is still a document', async () => {+ const root = await corpus();+ expect(await reported(root, 'ls -l')).toContain('UPPER.MD');+ expect(await reported(root, 'ls')).toContain('UPPER.MD');+ });+});++describe('the reported set is the set the command was about', () => {+ test('grep -l reports only the file that matched', async () => {+ const root = await corpus();+ expect(await reported(root, 'grep -l alpha specs/*.md')).toEqual(['specs/one.md']);+ });++ test('a wiki-shaped grep pattern is the needle, not a file that was read', async () => {+ const root = await corpus();+ expect(await reported(root, 'grep specs/two.md README.md')).toEqual(['README.md']);+ });++ test('ls -a does not report the dot entries', async () => {+ const root = await corpus();+ const paths = await reported(root, 'ls -a');+ expect(paths).not.toContain('.');+ expect(paths).not.toContain('..');+ });++ test('a matched line that starts with a wiki path and a colon is content, not a filename', async () => {+ const root = await corpus();+ expect(await reported(root, 'grep "see also" README.md')).toEqual(['README.md']);+ });++ test('a grep with no search operand in a pipe defers to the file upstream', async () => {+ const root = await corpus();+ expect(await reported(root, 'cat README.md | grep also')).toEqual(['README.md']);+ });++ test('a grep with only an output-shaping flag in a pipe defers to the file upstream', async () => {+ const root = await corpus();+ expect(await reported(root, 'cat README.md | grep -l also')).toEqual(['README.md']);+ });++ test('a recursive grep with no operand reads stdin and defers to the file upstream', async () => {+ const root = await corpus();+ expect(await reported(root, 'cat README.md | grep -r also')).toEqual(['README.md']);+ });++ test('a non-wiki operand downstream does not hijack the producer', async () => {+ const root = await corpus();+ expect(await reported(root, 'cat README.md | sort plain.txt')).toEqual(['README.md']);+ });+});diff --git a/packages/server/src/mcp/tools/exec.test.ts b/packages/server/src/mcp/tools/exec.test.tsindex fd8f2940c..5ee180f9b 100644--- a/packages/server/src/mcp/tools/exec.test.ts+++ b/packages/server/src/mcp/tools/exec.test.ts@@ -290,6 +290,19 @@ describe('exec — stdout provenance headers', () => {expect(s.text?.startsWith('.:')).toBe(false);});+ test('`cat <FILE.MD>` prepends the header for an uppercase extension', async () => {+ const project = await bootstrap();+ writeFileSync(resolve(project, 'UPPER.MD'), '# Upper\n');++ const result = (await buildExecResult(+ { command: 'cat UPPER.MD' },+ { resolveCwd: async () => project, serverUrl: undefined, config: DEFAULT_CONFIG },+ )) as ExecResult;++ const s = structured(result);+ expect(s.text?.startsWith('==> UPPER.MD <==\n')).toBe(true);+ });+test('`cat <file.md>` prepends `==> <file> <==` header to stdout', async () => {const project = await bootstrap();const contentDir = resolve(project, 'articles');diff --git a/packages/server/src/mcp/tools/exec.ts b/packages/server/src/mcp/tools/exec.tsindex 8ceabdea4..3cb5735c2 100644--- a/packages/server/src/mcp/tools/exec.ts+++ b/packages/server/src/mcp/tools/exec.ts@@ -7,7 +7,7 @@ import {} from '@inkeep/open-knowledge-core';import { z } from 'zod';import { expandGlobStages } from '../../bash/expand-globs.ts';-import { extractReferencedPaths, pathArgs } from '../../bash/extract-paths.ts';+import { extractReferencedPaths, isWikiPath, pathArgs } from '../../bash/extract-paths.ts';import {createBashInstance,erofsTarget,@@ -342,7 +342,7 @@ function buildStdoutProvenance(return `${key}/:\n`;}- const wikiFiles = operands.filter((p) => /\.(md|mdx)$/.test(p) && fileByPath.has(rebase(p)));+ const wikiFiles = operands.filter((p) => isWikiPath(p) && fileByPath.has(rebase(p)));if (wikiFiles.length !== 1) return '';return `==> ${rebase(wikiFiles[0])} <==\n`;}@@ -371,8 +371,12 @@ async function classifyPaths(} else if (st.isFile()) {files.push(p);}- } catch {- if (/\.(md|mdx)$/i.test(p)) files.push(p);+ } catch (err) {+ const code = (err as { code?: string }).code;+ if (code !== 'ENOENT' && code !== 'ENOTDIR') {+ log.warn({ path: p, code }, 'stat failed for a reported path; dropping it');+ }+ return;}}),);