@resolveio/server-lib 22.3.188 → 22.3.189

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@resolveio/server-lib",
-  "version": "22.3.188",
+  "version": "22.3.189",
   "description": "",
   "scripts": {
     "package": "./build_package.sh",

package/util/ai-run-evidence-adapters.d.ts

@@ -67,7 +67,43 @@ export interface AssistantAnswerQualityDecision {
     failedChecks: string[];
     recordedAt: string;
 }
+export type AssistantAnswerActionabilityStatus = 'ready_to_answer' | 'needs_query_repair' | 'needs_permission' | 'needs_no_data_verification' | 'needs_date_window_repair' | 'needs_query_shape_repair' | 'needs_evidence' | 'needs_confidence_review' | 'needs_next_action' | 'incorrect' | 'blocked';
+export interface AssistantAnswerActionabilityContract {
+    contractId: string;
+    status: AssistantAnswerActionabilityStatus;
+    primaryCommand: string;
+    label: string;
+    canAnswerCustomer: boolean;
+    canDraftSupportReply: boolean;
+    canSendCustomerReply: boolean;
+    requiresHumanReview: boolean;
+    canRunWithoutCodexMonitor: boolean;
+    codexFallbackRequired: boolean;
+    costRisk: 'free_or_deterministic' | 'small_model_or_qa' | 'expensive_model' | 'release_or_customer_send' | 'manual_blocked';
+    queryResultClass: AssistantAnswerQualityDecision['queryStatus'];
+    confidenceLevel: AssistantAnswerQualityDecision['confidenceLevel'];
+    decisionBasis: {
+        answerQualityStatus: AssistantAnswerQualityStatus;
+        queryStatus: AssistantAnswerQualityDecision['queryStatus'];
+        queryEvidencePresent: boolean;
+        noDataConfirmed: boolean;
+        legalQueryShape: boolean;
+        dateWindowRequired: boolean;
+        dateWindowPresent: boolean;
+        citationCount: number;
+        nextActionCount: number;
+    };
+    requiredEvidence: string[];
+    successEvidence: string[];
+    blockers: string[];
+    nextActions: string[];
+    nextCommands: string[];
+    forbiddenActions: string[];
+    evidenceRefs: string[];
+    recordedAt: string;
+}
 export declare function evaluateAssistantAnswerQuality(input?: AssistantAnswerQualityInput): AssistantAnswerQualityDecision;
+export declare function buildAssistantAnswerActionabilityContract(decision: AssistantAnswerQualityDecision, now?: Date | string): AssistantAnswerActionabilityContract;
 export declare function buildSupportAIRunFromEvidence(input: SupportAIRunAdapterInput): AIRun;
 export declare function buildAICoderAIRunFromEvidence(input: AICoderAIRunAdapterInput): AIRun;
 export declare function buildAssistantAIRunFromEvidence(input: AssistantAIRunAdapterInput): AIRun;

package/util/ai-run-evidence-adapters.js

@@ -48,6 +48,7 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.evaluateAssistantAnswerQuality = evaluateAssistantAnswerQuality;
+exports.buildAssistantAnswerActionabilityContract = buildAssistantAnswerActionabilityContract;
 exports.buildSupportAIRunFromEvidence = buildSupportAIRunFromEvidence;
 exports.buildAICoderAIRunFromEvidence = buildAICoderAIRunFromEvidence;
 exports.buildAssistantAIRunFromEvidence = buildAssistantAIRunFromEvidence;
@@ -2714,6 +2715,185 @@ function assistantAnswerQualityGate(decision, now) {
         }
     };
 }
+function assistantActionabilityStatus(decision) {
+    switch (decision.status) {
+        case 'ready':
+            return 'ready_to_answer';
+        case 'query_error':
+            return 'needs_query_repair';
+        case 'permission_error':
+            return 'needs_permission';
+        case 'no_data_unverified':
+            return 'needs_no_data_verification';
+        case 'date_incorrect':
+        case 'missing_date_window':
+            return 'needs_date_window_repair';
+        case 'illegal_query_shape':
+            return 'needs_query_shape_repair';
+        case 'missing_data_source':
+        case 'missing_query_proof':
+        case 'missing_citations':
+            return 'needs_evidence';
+        case 'low_confidence':
+            return 'needs_confidence_review';
+        case 'missing_next_action':
+            return 'needs_next_action';
+        case 'incorrect':
+            return 'incorrect';
+        default:
+            return 'blocked';
+    }
+}
+function assistantActionabilityCommand(status) {
+    switch (status) {
+        case 'ready_to_answer':
+            return 'answer_from_verified_system_data';
+        case 'needs_query_repair':
+            return 'repair_assistant_query_and_rerun';
+        case 'needs_permission':
+            return 'request_assistant_data_permission';
+        case 'needs_no_data_verification':
+            return 'verify_no_data_with_scoped_probe';
+        case 'needs_date_window_repair':
+            return 'repair_assistant_date_window_and_rerun';
+        case 'needs_query_shape_repair':
+            return 'repair_assistant_mongo_query_shape';
+        case 'needs_confidence_review':
+            return 'review_assistant_confidence_evidence';
+        case 'needs_next_action':
+            return 'add_assistant_next_action';
+        case 'incorrect':
+            return 'repair_assistant_answer_from_failed_check';
+        case 'needs_evidence':
+        case 'blocked':
+        default:
+            return 'collect_assistant_answer_evidence';
+    }
+}
+function assistantActionabilityLabel(status) {
+    switch (status) {
+        case 'ready_to_answer':
+            return 'Answer From Verified Data';
+        case 'needs_query_repair':
+            return 'Repair Query';
+        case 'needs_permission':
+            return 'Request Data Permission';
+        case 'needs_no_data_verification':
+            return 'Verify No Data';
+        case 'needs_date_window_repair':
+            return 'Repair Date Window';
+        case 'needs_query_shape_repair':
+            return 'Repair Query Shape';
+        case 'needs_confidence_review':
+            return 'Review Confidence';
+        case 'needs_next_action':
+            return 'Add Next Action';
+        case 'incorrect':
+            return 'Repair Incorrect Answer';
+        default:
+            return 'Collect Answer Evidence';
+    }
+}
+function buildAssistantAnswerActionabilityContract(decision, now) {
+    var status = assistantActionabilityStatus(decision);
+    var primaryCommand = assistantActionabilityCommand(status);
+    var ready = status === 'ready_to_answer';
+    var noDataReady = ready && decision.queryStatus === 'no_data' && decision.noDataConfirmed;
+    var canAnswerCustomer = ready && (decision.queryStatus === 'ok'
+        || noDataReady
+        || decision.queryEvidenceRequired === false);
+    var canDraftSupportReply = canAnswerCustomer && decision.confidenceLevel === 'high';
+    var requiresHumanReview = !canAnswerCustomer || canDraftSupportReply;
+    var cheapRepair = /needs_(?:no_data|date_window|query_shape|next_action)|needs_evidence/.test(status);
+    var blockers = decision.blockers.length
+        ? decision.blockers
+        : (ready ? [] : [decision.reason]);
+    var requiredEvidence = Array.from(new Set(__spreadArray(__spreadArray(__spreadArray(__spreadArray(__spreadArray(__spreadArray(__spreadArray([], __read((decision.queryEvidenceRequired ? ['structured query/tool execution proof'] : [])), false), __read((decision.dateWindowRequired ? ['concrete date-window start and end'] : [])), false), __read((decision.queryStatus === 'no_data' ? ['noDataConfirmed=true from scoped probe or query evidence'] : [])), false), __read((decision.legalQueryShape ? [] : ['legal Mongo query/projection shape'])), false), __read((decision.citationRefs.length || decision.evidenceRefs.length ? [] : ['citationRefs or evidenceRefs'])), false), __read((decision.nextActions.length ? [] : ['one explicit next action or no-action state'])), false), __read((decision.confidenceLevel === 'low' || decision.confidenceLevel === 'unknown' ? ['medium/high confidence evidence'] : [])), false))).slice(0, 20);
+    return {
+        contractId: "assistant-actionability:".concat(decision.status, ":").concat(decision.queryStatus, ":").concat(decision.recordedAt),
+        status: status,
+        primaryCommand: primaryCommand,
+        label: assistantActionabilityLabel(status),
+        canAnswerCustomer: canAnswerCustomer,
+        canDraftSupportReply: canDraftSupportReply,
+        canSendCustomerReply: false,
+        requiresHumanReview: requiresHumanReview,
+        canRunWithoutCodexMonitor: ready || cheapRepair,
+        codexFallbackRequired: !ready && !cheapRepair,
+        costRisk: ready
+            ? 'free_or_deterministic'
+            : status === 'needs_permission'
+                ? 'manual_blocked'
+                : (status === 'needs_query_repair' || status === 'incorrect' ? 'small_model_or_qa' : 'free_or_deterministic'),
+        queryResultClass: decision.queryStatus,
+        confidenceLevel: decision.confidenceLevel,
+        decisionBasis: {
+            answerQualityStatus: decision.status,
+            queryStatus: decision.queryStatus,
+            queryEvidencePresent: decision.queryEvidencePresent,
+            noDataConfirmed: decision.noDataConfirmed,
+            legalQueryShape: decision.legalQueryShape,
+            dateWindowRequired: decision.dateWindowRequired,
+            dateWindowPresent: decision.dateWindowPresent,
+            citationCount: decision.citationRefs.length + decision.evidenceRefs.length,
+            nextActionCount: decision.nextActions.length
+        },
+        requiredEvidence: requiredEvidence,
+        successEvidence: Array.from(new Set(__spreadArray(__spreadArray(__spreadArray(__spreadArray([], __read((ready ? ['assistant answer quality gate passed'] : [])), false), __read((decision.queryEvidenceRefs.length ? decision.queryEvidenceRefs : [])), false), __read((decision.citationRefs.length ? decision.citationRefs : [])), false), __read((decision.evidenceRefs.length ? decision.evidenceRefs : [])), false))).slice(0, 20),
+        blockers: blockers,
+        nextActions: decision.nextActions,
+        nextCommands: Array.from(new Set(__spreadArray(__spreadArray(__spreadArray(__spreadArray(__spreadArray(__spreadArray([
+            primaryCommand
+        ], __read((status === 'needs_query_repair' ? ['fix_query_error', 'rerun_assistant_query'] : [])), false), __read((status === 'needs_no_data_verification' ? ['run_tiny_shape_probe', 'record_no_data_confirmed'] : [])), false), __read((status === 'needs_date_window_repair' ? ['resolve_current_date', 'record_concrete_date_window', 'rerun_assistant_query'] : [])), false), __read((status === 'needs_query_shape_repair' ? ['rewrite_illegal_projection', 'rerun_query_shape_validator'] : [])), false), __read((status === 'needs_permission' ? ['request_permission_or_choose_allowed_route'] : [])), false), [
+            'record_assistant_actionability_result'
+        ], false))).slice(0, 20),
+        forbiddenActions: Array.from(new Set(__spreadArray(__spreadArray(__spreadArray(__spreadArray([
+            'Do not answer from keyword or route guesses without verified query evidence.',
+            'Do not claim no data when queryStatus is query_error or permission_error.'
+        ], __read((decision.queryStatus === 'no_data' && !decision.noDataConfirmed ? ['Do not present no-data answer until noDataConfirmed=true.'] : [])), false), __read((decision.legalQueryShape ? [] : ['Do not answer from illegal Mongo projection/query shape.'])), false), __read((decision.dateWindowRequired && !decision.dateWindowPresent ? ['Do not answer dated questions without concrete start/end date evidence.'] : [])), false), __read((decision.confidenceLevel === 'low' || decision.confidenceLevel === 'unknown' ? ['Do not draft support/customer reply from low or unknown confidence.'] : [])), false))).slice(0, 20),
+        evidenceRefs: Array.from(new Set(__spreadArray(__spreadArray(__spreadArray([], __read(decision.queryEvidenceRefs), false), __read(decision.citationRefs), false), __read(decision.evidenceRefs), false))).slice(0, 40),
+        recordedAt: isoNow(now || decision.recordedAt)
+    };
+}
+function assistantAnswerActionabilityGate(contract, now) {
+    var status = contract.status === 'ready_to_answer'
+        ? 'pass'
+        : contract.status === 'incorrect' || contract.status === 'needs_query_shape_repair' || contract.status === 'needs_date_window_repair'
+            ? 'fail'
+            : 'blocked';
+    return {
+        key: 'assistant_answer_actionability',
+        label: 'Assistant answer actionability',
+        status: status,
+        reason: status === 'pass'
+            ? 'Assistant answer can proceed from verified structured evidence.'
+            : (contract.blockers.join(' ') || 'Assistant answer is blocked until actionability evidence is complete.'),
+        evidenceRefs: contract.evidenceRefs,
+        recordedAt: isoNow(now || contract.recordedAt),
+        metadata: {
+            contractId: contract.contractId,
+            status: contract.status,
+            primaryCommand: contract.primaryCommand,
+            label: contract.label,
+            canAnswerCustomer: contract.canAnswerCustomer,
+            canDraftSupportReply: contract.canDraftSupportReply,
+            canSendCustomerReply: contract.canSendCustomerReply,
+            requiresHumanReview: contract.requiresHumanReview,
+            canRunWithoutCodexMonitor: contract.canRunWithoutCodexMonitor,
+            codexFallbackRequired: contract.codexFallbackRequired,
+            costRisk: contract.costRisk,
+            queryResultClass: contract.queryResultClass,
+            confidenceLevel: contract.confidenceLevel,
+            decisionBasis: contract.decisionBasis,
+            requiredEvidence: contract.requiredEvidence,
+            successEvidence: contract.successEvidence,
+            blockers: contract.blockers,
+            nextActions: contract.nextActions,
+            nextCommands: contract.nextCommands,
+            forbiddenActions: contract.forbiddenActions
+        }
+    };
+}
 function applyAssistantAnswerQualityGate(qa, decision, now) {
     var gate = assistantAnswerQualityGate(decision, now);
     if (decision.ready) {
@@ -3418,6 +3598,16 @@ function buildAssistantAIRunFromEvidence(input) {
         recordedAt: answerQualityGate.recordedAt,
         metadata: answerQualityGate.metadata
     });
+    var answerActionabilityContract = buildAssistantAnswerActionabilityContract(answerQualityDecision, input.now);
+    var answerActionabilityGate = assistantAnswerActionabilityGate(answerActionabilityContract, input.now);
+    pushEvent(events, {
+        type: 'assistant_message',
+        category: 'assistant_answer_actionability',
+        message: answerActionabilityGate.reason,
+        artifactPaths: answerActionabilityGate.evidenceRefs,
+        recordedAt: answerActionabilityGate.recordedAt,
+        metadata: answerActionabilityGate.metadata
+    });
     var correctnessChecks = asArray(input.correctnessChecks);
     var hasPassedCorrectnessCheck = correctnessChecks.some(function (check) { return /^(pass|passed|success|ok)$/i.test(cleanText(check.status || (check.passed === true ? 'pass' : ''), 80)); });
     var correctnessEvidence = {
@@ -3461,6 +3651,7 @@ function buildAssistantAIRunFromEvidence(input) {
         startedAt: dateValue(conversation, ['startedAt', 'createdAt']),
         completedAt: dateValue(conversation, ['completedAt', 'closedAt', 'updatedAt']),
         events: events,
+        gates: [answerActionabilityGate],
         qa: qa,
         cost: cost,
         rejected: failedReports.length > 0 || conversation.rejected === true,
@@ -3491,6 +3682,28 @@ function buildAssistantAIRunFromEvidence(input) {
                 queryExecutionCount: answerQualityDecision.queryExecutionCount,
                 nextActions: answerQualityDecision.nextActions,
                 blockers: answerQualityDecision.blockers
+            },
+            answerActionability: {
+                contractId: answerActionabilityContract.contractId,
+                status: answerActionabilityContract.status,
+                primaryCommand: answerActionabilityContract.primaryCommand,
+                label: answerActionabilityContract.label,
+                canAnswerCustomer: answerActionabilityContract.canAnswerCustomer,
+                canDraftSupportReply: answerActionabilityContract.canDraftSupportReply,
+                canSendCustomerReply: answerActionabilityContract.canSendCustomerReply,
+                requiresHumanReview: answerActionabilityContract.requiresHumanReview,
+                canRunWithoutCodexMonitor: answerActionabilityContract.canRunWithoutCodexMonitor,
+                codexFallbackRequired: answerActionabilityContract.codexFallbackRequired,
+                costRisk: answerActionabilityContract.costRisk,
+                queryResultClass: answerActionabilityContract.queryResultClass,
+                confidenceLevel: answerActionabilityContract.confidenceLevel,
+                decisionBasis: answerActionabilityContract.decisionBasis,
+                requiredEvidence: answerActionabilityContract.requiredEvidence,
+                successEvidence: answerActionabilityContract.successEvidence,
+                blockers: answerActionabilityContract.blockers,
+                nextActions: answerActionabilityContract.nextActions,
+                nextCommands: answerActionabilityContract.nextCommands,
+                forbiddenActions: answerActionabilityContract.forbiddenActions
             }
         }
     });