@payconductor/houndsman 0.5.0 → 0.7.0

package/src/harness/prompts/states/investigate-prompt.ts

@@ -0,0 +1,37 @@
+/**
+ * Prompt do estado INVESTIGATE — o coração da coleta de evidências.
+ */
+
+import type { AgentContext } from "../../agent/agent-context";
+import type { InvestigationTask } from "../../investigation/investigation-task";
+
+/** Instruções do estado de investigação. */
+export function investigatePrompt(
+	context: AgentContext,
+	tasks: readonly InvestigationTask[],
+): string {
+	const lines = [
+		"## Tarefas priorizadas",
+		...tasks.map(
+			(task, index) =>
+				`${index + 1}. [${task.severity}] ${task.rule} — arquivos: ${task.files.slice(0, 8).join(", ") || "(domínio)"}`,
+		),
+		"",
+		"## Como investigar",
+		"- Use file_outline/symbol_context/find_references em vez de ler arquivos inteiros.",
+		"- Registre evidência para cada draft (evidenceIds).",
+		"- Prefira não concluir quando faltar evidência: use coverage 'skipped' com motivo.",
+		"- Não cite arquivos fora do domínio/impacto.",
+		"",
+		"## Formato",
+		"Produza JSON: { findingDrafts: [...], coverage: [{ rule, status, reason? }] }.",
+	];
+	if (context.files.length > 0) {
+		lines.push(
+			"",
+			"## Arquivos do domínio",
+			...context.files.slice(0, 40).map((file) => `- ${file}`),
+		);
+	}
+	return lines.join("\n");
+}

package/src/harness/prompts/states/orient-prompt.ts

@@ -0,0 +1,15 @@
+/**
+ * Prompt do estado ORIENT.
+ */
+
+import type { AgentContext } from "../../agent/agent-context";
+
+/** Pede hipóteses iniciais (sem achados). */
+export function orientPrompt(context: AgentContext): string {
+	return [
+		`Oriente a revisão do watchdog '${context.watchdog.name}'.`,
+		"Liste hipóteses de violação que precisam ser investigadas.",
+		"Use as regras e o delta AST fornecidos. Não emita findings neste estado.",
+		"Produza JSON com `hypotheses`.",
+	].join("\n");
+}

package/src/harness/prompts/states/verify-prompt.ts

@@ -0,0 +1,22 @@
+/**
+ * Prompt do estado VERIFY (crítica refutadora).
+ *
+ * O crítico determinístico é o default; este prompt fica disponível para um
+ * crítico por IA, que deve tentar **derrubar** cada draft.
+ */
+
+import type { FindingDraft } from "../../investigation/evidence";
+
+/** Prompt de refutação. */
+export function verifyPrompt(drafts: readonly FindingDraft[]): string {
+	return [
+		"Tente refutar cada draft abaixo.",
+		"Responda `keep` apenas se a evidência sustenta a violação.",
+		"Use `downgrade` quando a evidência sustenta algo mais leve.",
+		...drafts.map(
+			(draft) =>
+				`- ${draft.rule} · ${draft.file}:${draft.line ?? "?"} · confiança ${draft.confidence}`,
+		),
+		"Produza JSON com `decisions`.",
+	].join("\n");
+}

package/src/harness/tools/agent-tool.ts

@@ -0,0 +1,102 @@
+/**
+ * Contrato das tools do harness nativo.
+ *
+ * Cada tool declara metadados (categoria, capabilities, custo, cache, limite) e
+ * um schema Zod. É read-only por construção: não executa shell arbitrário, não
+ * escreve arquivos e não acessa a rede.
+ */
+
+import type { ZodType, ZodTypeAny } from "zod";
+import type { AstService } from "../../core/ast/service";
+import type { DiffSource } from "../../core/diff-source";
+import type { Watchdog } from "../../core/domain/watchdog";
+import type { AgentContext } from "../agent/agent-context";
+import type { AgentReporter } from "../agent/agent-reporter";
+import type { AgentState } from "../investigation/agent-state";
+import type { Evidence } from "../investigation/evidence";
+import type { RuleAnalysis } from "../investigation/rule-analyzer";
+import type { ToolCache } from "./tool-cache";
+import type { ToolCallBudget } from "./tool-call-budget";
+
+/** Categoria de agrupamento (usada no prompt e na policy). */
+export type ToolCategory = "context" | "code" | "symbol" | "ast" | "rules" | "evidence";
+
+/** Capability declarada por uma tool (a policy libera por capability). */
+export type ToolCapability =
+	| "read"
+	| "search"
+	| "outline"
+	| "symbol"
+	| "references"
+	| "ast"
+	| "impact"
+	| "rules"
+	| "tests"
+	| "docs";
+
+/** Metadados estáveis (o prompt é gerado a partir daqui). */
+export type ToolMetadata = {
+	name: string;
+	description: string;
+	category: ToolCategory;
+	capabilities: readonly ToolCapability[];
+	readOnly: true;
+	/** Custo relativo para o planner (1 = barato, 5 = caro). */
+	cost: 1 | 2 | 3 | 4 | 5;
+	cacheTtlMs?: number;
+	maxCallsPerAgent?: number;
+};
+
+/** Resultado de uma tool (sempre estruturado). */
+export type ToolResult<T = unknown> = {
+	ok: boolean;
+	data?: T;
+	evidence?: Evidence[];
+	truncated?: boolean;
+	hint?: string;
+	error?: string;
+};
+
+/** Contexto de execução de uma tool. */
+export type ToolContext = {
+	repoRoot: string;
+	watchdog: Watchdog;
+	diff: DiffSource;
+	ast: AstService;
+	state: AgentState;
+	budget: ToolCallBudget;
+	cache: ToolCache;
+	logger: AgentReporter;
+	agent: AgentContext;
+	/** Análises determinísticas das regras do watchdog (por texto). */
+	rules: ReadonlyMap<string, RuleAnalysis>;
+};
+
+/** Tool executável por um agente. */
+export interface AgentTool<I = unknown, O = unknown> {
+	readonly metadata: ToolMetadata;
+	readonly inputSchema: ZodType<I>;
+	execute(input: I, context: ToolContext): Promise<ToolResult<O>>;
+}
+
+/** Módulo de registro de tools (permite agrupar por domínio). */
+export interface ToolModule {
+	register(registry: ToolRegistryLike): void;
+}
+
+/**
+ * Forma aceita pelo registry. `execute(input: never)` aceita qualquer tool
+ * concreta por contravariância, sem apelar para `any`.
+ */
+export type RegisterableTool = {
+	readonly metadata: ToolMetadata;
+	readonly inputSchema: ZodTypeAny;
+	execute(input: never, context: ToolContext): Promise<ToolResult<unknown>>;
+};
+
+/** Superfície mínima de registro (evita dependência circular com a classe). */
+export interface ToolRegistryLike {
+	registerTool(tool: RegisterableTool): void;
+}
+
+export type { ZodTypeAny };

package/src/harness/tools/builtin/changed-symbols-tool.ts

@@ -0,0 +1,48 @@
+/**
+ * Tool `changed_symbols` — delta AST da revisão (o que realmente mudou).
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+
+const Input = z.object({ file: z.string().optional() });
+
+/** Símbolos adicionados/removidos/modificados e assinaturas alteradas. */
+export class ChangedSymbolsTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "changed_symbols",
+		description: "Delta AST da revisão: símbolos adicionados/removidos/modificados.",
+		category: "ast",
+		capabilities: ["ast"],
+		readOnly: true,
+		cost: 1,
+		cacheTtlMs: 300_000,
+	};
+
+	readonly inputSchema = Input;
+
+	async execute(
+		input: z.infer<typeof Input>,
+		context: import("../tool-context").ToolContext,
+	): Promise<ToolResult<unknown>> {
+		const entries = [];
+		for (const [file, analysis] of context.agent.ast) {
+			if (input.file && file !== input.file) continue;
+			if (!analysis.delta) continue;
+			entries.push({
+				file,
+				added: analysis.delta.addedSymbols.map((symbol) => symbol.name),
+				removed: analysis.delta.removedSymbols.map((symbol) => symbol.name),
+				modified: analysis.delta.modifiedSymbols.map((symbol) => symbol.name),
+				changedSignatures: analysis.delta.changedSignatures,
+				addedImports: analysis.delta.addedImports,
+				removedImports: analysis.delta.removedImports,
+			});
+		}
+		return {
+			ok: true,
+			data: { files: entries },
+			...(entries.length === 0 ? { hint: "Sem delta AST para os filtros." } : {}),
+		};
+	}
+}

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),
+			},
+		};
+	}
+}