Handoff Without the Drop: Engineering Low-Latency Human Escalation for Agent-Based Customer Support

// Composite escalation signal evaluator — TypeScript
type EscalationSignal = {
  intentStabilityScore: number;   // 0-1, lower = more drift across turns
  sentimentSlope: number;          // negative = worsening
  confidenceScore: number;         // model self-reported
  outOfScopeTrigger: boolean;
};

type EscalationReasonCode =
  | 'OUT_OF_SCOPE'
  | 'SENTIMENT_DEGRADATION'
  | 'INTENT_DRIFT'
  | 'CONFIDENCE_FLOOR'
  | 'COMPOSITE_THRESHOLD';

function evaluateEscalation(
  signal: EscalationSignal,
  config: { sentimentFloor: number; confidenceFloor: number; stabilityFloor: number }
): EscalationReasonCode | null {
  if (signal.outOfScopeTrigger) return 'OUT_OF_SCOPE';
  if (signal.sentimentSlope < config.sentimentFloor) return 'SENTIMENT_DEGRADATION';
  if (signal.intentStabilityScore < config.stabilityFloor) return 'INTENT_DRIFT';
  if (signal.confidenceScore < config.confidenceFloor) return 'CONFIDENCE_FLOOR';

  // Composite: any two signals in borderline range triggers escalation
  const borderlineCount = [
    signal.sentimentSlope < config.sentimentFloor * 0.6,
    signal.intentStabilityScore < config.stabilityFloor * 0.6,
    signal.confidenceScore < config.confidenceFloor * 0.6,
  ].filter(Boolean).length;

  return borderlineCount >= 2 ? 'COMPOSITE_THRESHOLD' : null;
}

// Handoff context packager — TypeScript
type ConversationEvent = {
  eventId: string;
  lamportClock: number;
  causalPredecessorId: string | null;
  type: 'message' | 'tool_call' | 'tool_result' | 'action';
  payload: unknown;
  wallClockMs: number;
};

type HandoffBundle = {
  conversationId: string;
  escalationReasonCode: string;
  agentHypothesis: string;        // agent's last stated goal inference
  orderedEvents: ConversationEvent[];
  expiresAtMs: number;
};

function packageHandoff(
  conversationId: string,
  events: ConversationEvent[],
  reasonCode: string,
  agentHypothesis: string,
  ttlMs = 120_000
): HandoffBundle {
  const ordered = [...events].sort((a, b) => a.lamportClock - b.lamportClock);
  return {
    conversationId,
    escalationReasonCode: reasonCode,
    agentHypothesis,
    orderedEvents: ordered,
    expiresAtMs: Date.now() + ttlMs,
  };
}

// Async threshold recalibration consumer — TypeScript (simplified)
type OutcomeEvent = {
  conversationId: string;
  reasonCode: string;
  repDisposition: 'necessary' | 'too_late' | 'unnecessary';
  timestampMs: number;
};

type ThresholdConfig = {
  confidenceFloor: number;
  sentimentFloor: number;
  stabilityFloor: number;
};

const LEARNING_RATE = 0.05;

function applyDispositionUpdate(
  current: ThresholdConfig,
  event: OutcomeEvent
): ThresholdConfig {
  const delta = event.repDisposition === 'unnecessary'
    ? -LEARNING_RATE   // thresholds too sensitive, relax them
    : event.repDisposition === 'too_late'
    ? +LEARNING_RATE   // thresholds too loose, tighten them
    : 0;               // necessary — no change

  // Only adjust the dimension that fired the escalation
  return {
    ...current,
    confidenceFloor: event.reasonCode === 'CONFIDENCE_FLOOR'
      ? clamp(current.confidenceFloor + delta, 0.3, 0.9)
      : current.confidenceFloor,
    sentimentFloor: event.reasonCode === 'SENTIMENT_DEGRADATION'
      ? clamp(current.sentimentFloor + delta, -1.0, -0.1)
      : current.sentimentFloor,
    stabilityFloor: event.reasonCode === 'INTENT_DRIFT'
      ? clamp(current.stabilityFloor + delta, 0.2, 0.8)
      : current.stabilityFloor,
  };
}

function clamp(val: number, min: number, max: number): number {
  return Math.max(min, Math.min(max, val));
}

// Rep-zone routing dispatcher — TypeScript
type RepZone = 'billing' | 'account' | 'technical' | 'general';

type QueueStatus = {
  zone: RepZone;
  depth: number;
  avgPickupMs: number;
  capacity: number;
};

type DispatchResult =
  | { assigned: true; repId: string; zone: RepZone; estimatedPickupMs: number }
  | { assigned: false; reason: 'queue_saturated' | 'no_capable_rep'; backpressureMs: number };

async function dispatchToRep(
  escalationZone: RepZone,
  queueStatuses: QueueStatus[],
  fallbackZoneOrder: RepZone[],
  saturationThreshold = 0.85
): Promise<DispatchResult> {
  const preferredStatus = queueStatuses.find(q => q.zone === escalationZone);
  const candidates = [escalationZone, ...fallbackZoneOrder]
    .map(z => queueStatuses.find(q => q.zone === z))
    .filter((q): q is QueueStatus => !!q && q.depth / q.capacity < saturationThreshold);

  if (candidates.length === 0) {
    const worstDepth = preferredStatus?.avgPickupMs ?? 30_000;
    return { assigned: false, reason: 'queue_saturated', backpressureMs: worstDepth };
  }

  // pick lowest depth in priority order
  const target = candidates.sort((a, b) => a.depth - b.depth)[0];
  const repId = await assignNextAvailableRep(target.zone);
  return { assigned: true, repId, zone: target.zone, estimatedPickupMs: target.avgPickupMs };
}

declare function assignNextAvailableRep(zone: RepZone): Promise<string>;

// Escalation config as a governed artifact — TypeScript
// This is the artifact that gets code-reviewed, not just the code that reads it

type EscalationConfigRecord = {
  version: string;
  owner: string;
  rationale: string;           // why these thresholds, what data backs them
  effectiveDate: string;
  thresholds: {
    confidenceFloor: number;
    sentimentFloor: number;
    stabilityFloor: number;
    compositeMinDimensions: number;
  };
  approvedBy: string;
  reviewNotes: string;
};

// Example — this lives in your config store and is the source of truth
const currentEscalationConfig: EscalationConfigRecord = {
  version: '2026-07-25-v3',
  owner: 'sam@platform-team',
  rationale: 'Sentiment floor raised from -0.4 to -0.3 after Q2 analysis showed 18% of escalations at -0.4 resolved without rep; confidence floor held at 0.55 pending more billing-domain labeled data',
  effectiveDate: '2026-07-25',
  thresholds: {
    confidenceFloor: 0.55,
    sentimentFloor: -0.3,
    stabilityFloor: 0.45,
    compositeMinDimensions: 2,
  },
  approvedBy: 'platform-review-2026-07-24',
  reviewNotes: 'Generated initial draft with Claude Code, reviewed against 500 labeled conversations from June; composite threshold logic hand-written after LLM version produced over-escalation on billing queries',
};