@payconductor/houndsman 0.5.0 → 0.7.0

package/README.md

@@ -27,7 +27,12 @@ diferente das PRs. O motor só coordena a caçada — as regras são problema se
 - **Bun** — runtime obrigatório.
 - **git** — o diff usa `git diff <base>...<head>`.
 - **gh** (Opcional) — Obtém contexto da PR e dispara comentários para o GitHub
-- **`TYPESAFE_API_KEY`** (Opcional) — Env a ser informada na raiz, usada em pré-analise com JEV
+- **`HOUNDSMAN_TYPE_SAFE_API_KEY`** (opcional) — pré-análise Jev.
+- **`HOUNDSMAN_DEEP_SEEK_API_KEY`** (opcional) — IA própria do `hunt` nativo e das features de IA.
+- **`HOUNDSMAN_OPENAI_API_KEY`** / **`HOUNDSMAN_ANTHROPIC_API_KEY`** (opcional) — apenas se
+  `ai.provider` for `openai`/`anthropic`.
+
+> Coloque as chaves em um `.env` na raiz do projeto; o Bun carrega automaticamente.
 
 ### 2. Instale o CLI (global)
 
@@ -48,13 +53,14 @@ Cria a camada `.houndsman/`, que é **autocontida** (não instala nada no seu pr
 | Caminho | Dono | O que é |
 |---|---|---|
 | `houndsman.config.ts` | você | Configuração do projeto (um objeto de dados) |
-| `.houndsman/watchdogs/` | você | Suas regras — começa com **1 watchdog de exemplo** |
+| `.houndsman/watchdogs/` | você | Suas regras — começa com um watchdog `default` (fallback) e um `example` |
 | `.houndsman/exclusions.ts` | você | Arquivos que nunca entram na revisão |
 | `.houndsman/doc-mappings.ts` | você | path → documentação de contexto |
 | `.houndsman/core/**` | auto | Tipos + docs do skill (sincronizados por `houndsman update`) |
 
-> O `setup` já cria a camada inicial com um watchdog de exemplo — troque o exemplo pelas
-> regras reais do seu projeto (ou use `/houndsman train`).
+> O `setup` já cria a camada inicial com um watchdog `default` (fallback, cobre arquivos sem
+> domínio) e um `example` — troque o exemplo pelas regras reais do seu projeto (ou use
+> `/houndsman train`).
 
 ### 4. Escreva suas regras
 
@@ -78,6 +84,20 @@ O skill orquestra tudo e persiste o relatório no storage global (SQLite em
 `<HOUNDSMAN_HOME>/houndsman.db`); a UI lê os artefatos direto do storage. Não precisa rodar
 nenhum script à mão.
 
+### 7. Revisão nativa (opcional) — `houndsman hunt`
+
+Além do skill, o houndsman tem um **harness próprio**: o `hunt` roda o agente de revisão
+dentro do CLI, com tools read-only, investigação por evidência e a mesma saída `review.md`.
+
+```bash
+bun run houndsman hunt --dry-run     # inspeciona watchdogs/arquivos, sem IA
+HOUNDSMAN_DEEP_SEEK_API_KEY=... bun run houndsman hunt
+bun run houndsman hunt --resume      # preserva findings válidos do staging
+bun run houndsman hunt --fail-on-blocking
+```
+
+Detalhes (catálogo de tools, máquina de estados, custos e segurança): [`docs/HARNESS.md`](docs/HARNESS.md).
+
 ---
 
 ## O fluxo de trabalho

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@payconductor/houndsman",
-	"version": "0.5.0",
+	"version": "0.7.0",
 	"description": "Orquestrador de revisão de Pull Requests: classifica o diff, despacha watchdogs especializados por domínio e consolida o relatório.",
 	"type": "module",
 	"license": "MIT",
@@ -51,14 +51,22 @@
 		"ci:check:fix": "biome check --fix",
 		"ci:fix": "bun run ci:check:fix && bun run ci:format:fix",
 		"ci:format": "biome format",
-		"ci:format:fix": "biome format --fix"
+		"ci:format:fix": "biome format --fix",
+		"grammars:sync": "bun run ./scripts/sync-grammars.ts"
 	},
 	"dependencies": {
+		"@ai-sdk/deepseek": "3.0.67",
+		"ai": "7.0.143",
 		"axios": "^1.12.2",
-		"preact": "^11.0.1"
+		"chalk": "^6.0.1",
+		"ora": "^9.4.1",
+		"preact": "^11.0.1",
+		"web-tree-sitter": "0.27.1",
+		"zod": "4.6.7"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.2.4",
+		"@vscode/tree-sitter-wasm": "0.3.1",
 		"bun-types": "^1.3.14",
 		"typescript": "^7.0.2"
 	}

package/src/cli/commands/command.ts

@@ -6,13 +6,18 @@
  */
 
 import type { HoundsmanEngine } from "../../core/engine/houndsman-engine";
+import type { LoggerLike } from "../../core/logging";
 
 /** Contexto de execução de um comando. */
 export type CliContext = {
 	cwd: string;
 	/** Carrega a config do projeto e devolve o engine (lazy). */
 	engine: () => Promise<HoundsmanEngine>;
+	/** Logger único do CLI (cores/spinner/progresso). */
+	logger: LoggerLike;
+	/** @deprecated use `logger.info`. */
 	out: (message: string) => void;
+	/** @deprecated use `logger.error`. */
 	err: (message: string) => void;
 };
 

package/src/cli/commands/doctor-command.ts

@@ -1,60 +1,152 @@
-/** Comando `doctor` (alias `check`) — valida config, ambiente e credencial Jev. */
+/** Comando `doctor` (alias `check`) — valida config, ambiente e credenciais. */
 
+import type { AiClient } from "../../core/ai/ai-client";
+import { ArgParser } from "../../core/arg-parser";
+import type { AiProviderKind } from "../../core/config";
+import { ENV_NAMES, env } from "../../core/env";
 import { checkRegistry } from "../../core/registry-check";
 import { storageLocation } from "../../core/storage/paths";
 import type { CliContext, Command } from "./command";
 
+/** Chave de ambiente esperada por provider. */
+function keyFor(provider: AiProviderKind): string | undefined {
+	switch (provider) {
+		case "deepseek":
+			return env.deepSeekApiKey;
+		case "openai":
+			return env.openAiApiKey;
+		case "anthropic":
+			return env.anthropicApiKey;
+		default:
+			return undefined;
+	}
+}
+
+/** Nome da variável de ambiente por provider. */
+function envNameFor(provider: AiProviderKind): string {
+	switch (provider) {
+		case "openai":
+			return ENV_NAMES.openAiApiKey;
+		case "anthropic":
+			return ENV_NAMES.anthropicApiKey;
+		default:
+			return ENV_NAMES.deepSeekApiKey;
+	}
+}
+
 export class DoctorCommand implements Command {
 	readonly name = "doctor";
 
-	async run(_args: string[], context: CliContext): Promise<number> {
+	async run(args: string[], context: CliContext): Promise<number> {
+		const parser = ArgParser.from(args);
+		const noPing = parser.has("--no-ping");
 		const engine = await context.engine();
-		context.out("→ Validando configuração do projeto...");
+		const { logger } = context;
+
+		logger.step("Validando configuração do projeto...");
 		const { problems, warnings, jevQuestions } = checkRegistry(engine.config);
 
 		if (problems.length > 0) {
-			context.err("\n❌ Problemas na configuração de revisão:\n");
-			for (const problem of problems) context.err(`  - ${problem}`);
+			logger.error("Problemas na configuração de revisão:");
+			for (const problem of problems) logger.error(`  - ${problem}`);
 			return 1;
 		}
-		context.out(
-			`  ✅ ${engine.config.watchdogIds.length} watchdogs, ${jevQuestions} pergunta(s) Jev.`,
+		logger.success(
+			`${engine.config.watchdogIds.length} watchdogs, ${jevQuestions} pergunta(s) Jev.`,
 		);
 
 		if (warnings.length > 0) {
-			context.out(`\n⚠️  ${warnings.length} aviso(s) (não bloqueantes):`);
-			for (const warning of warnings) context.out(`  - ${warning}`);
-		}
-
-		context.out("\n→ Ambiente:");
-		context.out(`  ${Bun.which("git") ? "✅" : "❌"} git`);
-		context.out(`  ${Bun.which("gh") ? "✅" : "⚠️ "} gh (opcional — contexto da PR)`);
-		context.out("\n→ Persistência:");
-		context.out(`  provider: ${engine.storage.kind}`);
-		context.out(`  ${storageLocation(engine.config)}`);
-		context.out(`  repo: ${engine.repo.key}`);
-		await this.reportJevCredential(context);
+			logger.warn(`${warnings.length} aviso(s) (não bloqueantes):`);
+			for (const warning of warnings) logger.bullet(warning);
+		}
+
+		logger.step("Ambiente:");
+		logger.bullet(`${Bun.which("git") ? "✅" : "❌"} git`);
+		logger.bullet(`${Bun.which("gh") ? "✅" : "⚠️ "} gh (opcional — contexto da PR)`);
+		const ast = await engine.ast.check();
+		logger.bullet(`${ast.ok ? "✅" : "⚠️ "} AST: ${ast.detail}`);
+
+		const provider = engine.ai.projectConfig.aiProvider;
+		const key = keyFor(provider);
+		logger.bullet(
+			`${key ? "✅" : "⚠️ "} ${envNameFor(provider)} (provider ${provider})`,
+		);
+		logger.bullet(
+			`IA: provider=${provider}, model=${engine.ai.modelId}, ` +
+				`disponível=${engine.ai.available ? "sim" : "não"}`,
+		);
+
+		await this.reportAiCredential(context, engine.ai, provider, key, noPing);
+		await this.reportJevCredential(context, noPing);
+
+		logger.step("Persistência:");
+		logger.bullet(`provider: ${engine.storage.kind}`);
+		logger.bullet(storageLocation(engine.config));
+		logger.bullet(`repo: ${engine.repo.key}`);
 		return 0;
 	}
 
+	/**
+	 * Valida a credencial do provider de IA com um ping mínimo. Fail-open:
+	 * problemas de credencial são diagnóstico e não alteram o exit code.
+	 */
+	private async reportAiCredential(
+		context: CliContext,
+		ai: AiClient,
+		provider: AiProviderKind,
+		key: string | undefined,
+		noPing: boolean,
+	): Promise<void> {
+		if (!key) {
+			context.logger.warn(
+				`IA: ${provider} sem credencial — features de IA ficam fail-open.`,
+			);
+			return;
+		}
+		if (noPing) {
+			context.logger.info("IA: validação pulada (--no-ping).");
+			return;
+		}
+		context.logger.step("Validando credencial de IA...");
+		const check = await ai.validateCredential();
+		if (check.ok) {
+			context.logger.success(
+				`IA: credencial válida (modelo ${check.model ?? provider}).`,
+			);
+		} else if (check.kind === "invalid") {
+			context.logger.error(`IA: credencial inválida — ${check.detail}`);
+		} else {
+			context.logger.warn(`IA: não foi possível validar — ${check.detail}`);
+		}
+	}
+
 	/**
 	 * Reporta o estado da credencial Jev: presença e validade (chamada mínima).
 	 * Fail-open — nunca altera o exit code (`doctor` é diagnóstico).
 	 */
-	private async reportJevCredential(context: CliContext): Promise<void> {
+	private async reportJevCredential(
+		context: CliContext,
+		noPing: boolean,
+	): Promise<void> {
 		const { JevClient } = await import("../../core/jev");
 		const client = new JevClient();
 		if (!client.isConfigured()) {
-			context.out("  ⚠️  TYPESAFE_API_KEY (opcional — pré-análise Jev)");
+			context.logger.warn(
+				`${ENV_NAMES.typeSafeApiKey} (opcional — pré-análise Jev)`,
+			);
+			return;
+		}
+		if (noPing) {
+			context.logger.info("Jev: validação pulada (--no-ping).");
 			return;
 		}
 		const check = await client.validateCredential();
 		if (check.ok) {
-			context.out(`  ✅ Jev: credencial válida (modelo ${check.model}).`);
+			context.logger.success(`Jev: credencial válida (modelo ${check.model}).`);
 		} else if (check.kind === "invalid") {
-			context.out(`  ❌ Jev: credencial inválida — ${check.detail}`);
+			context.logger.error(`Jev: credencial inválida — ${check.detail}`);
 		} else {
-			context.out(`  ⚠️  Jev: não foi possível validar — ${check.detail}`);
+			context.logger.warn(`Jev: não foi possível validar — ${check.detail}`);
 		}
 	}
 }

package/src/cli/commands/hunt-command.ts

@@ -0,0 +1,25 @@
+/** Comando `hunt` — revisão nativa com IA (harness próprio). */
+
+import { HuntHarness } from "../../harness";
+import { parseHuntArgs } from "../../harness/hunt/hunt-options";
+import type { CliContext, Command } from "./command";
+
+/** Executa o harness nativo. */
+export class HuntCommand implements Command {
+	readonly name = "hunt";
+
+	async run(args: string[], context: CliContext): Promise<number> {
+		const options = parseHuntArgs(args);
+		const engine = await context.engine();
+		try {
+			const harness = await HuntHarness.from(engine, options, context.logger);
+			const result = await harness.run();
+			for (const message of result.messages) context.logger.info(message);
+			if (result.status === "failed") return 1;
+			if (options.failOnBlocking && result.blockers > 0) return 1;
+			return 0;
+		} finally {
+			engine.close();
+		}
+	}
+}

package/src/cli/commands/server-command.ts

@@ -26,9 +26,15 @@ export class ServerCommand implements Command {
 		const parser = ArgParser.from(args);
 		const port = Number(parser.value("--port")) || 7331;
 		const host = parser.value("--host") ?? "127.0.0.1";
+		const editorPreference = parser.value("--editor");
 
 		const { startServer } = await import("../../server");
-		const { url } = startServer({ config: engine.config, port, host });
+		const { url } = startServer({
+			config: engine.config,
+			port,
+			host,
+			editorPreference,
+		});
 		context.out(`[houndsman] servidor em ${url}`);
 		context.out("[houndsman] Ctrl+C para encerrar.");
 		if (parser.has("--open")) openBrowser(url);

package/src/cli/help.ts

@@ -5,9 +5,10 @@ Comandos:
   (nenhum)            Prepara a revisão (classification + briefs + manifesto)
   --finalize          Consolida os findings em review.md
   context             Coleta o contexto da PR via gh (Passo 0)
+  hunt                Revisão nativa com IA (harness próprio): prepare + agentes + finalize
   findings <sub>      Triagem/correção dos findings (list · show · set · done · reset · sync · summary · batch · verify · submit · path)
   status [ping]       Mostra o status da run (ping renova o heartbeat da execução)
-  server              Sobe a UI local de triagem (--port, --host, --open)
+  server              Sobe a UI local de triagem (--port, --host, --open, --editor)
   setup               Cria a configuração inicial do projeto (config + skills)
   update              Sincroniza os arquivos auto-gerados (.houndsman/core)
   doctor              Valida a configuração, o ambiente e a credencial Jev
@@ -22,8 +23,16 @@ Flags:
   --clean             Descarta findings brutos do staging anterior
   --full              Força review completo (ignora o modo incremental)
   --no-jev            Desativa a pré-análise Jev
+  --no-ast            Desativa a análise estrutural (tree-sitter)
+  --no-ai             Desativa as features de IA do fluxo normal
   --fail-on-blocking  Exit 1 se houver bloqueantes (com --finalize)
 
+Flags do hunt:
+  --base <b> · --head <ref> · --branch <nome> · --watchdog <id>
+  --full · --clean · --no-ast · --with-jev
+  --resume · --allow-partial · --dry-run · --fail-on-blocking
+  --max-calls <n> · --concurrency <n> · --provider <p> · --model <m>
+
 Flags de findings:
   --decision <d>      pending | execute | ignore
   --exec <e>          pending | in_progress | done | stale
@@ -41,8 +50,15 @@ Flags de findings:
   --fail-on-persisting (verify) Exit 1 se algum blocking persistir
   --include-sent      (submit) Reenvia findings já enviados à PR
   --dry-run           (submit) Só a prévia do envio, sem postar
+  --no-ping           (doctor) Pula a validação de rede das credenciais
 
 Persistência:
   Runs, findings e artefatos ficam no storage global (SQLite em
   <HOUNDSMAN_HOME>/houndsman.db). Use storage.provider: "file" na config para
-  voltar ao backend de arquivos. Nada é gravado em .houndsman/.runs.`;
+  voltar ao backend de arquivos. Nada é gravado em .houndsman/.runs.
+
+Ambiente (o Bun carrega .env automaticamente):
+  HOUNDSMAN_TYPE_SAFE_API_KEY   Pré-análise Jev (opcional)
+  HOUNDSMAN_DEEP_SEEK_API_KEY   IA (provider deepseek, opcional)
+  HOUNDSMAN_OPENAI_API_KEY     IA (provider openai, opcional)
+  HOUNDSMAN_ANTHROPIC_API_KEY  IA (provider anthropic, opcional)`;

package/src/cli/index.ts

@@ -24,17 +24,19 @@
  *   watchdog <id>        Contexto de um watchdog (`--rules`, `--json`)
  *
  * Flags: `--base <b>` · `--head <ref>` · `--branch <b>` · `--config <path>` ·
- *   `--clean` · `--full` · `--no-jev` · `--fail-on-blocking`.
+ *   `--clean` · `--full` · `--no-jev` · `--no-ast` · `--fail-on-blocking`.
  */
 
 import { loadConfig } from "../core/config-loader";
 import { HoundsmanEngine } from "../core/engine/houndsman-engine";
+import { logger } from "../core/logging";
 import { ArgParser } from "./arg-parser";
 import type { CliContext } from "./commands/command";
 import { ContextCommand } from "./commands/context-command";
 import { DoctorCommand } from "./commands/doctor-command";
 import { FindingsCommand } from "./commands/findings-command";
 import { HelpCommand } from "./commands/help-command";
+import { HuntCommand } from "./commands/hunt-command";
 import { CommandRegistry } from "./commands/registry";
 import { ReviewCommand } from "./commands/review-command";
 import { ServerCommand } from "./commands/server-command";
@@ -53,6 +55,7 @@ function buildRegistry(): CommandRegistry {
 	return new CommandRegistry()
 		.register(new ReviewCommand(), { fallback: true })
 		.register(new HelpCommand())
+		.register(new HuntCommand())
 		.register(new ContextCommand())
 		.register(new FindingsCommand())
 		.register(new StatusCommand())
@@ -77,15 +80,16 @@ export async function main(): Promise<void> {
 	const command = registry.resolve(commandName);
 
 	if (!command) {
-		console.error(`Subcomando desconhecido: '${commandName}'.\n`);
-		console.error(HELP);
+		logger.error(`Subcomando desconhecido: '${commandName}'.\n`);
+		logger.info(HELP);
 		process.exit(1);
 	}
 
 	const context: CliContext = {
 		cwd: process.cwd(),
-		out: (message) => console.log(message),
-		err: (message) => console.error(message),
+		logger,
+		out: (message) => logger.info(message),
+		err: (message) => logger.error(message),
 		engine: async () => {
 			const { config } = await loadConfig({
 				configPath: parser.value("--config"),
@@ -100,7 +104,7 @@ export async function main(): Promise<void> {
 
 if (import.meta.main) {
 	await main().catch((error) => {
-		console.error(error instanceof Error ? error.message : String(error));
+		logger.error(error instanceof Error ? error.message : String(error));
 		process.exit(1);
 	});
 }

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