@payconductor/houndsman 0.12.0 → 0.13.0

package/src/core/hunt/hunt-runner.ts

@@ -0,0 +1,328 @@
+/**
+ * Orquestração do harness local (`houndsman hunt`).
+ *
+ * Recebe os briefs já preparados e despacha um processo maki por watchdog. O
+ * watchdog devolve o JSON na resposta final; validamos com o mesmo parser do
+ * `--finalize` e gravamos em `findings/<id>.json`. Falhas são reportadas por
+ * watchdog — a política de finalizar ou não fica com o chamador (CLI).
+ */
+
+import { readFileSync } from "node:fs";
+import { parseWatchdogReport } from "../report-builder";
+import { systemClock } from "../services/clock";
+import type { ReviewWorkArea } from "../storage/work-area";
+import { renderHuntPrompt, renderRetrySuffix } from "./maki-prompt";
+import {
+	extractJsonObject,
+	type MakiProcessRunner,
+	type MakiRunMetrics,
+	type MakiUsage,
+} from "./maki-runner";
+import { mapPool } from "./pool";
+
+/** Evento de progresso (CLI loga; core não escreve saída). */
+export type HuntEvent =
+	| { type: "start"; watchdogId: string }
+	| {
+			type: "retry";
+			watchdogId: string;
+			attempt: number;
+			maxAttempts: number;
+			error: string;
+	  }
+	| {
+			type: "done";
+			watchdogId: string;
+			findings: number;
+			reviewedFiles: number;
+			attempts: number;
+			metrics: MakiRunMetrics;
+	  }
+	| {
+			type: "failed";
+			watchdogId: string;
+			error: string;
+			attempts: number;
+			metrics: MakiRunMetrics;
+	  };
+
+/** Resultado de um watchdog. */
+export type HuntWatchdogResult = {
+	watchdogId: string;
+	status: "done" | "failed";
+	findings: number;
+	reviewedFiles: number;
+	attempts: number;
+	durationMs: number;
+	sessionId?: string;
+	numTurns?: number;
+	costUsd?: number;
+	usage?: MakiUsage;
+	error?: string;
+};
+
+/** Agregados do relatório. */
+export type HuntTotals = {
+	watchdogs: number;
+	done: number;
+	failed: number;
+	findings: number;
+	costUsd: number;
+	inputTokens: number;
+	outputTokens: number;
+	totalTokens: number;
+};
+
+/** Relatório persistido como `hunt-report.json`. */
+export type HuntReport = {
+	version: 1;
+	engine: "maki";
+	model: string;
+	startedAt: string;
+	finishedAt: string;
+	durationMs: number;
+	watchdogs: HuntWatchdogResult[];
+	totals: HuntTotals;
+};
+
+/** Dependências do runner. */
+export type HuntRunnerOptions = {
+	/** Staging da review (briefs/findings). */
+	work: ReviewWorkArea;
+	/** Raiz de leitura dos arquivos da review. */
+	root: string;
+	projectName: string;
+	/** Spec `provider/model-id`. */
+	model: string;
+	apiKeyEnv: string;
+	apiKey: string;
+	concurrency: number;
+	timeoutMs: number;
+	retries: number;
+	runner: MakiProcessRunner;
+	onEvent?: (event: HuntEvent) => void;
+};
+
+/** Despacha os briefs via maki e devolve o relatório consolidado. */
+export class HuntRunner {
+	private readonly options: HuntRunnerOptions;
+
+	constructor(options: HuntRunnerOptions) {
+		this.options = options;
+	}
+
+	async run(activeIds: readonly string[]): Promise<HuntReport> {
+		const startedAt = systemClock();
+		const startedMs = Date.now();
+		const watchdogs = await mapPool(activeIds, this.options.concurrency, (id) =>
+			this.runOne(id),
+		);
+		const finishedAt = systemClock();
+		return {
+			version: 1,
+			engine: "maki",
+			model: this.options.model,
+			startedAt,
+			finishedAt,
+			durationMs: Date.now() - startedMs,
+			watchdogs,
+			totals: totalsOf(watchdogs),
+		};
+	}
+
+	private async runOne(watchdogId: string): Promise<HuntWatchdogResult> {
+		const briefPath = this.options.work.briefFile(watchdogId);
+		let brief: string;
+		try {
+			brief = readFileSync(briefPath, "utf8");
+		} catch {
+			const error = `Brief ausente: ${briefPath}`;
+			this.emit({
+				type: "failed",
+				watchdogId,
+				error,
+				attempts: 0,
+				metrics: { durationMs: 0 },
+			});
+			return failedResult(watchdogId, error, 0, { durationMs: 0 });
+		}
+
+		const basePrompt = renderHuntPrompt({
+			projectName: this.options.projectName,
+			watchdogId,
+			brief,
+		});
+
+		this.emit({ type: "start", watchdogId });
+		let attempts = 0;
+		let lastError = "";
+		const accumulated: MakiRunMetrics = { durationMs: 0 };
+
+		while (attempts <= this.options.retries) {
+			attempts++;
+			const prompt =
+				attempts === 1
+					? basePrompt
+					: `${basePrompt}\n${renderRetrySuffix(lastError)}`;
+			const result = await this.options.runner.run({
+				prompt,
+				cwd: this.options.root,
+				model: this.options.model,
+				apiKeyEnv: this.options.apiKeyEnv,
+				apiKey: this.options.apiKey,
+				timeoutMs: this.options.timeoutMs,
+			});
+			mergeMetrics(accumulated, result.metrics);
+
+			if (!result.ok) {
+				lastError = result.error;
+				this.emitRetry(watchdogId, attempts, lastError);
+				continue;
+			}
+
+			const raw = extractJsonObject(result.text);
+			if (raw === null) {
+				lastError = "a resposta final não contém um objeto JSON.";
+				this.emitRetry(watchdogId, attempts, lastError);
+				continue;
+			}
+
+			const warnings: string[] = [];
+			const report = parseWatchdogReport(raw, `maki:${watchdogId}`, (message) =>
+				warnings.push(message),
+			);
+			if (!report) {
+				lastError = warnings[0] ?? "JSON fora do schema do watchdog.";
+				this.emitRetry(watchdogId, attempts, lastError);
+				continue;
+			}
+			if (report.watchdogId !== watchdogId) {
+				lastError = `watchdogId '${report.watchdogId}' não corresponde a '${watchdogId}'.`;
+				this.emitRetry(watchdogId, attempts, lastError);
+				continue;
+			}
+
+			this.options.work.writeFinding(
+				watchdogId,
+				`${JSON.stringify(report, null, 2)}\n`,
+			);
+			const done: HuntWatchdogResult = {
+				watchdogId,
+				status: "done",
+				findings: report.findings.length,
+				reviewedFiles: report.reviewedFiles.length,
+				attempts,
+				durationMs: accumulated.durationMs,
+				sessionId: accumulated.sessionId,
+				numTurns: accumulated.numTurns,
+				costUsd: accumulated.costUsd,
+				usage: accumulated.usage,
+			};
+			this.emit({
+				type: "done",
+				watchdogId,
+				findings: done.findings,
+				reviewedFiles: done.reviewedFiles,
+				attempts,
+				metrics: accumulated,
+			});
+			return done;
+		}
+
+		const error = lastError || "falha desconhecida.";
+		this.emit({ type: "failed", watchdogId, error, attempts, metrics: accumulated });
+		return failedResult(watchdogId, error, attempts, accumulated);
+	}
+
+	private emit(event: HuntEvent): void {
+		try {
+			this.options.onEvent?.(event);
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Avisa a próxima tentativa (só quando ainda há retry). */
+	private emitRetry(watchdogId: string, attempt: number, error: string): void {
+		if (attempt > this.options.retries) return;
+		this.emit({
+			type: "retry",
+			watchdogId,
+			attempt,
+			maxAttempts: this.options.retries + 1,
+			error,
+		});
+	}
+}
+
+/** Soma métricas de várias tentativas no acumulado. */
+function mergeMetrics(target: MakiRunMetrics, source: MakiRunMetrics): void {
+	target.durationMs += source.durationMs;
+	target.sessionId = source.sessionId ?? target.sessionId;
+	if (source.numTurns !== undefined) {
+		target.numTurns = (target.numTurns ?? 0) + source.numTurns;
+	}
+	if (source.costUsd !== undefined) {
+		target.costUsd = (target.costUsd ?? 0) + source.costUsd;
+	}
+	if (source.usage) {
+		target.usage = {
+			inputTokens:
+				(target.usage?.inputTokens ?? 0) + (source.usage.inputTokens ?? 0),
+			outputTokens:
+				(target.usage?.outputTokens ?? 0) + (source.usage.outputTokens ?? 0),
+			totalTokens:
+				(target.usage?.totalTokens ?? 0) + (source.usage.totalTokens ?? 0),
+			cacheReadInputTokens:
+				(target.usage?.cacheReadInputTokens ?? 0) +
+				(source.usage.cacheReadInputTokens ?? 0),
+		};
+	}
+}
+
+/** Resultado de falha de um watchdog. */
+function failedResult(
+	watchdogId: string,
+	error: string,
+	attempts: number,
+	metrics: MakiRunMetrics,
+): HuntWatchdogResult {
+	return {
+		watchdogId,
+		status: "failed",
+		findings: 0,
+		reviewedFiles: 0,
+		attempts,
+		durationMs: metrics.durationMs,
+		sessionId: metrics.sessionId,
+		numTurns: metrics.numTurns,
+		costUsd: metrics.costUsd,
+		usage: metrics.usage,
+		error,
+	};
+}
+
+/** Agrega os resultados por watchdog. */
+function totalsOf(watchdogs: readonly HuntWatchdogResult[]): HuntTotals {
+	const totals: HuntTotals = {
+		watchdogs: watchdogs.length,
+		done: 0,
+		failed: 0,
+		findings: 0,
+		costUsd: 0,
+		inputTokens: 0,
+		outputTokens: 0,
+		totalTokens: 0,
+	};
+	for (const watchdog of watchdogs) {
+		if (watchdog.status === "done") totals.done++;
+		else totals.failed++;
+		totals.findings += watchdog.findings;
+		totals.costUsd += watchdog.costUsd ?? 0;
+		totals.inputTokens += watchdog.usage?.inputTokens ?? 0;
+		totals.outputTokens += watchdog.usage?.outputTokens ?? 0;
+		totals.totalTokens += watchdog.usage?.totalTokens ?? 0;
+	}
+	totals.costUsd = Number(totals.costUsd.toFixed(6));
+	return totals;
+}

package/src/core/hunt/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Fachada do harness local (`core/hunt`).
+ *
+ * A skill `/houndsman hunt` não importa nada daqui: este módulo é exclusivo do
+ * caminho CLI (`houndsman hunt`), que usa o maki para executar os briefs.
+ */
+
+export type {
+	HuntEvent,
+	HuntReport,
+	HuntRunnerOptions,
+	HuntTotals,
+	HuntWatchdogResult,
+} from "./hunt-runner";
+export { HuntRunner } from "./hunt-runner";
+export type {
+	InstallMakiOptions,
+	InstallMakiResult,
+	MakiBinary,
+	MakiBinarySource,
+	MakiInstallManifest,
+} from "./maki-install";
+export {
+	installMaki,
+	makiCurrentFile,
+	makiInstallDir,
+	makiSourceLabel,
+	makiToolsRoot,
+	probeMakiVersion,
+	readMakiInstall,
+	requireMakiBinary,
+	resolveMakiBinary,
+	uninstallMaki,
+} from "./maki-install";
+export type { MakiModel } from "./maki-model";
+export {
+	houndsmanKeyEnvFor,
+	MAKI_API_KEY_ENV,
+	requireMakiModel,
+	resolveMakiModel,
+} from "./maki-model";
+export { renderHuntPrompt, renderRetrySuffix } from "./maki-prompt";
+export type {
+	MakiJsonOutput,
+	MakiProcessRunner,
+	MakiRunMetrics,
+	MakiRunRequest,
+	MakiRunResult,
+	MakiUsage,
+} from "./maki-runner";
+export {
+	extractJsonObject,
+	MAKI_DISALLOWED_TOOLS,
+	makiArgs,
+	metricsFrom,
+	parseMakiOutput,
+	SpawnMakiRunner,
+} from "./maki-runner";
+export { mapPool } from "./pool";

package/src/core/hunt/maki-install.ts

@@ -0,0 +1,331 @@
+/**
+ * Instalação e descoberta do binário do maki (harness local).
+ *
+ * O binário é opcional e fica fora do projeto: `<HOUNDSMAN_HOME>/tools/maki`.
+ * `houndsman hunt install` baixa o release fixado e verifica o sha256; o
+ * `houndsman update`/`setup` nunca toca nisso. A skill `/houndsman hunt`
+ * (harness externo) não usa este módulo.
+ */
+
+import { createHash } from "node:crypto";
+import {
+	chmodSync,
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { env } from "../env";
+import { displayPath } from "../paths";
+import { systemClock } from "../services/clock";
+import { houndsmanHome } from "../storage/paths";
+import {
+	checksumFor,
+	effectiveMakiVersion,
+	makiAssetFor,
+	makiBinaryName,
+	makiChecksumsUrl,
+	makiDownloadUrl,
+	normalizeMakiVersion,
+} from "./maki-release";
+
+/** Origem do binário resolvido. */
+export type MakiBinarySource = "env" | "config" | "managed" | "path";
+
+/** Binário do maki disponível para execução. */
+export type MakiBinary = {
+	path: string;
+	source: MakiBinarySource;
+	/** Versão conhecida (instalação gerenciada). */
+	version?: string;
+};
+
+/** Manifesto da instalação gerenciada (`current.json`). */
+export type MakiInstallManifest = {
+	version: string;
+	path: string;
+	asset?: string;
+	sha256?: string;
+	installedAt: string;
+};
+
+/** Raiz das versões gerenciadas do maki. */
+export function makiToolsRoot(): string {
+	return join(houndsmanHome(), "tools", "maki");
+}
+
+/** Diretório de uma versão instalada. */
+export function makiInstallDir(version: string): string {
+	return join(makiToolsRoot(), normalizeMakiVersion(version));
+}
+
+/** Caminho do ponteiro para a instalação ativa. */
+export function makiCurrentFile(): string {
+	return join(makiToolsRoot(), "current.json");
+}
+
+/** Lê o manifesto da instalação gerenciada (null se ausente/inválido). */
+export function readMakiInstall(): MakiInstallManifest | null {
+	const file = makiCurrentFile();
+	if (!existsSync(file)) return null;
+	try {
+		const parsed = JSON.parse(
+			readFileSync(file, "utf8"),
+		) as Partial<MakiInstallManifest>;
+		if (typeof parsed.version !== "string" || typeof parsed.path !== "string") {
+			return null;
+		}
+		return {
+			version: parsed.version,
+			path: parsed.path,
+			asset: parsed.asset,
+			sha256: parsed.sha256,
+			installedAt: parsed.installedAt ?? systemClock(),
+		};
+	} catch {
+		return null;
+	}
+}
+
+/** Grava o ponteiro da instalação ativa. */
+function writeInstallManifest(manifest: MakiInstallManifest): void {
+	const file = makiCurrentFile();
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+/**
+ * Resolve o binário: `HOUNDSMAN_MAKI_PATH` > `hunt.binaryPath` > instalação
+ * gerenciada > `maki` no PATH. Não valida existência (use `requireMakiBinary`).
+ */
+export function resolveMakiBinary(configPath?: string): MakiBinary | null {
+	const explicit = env.makiPath ?? configPath?.trim();
+	if (explicit && explicit.length > 0) {
+		return { path: resolve(explicit), source: env.makiPath ? "env" : "config" };
+	}
+	const managed = readMakiInstall();
+	if (managed)
+		return { path: managed.path, source: "managed", version: managed.version };
+	const which = Bun.which("maki");
+	if (which) return { path: which, source: "path" };
+	return null;
+}
+
+/** Rótulo legível da origem (diagnóstico). */
+export function makiSourceLabel(source: MakiBinarySource): string {
+	switch (source) {
+		case "env":
+			return "HOUNDSMAN_MAKI_PATH";
+		case "config":
+			return "hunt.binaryPath";
+		case "managed":
+			return "instalação gerenciada";
+		default:
+			return "PATH";
+	}
+}
+
+/** Resolve e exige um binário existente; lança erro acionável quando ausente. */
+export function requireMakiBinary(configPath?: string): MakiBinary {
+	const binary = resolveMakiBinary(configPath);
+	if (!binary) {
+		throw new Error(
+			"Capability `hunt` não instalada: rode `houndsman hunt install` (ou defina HOUNDSMAN_MAKI_PATH).",
+		);
+	}
+	if (!existsSync(binary.path)) {
+		throw new Error(
+			`Binário do maki não encontrado em ${displayPath(binary.path)} (${makiSourceLabel(binary.source)}). ` +
+				"Rode `houndsman hunt install --force` ou ajuste HOUNDSMAN_MAKI_PATH.",
+		);
+	}
+	return binary;
+}
+
+/** Lê a versão do binário (`maki --version`); `undefined` se indisponível. */
+export function probeMakiVersion(binaryPath: string): string | undefined {
+	try {
+		const result = Bun.spawnSync([binaryPath, "--version"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		if (result.exitCode !== 0) return undefined;
+		const output = result.stdout.toString().trim();
+		return output.match(/\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?/)?.[0];
+	} catch {
+		return undefined;
+	}
+}
+
+/** Opções de instalação. */
+export type InstallMakiOptions = {
+	/** Versão alvo (`vX.Y.Z` ou `X.Y.Z`). */
+	version?: string;
+	/** Reinstala mesmo se o binário já existir. */
+	force?: boolean;
+	/** Arquivo local (`.tar.gz`/`.zip`) para ambientes offline. */
+	from?: string;
+	/** Progresso textual (CLI). */
+	log?: (message: string) => void;
+	/** `fetch` injetável (testes). */
+	fetchImpl?: typeof fetch;
+};
+
+/** Resultado da instalação. */
+export type InstallMakiResult = {
+	version: string;
+	path: string;
+	skipped: boolean;
+};
+
+/** Baixa (ou extrai) o maki para `<HOUNDSMAN_HOME>/tools/maki/<versão>`. */
+export async function installMaki(
+	options: InstallMakiOptions = {},
+): Promise<InstallMakiResult> {
+	const version = effectiveMakiVersion(options.version);
+	const binaryName = makiBinaryName();
+	const target = join(makiInstallDir(version), binaryName);
+	const log = options.log ?? (() => {});
+
+	if (existsSync(target) && !options.force) {
+		writeInstallManifest({ version, path: target, installedAt: systemClock() });
+		return { version, path: target, skipped: true };
+	}
+
+	const asset = makiAssetFor(process.platform, process.arch, version);
+	if (!asset) {
+		throw new Error(
+			`Sem release do maki para ${process.platform}/${process.arch}. ` +
+				"Instale manualmente (https://github.com/tontinton/maki/releases) e defina HOUNDSMAN_MAKI_PATH.",
+		);
+	}
+
+	const temp = mkdtempSync(join(tmpdir(), "houndsman-maki-"));
+	try {
+		let archivePath: string;
+		let checksum: string | undefined;
+
+		if (options.from) {
+			archivePath = resolve(options.from);
+			if (!existsSync(archivePath)) {
+				throw new Error(
+					`Arquivo do maki não encontrado: ${displayPath(archivePath)}.`,
+				);
+			}
+			log(`Extraindo ${displayPath(archivePath)}...`);
+		} else {
+			const fetchImpl = options.fetchImpl ?? fetch;
+			const url = makiDownloadUrl(version, asset.name);
+			log(`Baixando maki v${version} (${asset.name})...`);
+			const response = await fetchImpl(url);
+			if (!response.ok) {
+				throw new Error(
+					`Falha ao baixar o maki (HTTP ${response.status}): ${url}`,
+				);
+			}
+			const bytes = new Uint8Array(await response.arrayBuffer());
+
+			const checksumsResponse = await fetchImpl(makiChecksumsUrl(version));
+			if (checksumsResponse.ok) {
+				const expected = checksumFor(await checksumsResponse.text(), asset.name);
+				if (expected) {
+					const actual = createHash("sha256").update(bytes).digest("hex");
+					if (actual !== expected) {
+						throw new Error(
+							`Checksum inválido para ${asset.name} (esperado ${expected.slice(0, 12)}…, obtido ${actual.slice(0, 12)}…).`,
+						);
+					}
+					checksum = expected;
+					log("Checksum sha256 verificado.");
+				} else {
+					log(
+						"Aviso: release sem checksum para o asset; seguindo sem verificação.",
+					);
+				}
+			} else {
+				log(
+					`Aviso: não foi possível obter sha256sums.txt (HTTP ${checksumsResponse.status}).`,
+				);
+			}
+
+			archivePath = join(temp, asset.name);
+			writeFileSync(archivePath, bytes);
+		}
+
+		const extractDir = join(temp, "extract");
+		mkdirSync(extractDir, { recursive: true });
+		extractArchive(archivePath, extractDir);
+		const found = findFile(extractDir, binaryName);
+		if (!found) {
+			throw new Error(
+				`O pacote do maki não contém '${binaryName}'. Conteúdo inesperado em ${basename(archivePath)}.`,
+			);
+		}
+
+		const installDir = makiInstallDir(version);
+		mkdirSync(installDir, { recursive: true });
+		copyFileSync(found, target);
+		chmodSync(target, 0o755);
+		writeInstallManifest({
+			version,
+			path: target,
+			asset: asset.name,
+			sha256: checksum,
+			installedAt: systemClock(),
+		});
+		return { version, path: target, skipped: false };
+	} finally {
+		rmSync(temp, { recursive: true, force: true });
+	}
+}
+
+/** Remove todas as versões gerenciadas; devolve o caminho removido (ou null). */
+export function uninstallMaki(): string | null {
+	const root = makiToolsRoot();
+	if (!existsSync(root)) return null;
+	rmSync(root, { recursive: true, force: true });
+	return root;
+}
+
+/** Extrai `.tar.gz`/`.zip` (Windows usa o `tar.exe`/bsdtar do sistema). */
+function extractArchive(archive: string, directory: string): void {
+	try {
+		const result = Bun.spawnSync(["tar", "-xf", archive, "-C", directory], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		if (result.exitCode !== 0) {
+			const detail = result.stderr.toString().trim();
+			throw new Error(
+				`Falha ao extrair ${basename(archive)}${detail ? `: ${detail}` : "."}`,
+			);
+		}
+	} catch (error) {
+		if (error instanceof Error && error.message.startsWith("Falha ao extrair")) {
+			throw error;
+		}
+		throw new Error(
+			`Falha ao extrair ${basename(archive)}: 'tar' indisponível no sistema.`,
+		);
+	}
+}
+
+/** Procura um arquivo por nome, com profundidade limitada. */
+function findFile(root: string, name: string, depth = 0): string | null {
+	if (depth > 4) return null;
+	for (const entry of readdirSync(root, { withFileTypes: true })) {
+		const full = join(root, entry.name);
+		if (entry.isFile() && entry.name === name) return full;
+		if (entry.isDirectory()) {
+			const found = findFile(full, name, depth + 1);
+			if (found) return found;
+		}
+	}
+	return null;
+}