@payconductor/houndsman 0.4.0 → 0.6.0

package/src/harness/tools/builtin/doc-context-tool.ts

@@ -0,0 +1,74 @@
+/**
+ * Tool `doc_context` — trechos de docs mapeados (nunca o documento inteiro).
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+import { PathGuard } from "../path-guard";
+import { TOOL_LIMITS } from "../result-limiter";
+import { readLines, snippet } from "./helpers";
+
+const Input = z.object({
+	query: z.string().min(2),
+	docs: z.array(z.string()).optional(),
+});
+
+/** Procura a query nos docs do brief e devolve 2 KB de contexto. */
+export class DocContextTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "doc_context",
+		description: "Trechos de documentação relevantes para a revisão.",
+		category: "context",
+		capabilities: ["docs", "search"],
+		readOnly: true,
+		cost: 2,
+		cacheTtlMs: 120_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		const guard = new PathGuard(context.repoRoot);
+		const docs = input.docs ?? [...context.agent.docs];
+		const needle = input.query.toLowerCase();
+		const matches: unknown[] = [];
+		const evidence: import("../../investigation/evidence").Evidence[] = [];
+
+		for (const doc of docs.slice(0, 20)) {
+			let relative: string;
+			try {
+				relative = guard.relativePath(doc);
+			} catch {
+				continue;
+			}
+			const lines = readLines(guard.assertReadable(relative));
+			if (!lines) continue;
+			const index = lines.findIndex((line) => line.toLowerCase().includes(needle));
+			if (index < 0) continue;
+			const start = Math.max(1, index - 2);
+			const end = Math.min(lines.length, index + 12);
+			matches.push({ file: relative, startLine: start, endLine: end });
+			evidence.push({
+				id: "",
+				file: relative,
+				startLine: start,
+				endLine: end,
+				snippet: snippet(lines, start, end).slice(0, TOOL_LIMITS.maxBytes),
+				kind: "doc",
+				sourceTool: "doc_context",
+				confidence: 0.5,
+			});
+			if (matches.length >= 5) break;
+		}
+
+		return {
+			ok: true,
+			data: { matches },
+			evidence,
+			...(matches.length === 0 ? { hint: "Nenhum doc menciona a query." } : {}),
+		};
+	}
+}

package/src/harness/tools/builtin/file-outline-tool.ts

@@ -0,0 +1,66 @@
+/**
+ * Tool `file_outline` — mapa de símbolos do arquivo (sem corpo).
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+import { PathGuard } from "../path-guard";
+
+const Input = z.object({ path: z.string().min(1) });
+
+/** Metadados + imports/exports + símbolos do arquivo. */
+export class FileOutlineTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "file_outline",
+		description: "Mapa de símbolos, imports e exports de um arquivo (sem corpo).",
+		category: "symbol",
+		capabilities: ["outline", "ast"],
+		readOnly: true,
+		cost: 2,
+		cacheTtlMs: 120_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		const guard = new PathGuard(context.repoRoot);
+		let path: string;
+		try {
+			path = guard.relativePath(input.path);
+		} catch (error) {
+			return {
+				ok: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+		const facts = await context.ast.factsOf(path);
+		if (!facts) {
+			return {
+				ok: false,
+				error: "AST indisponível para este arquivo (grammar/língua).",
+				hint: "Use read_file_range para inspecionar o trecho.",
+			};
+		}
+		return {
+			ok: true,
+			data: {
+				path,
+				language: facts.language,
+				symbols: facts.symbols.map((symbol) => ({
+					name: symbol.name,
+					kind: symbol.kind,
+					exported: symbol.exported,
+					startLine: symbol.startLine,
+					endLine: symbol.endLine,
+					signature: symbol.signature,
+				})),
+				imports: facts.imports,
+				exports: facts.exports,
+				decorators: facts.decorators,
+			},
+		};
+	}
+}

package/src/harness/tools/builtin/find-references-tool.ts

@@ -0,0 +1,66 @@
+/**
+ * Tool `find_references` — usos/chamadas de um símbolo via `git grep`.
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+import { TOOL_LIMITS } from "../result-limiter";
+import { gitGrep, parseGrepLine } from "./helpers";
+
+const Input = z.object({
+	symbol: z.string().min(2),
+	file: z.string().optional(),
+});
+
+/** Até 50 referências com arquivo/linha/trecho. */
+export class FindReferencesTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "find_references",
+		description: "Procura usos/chamadas de um símbolo (até 50 referências).",
+		category: "symbol",
+		capabilities: ["references", "search"],
+		readOnly: true,
+		cost: 2,
+		cacheTtlMs: 60_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		const args = ["-n", "-I", "-F", "-w", "-e", input.symbol];
+		if (input.file) args.push("--", input.file);
+		const result = gitGrep(context.repoRoot, args);
+		if (!result.ok) {
+			return { ok: true, data: { references: [], truncated: false } };
+		}
+		const lines = result.stdout.split("\n").map(parseGrepLine);
+		const references = lines
+			.filter((line): line is NonNullable<typeof line> => line !== null)
+			.slice(0, TOOL_LIMITS.maxResults)
+			.map((line) => ({
+				file: line.file,
+				line: line.line,
+				text: line.text.slice(0, 200),
+			}));
+		const evidence = references.slice(0, 10).map((reference) => ({
+			id: "",
+			file: reference.file,
+			startLine: reference.line,
+			endLine: reference.line,
+			snippet: reference.text,
+			kind: "reference" as const,
+			sourceTool: "find_references",
+			confidence: 0.7,
+		}));
+		const truncated = lines.length > references.length;
+		return {
+			ok: true,
+			data: { references, truncated },
+			evidence,
+			...(truncated ? { truncated: true, hint: "Refine com file." } : {}),
+		};
+	}
+}

package/src/harness/tools/builtin/find-symbol-tool.ts

@@ -0,0 +1,91 @@
+/**
+ * Tool `find_symbol` — localiza a definição de um símbolo via AST.
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+import { PathGuard } from "../path-guard";
+import { TOOL_LIMITS } from "../result-limiter";
+import { readLines, snippet } from "./helpers";
+
+const Input = z.object({
+	name: z.string().min(2),
+	kind: z.string().optional(),
+	file: z.string().optional(),
+});
+
+/** Definições encontradas (até 20), com evidência. */
+export class FindSymbolTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "find_symbol",
+		description: "Encontra a definição de um símbolo (AST) e o trecho curto.",
+		category: "symbol",
+		capabilities: ["symbol"],
+		readOnly: true,
+		cost: 3,
+		cacheTtlMs: 60_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		const guard = new PathGuard(context.repoRoot);
+		const files = input.file
+			? [input.file]
+			: [
+					...new Set([
+						...context.agent.files,
+						...(context.agent.impact?.affectedFiles ?? []),
+					]),
+				];
+		const definitions: unknown[] = [];
+		const evidence: import("../../investigation/evidence").Evidence[] = [];
+
+		for (const file of files.slice(0, 50)) {
+			let relative: string;
+			try {
+				relative = guard.relativePath(file);
+			} catch {
+				continue;
+			}
+			const facts = await context.ast.factsOf(relative);
+			if (!facts) continue;
+			for (const symbol of facts.symbols) {
+				if (!symbol.name.includes(input.name)) continue;
+				if (input.kind && symbol.kind !== input.kind) continue;
+				const lines = readLines(guard.assertReadable(relative)) ?? [];
+				definitions.push({
+					file: relative,
+					name: symbol.name,
+					kind: symbol.kind,
+					exported: symbol.exported,
+					startLine: symbol.startLine,
+					endLine: symbol.endLine,
+					signature: symbol.signature,
+				});
+				evidence.push({
+					id: "",
+					file: relative,
+					startLine: symbol.startLine,
+					endLine: Math.min(symbol.startLine + 10, symbol.endLine),
+					snippet: snippet(lines, symbol.startLine, symbol.startLine + 10),
+					kind: "definition",
+					sourceTool: "find_symbol",
+					confidence: 0.9,
+				});
+				if (definitions.length >= 20) break;
+			}
+			if (definitions.length >= 20) break;
+		}
+
+		return {
+			ok: definitions.length > 0,
+			data: { definitions: definitions.slice(0, 20) },
+			evidence: evidence.slice(0, TOOL_LIMITS.maxResults),
+			...(definitions.length === 0 ? { error: "símbolo não encontrado." } : {}),
+		};
+	}
+}

package/src/harness/tools/builtin/helpers.ts

@@ -0,0 +1,115 @@
+/**
+ * Helpers compartilhados pelas tools built-in (leitura, grep e snippets).
+ *
+ * Tudo é read-only e passa pelo `PathGuard`; nada executa shell arbitrário.
+ */
+
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+import { runGit } from "../../../core/git-runner";
+import type { PathGuard } from "../path-guard";
+import { limitLines, limitText, numberLines, TOOL_LIMITS } from "../result-limiter";
+
+/** Linhas de um arquivo; `null` se ilegível. */
+export function readLines(path: string): string[] | null {
+	try {
+		return readFileSync(path, "utf8").replace(/\r\n/g, "\n").split("\n");
+	} catch {
+		return null;
+	}
+}
+
+/** Trecho numerado de um arquivo (1-based, inclusivo). */
+export function numberedRange(
+	lines: readonly string[],
+	startLine: number,
+	endLine: number,
+): string {
+	const start = Math.max(1, startLine);
+	const end = Math.min(lines.length, Math.max(start, endLine));
+	const slice = lines.slice(start - 1, end);
+	return numberLines(start, slice);
+}
+
+/** Snippet bruto (sem numeração), limitado em linhas. */
+export function snippet(
+	lines: readonly string[],
+	startLine: number,
+	endLine: number,
+): string {
+	const start = Math.max(1, startLine);
+	const end = Math.min(lines.length, Math.max(start, endLine));
+	const limited = limitLines(lines.slice(start - 1, end), TOOL_LIMITS.maxSnippetLines);
+	return limitText(limited.lines.join("\n")).text;
+}
+
+/** Executa `git grep` na raiz do repositório. */
+export function gitGrep(
+	root: string,
+	args: string[],
+): { ok: boolean; stdout: string; stderr: string } {
+	try {
+		const stdout = runGit(["-C", root, "grep", ...args]);
+		return { ok: true, stdout, stderr: "" };
+	} catch (error) {
+		return {
+			ok: false,
+			stdout: "",
+			stderr: error instanceof Error ? error.message : String(error),
+		};
+	}
+}
+
+/** Caminho relativo normalizado. */
+export function relativeTo(root: string, path: string): string {
+	return relative(root, path).replace(/\\/g, "/");
+}
+
+/** Lê uma faixa validada (PathGuard + limites). */
+export function readRange(
+	guard: PathGuard,
+	path: string,
+	startLine: number,
+	endLine: number,
+): {
+	path: string;
+	startLine: number;
+	endLine: number;
+	totalLines: number;
+	content: string;
+	truncated: boolean;
+} | null {
+	const absolute = guard.assertReadable(path);
+	const lines = readLines(absolute);
+	if (!lines) return null;
+	const start = Math.max(1, startLine);
+	const requestedEnd = Math.max(start, endLine);
+	const cappedEnd = Math.min(
+		requestedEnd,
+		start + TOOL_LIMITS.maxLines - 1,
+		lines.length,
+	);
+	const limited = limitText(
+		numberLines(start, lines.slice(start - 1, cappedEnd)),
+		TOOL_LIMITS.maxBytes,
+	);
+	return {
+		path: relativeTo(guard.root, absolute),
+		startLine: start,
+		endLine: cappedEnd,
+		totalLines: lines.length,
+		content: limited.text,
+		truncated: limited.truncated || cappedEnd < requestedEnd,
+	};
+}
+
+/** Parseia uma linha `arquivo:linha:conteúdo` do `git grep -n`. */
+export function parseGrepLine(
+	line: string,
+): { file: string; line: number; text: string } | null {
+	const match = /^(.+?):(\d+):(.*)$/.exec(line);
+	if (!match) return null;
+	const [, file, number, text] = match;
+	if (!file || !number) return null;
+	return { file, line: Number.parseInt(number, 10), text: text ?? "" };
+}

package/src/harness/tools/builtin/impact-tool.ts

@@ -0,0 +1,48 @@
+/**
+ * Tool `impact` — importadores e exports alterados (impacto reverso).
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+
+const Input = z.object({ file: z.string().optional() });
+
+/** Dependências reversas do diff (top N). */
+export class ImpactTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "impact",
+		description:
+			"Arquivos que importam o diff e exports alterados (impacto reverso).",
+		category: "ast",
+		capabilities: ["impact"],
+		readOnly: true,
+		cost: 2,
+		cacheTtlMs: 300_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		const impact = context.agent.impact;
+		if (!impact) {
+			return {
+				ok: true,
+				data: { importers: {}, affectedFiles: [], exportedChanges: [] },
+			};
+		}
+		const importers = input.file
+			? { [input.file]: impact.importers[input.file] ?? [] }
+			: impact.importers;
+		return {
+			ok: true,
+			data: {
+				importers,
+				affectedFiles: impact.affectedFiles.slice(0, 40),
+				exportedChanges: impact.exportedChanges.slice(0, 40),
+			},
+		};
+	}
+}

package/src/harness/tools/builtin/imports-exports-tool.ts

@@ -0,0 +1,53 @@
+/**
+ * Tool `imports_exports` — imports, exports e decorators de um arquivo.
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+import { PathGuard } from "../path-guard";
+
+const Input = z.object({ file: z.string().min(1) });
+
+/** Lista estrutural do arquivo. */
+export class ImportsExportsTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "imports_exports",
+		description: "Imports, exports e decorators de um arquivo (AST).",
+		category: "ast",
+		capabilities: ["ast"],
+		readOnly: true,
+		cost: 2,
+		cacheTtlMs: 120_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		const guard = new PathGuard(context.repoRoot);
+		let path: string;
+		try {
+			path = guard.relativePath(input.file);
+		} catch (error) {
+			return {
+				ok: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+		const facts = await context.ast.factsOf(path);
+		if (!facts) {
+			return { ok: false, error: "AST indisponível para este arquivo." };
+		}
+		return {
+			ok: true,
+			data: {
+				file: path,
+				imports: facts.imports,
+				exports: facts.exports,
+				decorators: facts.decorators,
+			},
+		};
+	}
+}

package/src/harness/tools/builtin/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Registro das tools built-in do harness.
+ *
+ * Adicionar uma tool = criar a classe + registrar aqui + contract test. O
+ * `ReviewAgent` não muda.
+ */
+
+import type { ToolModule, ToolRegistryLike } from "../agent-tool";
+import { ChangedSymbolsTool } from "./changed-symbols-tool";
+import { DocContextTool } from "./doc-context-tool";
+import { FileOutlineTool } from "./file-outline-tool";
+import { FindReferencesTool } from "./find-references-tool";
+import { FindSymbolTool } from "./find-symbol-tool";
+import { ImpactTool } from "./impact-tool";
+import { ImportsExportsTool } from "./imports-exports-tool";
+import { ListFilesTool } from "./list-files-tool";
+import { PrContextTool } from "./pr-context-tool";
+import { ReadFileRangeTool } from "./read-file-range-tool";
+import { RuleSignalsTool } from "./rule-signals-tool";
+import { SearchCodeTool } from "./search-code-tool";
+import { SymbolContextTool } from "./symbol-context-tool";
+import { TestsForSymbolTool } from "./tests-for-symbol-tool";
+
+/** Módulo com todas as tools read-only. */
+export class BuiltinToolsModule implements ToolModule {
+	register(registry: ToolRegistryLike): void {
+		registry.registerTool(new PrContextTool());
+		registry.registerTool(new ListFilesTool());
+		registry.registerTool(new FileOutlineTool());
+		registry.registerTool(new ReadFileRangeTool());
+		registry.registerTool(new SearchCodeTool());
+		registry.registerTool(new FindSymbolTool());
+		registry.registerTool(new FindReferencesTool());
+		registry.registerTool(new SymbolContextTool());
+		registry.registerTool(new ChangedSymbolsTool());
+		registry.registerTool(new ImpactTool());
+		registry.registerTool(new ImportsExportsTool());
+		registry.registerTool(new RuleSignalsTool());
+		registry.registerTool(new TestsForSymbolTool());
+		registry.registerTool(new DocContextTool());
+	}
+}
+
+export {
+	ChangedSymbolsTool,
+	DocContextTool,
+	FileOutlineTool,
+	FindReferencesTool,
+	FindSymbolTool,
+	ImpactTool,
+	ImportsExportsTool,
+	ListFilesTool,
+	PrContextTool,
+	ReadFileRangeTool,
+	RuleSignalsTool,
+	SearchCodeTool,
+	SymbolContextTool,
+	TestsForSymbolTool,
+};

package/src/harness/tools/builtin/list-files-tool.ts

@@ -0,0 +1,85 @@
+/**
+ * Tool `list_files` — lista arquivos do repositório (mapa, não conteúdo).
+ */
+
+import { z } from "zod";
+import { runGit } from "../../../core/git-runner";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+import { TOOL_LIMITS } from "../result-limiter";
+
+const Input = z.object({
+	directory: z.string().optional(),
+	glob: z.string().optional(),
+});
+
+/** Lista até 200 arquivos rastreados pelo git. */
+export class ListFilesTool implements AgentTool<z.infer<typeof Input>, string[]> {
+	readonly metadata: ToolMetadata = {
+		name: "list_files",
+		description: "Lista arquivos rastreados (diretório/glob opcionais).",
+		category: "code",
+		capabilities: ["outline"],
+		readOnly: true,
+		cost: 1,
+		cacheTtlMs: 120_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<string[]>> {
+		// `git grep -l` com padrão vazio não lista tudo; usamos `ls-files`.
+		let files: string[];
+		try {
+			const stdout = runGit(["-C", context.repoRoot, "ls-files"]);
+			files = stdout
+				.split("\n")
+				.map((line) => line.trim())
+				.filter(Boolean);
+		} catch {
+			return { ok: false, error: "não foi possível listar os arquivos (git)." };
+		}
+		if (input.directory) {
+			const prefix = input.directory.replace(/\/+$/, "");
+			files = files.filter(
+				(file) => file.startsWith(`${prefix}/`) || file === prefix,
+			);
+		}
+		if (input.glob) {
+			const matcher = globToRegExp(input.glob);
+			files = files.filter((file) => matcher.test(file));
+		}
+		const truncated = files.length > TOOL_LIMITS.maxFiles;
+		return {
+			ok: true,
+			data: files.slice(0, TOOL_LIMITS.maxFiles),
+			truncated,
+			...(truncated ? { hint: "Refine com directory/glob." } : {}),
+		};
+	}
+}
+
+/** Converte um glob simples em regex. */
+export function globToRegExp(glob: string): RegExp {
+	let pattern = "";
+	for (let index = 0; index < glob.length; index++) {
+		const char = glob[index] ?? "";
+		if (char === "*") {
+			if (glob[index + 1] === "*") {
+				pattern += ".*";
+				index++;
+			} else {
+				pattern += "[^/]*";
+			}
+			continue;
+		}
+		if (char === "?") {
+			pattern += ".";
+			continue;
+		}
+		pattern += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+	}
+	return new RegExp(`^${pattern}$`);
+}

package/src/harness/tools/builtin/pr-context-tool.ts

@@ -0,0 +1,41 @@
+/**
+ * Tool `pr_context` — contexto resumido da PR (já compactado).
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+
+/** Contexto da PR para orientação do agente. */
+export class PrContextTool implements AgentTool<Record<string, never>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "pr_context",
+		description: "Contexto resumido da PR (objetivo, motivação, mudanças).",
+		category: "context",
+		capabilities: ["read"],
+		readOnly: true,
+		cost: 1,
+		cacheTtlMs: 300_000,
+	};
+
+	readonly inputSchema = z.object({});
+
+	async execute(
+		_input: Record<string, never>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		return {
+			ok: true,
+			data: {
+				project: context.agent.projectName,
+				branch: context.agent.branch,
+				watchdog: context.agent.watchdog.id,
+				scope: context.agent.watchdog.scope,
+				context: context.agent.context ?? null,
+				files: context.agent.files,
+				overflow: context.agent.overflow,
+				deleted: context.agent.deleted,
+				docs: context.agent.docs,
+			},
+		};
+	}
+}