@payconductor/houndsman 0.5.0 → 0.6.0

package/src/harness/hunt/hunt-session.ts

@@ -0,0 +1,372 @@
+/**
+ * Sessão do hunt nativo: prepare → agentes → finalize.
+ *
+ * Reutiliza o pipeline determinístico (briefs, classificação, storage) e apenas
+ * substitui o "despacho de subagentes" pelo harness.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import {
+	type AiUsage,
+	type AiUsageRecorder,
+	addUsage,
+	emptyUsage,
+	type ModelProvider,
+} from "../../core/ai";
+import type { AstAnalysis } from "../../core/ast/types";
+import { collectDiff } from "../../core/diff-source";
+import type { HoundsmanEngine } from "../../core/engine/houndsman-engine";
+import type { RunClassification } from "../../core/engine/review-scope";
+import { parseEntries } from "../../core/file-classifier";
+import { runGit, tryGit } from "../../core/git-runner";
+import type { LoggerLike } from "../../core/logging";
+import type { PrepareResult } from "../../core/orchestrator";
+import { defaultOptions, type ReviewOptions } from "../../core/orchestrator";
+import type { ContextSummary } from "../../core/report-builder";
+import type { AgentContext } from "../agent/agent-context";
+import { AgentFactory } from "../agent/agent-factory";
+import type { AgentReporter } from "../agent/agent-reporter";
+import type { AgentResult } from "../agent/agent-result";
+import { AgentRunner } from "../agent/agent-runner";
+import { AgentScheduler } from "../agent/agent-scheduler";
+import type { HarnessConfig } from "../config/harness-config";
+import { BuiltinToolsModule } from "../tools/builtin";
+import { ToolRegistry } from "../tools/tool-registry";
+import { defaultFileReader } from "../validation/finding-validator";
+import type { HuntOptions } from "./hunt-options";
+import type { HuntResult } from "./hunt-result";
+import { ReviewPlanner } from "./review-planner";
+
+/** Dependências da sessão. */
+export type HuntSessionDeps = {
+	engine: HoundsmanEngine;
+	options: HuntOptions;
+	config: HarnessConfig;
+	reporter: AgentReporter;
+	logger: LoggerLike;
+	provider?: ModelProvider;
+	recorder: AiUsageRecorder;
+};
+
+/** Executa o hunt. */
+export class HuntSession {
+	constructor(private readonly deps: HuntSessionDeps) {}
+
+	/** Roda prepare (seco ou não), agentes e finalize. */
+	async run(): Promise<HuntResult> {
+		const { engine, options, reporter } = this.deps;
+		const messages: string[] = [];
+		const reviewOptions: ReviewOptions = {
+			...defaultOptions(),
+			base: options.base,
+			head: options.head,
+			branch: options.branch,
+			noJev: options.noJev,
+			noAst: options.noAst,
+			full: options.full,
+			clean: options.clean,
+			noAi: true,
+			finalize: false,
+		};
+
+		const session = engine.session(reviewOptions);
+		const prepared: PrepareResult = await this.deps.logger.withSpinner(
+			"Preparando revisão...",
+			() => session.prepare(),
+		);
+		messages.push(...prepared.messages);
+		const review = session.context.review;
+		const work = session.context.work;
+
+		// Sem alterações desde a última revisão: não gasta IA nem reescreve nada.
+		const artifact = engine.storage.readArtifact(review.id, "classification.json");
+		if (
+			!artifact ||
+			prepared.messages.some((item) => item.startsWith("Nenhuma alteração"))
+		) {
+			return {
+				status: "completed",
+				reviewId: review.id,
+				blockers: 0,
+				attention: 0,
+				watchdogs: [],
+				usage: emptyUsage(),
+				messages,
+			};
+		}
+
+		const classification = this.readClassification(engine, review.id);
+		const planned = await this.plan(classification, session.context.review, work);
+		for (const item of planned) {
+			item.context.outputPath = work.findingFile(item.context.watchdog.id);
+		}
+
+		if (options.dryRun) {
+			messages.push(
+				`Dry-run: ${planned.length} watchdog(s) sem chamadas de IA.`,
+				...planned.map(
+					(item) =>
+						`- ${item.context.watchdog.id}: ${item.files.length} arquivo(s)` +
+						(item.overflow.length > 0
+							? `, ${item.overflow.length} fora do orçamento`
+							: ""),
+				),
+			);
+			return {
+				status: "dry-run",
+				reviewId: review.id,
+				blockers: 0,
+				attention: 0,
+				watchdogs: [],
+				usage: emptyUsage(),
+				messages,
+			};
+		}
+
+		if (!this.deps.provider) {
+			throw new Error(
+				"hunt exige IA configurada (HOUNDSMAN_DEEP_SEEK_API_KEY) ou provider injetado.",
+			);
+		}
+
+		const registry = new ToolRegistry();
+		registry.registerModule(new BuiltinToolsModule());
+		const factory = new AgentFactory({
+			provider: this.deps.provider,
+			registry,
+			reporter,
+			config: this.deps.config,
+			ast: engine.ast,
+			readFile: defaultFileReader(fileRoot()),
+		});
+		const runner = new AgentRunner(factory);
+		const scheduler = new AgentScheduler(
+			runner,
+			this.deps.config.concurrency,
+			reporter,
+		);
+
+		// `--resume`: watchdogs com findings válidos no staging são preservados.
+		const pending = options.resume
+			? planned.filter(
+					(item) =>
+						!hasValidFindings(work.findingFile(item.context.watchdog.id)),
+				)
+			: planned;
+		if (pending.length < planned.length) {
+			messages.push(
+				`Resume: ${planned.length - pending.length} watchdog(s) preservado(s) do staging.`,
+			);
+		}
+
+		const contexts: AgentContext[] = pending.map((item) => item.context);
+		const outcomes = await scheduler.run(contexts);
+		const results: AgentResult[] = [];
+		let partial = false;
+		let failed = false;
+
+		for (const [index, outcome] of outcomes.entries()) {
+			const context = contexts[index];
+			if (!context) continue;
+			results.push(outcome);
+			this.deps.recorder.record(
+				"harness",
+				this.deps.provider.modelId,
+				outcome.usage,
+			);
+			if (outcome.status === "done" && outcome.report) {
+				work.writeFinding(
+					context.watchdog.id,
+					`${JSON.stringify(outcome.report, null, 2)}\n`,
+				);
+				messages.push(
+					`[${context.watchdog.id}] ${outcome.report.findings.length} achado(s) em ${context.files.length} arquivo(s).`,
+				);
+				continue;
+			}
+			const reason = outcome.error ?? outcome.reason ?? "falha desconhecida";
+			if (options.allowPartial) {
+				partial = true;
+				const synthetic = {
+					watchdogId: context.watchdog.id,
+					reviewedFiles: [],
+					skipped: [`falha: ${reason}`],
+					findings: [],
+				};
+				work.writeFinding(
+					context.watchdog.id,
+					`${JSON.stringify(synthetic, null, 2)}\n`,
+				);
+				messages.push(`[${context.watchdog.id}] parcial: ${reason}`);
+			} else {
+				failed = true;
+				messages.push(`[${context.watchdog.id}] falhou: ${reason}`);
+			}
+		}
+
+		for (const item of planned) {
+			if (pending.some((entry) => entry.context === item.context)) continue;
+			results.push({
+				watchdogId: item.context.watchdog.id,
+				status: "skipped",
+				reason: "resume",
+				usage: emptyUsage(),
+			});
+		}
+
+		this.writeTranscript(engine, review.id, classification, results);
+		this.deps.recorder.write(engine.storage, review.id);
+
+		const usage = totalUsage(results);
+		if (failed) {
+			return {
+				status: "failed",
+				reviewId: review.id,
+				blockers: 0,
+				attention: 0,
+				watchdogs: results,
+				usage,
+				messages,
+			};
+		}
+
+		const finalized = await this.deps.logger.withSpinner(
+			"Consolidando relatório...",
+			async () => engine.session({ ...reviewOptions, finalize: true }).finalize(),
+		);
+		messages.push(...finalized.messages);
+		return {
+			status: partial ? "partial" : "completed",
+			reviewId: review.id,
+			blockers: finalized.blockers,
+			attention: finalized.attention,
+			watchdogs: results,
+			usage,
+			messages,
+		};
+	}
+
+	/** Lê a classificação persistida pelo prepare. */
+	private readClassification(
+		engine: HoundsmanEngine,
+		reviewId: string,
+	): RunClassification {
+		const artifact = engine.storage.readArtifact(reviewId, "classification.json");
+		if (!artifact) {
+			throw new Error("hunt: classification.json ausente após o prepare.");
+		}
+		return JSON.parse(artifact.content) as RunClassification;
+	}
+
+	/** Monta os contextos + AST + impacto. */
+	private async plan(
+		classification: RunClassification,
+		review: import("../../core/storage/types").ReviewRecord,
+		work: import("../../core/storage/work-area").ReviewWorkArea,
+	) {
+		const { engine, options } = this.deps;
+		const diff = collectDiff(options.base, options.head);
+		const entries = parseEntries(
+			runGit(["diff", `${options.base}...${options.head}`, "--name-status"]),
+		);
+		const baseRef = mergeBase(options.base, options.head) ?? options.base;
+		const ast: Map<string, AstAnalysis> = options.noAst
+			? new Map()
+			: await engine.ast.analyze(entries, diff, baseRef);
+		const impact = ast.size > 0 ? await engine.ast.impact(ast) : undefined;
+		const context =
+			work.readContextSummary() ?? readContextSummary(engine, review.id);
+		const planner = new ReviewPlanner({
+			config: engine.config,
+			project: engine.project,
+			classification,
+			context,
+			ast,
+			impact,
+			repoRoot: process.cwd(),
+			diff,
+			branch: review.branch,
+			watchdog: options.watchdog,
+			maxCalls: this.deps.config.maxCalls,
+		});
+		return planner.plan();
+	}
+
+	/** Grava o transcript completo da investigação. */
+	private writeTranscript(
+		engine: HoundsmanEngine,
+		reviewId: string,
+		classification: RunClassification,
+		results: AgentResult[],
+	): void {
+		const content = `${JSON.stringify(
+			{
+				provider: this.deps.config.provider,
+				model: this.deps.config.model,
+				classification: {
+					mode: classification.mode,
+					files: Object.keys(classification.files).length,
+					watchdogs: Object.keys(classification.watchdogs),
+				},
+				watchdogs: results.map((result) => ({
+					watchdogId: result.watchdogId,
+					status: result.status,
+					usage: result.usage,
+					...(result.error ? { error: result.error } : {}),
+					...(result.reason ? { reason: result.reason } : {}),
+				})),
+				journal: this.deps.reporter.journal.toJSON(),
+			},
+			null,
+			2,
+		)}\n`;
+		engine.storage.writeArtifact(reviewId, {
+			name: "harness-transcript.json",
+			kind: "harness-transcript",
+			content,
+		});
+	}
+}
+
+/** Findings válidos já gravados (resume). */
+function hasValidFindings(path: string): boolean {
+	if (!existsSync(path)) return false;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as { findings?: unknown };
+		return Array.isArray(parsed.findings);
+	} catch {
+		return false;
+	}
+}
+
+/** Soma o uso de todos os agentes. */
+function totalUsage(results: readonly AgentResult[]): AiUsage {
+	return results.reduce((acc, result) => addUsage(acc, result.usage), emptyUsage());
+}
+
+/** Resumo do contexto persistido (quando o staging já foi limpo). */
+function readContextSummary(
+	engine: HoundsmanEngine,
+	reviewId: string,
+): ContextSummary | null {
+	const artifact = engine.storage.readArtifact(reviewId, "context-summary.json");
+	if (!artifact) return null;
+	try {
+		return JSON.parse(artifact.content) as ContextSummary;
+	} catch {
+		return null;
+	}
+}
+
+/** Merge-base best effort. */
+function mergeBase(base: string, head: string): string | null {
+	const result = tryGit(["merge-base", base, head]);
+	if (!result.ok) return null;
+	const sha = result.stdout.trim();
+	return sha.length > 0 ? sha : null;
+}
+
+/** Raiz do repositório para leitura das tools. */
+function fileRoot(): string {
+	return process.cwd();
+}

package/src/harness/hunt/review-planner.ts

@@ -0,0 +1,98 @@
+/**
+ * Planejador da review nativa — monta um `AgentContext` por watchdog ativo.
+ *
+ * Lê a classificação já preparada (prepare) e aplica o orçamento por brief.
+ * Nada aqui chama IA.
+ */
+
+import type { AstAnalysis, AstImpact } from "../../core/ast/types";
+import type { HoundsmanConfig } from "../../core/config";
+import type { DiffSource } from "../../core/diff-source";
+import { discoverDocs } from "../../core/doc-discoverer";
+import { selectByBudget } from "../../core/domain/budget";
+import type { RunClassification } from "../../core/engine/review-scope";
+import type { ProjectConfig } from "../../core/project-config";
+import type { ContextSummary } from "../../core/report-builder";
+import type { ChurnMap } from "../../core/types";
+import type { AgentContext } from "../agent/agent-context";
+import { RuleAnalyzer } from "../investigation/rule-analyzer";
+
+/** Entrada do planejador. */
+export type ReviewPlannerInput = {
+	config: HoundsmanConfig;
+	project: ProjectConfig;
+	classification: RunClassification;
+	context: ContextSummary | null;
+	ast: ReadonlyMap<string, AstAnalysis>;
+	impact?: AstImpact;
+	repoRoot: string;
+	diff: DiffSource;
+	/** Branch alvo da review (prompt do agente). */
+	branch: string;
+	/** Filtra um único watchdog (`--watchdog`). */
+	watchdog?: string;
+	maxCalls: number;
+};
+
+/** Um watchdog planejado. */
+export type PlannedWatchdog = {
+	context: AgentContext;
+	files: string[];
+	overflow: string[];
+};
+
+/** Planeja os agentes da review. */
+export class ReviewPlanner {
+	private readonly input: ReviewPlannerInput;
+
+	constructor(input: ReviewPlannerInput) {
+		this.input = input;
+	}
+
+	/** Watchdogs ativos (filtrados) com contexto pronto. */
+	plan(): PlannedWatchdog[] {
+		const { config, project, classification, watchdog } = this.input;
+		const ids = Object.keys(classification.watchdogs).filter(
+			(id) => !watchdog || id === watchdog,
+		);
+		const docs = discoverDocs(Object.keys(classification.files), config);
+		const maxFiles = project.maxFilesPerBrief;
+		const analyzer = new RuleAnalyzer();
+		const planned: PlannedWatchdog[] = [];
+
+		for (const id of ids) {
+			const domain = project.watchdogs.find(id);
+			if (!domain) continue;
+			const churn: ChurnMap = classification.churn;
+			const { selected, overflow } = selectByBudget(
+				classification.watchdogs[id] ?? [],
+				churn,
+				maxFiles,
+			);
+			const rules = analyzer.analyze(domain.rules);
+			planned.push({
+				files: selected,
+				overflow,
+				context: {
+					watchdog: domain,
+					projectName: project.projectName,
+					branch: this.input.branch,
+					files: selected,
+					overflow,
+					deleted: classification.deleted,
+					docs,
+					context: this.input.context,
+					ast: this.input.ast,
+					impact: this.input.impact,
+					outputPath: "",
+					maxSteps: project.aiMaxStepsFor(id),
+					maxCalls: this.input.maxCalls,
+					repoRoot: this.input.repoRoot,
+					diff: this.input.diff,
+					rules,
+				},
+			});
+		}
+		return planned;
+	}
+}

package/src/harness/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Barrel do harness nativo.
+ *
+ * Atenção: `src/skill/` é o harness **externo** (markdown). Este é o runtime de
+ * agentes do próprio houndsman.
+ */
+
+export type { AgentContext } from "./agent/agent-context";
+export { AgentFactory } from "./agent/agent-factory";
+export type { AgentReporter } from "./agent/agent-reporter";
+export { LoggerReporter, SilentReporter } from "./agent/agent-reporter";
+export type { AgentResult } from "./agent/agent-result";
+export { AgentRunner } from "./agent/agent-runner";
+export { AgentScheduler } from "./agent/agent-scheduler";
+export { ReviewAgent } from "./agent/review-agent";
+export { HarnessConfig, type HarnessOverrides } from "./config/harness-config";
+export { HuntHarness } from "./hunt/hunt-harness";
+export { defaultHuntOptions, type HuntOptions, parseHuntArgs } from "./hunt/hunt-options";
+export type { HuntResult } from "./hunt/hunt-result";
+export { AgentState } from "./investigation/agent-state";
+export type {
+	CriticDecision,
+	Evidence,
+	FindingDraft,
+	RuleCoverage,
+} from "./investigation/evidence";
+export { EvidenceVerifier } from "./investigation/evidence-verifier";
+export { FindingCritic } from "./investigation/finding-critic";
+export { InvestigationPlanner } from "./investigation/investigation-planner";
+export { ReviewJournal } from "./investigation/review-journal";
+export { type RuleAnalysis, RuleAnalyzer } from "./investigation/rule-analyzer";
+export type { AgentTool, ToolContext, ToolResult } from "./tools/agent-tool";
+export { type AgentStateName, ToolPolicy } from "./tools/tool-policy";
+export { ToolRegistry } from "./tools/tool-registry";
+export { Toolbox } from "./tools/toolbox";
+export { FindingValidator } from "./validation/finding-validator";

package/src/harness/investigation/agent-state.ts

@@ -0,0 +1,134 @@
+/**
+ * Estado de um agente de investigação.
+ *
+ * Acumula tarefas, hipóteses, evidências, cobertura de regras, drafts e custo.
+ * É a única fonte de verdade que o verificador/crítico consultam.
+ */
+
+import {
+	type Evidence,
+	type EvidenceKind,
+	evidenceId,
+	type FindingDraft,
+	type RuleCoverage,
+	type RuleCoverageStatus,
+} from "./evidence";
+import type { InvestigationTask } from "./investigation-task";
+
+/** Entrada para registrar uma evidência. */
+export type EvidenceInput = Omit<Evidence, "id"> & { id?: string };
+
+/** Estado mutável de um agente. */
+export class AgentState {
+	readonly tasks: InvestigationTask[] = [];
+	readonly hypotheses: string[] = [];
+	readonly evidence = new Map<string, Evidence>();
+	readonly coverage = new Map<string, RuleCoverage>();
+	readonly drafts: FindingDraft[] = [];
+	readonly toolCalls = new Map<string, number>();
+	private sequence = 0;
+
+	/** Registra as tarefas do plano. */
+	setTasks(tasks: InvestigationTask[]): void {
+		this.tasks.push(...tasks);
+	}
+
+	/** Tarefas por status. */
+	tasksByStatus(status: InvestigationTask["status"]): InvestigationTask[] {
+		return this.tasks.filter((task) => task.status === status);
+	}
+
+	/** Marca uma tarefa como concluída. */
+	completeTask(id: string, reason?: string): void {
+		const task = this.tasks.find((item) => item.id === id);
+		if (!task) return;
+		task.status = "done";
+		if (reason) task.reason = reason;
+	}
+
+	/** Marca uma tarefa como pulada (com motivo). */
+	skipTask(id: string, reason: string): void {
+		const task = this.tasks.find((item) => item.id === id);
+		if (!task) return;
+		task.status = "skipped";
+		task.reason = reason;
+	}
+
+	/** Adiciona uma hipótese (sem duplicar). */
+	addHypothesis(hypothesis: string): void {
+		const value = hypothesis.trim();
+		if (value && !this.hypotheses.includes(value)) this.hypotheses.push(value);
+	}
+
+	/** Registra evidência e devolve o id gerado. */
+	addEvidence(input: EvidenceInput): Evidence {
+		const id = input.id?.trim() ? input.id.trim() : evidenceId(++this.sequence);
+		const evidence: Evidence = { ...input, id };
+		this.evidence.set(id, evidence);
+		return evidence;
+	}
+
+	/** Evidência por id (undefined se não existe). */
+	getEvidence(id: string): Evidence | undefined {
+		return this.evidence.get(id);
+	}
+
+	/** Evidências de uma tool/esécie. */
+	evidenceOfKind(kind: EvidenceKind): Evidence[] {
+		return [...this.evidence.values()].filter((item) => item.kind === kind);
+	}
+
+	/** Adiciona um draft de finding. */
+	addDraft(draft: FindingDraft): void {
+		this.drafts.push(draft);
+	}
+
+	/** Define a cobertura de uma regra (idempotente por texto). */
+	setCoverage(rule: string, status: RuleCoverageStatus, reason?: string): void {
+		const existing = this.coverage.get(rule);
+		if (existing) {
+			existing.status = status;
+			if (reason) existing.reason = reason;
+			return;
+		}
+		this.coverage.set(rule, {
+			rule,
+			status,
+			files: [],
+			symbols: [],
+			...(reason ? { reason } : {}),
+		});
+	}
+
+	/** Cobertura atual de uma regra. */
+	coverageOf(rule: string): RuleCoverage | undefined {
+		return this.coverage.get(rule);
+	}
+
+	/** `true` quando a regra já foi coberta de alguma forma. */
+	isCovered(rule: string): boolean {
+		return this.coverage.has(rule);
+	}
+
+	/** Registra o uso de uma tool (contagem por nome). */
+	recordToolCall(name: string): void {
+		this.toolCalls.set(name, (this.toolCalls.get(name) ?? 0) + 1);
+	}
+
+	/** Chamadas registradas de uma tool. */
+	callsOf(name: string): number {
+		return this.toolCalls.get(name) ?? 0;
+	}
+
+	/** Snapshot serializável (sem prompts). */
+	toJSON(): Record<string, unknown> {
+		return {
+			hypotheses: this.hypotheses,
+			tasks: this.tasks,
+			evidence: [...this.evidence.values()],
+			coverage: [...this.coverage.values()],
+			drafts: this.drafts,
+			toolCalls: Object.fromEntries(this.toolCalls),
+		};
+	}
+}