import type { AgentRequest } from "@agent/types"; import type { ClassifiedIntent, DerivedState, Intent, } from "../state/onboarding-state.js"; import type { Blackboard } from "../types.js"; export type AbstentionAction = | { kind: "proceed" } | { kind: "clarify"; templateKey: string } | { kind: "no-response" }; export interface AbstentionDecision { action: AbstentionAction; reason: | "low-confidence-early-turn" | "low-confidence-repeated" | "off-topic-strong" | "flagged-confused" | null; score: number; features: { classifyConfidence: number; intentKind: Intent["kind"]; turnIndex: number; sameIntentStreak: number; flaggedIssues: number; }; } function clampRatio(value: number): number { return Math.max(0, Math.min(1, value)); } function roundRatio(value: number): number { return Number(clampRatio(value).toFixed(3)); } function getExplicitTurnIndex(request: AgentRequest): number | null { const value = request.context?.["turnIndex"]; return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : null; } function inferTurnIndex(request: AgentRequest, blackboard: Blackboard | null): number { const explicit = getExplicitTurnIndex(request); if (explicit !== null) { return explicit; } if (!blackboard?.lastIntent) { return 0; } return blackboard.toneMemory.greetedAt ? 2 : 1; } function getSameIntentStreak( intentKind: Intent["kind"], blackboard: Blackboard | null, ): number { if (!blackboard || blackboard.lastIntent !== intentKind) { return 1; } return Math.max(2, (blackboard.sameIntentStreak ?? 1) + 1); } function computeScore(input: { confidence: number; flaggedIssues: number; intentKind: Intent["kind"]; sameIntentStreak: number; turnIndex: number; }): number { const lowConfidence = 1 - input.confidence; const offTopicBoost = input.intentKind === "off-topic-to-other" ? 0.25 : 0; const flaggedBoost = input.flaggedIssues > 0 ? 0.2 : 0; const repeatedBoost = input.sameIntentStreak >= 3 ? 0.15 : 0; const earlyBoost = input.turnIndex <= 1 ? 0.05 : 0; return roundRatio( lowConfidence + offTopicBoost + flaggedBoost + repeatedBoost + earlyBoost, ); } function makeDecision( features: AbstentionDecision["features"], action: AbstentionAction, reason: AbstentionDecision["reason"], ): AbstentionDecision { return { action, reason, score: computeScore({ confidence: features.classifyConfidence, flaggedIssues: features.flaggedIssues, intentKind: features.intentKind, sameIntentStreak: features.sameIntentStreak, turnIndex: features.turnIndex, }), features, }; } export function decideEarlyAbstention(input: { classified: ClassifiedIntent; derived: DerivedState; blackboard: Blackboard | null; request: AgentRequest; thresholds: { abstain: number; clarify: number; }; }): AbstentionDecision { const confidence = clampRatio(input.classified.confidence); const intentKind = input.classified.intent.kind; const features = { classifyConfidence: confidence, intentKind, turnIndex: inferTurnIndex(input.request, input.blackboard), sameIntentStreak: getSameIntentStreak(intentKind, input.blackboard), flaggedIssues: input.blackboard?.flaggedIssues.length ?? 0, }; if (intentKind === "off-topic-to-other" && confidence > 0.9) { return makeDecision(features, { kind: "no-response" }, "off-topic-strong"); } if ( (features.flaggedIssues > 0 || features.sameIntentStreak >= 3) && confidence < input.thresholds.abstain ) { return makeDecision( features, { kind: "no-response" }, features.flaggedIssues > 0 ? "flagged-confused" : "low-confidence-repeated", ); } if ( features.turnIndex <= 1 && confidence < input.thresholds.clarify && (intentKind === "unknown" || intentKind === "chitchat") ) { return makeDecision( features, { kind: "clarify", templateKey: "abstain-clarify-default" }, "low-confidence-early-turn", ); } return makeDecision(features, { kind: "proceed" }, null); }