@payconductor/houndsman 0.4.0 → 0.6.0

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

package/src/index.ts

@@ -5,13 +5,53 @@
  * (`houndsman.config.ts`): watchdogs, tipos e helpers de autoria.
  */
 
+export type {
+	AiResult,
+	AiTool,
+	AiUsage,
+	ModelProvider,
+	ModelRequest,
+	ModelResponse,
+} from "./core/ai";
+export {
+	AiBriefEnricher,
+	AiClassifier,
+	AiClient,
+	AiContextSummarizer,
+	AiPreAnalyzer,
+	AiUsageBudget,
+	AiUsageRecorder,
+	AiVerifier,
+	ModelFactory,
+} from "./core/ai";
 export { ArgParser } from "./core/arg-parser";
 export { assetPath, OUTPUT_FORMAT_FILE } from "./core/assets";
+export { computeDelta, emptyDelta, parseHunks } from "./core/ast/diff";
+export { buildImpact, resolveImport } from "./core/ast/impact";
+export { AstParser, languageForPath } from "./core/ast/parser";
+export { AstService } from "./core/ast/service";
+export type {
+	AstAnalysis,
+	AstDelta,
+	AstEntry,
+	AstExport,
+	AstFacts,
+	AstFileBrief,
+	AstImpact,
+	AstImport,
+	AstLanguage,
+	AstSymbol,
+	AstSymbolKind,
+} from "./core/ast/types";
 export { defaultRenderBrief, PROCEDURE, renderBrief } from "./core/brief";
 export type { FindingsCommandResult } from "./core/commands/findings";
 export { runFindingsCommand, runVerifyCommand } from "./core/commands/findings";
 export { ProjectScaffolder } from "./core/commands/scaffold";
 export type {
+	AiProviderKind,
+	HoundsmanAi,
+	HoundsmanAiFeatures,
+	HoundsmanAst,
 	HoundsmanBudgets,
 	HoundsmanConcurrency,
 	HoundsmanConfig,
@@ -20,6 +60,8 @@ export type {
 } from "./core/config";
 export {
 	DEFAULT_ALWAYS_INCLUDE_DOCS,
+	DEFAULT_AST_MAX_FILE_BYTES,
+	DEFAULT_AST_MAX_IMPACT_FILES,
 	DEFAULT_JEV_CONCURRENCY,
 	DEFAULT_MAX_FILES_PER_BRIEF,
 	defineHoundsmanConfig,
@@ -47,6 +89,8 @@ export { buildCarryover, mergeCarryover } from "./core/engine/carryover";
 export { HoundsmanEngine } from "./core/engine/houndsman-engine";
 export { ReviewScopeResolver } from "./core/engine/review-scope";
 export { ReviewSession } from "./core/engine/review-session";
+export type { HoundsmanEnv } from "./core/env";
+export { ENV_NAMES, env, readEnv } from "./core/env";
 export {
 	churnOf,
 	classifyEntries,
@@ -159,6 +203,7 @@ export type {
 	FileStatus,
 	FileStatusMap,
 	Rule,
+	RuleHints,
 	Severity,
 	WatchdogDefinition,
 	WatchdogMeta,
@@ -172,6 +217,7 @@ export {
 	SEVERITY_ORDER,
 	severityRank,
 } from "./core/types";
+export { applyConfidence, applyJev, summarizeVerify, verifyLocal } from "./core/verify";
 export {
 	findWatchdog,
 	getWatchdog,

package/src/server/client/App.tsx

@@ -1,25 +1,31 @@
 /**
  * App: layout do servidor — sidebar de execuções, header fixo (abas segmentadas,
- * auto-refresh e reancoragem), KPIs, filtros e os painéis de findings/artefatos.
- * Concentra o estado e as chamadas à API.
+ * auto-refresh e reancoragem), KPIs, filtros e os painéis de resumo/findings/
+ * artefatos. Concentra o estado e as chamadas à API.
  */
 
 import { useCallback, useEffect, useMemo, useRef, useState } from "preact/hooks";
 import { ArtifactsPanel } from "./ArtifactsPanel";
 import { AutoRefresh } from "./AutoRefresh";
-import { api, computeSummary } from "./api";
-import { AUTO_REFRESH_MS, TAB_CAPTIONS } from "./constants";
 import { Filters, type FiltersState } from "./Filters";
 import { FindingsList } from "./FindingsList";
-import { Layers, ListIcon, Refresh, Send } from "./icons";
+import { FileText, Layers, ListIcon, Refresh, Send } from "./icons";
+import { ResumePanel } from "./ResumePanel";
 import { RunList } from "./RunList";
 import { SubmitModal } from "./SubmitModal";
 import { SummaryBar } from "./SummaryBar";
-import type { Finding, FindingsResponse, RunSummary } from "./types";
+import { api, computeSummary } from "./utils/api";
+import { AUTO_REFRESH_MS, TAB_CAPTIONS } from "./utils/constants";
+import type { Finding, FindingsResponse, RunSummary } from "./utils/types";
 
-type Tab = "findings" | "artifacts";
+type Tab = "resume" | "findings" | "artifacts";
 
 const TABS: { id: Tab; label: string; hint: string }[] = [
+	{
+		id: "resume",
+		label: "Resumo",
+		hint: "Visão principal da revisão: negócio, números e pontos técnicos",
+	},
 	{
 		id: "findings",
 		label: "Findings",
@@ -36,7 +42,7 @@ export function App() {
 	const [runs, setRuns] = useState<RunSummary[]>([]);
 	const [slug, setSlug] = useState<string | null>(null);
 	const [data, setData] = useState<FindingsResponse | null>(null);
-	const [tab, setTab] = useState<Tab>("findings");
+	const [tab, setTab] = useState<Tab>("resume");
 	const [filters, setFilters] = useState<FiltersState>({
 		query: "",
 		decision: "all",
@@ -200,7 +206,9 @@ export function App() {
 								class={`seg-btn${tab === item.id ? " active" : ""}`}
 								onClick={() => setTab(item.id)}
 							>
-								{item.id === "findings" ? (
+								{item.id === "resume" ? (
+									<FileText size={15} />
+								) : item.id === "findings" ? (
 									<ListIcon size={15} />
 								) : (
 									<Layers size={15} />
@@ -254,6 +262,15 @@ export function App() {
 					</div>
 					{error && <p class="error">{error}</p>}
 
+					{slug && tab === "resume" && data && (
+						<ResumePanel
+							slug={slug}
+							branch={branch}
+							findings={data.findings}
+							summary={summary}
+							onOpenArtifacts={() => setTab("artifacts")}
+						/>
+					)}
 					{slug && tab === "findings" && data && (
 						<>
 							<SummaryBar summary={summary} />

package/src/server/client/ArtifactsPanel.tsx

@@ -1,20 +1,23 @@
 /**
  * Painel de artefatos: lista todos os artefatos persistidos da run e renderiza
- * o conteúdo bruto. JSON ganha destaque de sintaxe; briefs e relatórios são
+ * o conteúdo bruto. JSON ganha destaque de sintaxe; markdown é renderizado com
+ * o mesmo parser/highlight do restante da UI. Briefs e relatórios ficam
  * auditáveis pela mesma navegação.
  */
 
 import { useEffect, useMemo, useState } from "preact/hooks";
-import { api } from "./api";
+import { MarkdownText } from "./MarkdownText";
+import { api } from "./utils/api";
 import {
 	ARTIFACT_KIND_LABELS,
 	describeArtifact,
 	displayArtifactName,
 	groupArtifacts,
 	isJsonArtifact,
-} from "./constants";
-import { formatJson, highlightJson } from "./json-highlight";
-import type { ArtifactMeta } from "./types";
+	isMarkdownArtifact,
+} from "./utils/constants";
+import { formatJson, highlightJson } from "./utils/json-highlight";
+import type { ArtifactMeta } from "./utils/types";
 
 /** Prefere o relatório consolidado; senão, o primeiro artefato disponível. */
 function pickDefault(items: ArtifactMeta[]): string {
@@ -149,6 +152,10 @@ export function ArtifactsPanel({ slug }: { slug: string }) {
 					) : selected ? (
 						isJsonArtifact(selected) ? (
 							<JsonView content={content} />
+						) : isMarkdownArtifact(selected) ? (
+							<div class="artifact-view artifact-markdown">
+								<MarkdownText text={content} />
+							</div>
 						) : (
 							<pre class="artifact-view">{content || "—"}</pre>
 						)

package/src/server/client/AutoRefresh.tsx

@@ -6,7 +6,7 @@
  */
 
 import { useEffect, useState } from "preact/hooks";
-import { formatElapsed } from "./format";
+import { formatElapsed } from "./utils/format";
 
 export function AutoRefresh({
 	lastSync,

package/src/server/client/Filters.tsx

@@ -3,9 +3,14 @@
  * o toggle "ausentes".
  */
 
-import { DECISION_LABELS, DECISIONS, SEVERITY_LABELS, SEVERITY_ORDER } from "./constants";
 import { Search, Watch } from "./icons";
-import type { Decision, Severity } from "./types";
+import {
+	DECISION_LABELS,
+	DECISIONS,
+	SEVERITY_LABELS,
+	SEVERITY_ORDER,
+} from "./utils/constants";
+import type { Decision, Severity } from "./utils/types";
 
 export type FiltersState = {
 	query: string;