topchester-ai 0.3.0 → 0.5.0

package/README.md

@@ -1,5 +1,7 @@
 # Topchester Agent
 
+Website: https://topchester.com
+
 ## Overview
 
 Topchester Agent is a terminal-native TUI coding agent tightly coupled to a committed project knowledge base. The normal workflow is to compile project knowledge first, then let the agent use that knowledge while planning, editing, checking drift, and updating the repository.

package/dist/cli.mjs

@@ -1843,19 +1843,26 @@ function formatKnowledgeStatus(status) {
 	const lines = [
 		"KB status",
 		`workspace: ${status.workspaceRoot}`,
-		`knowledge folder: ${formatPathStatus$2(status.kbPath, status.kbExists, status.kbIsDirectory)} (${status.kbPathSource})`,
-		`local cache folder: ${formatPathStatus$2(status.cachePath, status.cacheExists, status.cacheIsDirectory)} (${status.cachePathSource})`
+		`knowledge folder: ${formatKnowledgePathStatus$2(status)} (${status.kbPathSource})`,
+		`local cache folder: ${formatPathStatus$1(status.cachePath, status.cacheExists, status.cacheIsDirectory)} (${status.cachePathSource})`
 	];
 	if (!status.kbExists) lines.push("state: no knowledge base found yet");
 	else if (!status.kbIsDirectory) lines.push("state: knowledge base path is not a folder");
+	else if (status.kbContentState !== "ready") lines.push("state: knowledge base folder is empty");
 	else lines.push("state: knowledge base found");
 	return lines;
 }
-function formatPathStatus$2(path, exists, isDirectory) {
+function formatPathStatus$1(path, exists, isDirectory) {
 	if (!exists) return `${path} [missing]`;
 	if (!isDirectory) return `${path} [not a folder]`;
 	return `${path} [ok]`;
 }
+function formatKnowledgePathStatus$2(status) {
+	if (!status.kbExists) return `${status.kbPath} [missing]`;
+	if (!status.kbIsDirectory) return `${status.kbPath} [not a folder]`;
+	if (status.kbContentState !== "ready") return `${status.kbPath} [empty]`;
+	return `${status.kbPath} [ok]`;
+}
 //#endregion
 //#region src/tui/markdown.ts
 const codeFenceSentinel = "topchester-code-fence";
@@ -2058,6 +2065,48 @@ function escapeRegex(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 //#endregion
+//#region src/tui/prompt-history.ts
+const DEFAULT_MAX_PROMPTS = 100;
+var PromptHistory = class {
+	maxPrompts;
+	prompts = [];
+	historyIndex = -1;
+	draft = "";
+	constructor(maxPrompts = DEFAULT_MAX_PROMPTS) {
+		this.maxPrompts = Math.max(1, maxPrompts);
+	}
+	add(value) {
+		const prompt = value.trim();
+		this.resetBrowsing();
+		if (prompt.length === 0 || prompt === this.prompts[0]) return;
+		this.prompts.unshift(prompt);
+		this.prompts = this.prompts.slice(0, this.maxPrompts);
+	}
+	previous(currentDraft) {
+		if (this.prompts.length === 0) return;
+		if (this.historyIndex === -1) {
+			this.draft = currentDraft;
+			this.historyIndex = 0;
+			return this.prompts[this.historyIndex];
+		}
+		this.historyIndex = Math.min(this.historyIndex + 1, this.prompts.length - 1);
+		return this.prompts[this.historyIndex];
+	}
+	next() {
+		if (this.historyIndex === -1) return;
+		if (this.historyIndex === 0) {
+			this.historyIndex = -1;
+			return this.draft;
+		}
+		this.historyIndex -= 1;
+		return this.prompts[this.historyIndex];
+	}
+	resetBrowsing() {
+		this.historyIndex = -1;
+		this.draft = "";
+	}
+};
+//#endregion
 //#region src/tui/status.ts
 function getStartupThreadMessages(context) {
 	const assignments = context.config.models?.assignments ?? {};
@@ -2136,10 +2185,17 @@ function formatKnowledgeFooterStatus(status) {
 	if (status.kbContentState !== "ready") return `${ui.label("○")} kb: ${ui.label("empty")}`;
 	return `${ui.ok("✅")} kb: ${ui.ok("ready")}`;
 }
-function formatPathStatus$1(path, exists, isDirectory) {
-	if (!exists) return `${path} ${ui.warn("[missing]")}`;
-	if (!isDirectory) return `${path} ${ui.error("[not a folder]")}`;
-	return `${path} ${ui.ok("[ok]")}`;
+function formatKnowledgePathStatus$1(status) {
+	const pathLabel = `${ui.label("")} ${formatWorkspaceRelativePath(status.kbPath, status.workspaceRoot)}`;
+	if (!status.kbExists) return `${pathLabel} ${ui.warn("[missing]")}`;
+	if (!status.kbIsDirectory) return `${pathLabel} ${ui.error("[not a folder]")}`;
+	if (status.kbContentState !== "ready") return `${pathLabel} ${ui.label("[empty]")}`;
+	return `${pathLabel} ${ui.ok("[ok]")}`;
+}
+function formatWorkspaceRelativePath(path, workspaceRoot) {
+	const relativePath = relative(workspaceRoot, path);
+	if (relativePath && !relativePath.startsWith("..") && !isAbsolute(relativePath)) return relativePath;
+	return path;
 }
 function getModelLabel(context) {
 	const purpose = context.config.models?.defaultPurpose ?? "agent.primary";
@@ -2188,6 +2244,7 @@ var ChatLayout = class {
 	activeModalActionIndex = 0;
 	activeSlashSuggestionIndex = 0;
 	threadScrollOffset = 0;
+	promptHistory = new PromptHistory();
 	constructor(terminal, messages, folderName, modelLabel, exitAgent = () => {}) {
 		this.terminal = terminal;
 		this.messages = messages;
@@ -2264,8 +2321,11 @@ var ChatLayout = class {
 		}
 		if (this.handleModalInput(data)) return;
 		if (this.handleSlashSuggestionInput(data)) return;
+		if (this.handlePromptHistoryInput(data)) return;
 		if (this.handleThreadScrollInput(data)) return;
+		const previousInput = this.input.getValue();
 		this.input.handleInput(data);
+		if (this.input.getValue() !== previousInput) this.promptHistory.resetBrowsing();
 	}
 	invalidate() {
 		this.input.invalidate();
@@ -2377,14 +2437,6 @@ var ChatLayout = class {
 	handleThreadScrollInput(data) {
 		const pageSize = Math.max(1, Math.floor(this.terminal.rows / 2));
 		const wheel = parseMouseWheel(data);
-		if (isUpKey(data)) {
-			this.threadScrollOffset += 3;
-			return true;
-		}
-		if (isDownKey(data)) {
-			this.threadScrollOffset = Math.max(0, this.threadScrollOffset - 3);
-			return true;
-		}
 		if (wheel === "up") {
 			this.threadScrollOffset += 3;
 			return true;
@@ -2411,6 +2463,20 @@ var ChatLayout = class {
 		}
 		return false;
 	}
+	handlePromptHistoryInput(data) {
+		if (this.promptHint) return false;
+		if (isUpKey(data)) {
+			const prompt = this.promptHistory.previous(this.input.getValue());
+			if (prompt !== void 0) this.input.setValue(prompt);
+			return true;
+		}
+		if (isDownKey(data)) {
+			const prompt = this.promptHistory.next();
+			if (prompt !== void 0) this.input.setValue(prompt);
+			return true;
+		}
+		return false;
+	}
 	handleSlashSuggestionInput(data) {
 		const suggestions = this.getSlashSuggestions();
 		if (suggestions.length === 0) {
@@ -2438,6 +2504,7 @@ var ChatLayout = class {
 	completeSlashSuggestion(suggestions) {
 		this.input.setValue(suggestions[this.activeSlashSuggestionIndex]?.value ?? this.input.getValue());
 		this.input.handleInput("\x1B[F");
+		this.promptHistory.resetBrowsing();
 	}
 	getSlashSuggestions() {
 		return getSlashCommandSuggestions(this.input.getValue());
@@ -2453,6 +2520,7 @@ var ChatLayout = class {
 		this.submitUserInput(message);
 	}
 	submitUserInput(message) {
+		this.promptHistory.add(message);
 		if (message.startsWith("/")) this.submitCommand?.(message);
 		else this.submitMessage?.(message);
 	}
@@ -2641,7 +2709,7 @@ const editFileTool = defineTool({
 	execute: (context, args) => editWorkspaceFile(context.workspaceRoot, args, { logger: context.logger })
 });
 async function editWorkspaceFile(workspaceRoot, args, options = {}) {
-	const scopedPath = resolveWorkspaceScopedPath$2(workspaceRoot, args.path);
+	const scopedPath = resolveWorkspaceScopedPath$3(workspaceRoot, args.path);
 	return enqueueFileMutation(scopedPath.path, async () => {
 		const fileStat = await statExistingFile(scopedPath.path, args.path);
 		const beforeBytes = await readFile(scopedPath.path);
@@ -2704,7 +2772,7 @@ function applyExactEdits(content, edits, path = "file") {
 		firstChangedLine: getFirstChangedLine(document.body, newBody)
 	};
 }
-function resolveWorkspaceScopedPath$2(workspaceRoot, path) {
+function resolveWorkspaceScopedPath$3(workspaceRoot, path) {
 	if (path.includes("\0")) throw new Error("edit_file path is invalid.");
 	const resolvedWorkspace = resolve(workspaceRoot);
 	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
@@ -2908,7 +2976,7 @@ const findFileTool = defineTool({
 	})
 });
 async function findWorkspaceFilesByName(workspaceRoot, args, options = {}) {
-	const scopedPath = resolveWorkspaceScopedPath$1(workspaceRoot, args.path);
+	const scopedPath = resolveWorkspaceScopedPath$2(workspaceRoot, args.path);
 	const matches = (await collectWorkspaceFiles(scopedPath.workspaceRoot, scopedPath.path, scopedPath.relativePath, options)).map((path) => {
 		const score = scoreFileMatch(args.query, path);
 		return score > 0 ? {
@@ -3106,7 +3174,7 @@ function scoreSubsequenceMatch(query, value) {
 function normalize(value) {
 	return value.trim().toLowerCase().replaceAll("\\", "/");
 }
-function resolveWorkspaceScopedPath$1(workspaceRoot, path) {
+function resolveWorkspaceScopedPath$2(workspaceRoot, path) {
 	const resolvedWorkspace = resolve(workspaceRoot);
 	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
 	const relativePath = relative(resolvedWorkspace, resolvedPath);
@@ -3164,7 +3232,7 @@ const grepTool = defineTool({
 	})
 });
 async function grepWorkspace(workspaceRoot, args, options = {}) {
-	const scopedPath = resolveWorkspaceScopedPath(workspaceRoot, args.path ?? ".");
+	const scopedPath = resolveWorkspaceScopedPath$1(workspaceRoot, args.path ?? ".");
 	const executable = await findSearchExecutable(options.pathEnv);
 	if (!executable) {
 		const warning = "grep could not run because neither rg nor grep is available on PATH.";
@@ -3228,7 +3296,7 @@ async function grepWorkspace(workspaceRoot, args, options = {}) {
 		content: truncateToolOutput(result.stdout.trimEnd() || "No matches.")
 	};
 }
-function resolveWorkspaceScopedPath(workspaceRoot, path) {
+function resolveWorkspaceScopedPath$1(workspaceRoot, path) {
 	const resolvedWorkspace = resolve(workspaceRoot);
 	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
 	const relativePath = relative(resolvedWorkspace, resolvedPath);
@@ -3286,6 +3354,93 @@ function truncateToolOutput(output) {
 function isRecord$1(value) {
 	return typeof value === "object" && value !== null;
 }
+const listFilesTool = defineTool({
+	name: "list_files",
+	description: "List files and directories inside a workspace folder.",
+	prompt: "list_files: list files and directories inside the workspace; top-level by default, recursive only when requested, with \"/\" after directory names. To use it, reply with only JSON: {\"tool\":\"list_files\",\"args\":{\"path\":\"src\",\"recursive\":false,\"limit\":500}}",
+	argsSchema: z.object({
+		path: z.string().optional().default("."),
+		recursive: z.boolean().optional().default(false),
+		limit: z.number().int().min(1).max(2e3).optional().default(500)
+	}),
+	execute: (context, args) => listWorkspaceFiles(context.workspaceRoot, args)
+});
+async function listWorkspaceFiles(workspaceRoot, args) {
+	const scopedPath = resolveWorkspaceScopedPath(workspaceRoot, args.path);
+	if (!(await stat(scopedPath.path)).isDirectory()) throw new Error(`list_files can only list directories inside the workspace: ${args.path}`);
+	const entries = args.recursive ? await collectRecursiveEntries(scopedPath.workspaceRoot, scopedPath.path, args.limit) : await collectTopLevelEntries(scopedPath.workspaceRoot, scopedPath.path, args.limit);
+	const truncated = entries.truncated;
+	const lines = entries.items.map((entry) => formatEntryPath(entry.relativePath, entry.isDirectory));
+	const notices = [];
+	if (truncated) notices.push(`[${args.limit} entry limit reached. Use a narrower path or a higher limit for more.]`);
+	return {
+		tool: "list_files",
+		path: scopedPath.relativePath,
+		content: [...lines.length > 0 ? lines : ["(empty directory)"], ...notices].join("\n"),
+		warning: truncated ? `${args.limit} entry limit reached.` : void 0
+	};
+}
+async function collectTopLevelEntries(workspaceRoot, startPath, limit) {
+	const entries = await sortedDirectoryEntries(startPath);
+	const items = [];
+	for (const entry of entries) {
+		if (items.length >= limit) return {
+			items,
+			truncated: true
+		};
+		const absolutePath = join(startPath, entry.name);
+		items.push({
+			relativePath: relative(workspaceRoot, absolutePath) || ".",
+			isDirectory: entry.isDirectory()
+		});
+	}
+	return {
+		items,
+		truncated: false
+	};
+}
+async function collectRecursiveEntries(workspaceRoot, startPath, limit) {
+	const items = [];
+	const pending = [startPath];
+	while (pending.length > 0) {
+		const currentPath = pending.shift() ?? startPath;
+		const entries = await sortedDirectoryEntries(currentPath);
+		for (const entry of entries) {
+			if (items.length >= limit) return {
+				items,
+				truncated: true
+			};
+			const absolutePath = join(currentPath, entry.name);
+			const item = {
+				relativePath: relative(workspaceRoot, absolutePath) || ".",
+				isDirectory: entry.isDirectory()
+			};
+			items.push(item);
+			if (item.isDirectory) pending.push(absolutePath);
+		}
+	}
+	return {
+		items,
+		truncated: false
+	};
+}
+async function sortedDirectoryEntries(path) {
+	return (await readdir(path, { withFileTypes: true })).sort((left, right) => left.name.toLowerCase().localeCompare(right.name.toLowerCase()));
+}
+function formatEntryPath(path, isDirectory) {
+	return isDirectory ? `${path}/` : path;
+}
+function resolveWorkspaceScopedPath(workspaceRoot, path) {
+	const resolvedWorkspace = resolve(workspaceRoot);
+	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
+	const relativePath = relative(resolvedWorkspace, resolvedPath);
+	if (relativePath.startsWith("..") || isAbsolute(relativePath)) throw new Error(`list_files can only list directories inside the workspace: ${path}`);
+	return {
+		workspaceRoot: resolvedWorkspace,
+		path: resolvedPath,
+		relativePath: relativePath || "."
+	};
+}
 const readFileTool = defineTool({
 	name: "read_file",
 	description: "Read a UTF-8 file inside the workspace.",
@@ -3311,6 +3466,7 @@ async function readWorkspaceFile(workspaceRoot, path) {
 //#region src/agent/tools/registry.ts
 const toolRegistry = {
 	[readFileTool.name]: readFileTool,
+	[listFilesTool.name]: listFilesTool,
 	[grepTool.name]: grepTool,
 	[findFileTool.name]: findFileTool,
 	[editFileTool.name]: editFileTool
@@ -3617,6 +3773,7 @@ function formatToolResultForPrompt(result) {
 function formatToolCallMessage(call, result) {
 	switch (call.tool) {
 		case "read_file": return `Tool read_file: ${call.args.path}`;
+		case "list_files": return `Tool list_files: ${call.args.path}${call.args.recursive ? " (recursive)" : ""}`;
 		case "grep": return `Tool grep: ${call.args.pattern} in ${call.args.path ?? "."}`;
 		case "find_file": return `Tool find_file: ${call.args.query} in ${call.args.path}`;
 		case "edit_file": return `Tool edit_file: ${call.args.path}${formatEditFileChangeSummary(result)}`;
@@ -3650,7 +3807,7 @@ function renderRuntimeEvent(event) {
 	switch (event.type) {
 		case "message": return [event.role === "assistant" ? agentMessage(event.text, event.meta) : systemMessage(event.text)];
 		case "tool_call": return [systemMessage(event.label)];
-		case "knowledge_status": return [systemMessage(`KB status: ${formatPathStatus$1(event.status.kbPath, event.status.kbExists, event.status.kbIsDirectory)} (${event.status.kbPathSource})`)];
+		case "knowledge_status": return [systemMessage(`KB status: ${formatKnowledgePathStatus$1(event.status)}${formatKbPathSource(event.status)}`)];
 		case "choice": return [modalMessage({
 			tone: event.tone,
 			title: event.title,
@@ -3660,6 +3817,9 @@ function renderRuntimeEvent(event) {
 		case "status": return [];
 	}
 }
+function formatKbPathSource(status) {
+	return status.kbPathSource === "env" ? " (custom)" : "";
+}
 //#endregion
 //#region src/tui/terminal.ts
 function enterAlternateScreen(terminal) {
@@ -4046,10 +4206,11 @@ kbCommand.command("status").description("show project knowledge base status").ac
 	const status = await ui.spinner("Checking knowledge base...", () => getKnowledgeStatus(context.workspaceRoot));
 	console.log(ui.heading("KB status"));
 	console.log(`${ui.label("workspace")}: ${status.workspaceRoot}`);
-	console.log(`${ui.label("knowledge folder")}: ${formatPathStatus(status.kbPath, status.kbExists, status.kbIsDirectory)} ${ui.label(`(${status.kbPathSource})`)}`);
+	console.log(`${ui.label("knowledge folder")}: ${formatKnowledgePathStatus(status)} ${ui.label(`(${status.kbPathSource})`)}`);
 	console.log(`${ui.label("local cache folder")}: ${formatPathStatus(status.cachePath, status.cacheExists, status.cacheIsDirectory)} ${ui.label(`(${status.cachePathSource})`)}`);
 	if (!status.kbExists) console.log(`${ui.label("state")}: ${ui.warn("no knowledge base found yet")}`);
 	else if (!status.kbIsDirectory) console.log(`${ui.label("state")}: ${ui.error("knowledge base path is not a folder")}`);
+	else if (status.kbContentState !== "ready") console.log(`${ui.label("state")}: ${ui.label("knowledge base folder is empty")}`);
 	else console.log(`${ui.label("state")}: ${ui.ok("knowledge base found")}`);
 });
 await program.parseAsync();
@@ -4101,6 +4262,12 @@ function formatPathStatus(path, exists, isDirectory) {
 	if (!isDirectory) return `${path} ${ui.error("[not a folder]")}`;
 	return `${path} ${ui.ok("[ok]")}`;
 }
+function formatKnowledgePathStatus(status) {
+	if (!status.kbExists) return `${status.kbPath} ${ui.warn("[missing]")}`;
+	if (!status.kbIsDirectory) return `${status.kbPath} ${ui.error("[not a folder]")}`;
+	if (status.kbContentState !== "ready") return `${status.kbPath} ${ui.label("[empty]")}`;
+	return `${status.kbPath} ${ui.ok("[ok]")}`;
+}
 //#endregion
 export {};