@payconductor/houndsman 0.8.0 → 0.10.0

package/src/core/pr-context.ts

@@ -229,13 +229,17 @@ export function renderContextBrief(
 
 	lines.push("## Regras", "");
 	lines.push(
-		"- **Seja curto** — o resumo abre o relatório e entra em **todos** os briefs.",
+		"- O resumo abre o relatório e o resumo final; nos briefs ele é recortado.",
 	);
 	lines.push("- Baseie-se **somente** no `context.json` — não invente intenção.");
-	lines.push("- `objective`: 1 frase (≤ 200 caracteres) sobre o que a PR entrega.");
-	lines.push("- `motivation`: 1 frase (≤ 240 caracteres) sobre o porquê.");
 	lines.push(
-		"- `changeSummary`: no máximo 4 bullets (≤ 160 caracteres cada), focados em comportamento — não liste arquivos.",
+		"- `objective`: até 2 frases (≤ 400 caracteres) sobre o que a PR entrega.",
+	);
+	lines.push(
+		"- `motivation`: até 3 frases (≤ 480 caracteres) sobre o porquê e o impacto.",
+	);
+	lines.push(
+		"- `changeSummary`: no máximo 6 bullets (≤ 240 caracteres cada), focados em comportamento — não liste arquivos.",
 	);
 	lines.push(
 		"- NÃO copie a descrição da PR: sintetize. Copie `source` do contexto bruto.",
@@ -253,7 +257,8 @@ const CONTEXT_SUMMARY_TEMPLATE = {
 		base: "main",
 		head: "feature/x",
 	},
-	objective: "O que a PR entrega, em 1 frase.",
-	motivation: "Por que a mudança é necessária, em 1-2 frases.",
+	objective: "O que a PR entrega, em 1-2 frases.",
+	motivation:
+		"Por que a mudança é necessária, com o problema e o impacto (até 3 frases).",
 	changeSummary: ["Bullet de comportamento 1", "Bullet de comportamento 2"],
 };

package/src/core/project-config.ts

@@ -8,6 +8,7 @@
 
 import type {
 	AiProviderKind,
+	AiProviderOptions,
 	HoundsmanAi,
 	HoundsmanAiFeatures,
 	HoundsmanAst,
@@ -138,6 +139,12 @@ export class ProjectConfig<TId extends string = string> {
 		return typeof value === "number" && Number.isFinite(value) ? value : 0;
 	}
 
+	/** Opções do AI SDK por provider (undefined quando ausentes/vazias). */
+	get aiProviderOptions(): AiProviderOptions | undefined {
+		const value = this.ai.providerOptions;
+		return value && Object.keys(value).length > 0 ? value : undefined;
+	}
+
 	get aiTimeoutMs(): number {
 		return positive(this.ai.timeoutMs, DEFAULT_AI_TIMEOUT_MS);
 	}
@@ -152,12 +159,13 @@ export class ProjectConfig<TId extends string = string> {
 		return value !== undefined && value > 0 ? value : undefined;
 	}
 
-	/** Features resolvidas com defaults (`context`/`brief` ligadas). */
+	/** Features resolvidas com defaults (`context`/`brief`/`technical` ligadas). */
 	get aiFeatures(): Required<HoundsmanAiFeatures> {
 		const features = this.ai.features ?? {};
 		return {
 			context: features.context !== false,
 			brief: features.brief !== false,
+			technical: features.technical !== false,
 			classification: features.classification === true,
 			preAnalysis: features.preAnalysis === true,
 			verify: features.verify === true,

package/src/core/renderers/resume-renderer.ts

@@ -3,19 +3,16 @@
  *
  * Artefato somente-leitura para humanos: não entra em briefs, não é lido pelos
  * watchdogs e não participa de nenhuma etapa seguinte. Une o contexto de
- * negócio da PR aos números técnicos diretos da revisão, com limite de
+ * negócio da PR aos pontos técnicos estruturais da revisão, com limite de
  * `RESUME_MAX_CHARS`.
  */
 
-import type {
-	ContextSummary,
-	MergedFinding,
-	WatchdogNameResolver,
-} from "../report-builder";
+import type { ContextSummary, MergedFinding } from "../report-builder";
 import { systemClock } from "../services/clock";
+import type { TechnicalSummary } from "../technical-summary";
 
 /** Teto de caracteres do artefato (inclui cabeçalho e quebras de linha). */
-export const RESUME_MAX_CHARS = 2500;
+export const RESUME_MAX_CHARS = 5000;
 
 /** Dados de classificação usados no resumo. */
 export type ResumeClassification = {
@@ -30,11 +27,10 @@ export type ReviewResumeInput = {
 	context?: ContextSummary | null;
 	classification: ResumeClassification;
 	findings: readonly MergedFinding[];
-	nameOf?: WatchdogNameResolver;
+	/** Pontos técnicos estruturais (não achados). */
+	technical?: TechnicalSummary | null;
 };
 
-const identityName: WatchdogNameResolver = (id) => id;
-
 const STATUS_BY_SEVERITY: Record<"blocking" | "attention" | "clean", string> = {
 	blocking: "❌ Mudanças necessárias",
 	attention: "⚠️ Aprovado com ressalvas",
@@ -80,36 +76,24 @@ function businessSection(input: ReviewResumeInput): string[] {
 	if (context.objective) lines.push(context.objective, "");
 	if (context.motivation) lines.push(`**Por quê:** ${context.motivation}`, "");
 	if (context.changeSummary && context.changeSummary.length > 0) {
-		for (const item of context.changeSummary.slice(0, 4)) {
-			lines.push(`- ${truncate(item, 180)}`);
+		for (const item of context.changeSummary.slice(0, 6)) {
+			lines.push(`- ${truncate(item, 240)}`);
 		}
 		lines.push("");
 	}
 	return lines;
 }
 
-/** Achados que exigem ação, em formato direto (máximo 5). */
-function technicalSection(
-	findings: readonly MergedFinding[],
-	nameOf: WatchdogNameResolver,
-): string[] {
-	const relevant = findings
-		.filter(
-			(finding) =>
-				finding.severity === "blocking" || finding.severity === "attention",
-		)
-		.slice(0, 5);
+/** Pontos técnicos estruturais (módulos, contratos, impacto) — não achados. */
+function technicalSection(summary: TechnicalSummary | null | undefined): string[] {
 	const lines = ["## Pontos técnicos", ""];
-	if (relevant.length === 0) {
-		lines.push("- Nenhum bloqueio ou ponto de atenção.", "");
+	if (!summary || (!summary.overview && summary.highlights.length === 0)) {
+		lines.push("Sem mudanças estruturais detectadas nesta revisão.", "");
 		return lines;
 	}
-	for (const finding of relevant) {
-		const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
-		const watchdogs = finding.watchdogs.map((id) => nameOf(id)).join(", ");
-		lines.push(
-			`- \`${location}\` — ${truncate(finding.message, 130)}${watchdogs ? ` _(${watchdogs})_` : ""}`,
-		);
+	if (summary.overview) lines.push(summary.overview, "");
+	for (const highlight of summary.highlights) {
+		lines.push(`- **${highlight.area}** — ${truncate(highlight.detail, 300)}`);
 	}
 	lines.push("");
 	return lines;
@@ -125,10 +109,9 @@ function clamp(markdown: string, max: number): string {
 
 /**
  * Renderiza o resumo final. Determinístico e sem chamadas externas: o texto
- * nasce do contexto já disponível e dos findings consolidados.
+ * nasce do contexto já disponível e dos pontos técnicos persistidos.
  */
 export function renderReviewResume(input: ReviewResumeInput): string {
-	const nameOf = input.nameOf ?? identityName;
 	const blockers = input.findings.filter((f) => f.severity === "blocking").length;
 	const attention = input.findings.filter((f) => f.severity === "attention").length;
 	const status =
@@ -144,7 +127,7 @@ export function renderReviewResume(input: ReviewResumeInput): string {
 		`**Data:** ${input.date ?? systemClock().slice(0, 10)} · **Status:** ${status}`,
 		"",
 		...businessSection(input),
-		...technicalSection(input.findings, nameOf),
+		...technicalSection(input.technical),
 	];
 
 	return clamp(`${lines.join("\n").trimEnd()}\n`, RESUME_MAX_CHARS);

package/src/core/report-builder.ts

@@ -63,14 +63,14 @@ export type ContextSummary = {
 const VALID_SEVERITIES = new Set<string>(SEVERITY_ORDER);
 
 /**
- * Limites do resumo da PR: mantém o relatório e os briefs enxutos — evita
- * confundir o watchdog humano e estourar o contexto da IA watchdog.
+ * Limites do resumo da PR: o contexto abre o relatório e o resumo final, mas
+ * não pode inflar os briefs — a injeção nos briefs é recortada em `brief.ts`.
  */
 const CONTEXT_LIMITS = {
-	objective: 200,
-	motivation: 240,
-	changeSummaryItem: 160,
-	changeSummaryItems: 4,
+	objective: 400,
+	motivation: 480,
+	changeSummaryItem: 240,
+	changeSummaryItems: 6,
 } as const;
 
 /** Corta `value` em `max` caracteres, sinalizando com reticências. */

package/src/core/services/worktree-manager.ts

@@ -4,7 +4,12 @@
  * Um worktree por branch revisada, criado em **detached HEAD** no commit da PR.
  * Detached evita o conflito "branch já checada" com o clone principal e é o
  * modo correto para revisão (somente leitura). Vive fora do projeto, em
- * `<HOUNDSMAN_HOME>/worktrees/<repoSlug>/<branchSlug>`.
+ * `<baseDir>/<repoSlug>/<branchSlug>`.
+ *
+ * Os dois segmentos são `<trecho-legível>-<hash8>`: o trecho legível é
+ * truncado porque o checkout de uma PR herda a profundidade dos arquivos do
+ * projeto, e o Windows (MAX_PATH = 260) estoura "Filename too long" com
+ * repo+branch longos. O hash mantém o nome determinístico e único.
  */
 
 import { createHash } from "node:crypto";
@@ -64,6 +69,22 @@ export type WorktreeManagerOptions = {
 	baseDir?: string;
 };
 
+/** Limite do trecho legível no diretório do repositório. */
+const REPO_SLUG_MAX = 24;
+/** Limite do trecho legível no diretório da branch. */
+const BRANCH_SLUG_MAX = 20;
+
+/**
+ * `<trecho legível truncado>-<hash8>`: curto o bastante para o MAX_PATH do
+ * Windows e estável para o mesmo par (repositório, branch).
+ */
+function hashName(key: string, readable: string, max: number, fallback: string): string {
+	const hash = createHash("sha1").update(key).digest("hex").slice(0, 8);
+	// Ponto/traço no fim do nome é descartado pelo Windows; corte antes do hash.
+	const head = readable.slice(0, max).replace(/[-._]+$/, "");
+	return `${head || fallback}-${hash}`;
+}
+
 /** Slug estável e legível para o diretório do repositório. */
 export function repoSlug(repoKey: string): string {
 	const clean = repoKey
@@ -71,8 +92,12 @@ export function repoSlug(repoKey: string): string {
 		.replace(/[^a-zA-Z0-9._-]+/g, "-")
 		.replace(/^-+|-+$/g, "")
 		.toLowerCase();
-	const hash = createHash("sha1").update(repoKey).digest("hex").slice(0, 8);
-	return `${clean.slice(-60) || "repo"}-${hash}`;
+	return hashName(repoKey, clean.slice(-REPO_SLUG_MAX), REPO_SLUG_MAX, "repo");
+}
+
+/** Slug estável e curto para o diretório de uma branch. */
+export function branchSlug(branch: string): string {
+	return hashName(branch, sanitizeBranch(branch), BRANCH_SLUG_MAX, "branch");
 }
 
 /** Normaliza um path para comparação (Windows é case-insensitive). */
@@ -154,8 +179,7 @@ export class WorktreeManager {
 
 	/** Caminho determinístico do worktree de uma branch. */
 	pathFor(branch: string): string {
-		const slug = sanitizeBranch(branch) || "branch";
-		return join(this.rootDir, slug);
+		return join(this.rootDir, branchSlug(branch));
 	}
 
 	/** Todos os worktrees registrados no repositório. */

package/src/core/storage/types.ts

@@ -102,6 +102,7 @@ export type ArtifactKind =
 	| "finding-report"
 	| "review"
 	| "resume"
+	| "technical"
 	| "domain-review"
 	| "verify"
 	| "ast"

package/src/core/technical-summary.ts

@@ -0,0 +1,398 @@
+/**
+ * Pontos técnicos estruturais do resumo final (`technical-summary.json`).
+ *
+ * Descrevem a arquitetura da mudança (módulos, contratos, implementações,
+ * dependências e impacto) — nunca os achados da revisão. A IA apenas refina a
+ * redação; sem ela, a heurística abaixo é o resultado final.
+ */
+
+import type { AstAnalysis, AstImpact, AstSymbol, AstSymbolKind } from "./ast/types";
+import type { ClassificationResult } from "./file-classifier";
+
+/** Destaque técnico exibido como um bullet do resumo. */
+export type TechnicalHighlight = {
+	/** Rótulo curto (ex.: "Contratos", "Implementações"). */
+	area: string;
+	/** Detalhe em uma linha, com paths/símbolos. */
+	detail: string;
+};
+
+/** Pontos técnicos de uma revisão. */
+export type TechnicalSummary = {
+	/** `ai` quando o texto veio do modelo; `deterministic` no fallback. */
+	source: "ai" | "deterministic";
+	/** Commit coberto — permite saber a que revisão o resumo se refere. */
+	headSha?: string;
+	/** Parágrafo curto de abertura (opcional). */
+	overview?: string;
+	highlights: TechnicalHighlight[];
+};
+
+/** Entrada mínima para montar os destaques. */
+export type TechnicalInput = {
+	classification: Pick<ClassificationResult, "files" | "churn">;
+	ast?: ReadonlyMap<string, AstAnalysis>;
+	impact?: AstImpact;
+	headSha?: string;
+};
+
+/** Entrada do payload enviado à IA (inclui contexto de negócio e domínios). */
+export type TechnicalPromptInput = TechnicalInput & {
+	branch: string;
+	context?: {
+		objective?: string;
+		motivation?: string;
+		changeSummary?: string[];
+	} | null;
+	domains?: readonly string[];
+};
+
+const MAX_HIGHLIGHTS = 6;
+const MAX_DETAIL = 240;
+
+/** Corta o texto em `max` caracteres, sinalizando com reticências. */
+function truncate(value: string, max: number): string {
+	const text = value.trim().replace(/\s+/g, " ");
+	return text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;
+}
+
+/** Diretório do arquivo (`(raiz)` para paths sem pasta). */
+function moduleOf(path: string): string {
+	const slash = path.lastIndexOf("/");
+	return slash > 0 ? path.slice(0, slash) : "(raiz)";
+}
+
+/** `true` para pacotes externos (fora do projeto e de aliases locais). */
+function isExternal(source: string): boolean {
+	return (
+		!source.startsWith(".") &&
+		!source.startsWith("/") &&
+		!source.startsWith("#") &&
+		!source.startsWith("@/")
+	);
+}
+
+/** `true` para símbolos que representam contratos públicos. */
+function isContract(kind: AstSymbolKind): boolean {
+	return kind === "interface" || kind === "type" || kind === "enum";
+}
+
+type SymbolRef = { symbol: AstSymbol; file: string };
+
+/** Lista curta de símbolos com o arquivo de origem. */
+function symbolDetail(refs: SymbolRef[], max = 4): string {
+	const seen = new Set<string>();
+	const parts: string[] = [];
+	for (const ref of refs) {
+		const key = `${ref.file}|${ref.symbol.name}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		parts.push(`\`${ref.symbol.name}\` (${ref.file})`);
+		if (parts.length === max) break;
+	}
+	const total = new Set(refs.map((ref) => `${ref.file}|${ref.symbol.name}`)).size;
+	return `${parts.join(", ")}${total > parts.length ? ` +${total - parts.length}` : ""}`;
+}
+
+type SignatureRef = {
+	name: string;
+	before: string;
+	after: string;
+	file: string;
+};
+
+/** Assinaturas alteradas, com o `antes → depois`. */
+function signatureDetail(changes: SignatureRef[], max = 3): string {
+	return changes
+		.slice(0, max)
+		.map(
+			(change) =>
+				`\`${change.name}\` (${truncate(change.before, 60)} → ${truncate(change.after, 60)})`,
+		)
+		.join(", ");
+}
+
+type ExportRef = {
+	name: string;
+	change: "added" | "removed";
+	file: string;
+};
+
+type PromptSymbolRef = { name: string; kind: string; file: string };
+
+/** Exports adicionados/removidos, com o arquivo. */
+function exportDetail(changes: ExportRef[], max = 4): string {
+	return changes
+		.slice(0, max)
+		.map((change) => `\`${change.name}\` (${change.change}, ${change.file})`)
+		.join(", ");
+}
+
+/** Agrupa paths por diretório, do maior para o menor grupo. */
+function groupByModule(paths: string[]): [string, number][] {
+	const counts = new Map<string, number>();
+	for (const path of paths) {
+		const dir = moduleOf(path);
+		counts.set(dir, (counts.get(dir) ?? 0) + 1);
+	}
+	return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+}
+
+/**
+ * Monta os destaques determinísticos. Prioriza símbolos do AST; sem fatos
+ * estruturais, agrupa os arquivos novos por diretório. Nunca lança.
+ */
+export function buildTechnicalSummary(input: TechnicalInput): TechnicalSummary {
+	const highlights: TechnicalHighlight[] = [];
+	const files = input.classification.files;
+	const added = Object.entries(files)
+		.filter(([, file]) => file.status === "added")
+		.map(([path]) => path);
+	const deleted = Object.entries(files)
+		.filter(([, file]) => file.status === "deleted")
+		.map(([path]) => path);
+
+	const contracts: SymbolRef[] = [];
+	const implementations: SymbolRef[] = [];
+	const functions: SymbolRef[] = [];
+	const signatures: SignatureRef[] = [];
+	const exportsChanged: ExportRef[] = [];
+	const imports = new Set<string>();
+
+	if (input.ast) {
+		for (const [file, analysis] of input.ast) {
+			const delta = analysis.delta;
+			if (!delta) continue;
+			for (const symbol of delta.addedSymbols) {
+				if (isContract(symbol.kind)) contracts.push({ symbol, file });
+				else if (symbol.kind === "class") implementations.push({ symbol, file });
+				else if (symbol.kind === "function") functions.push({ symbol, file });
+			}
+			for (const change of delta.changedSignatures) {
+				if (!change.exported) continue;
+				signatures.push({
+					name: change.name,
+					before: change.before,
+					after: change.after,
+					file,
+				});
+			}
+			for (const change of delta.changedExports) {
+				exportsChanged.push({
+					name: change.name,
+					change: change.change,
+					file,
+				});
+			}
+			for (const source of delta.addedImports) {
+				if (isExternal(source)) imports.add(source);
+			}
+		}
+	}
+
+	if (contracts.length > 0) {
+		highlights.push({ area: "Contratos", detail: symbolDetail(contracts) });
+	}
+	if (implementations.length > 0) {
+		highlights.push({
+			area: "Implementações",
+			detail: symbolDetail(implementations),
+		});
+	}
+	if (functions.length > 0 && contracts.length === 0 && implementations.length === 0) {
+		highlights.push({ area: "Funções", detail: symbolDetail(functions) });
+	}
+	if (signatures.length > 0) {
+		highlights.push({
+			area: "Assinaturas alteradas",
+			detail: signatureDetail(signatures),
+		});
+	}
+	if (exportsChanged.length > 0) {
+		highlights.push({
+			area: "Exports alterados",
+			detail: exportDetail(exportsChanged),
+		});
+	}
+	if (imports.size > 0) {
+		highlights.push({
+			area: "Novas dependências",
+			detail: [...imports]
+				.slice(0, 6)
+				.map((source) => `\`${source}\``)
+				.join(", "),
+		});
+	}
+
+	// Sem fatos do AST, a estrutura visível é o conjunto de diretórios novos.
+	if (highlights.length === 0) {
+		for (const [dir, count] of groupByModule(added).slice(0, 3)) {
+			highlights.push({
+				area: "Estrutura",
+				detail: `Novo diretório \`${dir}\` com ${count} arquivo(s).`,
+			});
+		}
+	}
+
+	if (deleted.length > 0 && highlights.length < MAX_HIGHLIGHTS) {
+		highlights.push({
+			area: "Remoções",
+			detail: `${deleted
+				.slice(0, 4)
+				.map((path) => `\`${path}\``)
+				.join(", ")}${deleted.length > 4 ? ` +${deleted.length - 4}` : ""}`,
+		});
+	}
+
+	if (
+		input.impact &&
+		input.impact.affectedFiles.length > 0 &&
+		highlights.length < MAX_HIGHLIGHTS
+	) {
+		const exported = input.impact.exportedChanges.length;
+		highlights.push({
+			area: "Impacto",
+			detail:
+				`${input.impact.affectedFiles.length} arquivo(s) importam os alterados` +
+				(exported > 0 ? `; ${exported} export(s) público(s) alterado(s)` : "") +
+				".",
+		});
+	}
+
+	return {
+		source: "deterministic",
+		headSha: input.headSha,
+		highlights: highlights.slice(0, MAX_HIGHLIGHTS).map((highlight) => ({
+			area: truncate(highlight.area, 80),
+			detail: truncate(highlight.detail, MAX_DETAIL),
+		})),
+	};
+}
+
+/** Payload compacto enviado ao modelo (nunca arquivos inteiros). */
+export function buildTechnicalPromptPayload(
+	input: TechnicalPromptInput,
+): Record<string, unknown> {
+	const files = Object.entries(input.classification.files)
+		.map(([path, file]) => ({
+			path,
+			status: file.status,
+			additions: input.classification.churn[path]?.additions ?? 0,
+			deletions: input.classification.churn[path]?.deletions ?? 0,
+		}))
+		.sort(
+			(a, b) =>
+				b.additions + b.deletions - (a.additions + a.deletions) ||
+				a.path.localeCompare(b.path),
+		)
+		.slice(0, 80);
+
+	const contracts: PromptSymbolRef[] = [];
+	const implementations: PromptSymbolRef[] = [];
+	const signatures: SignatureRef[] = [];
+	const exportsChanged: ExportRef[] = [];
+	const imports = new Set<string>();
+	const deletedFiles: string[] = [];
+
+	for (const [path, file] of Object.entries(input.classification.files)) {
+		if (file.status === "deleted") deletedFiles.push(path);
+	}
+
+	if (input.ast) {
+		for (const [file, analysis] of input.ast) {
+			const delta = analysis.delta;
+			if (!delta) continue;
+			for (const symbol of delta.addedSymbols) {
+				if (isContract(symbol.kind)) {
+					contracts.push({ name: symbol.name, kind: symbol.kind, file });
+				} else if (symbol.kind === "class") {
+					implementations.push({ name: symbol.name, kind: symbol.kind, file });
+				}
+			}
+			for (const change of delta.changedSignatures) {
+				if (change.exported) {
+					signatures.push({
+						name: change.name,
+						before: change.before,
+						after: change.after,
+						file,
+					});
+				}
+			}
+			for (const change of delta.changedExports) {
+				exportsChanged.push({
+					name: change.name,
+					change: change.change,
+					file,
+				});
+			}
+			for (const source of delta.addedImports) {
+				if (isExternal(source)) imports.add(source);
+			}
+		}
+	}
+
+	return {
+		branch: input.branch,
+		headSha: input.headSha,
+		business: input.context
+			? {
+					objective: input.context.objective,
+					motivation: input.context.motivation,
+					changeSummary: input.context.changeSummary,
+				}
+			: undefined,
+		domains: input.domains ?? [],
+		files,
+		structure: {
+			contracts: contracts.slice(0, 40),
+			implementations: implementations.slice(0, 40),
+			changedSignatures: signatures.slice(0, 20),
+			changedExports: exportsChanged.slice(0, 20),
+			addedImports: [...imports].slice(0, 20),
+			deletedFiles: deletedFiles.slice(0, 20),
+		},
+		impact: input.impact
+			? {
+					affectedFiles: input.impact.affectedFiles.length,
+					importers: Object.keys(input.impact.importers).length,
+					exportedChanges: input.impact.exportedChanges.length,
+				}
+			: undefined,
+	};
+}
+
+/** Valida/normaliza o `technical-summary.json`; null quando vazio/inválido. */
+export function parseTechnicalSummary(raw: unknown): TechnicalSummary | null {
+	if (typeof raw !== "object" || raw === null) return null;
+	const obj = raw as Record<string, unknown>;
+
+	const highlights: TechnicalHighlight[] = [];
+	if (Array.isArray(obj.highlights)) {
+		for (const item of obj.highlights) {
+			if (typeof item !== "object" || item === null) continue;
+			const entry = item as Record<string, unknown>;
+			const area = typeof entry.area === "string" ? entry.area.trim() : "";
+			const detail = typeof entry.detail === "string" ? entry.detail.trim() : "";
+			if (!area || !detail) continue;
+			highlights.push({
+				area: truncate(area, 80),
+				detail: truncate(detail, MAX_DETAIL),
+			});
+			if (highlights.length === MAX_HIGHLIGHTS) break;
+		}
+	}
+
+	const overview =
+		typeof obj.overview === "string" && obj.overview.trim().length > 0
+			? truncate(obj.overview, 600)
+			: undefined;
+	if (highlights.length === 0 && !overview) return null;
+
+	return {
+		source: obj.source === "deterministic" ? "deterministic" : "ai",
+		headSha: typeof obj.headSha === "string" ? obj.headSha : undefined,
+		overview,
+		highlights,
+	};
+}

package/src/harness/agent/agent-factory.ts

@@ -37,6 +37,7 @@ export class AgentFactory {
 			reporter: this.deps.reporter,
 			maxOutputTokens: config.maxOutputTokensFor(context.watchdog.id),
 			temperature: config.temperature,
+			providerOptions: config.providerOptions,
 			timeoutMs: config.timeoutMs,
 			ast: this.deps.ast,
 			readFile: this.deps.readFile,