@payconductor/houndsman 0.11.0 → 0.13.0

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

@@ -0,0 +1,276 @@
+/**
+ * Execução headless do maki (harness local).
+ *
+ * Um processo por watchdog, sem TUI: o prompt vai por stdin (`maki -p`) e o
+ * houndsman lê o JSON de `--output-format json`. O watchdog não recebe
+ * permissão de escrita: `write`/`edit`/`bash`/rede/`task` são negados (deny
+ * vence qualquer yolo). Nenhuma config global do maki é alterada.
+ */
+
+/** Ferramentas negadas ao watchdog (deny vence `--yolo`). */
+export const MAKI_DISALLOWED_TOOLS =
+	"bash,webfetch,websearch,write,edit,multiedit,edit_lines,insert_lines,task";
+
+/** Pedido de execução de um watchdog. */
+export type MakiRunRequest = {
+	/** Prompt completo (brief + contrato). */
+	prompt: string;
+	/** Raiz de leitura (worktree ou clone principal). */
+	cwd: string;
+	/** Spec `provider/model-id`. */
+	model: string;
+	/** Variável nativa que o maki lê (`DEEPSEEK_API_KEY` etc.). */
+	apiKeyEnv: string;
+	/** Valor da chave (injetado só no processo filho). */
+	apiKey: string;
+	/** Timeout do processo (ms). */
+	timeoutMs: number;
+};
+
+/** Uso de tokens normalizado. */
+export type MakiUsage = {
+	inputTokens?: number;
+	outputTokens?: number;
+	totalTokens?: number;
+	cacheReadInputTokens?: number;
+};
+
+/** Métricas de uma execução. */
+export type MakiRunMetrics = {
+	sessionId?: string;
+	durationMs: number;
+	numTurns?: number;
+	costUsd?: number;
+	usage?: MakiUsage;
+};
+
+/** Resultado de uma execução. */
+export type MakiRunResult =
+	| {
+			ok: true;
+			/** Texto final do agente (deve conter o JSON dos findings). */
+			text: string;
+			metrics: MakiRunMetrics;
+			stderr: string;
+			exitCode: number;
+	  }
+	| {
+			ok: false;
+			error: string;
+			metrics: MakiRunMetrics;
+			stderr: string;
+			exitCode?: number;
+			timedOut?: boolean;
+	  };
+
+/** Runner injetável (testes usam um fake sem processo). */
+export interface MakiProcessRunner {
+	run(request: MakiRunRequest): Promise<MakiRunResult>;
+}
+
+/** Saída JSON do `maki --print --output-format json`. */
+export type MakiJsonOutput = {
+	type?: string;
+	subtype?: string;
+	is_error?: boolean;
+	result?: string;
+	session_id?: string;
+	duration_ms?: number;
+	num_turns?: number;
+	total_cost_usd?: number;
+	usage?: {
+		input_tokens?: number;
+		output_tokens?: number;
+		total_tokens?: number;
+		cache_read_input_tokens?: number;
+	};
+};
+
+/** Argumentos do processo (o prompt vai por stdin). */
+export function makiArgs(model: string): string[] {
+	return [
+		"-p",
+		"--output-format",
+		"json",
+		"--model",
+		model,
+		"--disallowed-tools",
+		MAKI_DISALLOWED_TOOLS,
+	];
+}
+
+/** Runner real, via `Bun.spawn`. */
+export class SpawnMakiRunner implements MakiProcessRunner {
+	private readonly binary: string;
+
+	constructor(binary: string) {
+		this.binary = binary;
+	}
+
+	async run(request: MakiRunRequest): Promise<MakiRunResult> {
+		const started = Date.now();
+		let timedOut = false;
+		try {
+			const proc = Bun.spawn([this.binary, ...makiArgs(request.model)], {
+				cwd: request.cwd,
+				env: { ...process.env, [request.apiKeyEnv]: request.apiKey },
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+
+			try {
+				proc.stdin.write(request.prompt);
+				void Promise.resolve(proc.stdin.end()).catch(() => {});
+			} catch {
+				// O processo pode ter encerrado antes de ler o stdin; o exit code
+				// e o stderr abaixo explicam o motivo.
+			}
+
+			// Consome os pipes desde já para não travar em saídas grandes.
+			const stdoutPromise = new Response(proc.stdout).text();
+			const stderrPromise = new Response(proc.stderr).text();
+			const timer = setTimeout(
+				() => {
+					timedOut = true;
+					proc.kill();
+				},
+				Math.max(1_000, request.timeoutMs),
+			);
+			const exitCode = await proc.exited;
+			clearTimeout(timer);
+			const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+			const durationMs = Date.now() - started;
+			const parsed = parseMakiOutput(stdout);
+			const metrics = metricsFrom(parsed, durationMs);
+
+			if (timedOut) {
+				return {
+					ok: false,
+					error: `Timeout após ${Math.round(durationMs / 1000)}s no maki.`,
+					metrics,
+					stderr,
+					exitCode,
+					timedOut: true,
+				};
+			}
+			if (exitCode !== 0 || parsed?.is_error === true) {
+				return {
+					ok: false,
+					error:
+						parsed?.result?.trim() ||
+						stderr.trim() ||
+						`maki saiu com código ${exitCode}.`,
+					metrics,
+					stderr,
+					exitCode,
+				};
+			}
+			if (typeof parsed?.result !== "string" || parsed.result.trim().length === 0) {
+				return {
+					ok: false,
+					error: "maki não retornou `result` (esperado com --output-format json).",
+					metrics,
+					stderr,
+					exitCode,
+				};
+			}
+			return {
+				ok: true,
+				text: parsed.result,
+				metrics,
+				stderr,
+				exitCode,
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error:
+					error instanceof Error
+						? `Falha ao executar o maki: ${error.message}`
+						: `Falha ao executar o maki: ${String(error)}`,
+				metrics: { durationMs: Date.now() - started },
+				stderr: "",
+			};
+		}
+	}
+}
+
+/** Extrai o objeto JSON do stdout do maki (linha única ou objeto completo). */
+export function parseMakiOutput(stdout: string): MakiJsonOutput | null {
+	const whole = tryParseJson(stdout.trim());
+	if (whole.ok && isObject(whole.value)) return whole.value as MakiJsonOutput;
+
+	const lines = stdout.split(/\r?\n/);
+	for (let index = lines.length - 1; index >= 0; index--) {
+		const line = lines[index].trim();
+		if (!line.startsWith("{")) continue;
+		const parsed = tryParseJson(line);
+		if (parsed.ok && isObject(parsed.value)) return parsed.value as MakiJsonOutput;
+	}
+	return null;
+}
+
+/**
+ * Extrai o JSON dos findings da resposta final do agente.
+ * Aceita JSON puro, bloco markdown ou objeto cercado por texto.
+ */
+export function extractJsonObject(text: string): unknown | null {
+	const trimmed = text.trim();
+	if (trimmed.length === 0) return null;
+
+	const direct = tryParseJson(trimmed);
+	if (direct.ok) return direct.value;
+
+	const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+	if (fenced) {
+		const parsed = tryParseJson(fenced[1].trim());
+		if (parsed.ok) return parsed.value;
+	}
+
+	const start = trimmed.indexOf("{");
+	const end = trimmed.lastIndexOf("}");
+	if (start >= 0 && end > start) {
+		const parsed = tryParseJson(trimmed.slice(start, end + 1));
+		if (parsed.ok) return parsed.value;
+	}
+	return null;
+}
+
+/** Normaliza as métricas do JSON do maki. */
+export function metricsFrom(
+	output: MakiJsonOutput | null,
+	durationMs: number,
+): MakiRunMetrics {
+	const usage = output?.usage;
+	return {
+		sessionId: typeof output?.session_id === "string" ? output.session_id : undefined,
+		durationMs: numberOr(output?.duration_ms) ?? durationMs,
+		numTurns: numberOr(output?.num_turns),
+		costUsd: numberOr(output?.total_cost_usd),
+		usage: usage
+			? {
+					inputTokens: numberOr(usage.input_tokens),
+					outputTokens: numberOr(usage.output_tokens),
+					totalTokens: numberOr(usage.total_tokens),
+					cacheReadInputTokens: numberOr(usage.cache_read_input_tokens),
+				}
+			: undefined,
+	};
+}
+
+function numberOr(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function tryParseJson(text: string): { ok: true; value: unknown } | { ok: false } {
+	try {
+		return { ok: true, value: JSON.parse(text) };
+	} catch {
+		return { ok: false };
+	}
+}

package/src/core/hunt/pool.ts

@@ -0,0 +1,30 @@
+/**
+ * Pool de concorrência mínimo (harness local).
+ *
+ * Mantém no máximo `limit` promessas ativas e preserva a ordem dos resultados.
+ * Não trata erros: o chamador decide se cada item falha isoladamente.
+ */
+
+/** Executa `mapper` para cada item com concorrência limitada. */
+export async function mapPool<T, R>(
+	items: readonly T[],
+	limit: number,
+	mapper: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+	const results = new Array<R>(items.length);
+	if (items.length === 0) return results;
+
+	let next = 0;
+	const workers = Array.from(
+		{ length: Math.max(1, Math.min(limit, items.length)) },
+		async () => {
+			while (true) {
+				const index = next++;
+				if (index >= items.length) return;
+				results[index] = await mapper(items[index], index);
+			}
+		},
+	);
+	await Promise.all(workers);
+	return results;
+}

package/src/core/jev/jev-detector.ts

@@ -156,10 +156,15 @@ export class JevDetector {
 		const hunk =
 			diff.byFile.get(filePath)?.slice(0, JevDetector.MAX_DIFF_CHARS) ?? "";
 		const parts = [`Arquivo: ${filePath} (${status})`];
+		parts.push(
+			"Escopo: apenas o diff abaixo refere-se ao que mudou nesta revisão.",
+			"O topo do arquivo é contexto para entender imports/declarações — não reporte",
+			"problemas apenas nele.",
+		);
 		if (header) {
-			parts.push("--- topo do arquivo (imports/declarações) ---", header);
+			parts.push("--- topo do arquivo (contexto) ---", header);
 		}
-		if (hunk) parts.push("--- diff ---", hunk);
+		if (hunk) parts.push("--- diff (escopo alterado) ---", hunk);
 		return parts.join("\n").slice(0, JevDetector.MAX_STATE_CHARS);
 	}
 

package/src/core/logging/index.ts

@@ -1,7 +1,7 @@
 /**
  * Instância pronta do logger (`import { logger } from "../core/logging"`).
  *
- * Infraestrutura compartilhada por `cli`, `harness` e `server`. Módulos de
+ * Infraestrutura compartilhada por `cli` e `server`. Módulos de
  * negócio do core não escrevem saída.
  */
 
@@ -15,3 +15,5 @@ export type {
 	SpinnerLike,
 } from "./logger";
 export { Logger, SilentLogger } from "./logger";
+export type { ProgressBoardOptions } from "./progress";
+export { formatDuration, PhaseReporter, ProgressBoard } from "./progress";

package/src/core/logging/logger.ts

@@ -1,11 +1,11 @@
 /**
- * Logger único do CLI/harness (infraestrutura).
+ * Logger único do CLI (infraestrutura).
  *
  * Usa `chalk` para cor e `ora` para spinner, mas cai para texto puro quando a
  * saída não é TTY, `NO_COLOR` está definido, `TERM=dumb` ou `--quiet`.
  *
- * Não é usado por módulos de negócio do `core/`: só `cli/`, `harness/` e
- * `server/` escrevem saída.
+ * Não é usado por módulos de negócio do `core/`: só `cli/` e `server/`
+ * escrevem saída.
  */
 
 import { Chalk, type ChalkInstance } from "chalk";
@@ -38,6 +38,10 @@ export interface LoggerLike {
 		text: string,
 		run: (spinner: SpinnerLike | null) => Promise<T>,
 	): Promise<T>;
+	/** `true` quando a saída é um TTY e o modo quiet está desligado. */
+	readonly interactive: boolean;
+	/** Stream de saída (usado pelos blocos de progresso). */
+	readonly stream: NodeJS.WritableStream;
 }
 
 /** Opções do logger (injetáveis nos testes). */
@@ -82,6 +86,16 @@ export class Logger implements LoggerLike {
 		this.tty = options.isTTY ?? Boolean(process.stdout.isTTY);
 	}
 
+	/** Loader/blocos só fazem sentido em terminal interativo. */
+	get interactive(): boolean {
+		return this.tty && !this.quiet;
+	}
+
+	/** Stream dos blocos de progresso. */
+	get stream(): NodeJS.WritableStream {
+		return this.out;
+	}
+
 	/** Só aparece em `--verbose`. */
 	debug(message: string): void {
 		if (!this.verbose || this.quiet) return;
@@ -164,6 +178,11 @@ export class Logger implements LoggerLike {
 
 /** Logger silencioso para testes/serviços. */
 export class SilentLogger implements LoggerLike {
+	readonly interactive = false;
+	readonly stream: NodeJS.WritableStream = {
+		write: () => true,
+	} as unknown as NodeJS.WritableStream;
+
 	debug(_message?: string): void {}
 	info(_message?: string): void {}
 	success(_message?: string): void {}

package/src/core/logging/progress.ts

@@ -0,0 +1,282 @@
+/**
+ * Progresso visual do CLI (infraestrutura).
+ *
+ * `PhaseReporter` acompanha fases sequenciais (spinner em TTY; `→`/`✔` em
+ * pipe). `ProgressBoard` mantém tarefas concorrentes com loader e tempo
+ * decorrido — é o que o harness local usa por watchdog.
+ *
+ * Progresso é diagnóstico: nenhum método lança.
+ */
+
+import type { LoggerLike, SpinnerLike } from "./logger";
+
+/** Formata uma duração em ms (`820ms`, `12.3s`, `2m05s`). */
+export function formatDuration(ms: number): string {
+	const safe = Math.max(0, Math.round(ms));
+	if (safe < 1_000) return `${safe}ms`;
+	const seconds = safe / 1_000;
+	if (seconds < 10) return `${seconds.toFixed(1)}s`;
+	if (seconds < 60) return `${Math.round(seconds)}s`;
+	const minutes = Math.floor(seconds / 60);
+	const rest = Math.round(seconds % 60);
+	return `${minutes}m${String(rest).padStart(2, "0")}s`;
+}
+
+/** Relógio curto no formato `m:ss` (usado no loader). */
+function clock(ms: number): string {
+	const total = Math.max(0, Math.round(ms / 1_000));
+	const minutes = Math.floor(total / 60);
+	return `${minutes}:${String(total % 60).padStart(2, "0")}`;
+}
+
+/** Relógio de uma fase: spinner no TTY, linhas `→`/`✔` em pipe. */
+export class PhaseReporter {
+	private readonly logger: LoggerLike;
+	private active: { stage: string; spinner: SpinnerLike } | null = null;
+
+	constructor(logger: LoggerLike) {
+		this.logger = logger;
+	}
+
+	/** Abre a fase (substituindo qualquer loader anterior). */
+	begin(stage: string, message: string): void {
+		try {
+			this.stop();
+			const spinner = this.logger.spinner(message);
+			if (spinner) {
+				spinner.start();
+				this.active = { stage, spinner };
+				return;
+			}
+			this.logger.step(message);
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Fecha a fase com a duração medida. */
+	end(stage: string, message: string, durationMs: number): void {
+		try {
+			const text = `${message} (${formatDuration(durationMs)})`;
+			if (this.active?.stage === stage) {
+				const { spinner } = this.active;
+				this.active = null;
+				spinner.succeed(text);
+				return;
+			}
+			this.logger.success(text);
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Encerra um loader pendente (sem mensagem de sucesso). */
+	stop(): void {
+		if (!this.active) return;
+		const { spinner } = this.active;
+		this.active = null;
+		try {
+			spinner.stop();
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+}
+
+/** Tarefa concorrente exibida pelo board. */
+type BoardTask = {
+	id: string;
+	detail: string;
+	startedMs: number;
+};
+
+export type ProgressBoardOptions = {
+	logger: LoggerLike;
+	/** Intervalo de repintura do loader em TTY (ms). */
+	frameMs?: number;
+	/** Intervalo do heartbeat textual fora de TTY (ms). */
+	heartbeatMs?: number;
+};
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/**
+ * Board de tarefas concorrentes (watchdogs do `hunt`).
+ *
+ * Em TTY repinta um bloco com loader + tempo decorrido por tarefa. Fora de
+ * TTY mantém as linhas de início/fim e emite um heartbeat periódico com quem
+ * ainda está rodando — o log do CI continua mostrando progresso.
+ */
+export class ProgressBoard {
+	private readonly logger: LoggerLike;
+	private readonly frameMs: number;
+	private readonly heartbeatMs: number;
+	private readonly tasks = new Map<string, BoardTask>();
+	private timer: ReturnType<typeof setInterval> | null = null;
+	private rendered = 0;
+	private frame = 0;
+	private done = 0;
+	private failed = 0;
+	private total = 0;
+	private lastHeartbeat = Date.now();
+
+	constructor(options: ProgressBoardOptions) {
+		this.logger = options.logger;
+		this.frameMs = options.frameMs ?? 200;
+		this.heartbeatMs = options.heartbeatMs ?? 30_000;
+	}
+
+	/** Define o total de tarefas do lote (rodapé do bloco). */
+	start(total: number): void {
+		this.total = Math.max(0, total);
+	}
+
+	/** Registra uma tarefa em execução. */
+	add(id: string, detail = "em execução"): void {
+		try {
+			this.tasks.set(id, { id, detail, startedMs: Date.now() });
+			if (!this.logger.interactive) this.logger.bullet(`${id}: ${detail}…`);
+			this.ensureTimer();
+			this.paint();
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Atualiza o detalhe de uma tarefa (ex.: tentativa atual). */
+	update(id: string, detail: string): void {
+		const task = this.tasks.get(id);
+		if (!task) return;
+		task.detail = detail;
+		this.paint();
+	}
+
+	/** Atualiza o detalhe e avisa em pipe (tentativas/retries). */
+	retry(id: string, detail: string, message: string): void {
+		try {
+			this.update(id, detail);
+			if (!this.logger.interactive) this.logger.bullet(message);
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Conclui uma tarefa com a mensagem final. */
+	succeed(id: string, message: string): void {
+		try {
+			if (this.tasks.delete(id)) this.done++;
+			if (!this.logger.interactive) {
+				this.logger.success(message);
+				return;
+			}
+			this.clear();
+			this.logger.success(message);
+			this.paint();
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Falha uma tarefa com a mensagem final. */
+	fail(id: string, message: string): void {
+		try {
+			if (this.tasks.delete(id)) this.failed++;
+			if (!this.logger.interactive) {
+				this.logger.warn(message);
+				return;
+			}
+			this.clear();
+			this.logger.warn(message);
+			this.paint();
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Encerra o board (timer + bloco renderizado). */
+	stop(): void {
+		this.stopTimer();
+		this.clear();
+	}
+
+	private ensureTimer(): void {
+		if (this.timer) return;
+		const period = this.logger.interactive ? this.frameMs : this.heartbeatMs;
+		this.timer = setInterval(() => this.tick(), period);
+		// Nunca segura o processo vivo por causa de um loader.
+		(this.timer as unknown as { unref?: () => void }).unref?.();
+	}
+
+	private stopTimer(): void {
+		if (!this.timer) return;
+		clearInterval(this.timer);
+		this.timer = null;
+	}
+
+	private tick(): void {
+		if (this.tasks.size === 0) {
+			this.stopTimer();
+			return;
+		}
+		if (this.logger.interactive) {
+			this.frame++;
+			this.paint();
+			return;
+		}
+		if (Date.now() - this.lastHeartbeat < this.heartbeatMs) return;
+		this.lastHeartbeat = Date.now();
+		try {
+			const running = [...this.tasks.values()]
+				.map((task) => `${task.id} (${clock(Date.now() - task.startedMs)})`)
+				.join(", ");
+			this.logger.bullet(`${this.tasks.size} tarefa(s) em execução: ${running}`);
+		} catch {
+			// Progresso nunca derruba a revisão.
+		}
+	}
+
+	/** Linhas do bloco (ativas + rodapé). */
+	private lines(): string[] {
+		const now = Date.now();
+		const active = [...this.tasks.values()];
+		const width = Math.max(...active.map((task) => task.id.length), 0);
+		const spinner = FRAMES[this.frame % FRAMES.length];
+		const rows = active.map(
+			(task) =>
+				`  ${spinner} ${task.id.padEnd(width)}  ${task.detail} · ${clock(now - task.startedMs)}`,
+		);
+		const finished = this.done + this.failed;
+		const failures = this.failed > 0 ? ` · ${this.failed} falha(s)` : "";
+		rows.push(
+			`  ${finished}/${this.total} concluído(s)${failures} · ${active.length} em execução`,
+		);
+		return rows;
+	}
+
+	/** Repinta o bloco no lugar (movendo o cursor para cima). */
+	private paint(): void {
+		if (!this.logger.interactive) return;
+		const lines = this.lines();
+		const stream = this.logger.stream;
+		const total = Math.max(this.rendered, lines.length);
+		if (this.rendered > 0) stream.write(`\u001b[${this.rendered}A`);
+		for (let index = 0; index < total; index++) {
+			stream.write(`\u001b[2K${lines[index] ?? ""}\n`);
+		}
+		const extra = total - lines.length;
+		if (extra > 0) stream.write(`\u001b[${extra}A`);
+		this.rendered = lines.length;
+	}
+
+	/** Apaga o bloco renderizado (deixa o cursor no início dele). */
+	private clear(): void {
+		if (!this.logger.interactive || this.rendered === 0) return;
+		const stream = this.logger.stream;
+		stream.write(`\u001b[${this.rendered}A`);
+		for (let index = 0; index < this.rendered; index++) {
+			stream.write("\u001b[2K\n");
+		}
+		stream.write(`\u001b[${this.rendered}A`);
+		this.rendered = 0;
+	}
+}