@payconductor/houndsman 0.4.0 → 0.6.0

package/src/core/ai/ai-client.ts

@@ -0,0 +1,221 @@
+/**
+ * Fachada de IA (`core/ai`) — fail-open, budget e uso.
+ *
+ * As features do core usam `generateObject`/`generateText` e tratam `ok:false`
+ * como "sem IA": a revisão determinística segue idêntica. O harness nativo usa
+ * `requireProvider` e falha com mensagem clara quando a IA não está configurada.
+ */
+
+import type { ZodType } from "zod";
+import type { ProjectConfig } from "../project-config";
+import { AiConfigurationError, errorMessage } from "./errors";
+import { ModelFactory } from "./model-factory";
+import type { AiResult, AiTool, AiUsage, ModelProvider, ModelRequest } from "./types";
+import { AiUsageBudget } from "./usage-budget";
+import { AiUsageRecorder } from "./usage-recorder";
+
+/** Opções de construção do cliente. */
+export type AiClientOptions = {
+	project: ProjectConfig;
+	/** Provider injetado (testes) — dispensa chave/rede. */
+	provider?: ModelProvider | null;
+	factory?: ModelFactory;
+	recorder?: AiUsageRecorder;
+	budget?: AiUsageBudget;
+};
+
+/** Pedido de objeto estruturado. */
+export type ObjectRequest<T> = {
+	instructions?: string;
+	prompt: string;
+	outputSchema: ZodType<T>;
+	tools?: Record<string, AiTool>;
+	maxSteps?: number;
+	maxOutputTokens?: number;
+	temperature?: number;
+	signal?: AbortSignal;
+};
+
+/** Pedido de texto livre. */
+export type TextRequest = Omit<ObjectRequest<string>, "outputSchema">;
+
+/** Resultado da validação de credencial (doctor). */
+export type AiCredentialCheck = {
+	ok: boolean;
+	kind: "ok" | "missing" | "invalid" | "unreachable";
+	detail: string;
+	model?: string;
+};
+
+/** Cliente de IA compartilhado pela review. */
+export class AiClient {
+	private readonly project: ProjectConfig;
+	private readonly factory: ModelFactory;
+	private readonly override: ModelProvider | null | undefined;
+	readonly recorder: AiUsageRecorder;
+	readonly budget: AiUsageBudget;
+
+	constructor(options: AiClientOptions) {
+		this.project = options.project;
+		this.factory = options.factory ?? new ModelFactory(options.project);
+		this.override = options.provider;
+		this.recorder =
+			options.recorder ??
+			new AiUsageRecorder(this.project.aiProvider, this.project.aiModel);
+		this.budget =
+			options.budget ??
+			new AiUsageBudget({
+				maxCalls: this.project.aiMaxCallsPerReview,
+				maxTokens: this.project.aiMaxTokensPerReview,
+			});
+	}
+
+	get modelId(): string {
+		return this.project.aiModel;
+	}
+
+	/** Configuração resolvida do projeto (features, budgets). */
+	get projectConfig(): ProjectConfig {
+		return this.project;
+	}
+
+	/** Features resolvidas (context/brief ligadas por default). */
+	get features() {
+		return this.project.aiFeatures;
+	}
+
+	/** `true` quando há provider disponível (injetado ou configurado + chave). */
+	get available(): boolean {
+		if (this.override !== undefined) return this.override !== null;
+		return this.factory.isConfigured;
+	}
+
+	/** Provider obrigatório — usado pelo harness (falha clara sem IA). */
+	async requireProvider(model?: string): Promise<ModelProvider> {
+		if (this.override === null) {
+			throw new AiConfigurationError(
+				"IA indisponível: provider injetado como null.",
+			);
+		}
+		if (this.override) return this.override;
+		return this.factory.create({ model });
+	}
+
+	/** Geração de objeto estruturado, fail-open. */
+	async generateObject<T>(
+		feature: string,
+		request: ObjectRequest<T>,
+		model?: string,
+	): Promise<AiResult<T>> {
+		return this.run(
+			feature,
+			{ ...request, outputSchema: request.outputSchema },
+			model,
+		);
+	}
+
+	/** Geração de texto, fail-open. */
+	async generateText(
+		feature: string,
+		request: TextRequest,
+		model?: string,
+	): Promise<AiResult<string>> {
+		return this.run<string>(feature, { ...request }, model);
+	}
+
+	/**
+	 * Ping mínimo para o `doctor`: valida a credencial sem gastar tokens
+	 * relevantes. Não lança; devolve o diagnóstico.
+	 */
+	async validateCredential(
+		options: { timeoutMs?: number } = {},
+	): Promise<AiCredentialCheck> {
+		if (this.override === null || !this.available) {
+			return {
+				ok: false,
+				kind: "missing",
+				detail: "provider/chave de IA não configurados",
+			};
+		}
+		const timeoutMs = Math.max(
+			1_000,
+			options.timeoutMs ?? Math.min(this.project.aiTimeoutMs, 8_000),
+		);
+		const result = await this.generateText("doctor-ping", {
+			prompt: "Responda apenas OK.",
+			maxSteps: 1,
+			maxOutputTokens: 4,
+			temperature: 0,
+			signal: AbortSignal.timeout(timeoutMs),
+		});
+		if (result.ok) {
+			return {
+				ok: true,
+				kind: "ok",
+				detail: "credencial válida",
+				model: result.model,
+			};
+		}
+		const message = result.error ?? "falha desconhecida";
+		if (
+			/401|403|unauthorized|invalid.*(key|token)|authentication|api.?key/i.test(
+				message,
+			)
+		) {
+			return { ok: false, kind: "invalid", detail: message };
+		}
+		return { ok: false, kind: "unreachable", detail: message };
+	}
+
+	/** Executa a chamada respeitando budget, timeout e uso. */
+	private async run<T>(
+		feature: string,
+		request: Omit<ObjectRequest<T>, "outputSchema"> & {
+			outputSchema?: ZodType<T>;
+		},
+		model?: string,
+	): Promise<AiResult<T>> {
+		if (!this.available) {
+			return { ok: false, error: "IA não configurada (fail-open)." };
+		}
+		try {
+			this.budget.assertCanCall();
+		} catch (error) {
+			return { ok: false, error: errorMessage(error) };
+		}
+
+		try {
+			const provider = await this.requireProvider(model);
+			const response = await provider.generate({
+				...request,
+				signal: combineSignals(request.signal, this.project.aiTimeoutMs),
+			});
+			this.budget.record(response.usage);
+			this.recorder.record(feature, provider.modelId, response.usage);
+			return {
+				ok: true,
+				output: response.output,
+				usage: response.usage,
+				model: provider.modelId,
+			};
+		} catch (error) {
+			return { ok: false, error: errorMessage(error) };
+		}
+	}
+}
+
+/** Combina o sinal do chamador com o timeout configurado. */
+function combineSignals(
+	signal: AbortSignal | undefined,
+	timeoutMs: number,
+): AbortSignal | undefined {
+	const timeout =
+		Number.isFinite(timeoutMs) && timeoutMs > 0
+			? AbortSignal.timeout(timeoutMs)
+			: undefined;
+	if (!signal) return timeout;
+	if (!timeout) return signal;
+	return AbortSignal.any([signal, timeout]);
+}
+
+export type { AiUsage, ModelRequest };

package/src/core/ai/ai-sdk-model-provider.ts

@@ -0,0 +1,101 @@
+/**
+ * Adapter do AI SDK (`generateText` + `Output.object` + tools).
+ *
+ * O resto do motor depende só de `ModelProvider`; trocar de SDK é trocar este
+ * arquivo. O loop de tools é do SDK (`stepCountIs`), com timeout/cancelamento
+ * via `AbortSignal`.
+ */
+
+import type { LanguageModel, ToolSet } from "ai";
+import { generateText, Output, stepCountIs, tool } from "ai";
+import type { AiProviderKind } from "../config";
+import { AiProviderError } from "./errors";
+import {
+	type AiTool,
+	type AiUsage,
+	emptyUsage,
+	type ModelProvider,
+	type ModelRequest,
+	type ModelResponse,
+} from "./types";
+
+/** Converte as tools do motor para o formato do AI SDK. */
+function toToolSet(tools: Record<string, AiTool>): ToolSet {
+	const entries = Object.entries(tools).map(([name, item]) => [
+		name,
+		tool({
+			description: item.description,
+			inputSchema: item.inputSchema,
+			execute: async (input: unknown) => item.execute(input),
+		}),
+	]);
+	return Object.fromEntries(entries) as ToolSet;
+}
+
+/** Mapeia o uso do SDK de forma defensiva (campos opcionais por provider). */
+export function mapUsage(raw: unknown): AiUsage {
+	const usage = (raw ?? {}) as Record<string, unknown>;
+	const input = numberOrZero(usage.inputTokens ?? usage.promptTokens);
+	const output = numberOrZero(usage.outputTokens ?? usage.completionTokens);
+	const total = numberOrZero(usage.totalTokens) || input + output;
+	return { inputTokens: input, outputTokens: output, totalTokens: total, calls: 1 };
+}
+
+function numberOrZero(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+/** Provider de modelo apoiado no AI SDK. */
+export class AiSdkModelProvider implements ModelProvider {
+	constructor(
+		readonly name: AiProviderKind,
+		readonly modelId: string,
+		private readonly model: LanguageModel,
+	) {}
+
+	async generate<T>(request: ModelRequest<T>): Promise<ModelResponse<T>> {
+		const tools = request.tools ? toToolSet(request.tools) : undefined;
+		const hasTools = tools !== undefined && Object.keys(tools).length > 0;
+		const maxSteps = request.maxSteps ?? 1;
+
+		try {
+			const result = await generateText({
+				model: this.model,
+				system: request.instructions,
+				prompt: request.prompt,
+				...(hasTools ? { tools, stopWhen: stepCountIs(maxSteps) } : {}),
+				...(request.outputSchema
+					? { output: Output.object({ schema: request.outputSchema }) }
+					: {}),
+				...(request.maxOutputTokens
+					? { maxOutputTokens: request.maxOutputTokens }
+					: {}),
+				...(request.temperature !== undefined
+					? { temperature: request.temperature }
+					: {}),
+				...(request.signal ? { abortSignal: request.signal } : {}),
+				maxRetries: 0,
+			});
+
+			const output = request.outputSchema
+				? (result.output as T)
+				: ((result.text ?? "") as unknown as T);
+			return {
+				output,
+				usage: mapUsage(result.usage),
+				steps: result.steps?.length ?? 1,
+				finishReason: result.finishReason ?? "unknown",
+			};
+		} catch (error) {
+			if (error instanceof Error && error.name === "AbortError") {
+				throw new AiProviderError("Chamada de IA cancelada ou expirada.", error);
+			}
+			throw new AiProviderError(
+				error instanceof Error ? error.message : String(error),
+				error,
+			);
+		}
+	}
+}
+
+export { emptyUsage };

package/src/core/ai/errors.ts

@@ -0,0 +1,36 @@
+/**
+ * Erros da camada de IA — mensagens claras e sem segredos.
+ */
+
+/** Configuração ausente/inválida (provider, modelo ou chave). */
+export class AiConfigurationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "AiConfigurationError";
+	}
+}
+
+/** Teto de chamadas/tokens por review estourado. */
+export class AiBudgetError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "AiBudgetError";
+	}
+}
+
+/** Falha do provider (rede, timeout, resposta inválida). */
+export class AiProviderError extends Error {
+	constructor(
+		message: string,
+		readonly cause?: unknown,
+	) {
+		super(message);
+		this.name = "AiProviderError";
+	}
+}
+
+/** Mensagem segura de um erro desconhecido. */
+export function errorMessage(error: unknown): string {
+	if (error instanceof Error) return error.message;
+	return String(error);
+}

package/src/core/ai/features/brief-enricher.ts

@@ -0,0 +1,62 @@
+/**
+ * Enriquecimento de briefs via IA (`AiBriefEnricher`).
+ *
+ * Uma chamada por watchdog, concorrência limitada. A saída é um plano sugerido
+ * (`BriefPlan`) — nunca cria regra nem achado. Falha → brief inalterado.
+ */
+
+import type { AiClient } from "../ai-client";
+import { type BriefPromptInput, briefInstructions, briefPrompt } from "../prompts/brief";
+import { type BriefPlan, BriefPlanSchema } from "../schemas";
+
+/** Enriquecimento de briefs (fail-open por watchdog). */
+export class AiBriefEnricher {
+	constructor(private readonly client: AiClient) {}
+
+	/** `true` quando a feature está ligada e há IA disponível. */
+	get enabled(): boolean {
+		return this.client.available && this.client.features.brief;
+	}
+
+	/** Plano de um watchdog; `null` em falha. */
+	async enrich(input: BriefPromptInput): Promise<BriefPlan | null> {
+		if (!this.enabled) return null;
+		const result = await this.client.generateObject<BriefPlan>(
+			"brief",
+			{
+				instructions: briefInstructions(),
+				prompt: briefPrompt(input),
+				outputSchema: BriefPlanSchema,
+				maxSteps: 1,
+				maxOutputTokens: 700,
+			},
+			this.client.projectConfig.aiModelFor(input.watchdogId),
+		);
+		if (!result.ok) return null;
+		return result.output;
+	}
+
+	/** Enriquece vários watchdogs com concorrência limitada. */
+	async enrichAll(
+		inputs: readonly BriefPromptInput[],
+	): Promise<Map<string, BriefPlan>> {
+		const plans = new Map<string, BriefPlan>();
+		if (!this.enabled || inputs.length === 0) return plans;
+		const concurrency = Math.max(1, this.client.projectConfig.aiConcurrency);
+		let cursor = 0;
+
+		const worker = async (): Promise<void> => {
+			while (cursor < inputs.length) {
+				const input = inputs[cursor++];
+				if (!input) return;
+				const plan = await this.enrich(input);
+				if (plan) plans.set(input.watchdogId, plan);
+			}
+		};
+
+		await Promise.all(
+			Array.from({ length: Math.min(concurrency, inputs.length) }, () => worker()),
+		);
+		return plans;
+	}
+}

package/src/core/ai/features/classifier.ts

@@ -0,0 +1,50 @@
+/**
+ * Classificação fallback por IA (arquivos que nenhum watchdog casou).
+ */
+
+import type { AiClient } from "../ai-client";
+import {
+	classificationInstructions,
+	classificationPrompt,
+} from "../prompts/classification";
+import { type AiClassification, ClassificationSchema } from "../schemas";
+
+/** Atribui arquivos não classificados a watchdogs conhecidos. */
+export class AiClassifier {
+	constructor(private readonly client: AiClient) {}
+
+	get enabled(): boolean {
+		return this.client.available && this.client.features.classification;
+	}
+
+	/**
+	 * Devolve `arquivo → watchdogId` apenas para ids válidos. Arquivos sem
+	 * atribuição simplesmente continuam não classificados.
+	 */
+	async classify(
+		files: readonly string[],
+		watchdogs: readonly { id: string; name: string; scope: string }[],
+	): Promise<Map<string, string>> {
+		const assignments = new Map<string, string>();
+		if (!this.enabled || files.length === 0 || watchdogs.length === 0) {
+			return assignments;
+		}
+		const known = new Set(watchdogs.map((item) => item.id));
+		const filesSet = new Set(files);
+		const result = await this.client.generateObject<AiClassification>(
+			"classification",
+			{
+				instructions: classificationInstructions(),
+				prompt: classificationPrompt({ files, watchdogs }),
+				outputSchema: ClassificationSchema,
+				maxSteps: 1,
+			},
+		);
+		if (!result.ok) return assignments;
+		for (const item of result.output.assignments) {
+			if (!known.has(item.watchdogId) || !filesSet.has(item.file)) continue;
+			assignments.set(item.file, item.watchdogId);
+		}
+		return assignments;
+	}
+}

package/src/core/ai/features/context-summarizer.ts

@@ -0,0 +1,31 @@
+/**
+ * Resumo do contexto da PR via IA (fallback ao subagente de contexto).
+ */
+
+import { type ContextSummary, parseContextSummary } from "../../report-builder";
+import type { AiClient } from "../ai-client";
+import { contextInstructions, contextPrompt } from "../prompts/context";
+import { type ContextSummaryPlan, ContextSummarySchema } from "../schemas";
+
+/** Resume `context.json` em um `ContextSummary` curto. */
+export class AiContextSummarizer {
+	constructor(private readonly client: AiClient) {}
+
+	/** `true` quando a feature está ligada e há IA disponível. */
+	get enabled(): boolean {
+		return this.client.available && this.client.features.context;
+	}
+
+	/** Falha-aberto: sem IA ou saída inválida → `null`. */
+	async summarize(raw: string): Promise<ContextSummary | null> {
+		if (!this.enabled) return null;
+		const result = await this.client.generateObject<ContextSummaryPlan>("context", {
+			instructions: contextInstructions(),
+			prompt: contextPrompt(raw),
+			outputSchema: ContextSummarySchema,
+			maxSteps: 1,
+		});
+		if (!result.ok) return null;
+		return parseContextSummary({ ...result.output, available: true });
+	}
+}

package/src/core/ai/features/pre-analyzer.ts

@@ -0,0 +1,51 @@
+/**
+ * Pré-análise por IA (substitui o Jev quando a feature está ligada).
+ *
+ * Produz candidatos no mesmo shape do Jev — nunca bloqueiam a revisão.
+ */
+
+import type { JevCandidate } from "../../jev";
+import type { AiClient } from "../ai-client";
+import {
+	type PreAnalysisPromptInput,
+	preAnalysisInstructions,
+	preAnalysisPrompt,
+} from "../prompts/pre-analysis";
+import { type AiCandidate, CandidateSchema } from "../schemas";
+
+/** Gera candidatos de pré-análise para um watchdog. */
+export class AiPreAnalyzer {
+	constructor(private readonly client: AiClient) {}
+
+	get enabled(): boolean {
+		return this.client.available && this.client.features.preAnalysis;
+	}
+
+	/** Candidatos validados contra as regras e arquivos fornecidos. */
+	async analyze(input: PreAnalysisPromptInput): Promise<JevCandidate[]> {
+		if (!this.enabled || input.files.length === 0) return [];
+		const rules = new Set(input.rules.map((rule) => rule.text.trim()));
+		const files = new Set(input.files.map((item) => item.file));
+		const result = await this.client.generateObject<{ candidates: AiCandidate[] }>(
+			"pre-analysis",
+			{
+				instructions: preAnalysisInstructions(),
+				prompt: preAnalysisPrompt(input),
+				outputSchema: CandidateSchema,
+				maxSteps: 1,
+			},
+			this.client.projectConfig.aiModelFor(input.watchdogId),
+		);
+		if (!result.ok) return [];
+		return result.output.candidates
+			.filter((item) => files.has(item.file) && rules.has(item.rule.trim()))
+			.map((item) => ({
+				watchdogId: input.watchdogId,
+				rule: item.rule,
+				severity: item.severity,
+				file: item.file,
+				confidence: item.confidence,
+				questionKey: "ai",
+			}));
+	}
+}

package/src/core/ai/features/verifier.ts

@@ -0,0 +1,45 @@
+/**
+ * Verificação de findings por IA (casos ambíguos do `verify`).
+ *
+ * Retorna `id → confiança` para o `applyConfidence` do core. Falha-aberto:
+ * ids ausentes mantêm o provisório local.
+ */
+
+import type { AiClient } from "../ai-client";
+import {
+	type VerifyPromptInput,
+	verifyInstructions,
+	verifyPrompt,
+} from "../prompts/verify";
+import { type AiVerdict, VerifySchema } from "../schemas";
+
+/** Confirma/refuta findings ambíguos. */
+export class AiVerifier {
+	constructor(private readonly client: AiClient) {}
+
+	get enabled(): boolean {
+		return this.client.available && this.client.features.verify;
+	}
+
+	/** Mapa id → confiança (0–1) de persistência. */
+	async verify(input: VerifyPromptInput): Promise<Map<string, number>> {
+		const confidence = new Map<string, number>();
+		if (!this.enabled || input.findings.length === 0) return confidence;
+		const ids = new Set(input.findings.map((item) => item.id));
+		const result = await this.client.generateObject<{ verdicts: AiVerdict[] }>(
+			"verify",
+			{
+				instructions: verifyInstructions(),
+				prompt: verifyPrompt(input),
+				outputSchema: VerifySchema,
+				maxSteps: 1,
+			},
+		);
+		if (!result.ok) return confidence;
+		for (const verdict of result.output.verdicts) {
+			if (!ids.has(verdict.id)) continue;
+			confidence.set(verdict.id, verdict.persisting ? verdict.confidence : 0);
+		}
+		return confidence;
+	}
+}

package/src/core/ai/index.ts

@@ -0,0 +1,56 @@
+/**
+ * Barrel da camada de IA (`core/ai`).
+ */
+
+export type { AiProviderKind } from "../config";
+export type {
+	AiClientOptions,
+	AiCredentialCheck,
+	ObjectRequest,
+	TextRequest,
+} from "./ai-client";
+export { AiClient } from "./ai-client";
+export { AiSdkModelProvider, mapUsage } from "./ai-sdk-model-provider";
+export {
+	AiBudgetError,
+	AiConfigurationError,
+	AiProviderError,
+	errorMessage,
+} from "./errors";
+export { AiBriefEnricher } from "./features/brief-enricher";
+export { AiClassifier } from "./features/classifier";
+export { AiContextSummarizer } from "./features/context-summarizer";
+export { AiPreAnalyzer } from "./features/pre-analyzer";
+export { AiVerifier } from "./features/verifier";
+export { hasProviderCredential, ModelFactory } from "./model-factory";
+export {
+	type AiCandidate,
+	type AiClassification,
+	type AiVerdict,
+	type AiWatchdogReport,
+	type BriefPlan,
+	BriefPlanSchema,
+	CandidateSchema,
+	ClassificationSchema,
+	type ContextSummaryPlan,
+	ContextSummarySchema,
+	SeveritySchema,
+	VerifySchema,
+	WatchdogReportSchema,
+} from "./schemas";
+export {
+	type AiResult,
+	type AiTool,
+	type AiUsage,
+	addUsage,
+	emptyUsage,
+	type ModelProvider,
+	type ModelRequest,
+	type ModelResponse,
+} from "./types";
+export { type AiBudgetLimits, AiUsageBudget } from "./usage-budget";
+export {
+	type AiUsageEntry,
+	type AiUsageFile,
+	AiUsageRecorder,
+} from "./usage-recorder";