@payconductor/houndsman 0.5.0 → 0.6.0

package/src/harness/tools/builtin/read-file-range-tool.ts

@@ -0,0 +1,73 @@
+/**
+ * Tool `read_file_range` — lê um trecho explícito (nunca o arquivo 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, readRange } from "./helpers";
+
+const Input = z.object({
+	path: z.string().min(1),
+	startLine: z.number().int().min(1),
+	endLine: z.number().int().min(1),
+});
+
+/** Leitura por faixa, com no máximo 200 linhas/32 KB. */
+export class ReadFileRangeTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "read_file_range",
+		description: "Lê um trecho de arquivo (faixa obrigatória, até 200 linhas).",
+		category: "code",
+		capabilities: ["read"],
+		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);
+		try {
+			const range = readRange(guard, input.path, input.startLine, input.endLine);
+			if (!range) return { ok: false, error: "arquivo ilegível." };
+			const lines = readLines(guard.assertReadable(input.path)) ?? [];
+			const evidence = {
+				id: "",
+				file: range.path,
+				startLine: range.startLine,
+				endLine: range.endLine,
+				snippet: lines.slice(range.startLine - 1, range.endLine).join("\n"),
+				kind: "diff" as const,
+				sourceTool: "read_file_range",
+				confidence: 0.6,
+			};
+			return {
+				ok: true,
+				data: range,
+				...(range.truncated
+					? {
+							truncated: true,
+							hint: `Faixa limitada a ${TOOL_LIMITS.maxLines} linhas; refine o intervalo.`,
+						}
+					: {}),
+				evidence: [
+					{
+						...evidence,
+						snippet: evidence.snippet.slice(0, TOOL_LIMITS.maxBytes),
+					},
+				],
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	}
+}

package/src/harness/tools/builtin/rule-signals-tool.ts

@@ -0,0 +1,36 @@
+/**
+ * Tool `rule_signals` — traduz uma regra em sinais e checks.
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+
+const Input = z.object({ rule: z.string().min(3) });
+
+/** Devolve a `RuleAnalysis` determinística da regra. */
+export class RuleSignalsTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "rule_signals",
+		description: "Sinais, keywords e checks sugeridos para uma regra do watchdog.",
+		category: "rules",
+		capabilities: ["rules"],
+		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 analysis =
+			context.rules.get(input.rule) ??
+			[...context.rules.values()].find((item) => item.rule.includes(input.rule));
+		if (!analysis) {
+			return { ok: false, error: "regra não encontrada no watchdog." };
+		}
+		return { ok: true, data: analysis };
+	}
+}

package/src/harness/tools/builtin/search-code-tool.ts

@@ -0,0 +1,65 @@
+/**
+ * Tool `search_code` — localiza padrões via `git grep` e devolve snippets.
+ */
+
+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({
+	query: z.string().min(2),
+	mode: z.enum(["fixed", "regex"]).optional(),
+	path: z.string().optional(),
+	contextLines: z.number().int().min(0).max(3).optional(),
+	maxResults: z.number().int().min(1).max(50).optional(),
+});
+
+/** Busca com limite de resultados e snippets curtos. */
+export class SearchCodeTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "search_code",
+		description: "Procura um padrão no código (até 50 resultados com snippet).",
+		category: "code",
+		capabilities: ["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 mode = input.mode === "regex" ? "-E" : "-F";
+		const args = ["-n", "-I", mode, "-e", input.query];
+		if (input.path) args.push("--", input.path);
+		const result = gitGrep(context.repoRoot, args);
+		if (!result.ok) {
+			// `git grep` retorna 1 quando não há match (não é erro).
+			if (result.stderr.includes("exit") || result.stdout === "") {
+				return { ok: true, data: { results: [], truncated: false } };
+			}
+			return { ok: false, error: result.stderr || "falha no git grep." };
+		}
+		const max = input.maxResults ?? TOOL_LIMITS.maxResults;
+		const results = result.stdout
+			.split("\n")
+			.map(parseGrepLine)
+			.filter((line): line is NonNullable<typeof line> => line !== null)
+			.slice(0, max)
+			.map((line) => ({
+				file: line.file,
+				line: line.line,
+				text: line.text.slice(0, 240),
+			}));
+		const truncated = result.stdout.trim().split("\n").length > results.length;
+		return {
+			ok: true,
+			data: { results, truncated },
+			...(truncated ? { truncated: true, hint: "Refine a query/path." } : {}),
+		};
+	}
+}

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

@@ -0,0 +1,106 @@
+/**
+ * Tool `symbol_context` — definição + janela curta do corpo + referências.
+ */
+
+import { z } from "zod";
+import type { AgentTool, ToolMetadata, ToolResult } from "../agent-tool";
+import { PathGuard } from "../path-guard";
+import { TOOL_LIMITS } from "../result-limiter";
+import { gitGrep, numberedRange, parseGrepLine, readLines, snippet } from "./helpers";
+
+const Input = z.object({
+	symbol: z.string().min(2),
+	file: z.string().optional(),
+});
+
+/** Devolve no máximo ~120 linhas do símbolo (nunca o arquivo inteiro). */
+export class SymbolContextTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "symbol_context",
+		description: "Definição + assinatura + corpo curto + referências de um símbolo.",
+		category: "symbol",
+		capabilities: ["symbol", "read"],
+		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 maxLines = Math.min(TOOL_LIMITS.maxLines, 120);
+
+		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;
+			const symbol = facts.symbols.find((item) => item.name === input.symbol);
+			if (!symbol) continue;
+
+			const lines = readLines(guard.assertReadable(relative)) ?? [];
+			const endLine = Math.min(symbol.endLine, symbol.startLine + maxLines - 1);
+			const references = referencesOf(context.repoRoot, input.symbol);
+			return {
+				ok: true,
+				data: {
+					file: relative,
+					name: symbol.name,
+					kind: symbol.kind,
+					exported: symbol.exported,
+					signature: symbol.signature,
+					startLine: symbol.startLine,
+					endLine,
+					truncatedBody: symbol.endLine > endLine,
+					body: numberedRange(lines, symbol.startLine, endLine),
+					references,
+				},
+				evidence: [
+					{
+						id: "",
+						file: relative,
+						startLine: symbol.startLine,
+						endLine,
+						snippet: snippet(lines, symbol.startLine, endLine),
+						kind: "definition",
+						sourceTool: "symbol_context",
+						confidence: 0.9,
+					},
+				],
+			};
+		}
+		return {
+			ok: false,
+			error: `símbolo '${input.symbol}' não encontrado (AST).`,
+			hint: "Use search_code/find_references.",
+		};
+	}
+}
+
+/** Referências resumidas (arquivo:linha). */
+function referencesOf(root: string, symbol: string): { file: string; line: number }[] {
+	const result = gitGrep(root, ["-n", "-I", "-F", "-w", "-e", symbol]);
+	if (!result.ok) return [];
+	return result.stdout
+		.split("\n")
+		.map(parseGrepLine)
+		.filter((line): line is NonNullable<typeof line> => line !== null)
+		.slice(0, 20)
+		.map((line) => ({ file: line.file, line: line.line }));
+}

package/src/harness/tools/builtin/tests-for-symbol-tool.ts

@@ -0,0 +1,61 @@
+/**
+ * Tool `tests_for_symbol` — arquivos de teste relacionados a um símbolo.
+ */
+
+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() });
+
+const TEST_PATHSPECS = [
+	"*.test.*",
+	"*.spec.*",
+	"**/__tests__/**",
+	"**/tests/**",
+	"**/test/**",
+];
+
+/** Referências em arquivos de teste (até 20 arquivos). */
+export class TestsForSymbolTool implements AgentTool<z.infer<typeof Input>, unknown> {
+	readonly metadata: ToolMetadata = {
+		name: "tests_for_symbol",
+		description: "Arquivos de teste que mencionam um símbolo.",
+		category: "evidence",
+		capabilities: ["tests", "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 args = ["-n", "-I", "-F", "-w", "-e", input.symbol];
+		if (input.file) args.push("--", input.file);
+		else args.push("--", ...TEST_PATHSPECS);
+		const result = gitGrep(context.repoRoot, args);
+		if (!result.ok) return { ok: true, data: { files: [], references: [] } };
+		const references = result.stdout
+			.split("\n")
+			.map(parseGrepLine)
+			.filter((line): line is NonNullable<typeof line> => line !== null)
+			.slice(0, TOOL_LIMITS.maxResults);
+		const files = [...new Set(references.map((line) => line.file))].slice(0, 20);
+		const evidence = references.slice(0, 10).map((line) => ({
+			id: "",
+			file: line.file,
+			startLine: line.line,
+			endLine: line.line,
+			snippet: line.text,
+			kind: "test" as const,
+			sourceTool: "tests_for_symbol",
+			confidence: 0.6,
+		}));
+		return { ok: true, data: { files, references }, evidence };
+	}
+}

package/src/harness/tools/path-guard.ts

@@ -0,0 +1,90 @@
+/**
+ * Guarda de caminhos das tools — impede leitura fora do repositório e de
+ * arquivos sensíveis (`..`, `.git`, `.env*`, binários, arquivos enormes).
+ */
+
+import { statSync } from "node:fs";
+import { extname, isAbsolute, relative, resolve, sep } from "node:path";
+
+/** Erro de caminho bloqueado (mensagem segura). */
+export class PathGuardError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "PathGuardError";
+	}
+}
+
+/** Extensões consideradas binárias. */
+const BINARY_EXTENSIONS = new Set([
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".webp",
+	".ico",
+	".pdf",
+	".zip",
+	".gz",
+	".tgz",
+	".wasm",
+	".node",
+	".so",
+	".dll",
+	".exe",
+	".lockb",
+]);
+
+/** Nomes/diretórios bloqueados. */
+function isBlockedPath(path: string): boolean {
+	const normalized = path.replace(/\\/g, "/");
+	if (/(^|\/)\.git(\/|$)/.test(normalized)) return true;
+	if (/(^|\/)node_modules(\/|$)/.test(normalized)) return true;
+	if (/(^|\/)\.env(\.|$)/.test(normalized)) return true;
+	if (/(^|\/)\.houndsman\/core\/grammars(\/|$)/.test(normalized)) return true;
+	return false;
+}
+
+/** Guarda de caminhos com raiz fixa. */
+export class PathGuard {
+	readonly root: string;
+	private readonly maxFileBytes: number;
+
+	constructor(root: string, maxFileBytes = 1_000_000) {
+		this.root = resolve(root);
+		this.maxFileBytes = maxFileBytes;
+	}
+
+	/** Resolve um caminho relativo dentro da raiz; lança se escapar. */
+	resolvePath(input: string): string {
+		if (!input.trim()) throw new PathGuardError("caminho vazio");
+		const absolute = isAbsolute(input) ? resolve(input) : resolve(this.root, input);
+		const rel = relative(this.root, absolute);
+		if (rel.startsWith("..") || rel.split(sep).includes("..")) {
+			throw new PathGuardError("caminho fora do repositório");
+		}
+		if (rel === "") throw new PathGuardError("caminho inválido");
+		if (isBlockedPath(rel)) throw new PathGuardError("caminho bloqueado");
+		if (BINARY_EXTENSIONS.has(extname(absolute).toLowerCase())) {
+			throw new PathGuardError("arquivo binário");
+		}
+		return absolute;
+	}
+
+	/** Resolve e valida tamanho/tipo; devolve o caminho absoluto. */
+	assertReadable(input: string): string {
+		const absolute = this.resolvePath(input);
+		let size = 0;
+		try {
+			size = statSync(absolute).size;
+		} catch {
+			throw new PathGuardError("arquivo inexistente");
+		}
+		if (size > this.maxFileBytes) throw new PathGuardError("arquivo muito grande");
+		return absolute;
+	}
+
+	/** Caminho relativo normalizado (para respostas). */
+	relativePath(input: string): string {
+		return relative(this.root, this.resolvePath(input)).replace(/\\/g, "/");
+	}
+}

package/src/harness/tools/result-limiter.ts

@@ -0,0 +1,49 @@
+/**
+ * Limites de resultado das tools (linhas, bytes, resultados).
+ *
+ * Nenhuma tool devolve arquivo inteiro por default. Os limites são parte do
+ * contrato: o agente recebe `truncated: true` e um `hint` para refinar.
+ */
+
+/** Limites canônicos das tools. */
+export const TOOL_LIMITS = {
+	maxLines: 200,
+	maxBytes: 32 * 1024,
+	maxResults: 50,
+	maxFiles: 200,
+	maxSnippetLines: 60,
+} as const;
+
+/** Resultado de um corte de linhas. */
+export type LimitedLines = { lines: string[]; truncated: boolean };
+
+/** Mantém no máximo `max` linhas. */
+export function limitLines(
+	lines: readonly string[],
+	max: number = TOOL_LIMITS.maxLines,
+): LimitedLines {
+	if (lines.length <= max) return { lines: [...lines], truncated: false };
+	return { lines: lines.slice(0, max), truncated: true };
+}
+
+/** Corta um texto em bytes (UTF-8) sem estourar o orçamento. */
+export function limitText(
+	text: string,
+	maxBytes: number = TOOL_LIMITS.maxBytes,
+): {
+	text: string;
+	truncated: boolean;
+} {
+	const encoder = new TextEncoder();
+	if (encoder.encode(text).length <= maxBytes) return { text, truncated: false };
+	let end = Math.min(text.length, maxBytes);
+	while (end > 0 && encoder.encode(text.slice(0, end)).length > maxBytes) end--;
+	return { text: text.slice(0, Math.max(0, end)), truncated: true };
+}
+
+/** Numera as linhas a partir de `startLine` (1-based), como `cat -n`. */
+export function numberLines(startLine: number, lines: readonly string[]): string {
+	return lines
+		.map((line, index) => `${String(startLine + index).padStart(4, " ")}\t${line}`)
+		.join("\n");
+}

package/src/harness/tools/secret-redactor.ts

@@ -0,0 +1,54 @@
+/**
+ * Redação de segredos em resultados de tools/logs.
+ *
+ * Cobre chaves do ambiente do houndsman, tokens comuns (`sk-...`, `Bearer`) e
+ * pares `chave=valor` sensíveis. Nunca loga prompt nem conteúdo de `.env`.
+ */
+
+import { env } from "../../core/env";
+
+/** Padrões genéricos de segredo. */
+const PATTERNS: readonly [RegExp, string][] = [
+	[/\bsk-[A-Za-z0-9_-]{8,}\b/g, "[REDACTED]"],
+	[/\bBearer\s+[A-Za-z0-9._~+/-]{8,}=*/gi, "Bearer [REDACTED]"],
+	[
+		/\b(api[_-]?key|token|secret|password|passwd|authorization)\b\s*[:=]\s*["']?[^\s"',}]+/gi,
+		"$1: [REDACTED]",
+	],
+	[/\b[A-Fa-f0-9]{32,}\b/g, "[REDACTED]"],
+];
+
+/** Substitui os valores reais do ambiente (sem revelá-los). */
+function redactEnvValues(text: string): string {
+	let result = text;
+	for (const value of [env.deepSeekApiKey, env.typeSafeApiKey]) {
+		if (!value || value.length < 6) continue;
+		result = result.split(value).join("[REDACTED]");
+	}
+	return result;
+}
+
+/** Redige segredos de um texto. */
+export function redactSecrets(text: string): string {
+	let result = redactEnvValues(text);
+	for (const [pattern, replacement] of PATTERNS) {
+		result = result.replace(pattern, replacement);
+	}
+	return result;
+}
+
+/** Redige recursivamente strings de um valor (preserva a forma). */
+export function redactValue<T>(value: T): T {
+	if (typeof value === "string") return redactSecrets(value) as unknown as T;
+	if (Array.isArray(value)) {
+		return value.map((item) => redactValue(item)) as unknown as T;
+	}
+	if (value && typeof value === "object") {
+		const output: Record<string, unknown> = {};
+		for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+			output[key] = redactValue(item);
+		}
+		return output as unknown as T;
+	}
+	return value;
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Cache de resultados de tools por execução de agente.
+ *
+ * Chave = tool + input serializado. Respeita TTL declarado no metadata. Evita
+ * reler o mesmo trecho em estados diferentes.
+ */
+
+/** Entrada do cache. */
+type CacheEntry = { value: unknown; expiresAt: number };
+
+/** Cache em memória (escopo de uma review/agente). */
+export class ToolCache {
+	private readonly entries = new Map<string, CacheEntry>();
+
+	/** Chave estável (JSON com chaves ordenadas). */
+	static key(tool: string, input: unknown): string {
+		return `${tool}:${stableStringify(input)}`;
+	}
+
+	get<T>(key: string): T | undefined {
+		const entry = this.entries.get(key);
+		if (!entry) return undefined;
+		if (entry.expiresAt <= Date.now()) {
+			this.entries.delete(key);
+			return undefined;
+		}
+		return entry.value as T;
+	}
+
+	set(key: string, value: unknown, ttlMs = 60_000): void {
+		this.entries.set(key, { value, expiresAt: Date.now() + ttlMs });
+	}
+
+	clear(): void {
+		this.entries.clear();
+	}
+}
+
+/** Serializa um valor com chaves ordenadas. */
+function stableStringify(value: unknown): string {
+	if (value === null || typeof value !== "object")
+		return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	const obj = value as Record<string, unknown>;
+	const body = Object.keys(obj)
+		.sort()
+		.map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`)
+		.join(",");
+	return `{${body}}`;
+}

package/src/harness/tools/tool-call-budget.ts

@@ -0,0 +1,60 @@
+/**
+ * Orçamento de chamadas de tool por agente.
+ */
+
+/** Erro de orçamento de tools. */
+export class ToolBudgetError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ToolBudgetError";
+	}
+}
+
+/** Orçamento de chamadas (total e por tool). */
+export class ToolCallBudget {
+	private readonly maxCalls: number;
+	private readonly maxPerTool: number;
+	private used = 0;
+	private readonly perTool = new Map<string, number>();
+
+	constructor(maxCalls = 30, maxPerTool = 12) {
+		this.maxCalls = maxCalls;
+		this.maxPerTool = maxPerTool;
+	}
+
+	get total(): number {
+		return this.used;
+	}
+
+	get remaining(): number {
+		return Math.max(0, this.maxCalls - this.used);
+	}
+
+	/** `true` quando ainda cabe a chamada. */
+	canCall(name: string): boolean {
+		if (this.used >= this.maxCalls) return false;
+		return (this.perTool.get(name) ?? 0) < this.maxPerTool;
+	}
+
+	/** Consome uma chamada; lança quando o orçamento acabou. */
+	consume(name: string): void {
+		if (this.used >= this.maxCalls) {
+			throw new ToolBudgetError(
+				`Orçamento de ${this.maxCalls} chamada(s) de tool por agente esgotado.`,
+			);
+		}
+		const calls = this.perTool.get(name) ?? 0;
+		if (calls >= this.maxPerTool) {
+			throw new ToolBudgetError(
+				`Limite de ${this.maxPerTool} chamada(s) da tool '${name}' atingido.`,
+			);
+		}
+		this.used++;
+		this.perTool.set(name, calls + 1);
+	}
+
+	/** Contagem por tool (transcript). */
+	snapshot(): Record<string, number> {
+		return Object.fromEntries(this.perTool);
+	}
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Contexto de execução das tools (reexport do contrato).
+ */
+
+export type { ToolContext } from "./agent-tool";