instar 0.23.12 → 0.23.13

package/dist/core/ResponseReviewGate.d.ts

@@ -0,0 +1,182 @@
+/**
+ * ResponseReviewGate — Main orchestrator for the response review pipeline.
+ *
+ * Evaluates agent responses before they reach users. Architecture:
+ *   1. Policy Enforcement Layer (PEL) — deterministic hard blocks
+ *   2. Gate Reviewer — fast LLM triage (does this need full review?)
+ *   3. Specialist Reviewers — parallel LLM calls checking specific dimensions
+ *
+ * Implements the 15-row normative decision matrix from the Coherence Gate spec.
+ * Handles retry tracking, conversation advancement detection, feedback composition,
+ * per-channel fail behavior, and reviewer criticality tiers.
+ *
+ * NOTE: The existing CoherenceGate.ts is a pre-action verification system
+ * (checks before deployment/git push). This is a response review pipeline —
+ * completely different purpose, same "Coherence Gate" branding.
+ */
+import { type GateResult } from './reviewers/gate-reviewer.js';
+import type { ResponseReviewConfig } from './types.js';
+export interface EvaluateRequest {
+    message: string;
+    sessionId: string;
+    stopHookActive: boolean;
+    context: {
+        channel: string;
+        topicId?: number;
+        recipientType?: 'primary-user' | 'secondary-user' | 'agent' | 'external-contact';
+        recipientId?: string;
+        isExternalFacing?: boolean;
+        transcriptPath?: string;
+    };
+}
+export interface EvaluateResponse {
+    pass: boolean;
+    feedback?: string;
+    issueCategories?: string[];
+    warnings?: string[];
+    retryCount?: number;
+    /** Internal: full violations for audit log (not sent to agent) */
+    _auditViolations?: AuditViolation[];
+    /** Internal: whether this was a PEL block */
+    _pelBlock?: boolean;
+    /** Internal: gate result */
+    _gateResult?: GateResult;
+    /** Internal: outcome for decision matrix tracking */
+    _outcome?: string;
+}
+export interface AuditViolation {
+    reviewer: string;
+    severity: 'block' | 'warn';
+    issue: string;
+    suggestion: string;
+    latencyMs: number;
+}
+export interface ResponseReviewGateOptions {
+    config: ResponseReviewConfig;
+    stateDir: string;
+    apiKey: string;
+    relationships?: {
+        getContextForPerson(id: string): string | null;
+    } | null;
+    adaptiveTrust?: {
+        getProfile(): any;
+    } | null;
+}
+export declare class ResponseReviewGate {
+    private config;
+    private stateDir;
+    private pel;
+    private gateReviewer;
+    private reviewers;
+    private recipientResolver;
+    private retrySessions;
+    private sessionMutexes;
+    private valueDocCache;
+    private reviewHistory;
+    private proposals;
+    private static RETENTION_DAYS;
+    constructor(options: ResponseReviewGateOptions);
+    /**
+     * Evaluate an agent's draft response. Main entry point.
+     * Implements the 15-row normative decision matrix.
+     */
+    evaluate(request: EvaluateRequest): Promise<EvaluateResponse>;
+    private _evaluate;
+    private initializeReviewers;
+    private loadCustomReviewers;
+    private getEnabledReviewers;
+    private getReviewerMode;
+    private resolveChannelConfig;
+    private isExternalChannel;
+    private composeFeedback;
+    private composePELFeedback;
+    private getIssueCategories;
+    private extractToolContext;
+    private extractUrls;
+    private loadValueDocs;
+    /**
+     * Deterministic value document summarization.
+     * Extracts headers, bullets, and bold text — not LLM summarization.
+     * Target: ~200-400 tokens for all three tiers combined.
+     */
+    private extractValueSection;
+    private getTranscriptVersion;
+    private acquireMutex;
+    private releaseMutex;
+    private logAudit;
+    getReviewHistory(options?: {
+        sessionId?: string;
+        reviewer?: string;
+        verdict?: string;
+        since?: string;
+        recipientId?: string;
+        limit?: number;
+    }): AuditLogEntry[];
+    /**
+     * Delete review history for a specific session (DSAR compliance).
+     */
+    deleteHistory(sessionId: string): number;
+    getReviewerStats(options?: {
+        period?: 'daily' | 'weekly' | 'all';
+        since?: string;
+    }): Record<string, any>;
+    /** Check if the gate is enabled and ready */
+    isEnabled(): boolean;
+    /**
+     * Run canary tests with known-bad messages. Returns results showing
+     * which canary messages were caught and which were missed.
+     */
+    runCanaryTests(): Promise<CanaryTestResult[]>;
+    /**
+     * Get reviewer health — per-reviewer pass rate relative to baseline expectations.
+     */
+    getReviewerHealth(): ReviewerHealthReport;
+    private lastCanaryResults;
+    /** Store canary results for health reporting */
+    setCanaryResults(results: CanaryTestResult[]): void;
+    getProposals(status?: 'pending' | 'approved' | 'rejected'): ReviewProposal[];
+    addProposal(proposal: Omit<ReviewProposal, 'id' | 'status' | 'createdAt'>): ReviewProposal;
+    resolveProposal(id: string, action: 'approve' | 'reject', resolution?: string): ReviewProposal | null;
+    getHealthDashboard(): Record<string, any>;
+}
+interface AuditLogEntry {
+    timestamp: string;
+    sessionId: string;
+    channel: string;
+    recipientType: string;
+    recipientId?: string;
+    verdict: string;
+    violations: AuditViolation[];
+    note: string;
+}
+export interface ReviewProposal {
+    id: string;
+    type: 'new-reviewer' | 'modify-reviewer' | 'config-change';
+    title: string;
+    description: string;
+    source: string;
+    status: 'pending' | 'approved' | 'rejected';
+    createdAt: string;
+    resolvedAt?: string;
+    resolution?: string;
+    data?: Record<string, unknown>;
+}
+export interface CanaryTestResult {
+    canaryId: string;
+    description: string;
+    expectedDimension: string;
+    caught: boolean;
+    verdict: string;
+    pass: boolean;
+}
+export interface ReviewerHealthReport {
+    overallStatus: 'healthy' | 'degraded' | 'failing';
+    reviewers: Record<string, {
+        passRate: number;
+        total: number;
+        status: 'healthy' | 'degraded' | 'failing';
+    }>;
+    lastCanaryRun: CanaryTestResult[] | null;
+}
+export {};
+//# sourceMappingURL=ResponseReviewGate.d.ts.map

package/dist/core/ResponseReviewGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResponseReviewGate.d.ts","sourceRoot":"","sources":["../../src/core/ResponseReviewGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAW7E,OAAO,KAAK,EAAE,oBAAoB,EAAuB,MAAM,YAAY,CAAC;AAI5E,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,aAAa,CAAC,EAAE,cAAc,GAAG,gBAAgB,GAAG,OAAO,GAAG,kBAAkB,CAAC;QACjF,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,cAAc,EAAE,CAAC;IACpC,6CAA6C;IAC7C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4BAA4B;IAC5B,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AASD,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE;QAAE,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC1E,aAAa,CAAC,EAAE;QAAE,UAAU,IAAI,GAAG,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9C;AA+BD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,GAAG,CAAyB;IACpC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,SAAS,CAA6C;IAC9D,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,aAAa,CAA6C;IAClE,OAAO,CAAC,cAAc,CAAyC;IAC/D,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,SAAS,CAAwB;IACzC,OAAO,CAAC,MAAM,CAAC,cAAc,CAAM;gBAEvB,OAAO,EAAE,yBAAyB;IA2B9C;;;OAGG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAYrD,SAAS;IAgTvB,OAAO,CAAC,mBAAmB;IA2B3B,OAAO,CAAC,mBAAmB;IAuB3B,OAAO,CAAC,mBAAmB;IAgC3B,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,oBAAoB;IAkB5B,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,eAAe;IAwCvB,OAAO,CAAC,kBAAkB;IAc1B,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,kBAAkB;IAkC1B,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,aAAa;IAqBrB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAkD3B,OAAO,CAAC,oBAAoB;YAYd,YAAY;IAW1B,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,QAAQ;IA2BhB,gBAAgB,CAAC,OAAO,CAAC,EAAE;QACzB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,aAAa,EAAE;IAgCnB;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAMxC,gBAAgB,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAkExG,6CAA6C;IAC7C,SAAS,IAAI,OAAO;IAMpB;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA6BnD;;OAEG;IACH,iBAAiB,IAAI,oBAAoB;IAmCzC,OAAO,CAAC,iBAAiB,CAAmC;IAE5D,gDAAgD;IAChD,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI;IAMnD,YAAY,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,cAAc,EAAE;IAO5E,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,QAAQ,GAAG,WAAW,CAAC,GAAG,cAAc;IAW1F,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,QAAQ,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAYrG,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CA8B1C;AAID,UAAU,aAAa;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd;AAID,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,GAAG,iBAAiB,GAAG,eAAe,CAAC;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAkED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;IAClD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;KAC5C,CAAC,CAAC;IACH,aAAa,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;CAC1C"}