@payconductor/houndsman 0.4.0 → 0.6.0

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

@@ -0,0 +1,83 @@
+/**
+ * Composition root do harness nativo (`houndsman hunt`).
+ */
+
+import { AiUsageRecorder, ModelFactory, type ModelProvider } from "../../core/ai";
+import { AiConfigurationError } from "../../core/ai/errors";
+import type { HoundsmanEngine } from "../../core/engine/houndsman-engine";
+import { logger as defaultLogger, type LoggerLike } from "../../core/logging";
+import { type AgentReporter, LoggerReporter } from "../agent/agent-reporter";
+import { HarnessConfig } from "../config/harness-config";
+import type { HuntOptions } from "./hunt-options";
+import type { HuntResult } from "./hunt-result";
+import { HuntSession } from "./hunt-session";
+
+/** Orquestrador do hunt nativo. */
+export class HuntHarness {
+	private constructor(
+		private readonly engine: HoundsmanEngine,
+		private readonly options: HuntOptions,
+		private readonly reporter: AgentReporter,
+		private readonly logger: LoggerLike,
+		private readonly config: HarnessConfig,
+		private readonly provider?: ModelProvider,
+	) {}
+
+	/**
+	 * Monta o harness: resolve provider/model (overrides das flags) e cria o
+	 * provider quando não é dry-run. `--provider`/`--model` sobrescrevem a config.
+	 */
+	static async from(
+		engine: HoundsmanEngine,
+		options: HuntOptions,
+		logger: LoggerLike = defaultLogger,
+		providerOverride?: ModelProvider,
+	): Promise<HuntHarness> {
+		const config = new HarnessConfig(engine.project, {
+			provider: options.provider,
+			model: options.model,
+			concurrency: options.concurrency,
+			maxCalls: options.maxCalls,
+		});
+		const reporter = new LoggerReporter(logger);
+		if (options.dryRun) {
+			return new HuntHarness(engine, options, reporter, logger, config);
+		}
+		if (providerOverride) {
+			return new HuntHarness(
+				engine,
+				options,
+				reporter,
+				logger,
+				config,
+				providerOverride,
+			);
+		}
+		const factory = new ModelFactory(config.withOverrides());
+		try {
+			const provider = await factory.create();
+			return new HuntHarness(engine, options, reporter, logger, config, provider);
+		} catch (error) {
+			if (error instanceof AiConfigurationError) {
+				throw new Error(
+					`hunt exige IA configurada: ${error.message} Use --dry-run para inspecionar o plano.`,
+				);
+			}
+			throw error;
+		}
+	}
+
+	/** Executa o hunt. */
+	async run(): Promise<HuntResult> {
+		const recorder = new AiUsageRecorder(this.config.provider, this.config.model);
+		return new HuntSession({
+			engine: this.engine,
+			options: this.options,
+			config: this.config,
+			reporter: this.reporter,
+			logger: this.logger,
+			provider: this.provider,
+			recorder,
+		}).run();
+	}
+}

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

@@ -0,0 +1,75 @@
+/**
+ * Opções do `houndsman hunt` (harness nativo).
+ */
+
+import { ArgParser } from "../../core/arg-parser";
+import type { AiProviderKind } from "../../core/config";
+
+/** Opções resolvidas do hunt. */
+export type HuntOptions = {
+	base: string;
+	head: string;
+	branch?: string;
+	watchdog?: string;
+	full: boolean;
+	clean: boolean;
+	noAst: boolean;
+	/** Hunt usa IA própria; Jev fica desligado por padrão (evita custo duplo). */
+	noJev: boolean;
+	resume: boolean;
+	allowPartial: boolean;
+	dryRun: boolean;
+	failOnBlocking: boolean;
+	maxCalls?: number;
+	concurrency?: number;
+	provider?: AiProviderKind;
+	model?: string;
+};
+
+/** Defaults do hunt. */
+export function defaultHuntOptions(): HuntOptions {
+	return {
+		base: "main",
+		head: "HEAD",
+		full: false,
+		clean: false,
+		noAst: false,
+		noJev: true,
+		resume: false,
+		allowPartial: false,
+		dryRun: false,
+		failOnBlocking: false,
+	};
+}
+
+/** Converte argv nas opções do hunt. */
+export function parseHuntArgs(args: string[]): HuntOptions {
+	const parser = ArgParser.from(args);
+	const options = defaultHuntOptions();
+	const base = parser.value("--base");
+	const head = parser.value("--head");
+	const branch = parser.value("--branch");
+	const watchdog = parser.value("--watchdog");
+	const provider = parser.value("--provider");
+	const model = parser.value("--model");
+	const maxCalls = parser.value("--max-calls");
+	const concurrency = parser.value("--concurrency");
+	if (base) options.base = base;
+	if (head) options.head = head;
+	if (branch) options.branch = branch;
+	if (watchdog) options.watchdog = watchdog;
+	if (provider) options.provider = provider as AiProviderKind;
+	if (model) options.model = model;
+	if (maxCalls) options.maxCalls = Number.parseInt(maxCalls, 10);
+	if (concurrency) options.concurrency = Number.parseInt(concurrency, 10);
+
+	if (parser.has("--full")) options.full = true;
+	if (parser.has("--clean")) options.clean = true;
+	if (parser.has("--no-ast")) options.noAst = true;
+	if (parser.has("--with-jev")) options.noJev = false;
+	if (parser.has("--resume")) options.resume = true;
+	if (parser.has("--allow-partial")) options.allowPartial = true;
+	if (parser.has("--dry-run")) options.dryRun = true;
+	if (parser.has("--fail-on-blocking")) options.failOnBlocking = true;
+	return options;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Resultado do `hunt`.
+ */
+
+import type { AiUsage } from "../../core/ai";
+import type { AgentResult } from "../agent/agent-result";
+
+/** Status final da execução. */
+export type HuntResult = {
+	status: "completed" | "partial" | "dry-run" | "failed";
+	reviewId: string;
+	blockers: number;
+	attention: number;
+	watchdogs: AgentResult[];
+	usage: AiUsage;
+	messages: string[];
+};

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