@payconductor/houndsman 0.5.0 → 0.7.0

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";

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

@@ -0,0 +1,105 @@
+/**
+ * Middleware de execução das tools.
+ *
+ * Cadeia: validação Zod → cache → budget → execução → limites → redaction →
+ * auditoria. Toda tool passa por aqui; nenhuma executa direto.
+ */
+
+import type { ToolResult } from "./agent-tool";
+import { limitText, TOOL_LIMITS } from "./result-limiter";
+import { redactSecrets, redactValue } from "./secret-redactor";
+import { ToolCache } from "./tool-cache";
+import { ToolBudgetError } from "./tool-call-budget";
+import type { ToolContext } from "./tool-context";
+import type { AgentStateName } from "./tool-policy";
+import type { RegisteredTool } from "./tool-registry";
+
+/** Executor com validação, cache, budget, limite e auditoria. */
+export class ToolMiddleware {
+	async run(
+		tool: RegisteredTool,
+		input: unknown,
+		context: ToolContext,
+		state: AgentStateName,
+	): Promise<ToolResult<unknown>> {
+		const parsed = tool.inputSchema.safeParse(input);
+		if (!parsed.success) {
+			return {
+				ok: false,
+				error: `input inválido para '${tool.metadata.name}': ${parsed.error.message}`,
+			};
+		}
+
+		const maxPerAgent = tool.metadata.maxCallsPerAgent;
+		if (
+			maxPerAgent !== undefined &&
+			context.state.callsOf(tool.metadata.name) >= maxPerAgent
+		) {
+			return {
+				ok: false,
+				error: `Limite de ${maxPerAgent} chamada(s) da tool '${tool.metadata.name}'.`,
+			};
+		}
+
+		const key = ToolCache.key(tool.metadata.name, parsed.data);
+		const cached = context.cache.get<ToolResult<unknown>>(key);
+		if (cached) return cached;
+
+		try {
+			context.budget.consume(tool.metadata.name);
+		} catch (error) {
+			return {
+				ok: false,
+				error: error instanceof ToolBudgetError ? error.message : String(error),
+			};
+		}
+
+		const started = performance.now();
+		try {
+			// Contravariância: a tool concreta aceita seu próprio input.
+			const result = (await tool.execute(
+				parsed.data as never,
+				context,
+			)) as ToolResult<unknown>;
+			const limited = limitResult(result);
+			const redacted = redactValue(limited);
+			context.cache.set(key, redacted, tool.metadata.cacheTtlMs ?? 60_000);
+			context.state.recordToolCall(tool.metadata.name);
+			const stored = (redacted.evidence ?? []).map(
+				(evidence) =>
+					context.state.getEvidence(evidence.id) ??
+					context.state.addEvidence(evidence),
+			);
+			if (stored.length > 0) redacted.evidence = stored;
+			context.logger.journal.recordToolCall(
+				tool.metadata.name,
+				state,
+				performance.now() - started,
+				redacted,
+			);
+			return redacted;
+		} catch (error) {
+			const message = redactSecrets(
+				error instanceof Error ? error.message : String(error),
+			);
+			context.logger.journal.recordToolCall(
+				tool.metadata.name,
+				state,
+				performance.now() - started,
+				{ ok: false, error: message },
+			);
+			return { ok: false, error: message };
+		}
+	}
+}
+
+/** Aplica tetos de texto ao resultado da tool. */
+function limitResult(result: ToolResult<unknown>): ToolResult<unknown> {
+	const copy: ToolResult<unknown> = { ...result };
+	if (typeof copy.data === "string") {
+		const limited = limitText(copy.data, TOOL_LIMITS.maxBytes);
+		copy.data = limited.text;
+		if (limited.truncated) copy.truncated = true;
+	}
+	return copy;
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Política de tools por estado do agente.
+ *
+ * O modelo só vê as tools permitidas no estado atual. Adicionar uma tool não
+ * exige alterar o agente — basta declarar capabilities compatíveis.
+ */
+
+import type { ToolCapability, ToolMetadata } from "./agent-tool";
+
+/** Estados da máquina de investigação. */
+export type AgentStateName = "ORIENT" | "PLAN" | "INVESTIGATE" | "VERIFY" | "CONCLUDE";
+
+/** Capabilities liberadas por estado. */
+const DEFAULT_POLICY: Record<AgentStateName, readonly ToolCapability[]> = {
+	ORIENT: ["read", "outline", "ast", "impact", "rules", "symbol"],
+	PLAN: ["rules", "symbol", "impact", "ast"],
+	INVESTIGATE: [
+		"read",
+		"search",
+		"outline",
+		"symbol",
+		"references",
+		"ast",
+		"impact",
+		"rules",
+		"tests",
+		"docs",
+	],
+	VERIFY: ["symbol", "references", "search", "read"],
+	CONCLUDE: [],
+};
+
+/** Política substituível. */
+export class ToolPolicy {
+	private readonly policy: Record<AgentStateName, readonly ToolCapability[]>;
+
+	constructor(policy: Partial<Record<AgentStateName, readonly ToolCapability[]>> = {}) {
+		this.policy = { ...DEFAULT_POLICY, ...policy };
+	}
+
+	/** Capabilities liberadas no estado. */
+	capabilities(state: AgentStateName): readonly ToolCapability[] {
+		return this.policy[state];
+	}
+
+	/** `true` se a tool pode ser usada no estado. */
+	allows(state: AgentStateName, metadata: ToolMetadata): boolean {
+		const allowed = this.policy[state];
+		return metadata.capabilities.some((capability) => allowed.includes(capability));
+	}
+}

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

@@ -0,0 +1,112 @@
+/**
+ * Registro das tools do harness.
+ *
+ * Módulos registram tools; nomes duplicados falham no startup. O registry gera
+ * as descrições do prompt a partir do metadata (nunca hardcoded).
+ */
+
+import type { AiTool } from "../../core/ai";
+import type {
+	RegisterableTool,
+	ToolContext,
+	ToolMetadata,
+	ToolModule,
+	ToolRegistryLike,
+	ToolResult,
+} from "./agent-tool";
+import type { ToolMiddleware } from "./tool-middleware";
+import type { AgentStateName, ToolPolicy } from "./tool-policy";
+
+/** Tool registrada, com a forma type-erased aceita pelo middleware. */
+export type RegisteredTool = RegisterableTool;
+
+/** Registry de tools. */
+export class ToolRegistry implements ToolRegistryLike {
+	private readonly tools = new Map<string, RegisteredTool>();
+
+	/** Registra uma tool; nome duplicado é erro de configuração. */
+	registerTool(tool: RegisterableTool): void {
+		if (this.tools.has(tool.metadata.name)) {
+			throw new Error(`Tool duplicada: '${tool.metadata.name}'.`);
+		}
+		this.tools.set(tool.metadata.name, tool);
+	}
+
+	/** Registra um módulo (agrupa tools). */
+	registerModule(module: ToolModule): void {
+		module.register(this);
+	}
+
+	/** Tool por nome. */
+	get(name: string): RegisteredTool | undefined {
+		return this.tools.get(name);
+	}
+
+	/** Todas as tools (ordem de registro). */
+	list(): RegisteredTool[] {
+		return [...this.tools.values()];
+	}
+
+	/** Tools com uma capability. */
+	listByCapability(capability: string): RegisteredTool[] {
+		return this.list().filter((tool) =>
+			(tool.metadata.capabilities as readonly string[]).includes(capability),
+		);
+	}
+
+	/** Descrição compacta das tools permitidas (para o prompt). */
+	describeForPrompt(policy: ToolPolicy, state: AgentStateName): string {
+		return this.list()
+			.filter((tool) => policy.allows(state, tool.metadata))
+			.map(
+				(tool) =>
+					`- ${tool.metadata.name} (${tool.metadata.capabilities.join(", ")}): ${tool.metadata.description}`,
+			)
+			.join("\n");
+	}
+
+	/** Converte as tools permitidas no formato do modelo. */
+	toModelTools(
+		policy: ToolPolicy,
+		state: AgentStateName,
+		context: ToolContext,
+		middleware: ToolMiddleware,
+	): Record<string, AiTool> {
+		const entries = this.list()
+			.filter((tool) => policy.allows(state, tool.metadata))
+			.map((tool) => [
+				tool.metadata.name,
+				{
+					name: tool.metadata.name,
+					description: tool.metadata.description,
+					inputSchema: tool.inputSchema,
+					execute: async (input: unknown): Promise<string> => {
+						const result = await middleware.run(tool, input, context, state);
+						return JSON.stringify(result);
+					},
+				},
+			]);
+		return Object.fromEntries(entries);
+	}
+
+	/** Metadados registrados. */
+	metadata(): ToolMetadata[] {
+		return this.list().map((tool) => tool.metadata);
+	}
+
+	/** Executa uma tool com middleware (usado nos testes). */
+	execute(
+		name: string,
+		input: unknown,
+		context: ToolContext,
+		middleware: ToolMiddleware,
+		state: AgentStateName = "INVESTIGATE",
+	): Promise<ToolResult<unknown>> {
+		const tool = this.tools.get(name);
+		if (!tool)
+			return Promise.resolve({ ok: false, error: `tool desconhecida: ${name}` });
+		return middleware.run(tool, input, context, state) as Promise<
+			ToolResult<unknown>
+		>;
+	}
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Resultado padrão de uma tool (reexport de contrato).
+ */
+
+export type { ToolResult } from "./agent-tool";
+
+/** Resultado de sucesso. */
+export function ok<T>(data: T, extra: Record<string, unknown> = {}) {
+	return { ok: true as const, data, ...extra };
+}
+
+/** Resultado de erro estruturado. */
+export function fail(error: string) {
+	return { ok: false as const, error };
+}

package/src/harness/tools/toolbox.ts

@@ -0,0 +1,36 @@
+/**
+ * Visão de tools por agente (registry + policy + middleware).
+ *
+ * O agente pede `toModelTools(state)` e recebe apenas o que pode usar naquele
+ * estado, já com cache/budget/redaction aplicados.
+ */
+
+import type { AiTool } from "../../core/ai";
+import type { ToolContext } from "./tool-context";
+import type { ToolMiddleware } from "./tool-middleware";
+import type { AgentStateName, ToolPolicy } from "./tool-policy";
+import type { ToolRegistry } from "./tool-registry";
+
+/** Fachada por agente. */
+export class Toolbox {
+	constructor(
+		readonly registry: ToolRegistry,
+		readonly policy: ToolPolicy,
+		readonly middleware: ToolMiddleware,
+	) {}
+
+	/** Tools permitidas no estado, no formato do modelo. */
+	toModelTools(state: AgentStateName, context: ToolContext): Record<string, AiTool> {
+		return this.registry.toModelTools(this.policy, state, context, this.middleware);
+	}
+
+	/** Descrição das tools permitidas (prompt). */
+	describe(state: AgentStateName): string {
+		return this.registry.describeForPrompt(this.policy, state);
+	}
+
+	/** Executa uma tool fora do modelo (testes/uso determinístico). */
+	execute(name: string, input: unknown, context: ToolContext, state: AgentStateName) {
+		return this.registry.execute(name, input, context, this.middleware, state);
+	}
+}

package/src/harness/validation/finding-validator.ts

@@ -0,0 +1,119 @@
+/**
+ * Validação final do relatório de um watchdog.
+ *
+ * Descarta findings que citam regra inexistente, arquivo fora do domínio/impacto,
+ * overflow (não lido) ou linha inválida. `reviewedFiles` só aceita arquivos
+ * existentes; overflow entra em `skipped`.
+ */
+
+import { readFileSync } from "node:fs";
+import type { WatchdogReport } from "../../core/report-builder";
+import { emergentText, isEmergentRule } from "../../core/rule-text";
+import { SEVERITY_ORDER, type Severity } from "../../core/types";
+import { capSeverity } from "../investigation/finding-critic";
+
+/** Contexto de validação. */
+export type ValidationContext = {
+	watchdogId: string;
+	knownRules: ReadonlySet<string>;
+	allowedFiles: ReadonlySet<string>;
+	overflow: ReadonlySet<string>;
+	readFile: (path: string) => string | null;
+	/** Aceita findings `Lógica:`/`Domínio:` fora das regras. */
+	allowEmergentFindings?: boolean;
+};
+
+/** Resultado da validação. */
+export type ValidationResult = {
+	report: WatchdogReport;
+	dropped: { finding: string; reason: string }[];
+};
+
+const SEVERITIES = new Set<string>(SEVERITY_ORDER);
+
+/** Validador de relatórios. */
+export class FindingValidator {
+	private readonly context: ValidationContext;
+
+	constructor(context: ValidationContext) {
+		this.context = context;
+	}
+
+	/** Valida/normaliza o relatório. */
+	validate(report: WatchdogReport): ValidationResult {
+		const dropped: { finding: string; reason: string }[] = [];
+		const findings = report.findings
+			.filter((finding) => {
+				const reason = this.reasonToDrop(finding);
+				if (!reason) return true;
+				dropped.push({
+					finding: `${finding.file}:${finding.line ?? "?"}`,
+					reason,
+				});
+				return false;
+			})
+			.map((finding) =>
+				isEmergentRule(finding.rule)
+					? {
+							...finding,
+							severity: capSeverity(finding.severity, "attention"),
+						}
+					: finding,
+			);
+
+		const reviewedFiles = report.reviewedFiles
+			.filter((file) => this.context.allowedFiles.has(file))
+			.filter((file) => this.context.readFile(file) !== null);
+
+		const skipped = new Set(report.skipped);
+		for (const file of this.context.overflow) skipped.add(`${file} (budget)`);
+
+		return {
+			report: {
+				watchdogId: this.context.watchdogId,
+				reviewedFiles: [...new Set(reviewedFiles)],
+				skipped: [...skipped],
+				findings,
+			},
+			dropped,
+		};
+	}
+
+	/** Motivo para descartar (ou `null` se válido). */
+	private reasonToDrop(finding: {
+		rule: string;
+		severity: Severity;
+		file: string;
+		line?: number;
+	}): string | null {
+		if (isEmergentRule(finding.rule)) {
+			if (!this.context.allowEmergentFindings)
+				return "finding emergente desabilitado";
+			if (!emergentText(finding.rule)) return "finding emergente sem descrição";
+		} else if (!this.context.knownRules.has(finding.rule.trim())) {
+			return "regra inexistente";
+		}
+		if (!SEVERITIES.has(finding.severity)) return "severidade inválida";
+		if (this.context.overflow.has(finding.file)) return "arquivo fora do orçamento";
+		if (!this.context.allowedFiles.has(finding.file))
+			return "arquivo fora do domínio";
+		const content = this.context.readFile(finding.file);
+		if (content === null) return "arquivo ausente";
+		if (finding.line !== undefined) {
+			const total = content.split("\n").length;
+			if (finding.line < 1 || finding.line > total) return "linha fora do arquivo";
+		}
+		return null;
+	}
+}
+
+/** Leitor de arquivos padrão (UTF-8; `null` se ausente). */
+export function defaultFileReader(root: string): (path: string) => string | null {
+	return (path: string) => {
+		try {
+			return readFileSync(`${root}/${path}`, "utf8");
+		} catch {
+			return null;
+		}
+	};
+}