@payconductor/houndsman 0.11.0 → 0.12.0

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

@@ -1,105 +0,0 @@
-/**
- * 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

@@ -1,51 +0,0 @@
-/**
- * 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

@@ -1,112 +0,0 @@
-/**
- * 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

@@ -1,15 +0,0 @@
-/**
- * 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

@@ -1,36 +0,0 @@
-/**
- * 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

@@ -1,119 +0,0 @@
-/**
- * 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;
-		}
-	};
-}

package/src/tests/fixtures/fake-agent-tools.ts

@@ -1,69 +0,0 @@
-/**
- * Tools fake para a suíte do harness.
- */
-
-import { z } from "zod";
-import type {
-	AgentTool,
-	ToolContext,
-	ToolMetadata,
-	ToolResult,
-} from "../../harness/tools/agent-tool";
-
-/** Tool de eco (testa registry/middleware). */
-export class EchoTool implements AgentTool<{ value: string }, { value: string }> {
-	readonly metadata: ToolMetadata = {
-		name: "echo",
-		description: "Devolve o valor recebido.",
-		category: "context",
-		capabilities: ["read"],
-		readOnly: true,
-		cost: 1,
-		cacheTtlMs: 60_000,
-	};
-
-	readonly inputSchema = z.object({ value: z.string() });
-
-	async execute(
-		input: { value: string },
-		_context: ToolContext,
-	): Promise<ToolResult<{ value: string }>> {
-		return { ok: true, data: { value: input.value } };
-	}
-}
-
-/** Tool que produz evidência para o estado. */
-export class EvidenceTool implements AgentTool<{ file: string }, unknown> {
-	readonly metadata: ToolMetadata = {
-		name: "evidence",
-		description: "Produz uma evidência fake.",
-		category: "evidence",
-		capabilities: ["read"],
-		readOnly: true,
-		cost: 1,
-	};
-
-	readonly inputSchema = z.object({ file: z.string() });
-
-	async execute(
-		input: { file: string },
-		_context: ToolContext,
-	): Promise<ToolResult<unknown>> {
-		return {
-			ok: true,
-			data: { file: input.file },
-			evidence: [
-				{
-					id: "",
-					file: input.file,
-					startLine: 1,
-					endLine: 1,
-					snippet: "const x: any = 1;",
-					kind: "definition",
-					sourceTool: "evidence",
-					confidence: 0.9,
-				},
-			],
-		};
-	}
-}

package/src/tests/fixtures/fake-investigation.ts

@@ -1,64 +0,0 @@
-/**
- * Fixtures de investigação/agente (sem rede, sem git).
- */
-
-import { AstService } from "../../core/ast/service";
-import { Watchdog } from "../../core/domain/watchdog";
-import type { AgentContext } from "../../harness/agent/agent-context";
-import { SilentReporter } from "../../harness/agent/agent-reporter";
-import type { ReviewAgentDeps } from "../../harness/agent/review-agent";
-import { RuleAnalyzer } from "../../harness/investigation/rule-analyzer";
-import { BuiltinToolsModule } from "../../harness/tools/builtin";
-import { ToolRegistry } from "../../harness/tools/tool-registry";
-import type { FakeModelProvider } from "./fake-model-provider";
-import { fakeHoundsmanConfig } from "./fake-project";
-
-/** Contexto de agente para o watchdog `alpha`. */
-export function fakeAgentContext(overrides: Partial<AgentContext> = {}): AgentContext {
-	const watchdog = new Watchdog(fakeHoundsmanConfig.watchdogs.alpha);
-	const rules = new RuleAnalyzer().analyze(watchdog.rules);
-	return {
-		watchdog,
-		projectName: "Fake",
-		branch: "main",
-		files: ["src/alpha/a.ts"],
-		overflow: [],
-		deleted: [],
-		docs: [],
-		context: null,
-		ast: new Map(),
-		outputPath: "findings/alpha.json",
-		maxSteps: 4,
-		maxCalls: 8,
-		repoRoot: process.cwd(),
-		diff: { byFile: new Map(), churn: new Map() },
-		rules,
-		...overrides,
-	};
-}
-
-/** Registry com tools built-in. */
-export function builtinRegistry(): ToolRegistry {
-	const registry = new ToolRegistry();
-	registry.registerModule(new BuiltinToolsModule());
-	return registry;
-}
-
-/** Deps completas de um `ReviewAgent` com provider fake. */
-export function fakeAgentDeps(
-	provider: FakeModelProvider,
-	overrides: Partial<ReviewAgentDeps> = {},
-): ReviewAgentDeps {
-	const context = overrides.context ?? fakeAgentContext();
-	return {
-		context,
-		provider,
-		registry: builtinRegistry(),
-		reporter: new SilentReporter(),
-		maxOutputTokens: 512,
-		temperature: 0,
-		timeoutMs: 5_000,
-		ast: new AstService(fakeHoundsmanConfig),
-		...overrides,
-	};
-}