TealDrift

class TealDrift {
  constructor(options: DriftOptions);

  /** Evaluate current request against baseline */
  evaluate(request: DriftRequest, ctx: DriftContext): Promise<DriftResult>;

  /** Get current baseline for an agent */
  getBaseline(agentId: string): Promise<Baseline>;

  /** Reset baseline (start fresh) */
  resetBaseline(agentId: string): Promise<void>;

  /** Check MCP tool definitions for drift */
  checkDefinitionDrift(agentId: string, currentTools: ToolDefinition[]): Promise<DefinitionDriftResult>;
}

interface DriftOptions {
  /** Enable drift detection */
  enabled: boolean;

  /** Minimum samples before drift detection activates */
  min_samples: number;

  /** Baseline window size */
  baselineWindow: string;  // '7d', '30d', etc.

  /** Drift sensitivity */
  sensitivity: 'low' | 'medium' | 'high';

  /** Drift score thresholds */
  thresholds?: {
    monitor: number;    // Default: 0.3
    escalate: number;   // Default: 0.6
    deny: number;       // Default: 0.8
  };

  /** Which dimensions to track */
  dimensions?: {
    actions: boolean;       // Default: true
    tools: boolean;         // Default: true
    content: boolean;       // Default: true
    temporal: boolean;      // Default: true
    errors: boolean;        // Default: true
  };

  /** MCP definition-drift monitoring */
  mcpMonitoring?: {
    enabled: boolean;
    /** Alert on new tools added */
    alertOnNewTools: boolean;
    /** Alert on tool parameter changes */
    alertOnParamChanges: boolean;
    /** Alert on tool removal */
    alertOnRemovedTools: boolean;
  };

  /** Storage backend for baselines */
  storage?: 'memory' | 'redis' | 'dynamodb';
}

import { TealDrift } from 'tealtiger/drift';

const drift = new TealDrift({
  enabled: true,
  min_samples: 100,
  baselineWindow: '7d',
  sensitivity: 'medium',
  thresholds: { monitor: 0.3, escalate: 0.6, deny: 0.8 }
});

const result = await drift.evaluate(
  {
    action: 'database.query',
    tool: 'sql_executor',
    content: 'SELECT * FROM users WHERE role = admin',
    metadata: { query_type: 'select', table: 'users' }
  },
  {
    agentId: 'data-analyst-bot',
    correlation_id: 'req-001',
    timestamp: Date.now()
  }
);

console.log(result.driftScore);      // 0.72 (significant drift)
console.log(result.flagged);         // true
console.log(result.recommendation);  // 'escalate'
console.log(result.deviations);      // Which dimensions deviated

interface DriftResult {
  /** Overall drift score (0.0 - 1.0) */
  driftScore: number;

  /** Whether drift exceeds the monitor threshold */
  flagged: boolean;

  /** Recommended action based on thresholds */
  recommendation: 'allow' | 'monitor' | 'escalate' | 'deny';

  /** Per-dimension deviation details */
  deviations: DriftDeviation[];

  /** Baseline statistics used for comparison */
  baselineStats: BaselineStats;

  /** Whether baseline has sufficient samples */
  baselineReady: boolean;

  /** Number of samples in current baseline */
  sampleCount: number;
}

interface DriftDeviation {
  /** Which dimension deviated */
  dimension: 'actions' | 'tools' | 'content' | 'temporal' | 'errors';

  /** Deviation score for this dimension */
  score: number;

  /** Human-readable explanation */
  explanation: string;

  /** Statistical details */
  stats: {
    baseline_mean: number;
    baseline_stddev: number;
    current_value: number;
    z_score: number;
  };
}

const drift = new TealDrift({
  min_samples: 100,  // Need 100 observations before drift detection activates
  // ...
});

const result = await drift.evaluate(request, ctx);

if (!result.baselineReady) {
  console.log(`Baseline building: ${result.sampleCount}/100 samples`);
  // During this period, all requests are allowed (no drift enforcement)
  // result.recommendation === 'allow'
  // result.driftScore === 0 (not computed yet)
}

const currentTools: ToolDefinition[] = [
  { name: 'web_search', parameters: { query: 'string' } },
  { name: 'file_read', parameters: { path: 'string' } },
  { name: 'database_query', parameters: { sql: 'string', database: 'string' } },
  // New tool that wasn't in the baseline:
  { name: 'shell_execute', parameters: { command: 'string' } }
];

const driftResult = await drift.checkDefinitionDrift('agent-001', currentTools);

console.log(driftResult.drifted);  // true
console.log(driftResult.changes);
// [
//   { type: 'tool_added', tool: 'shell_execute',
//     risk: 'high', reason: 'New tool with shell execution capability' }
// ]

interface DefinitionDriftResult {
  /** Whether any definition drift was detected */
  drifted: boolean;

  /** List of changes detected */
  changes: DefinitionChange[];

  /** Overall risk assessment */
  riskLevel: 'none' | 'low' | 'medium' | 'high' | 'critical';

  /** Baseline tool count vs. current */
  toolCount: { baseline: number; current: number };
}

interface DefinitionChange {
  /** Type of change */
  type: 'tool_added' | 'tool_removed' | 'params_changed' | 'description_changed';

  /** Affected tool name */
  tool: string;

  /** Risk level of this specific change */
  risk: 'low' | 'medium' | 'high' | 'critical';

  /** Explanation of why this is flagged */
  reason: string;

  /** Previous definition (for changes/removals) */
  previous?: ToolDefinition;

  /** Current definition (for additions/changes) */
  current?: ToolDefinition;
}

// Get current baseline
const baseline = await drift.getBaseline('agent-001');
console.log(baseline.sampleCount);     // 847
console.log(baseline.windowStart);     // '2026-05-25T00:00:00Z'
console.log(baseline.windowEnd);       // '2026-06-01T00:00:00Z'
console.log(baseline.actionDistribution);
// { 'file.read': 0.45, 'web_search': 0.30, 'database.query': 0.20, 'file.write': 0.05 }

// Reset baseline (e.g., after legitimate behavior change)
await drift.resetBaseline('agent-001');
// Baseline rebuilds from scratch — min_samples guard reactivates

import { TealEngine, TealDrift } from 'tealtiger';

const engine = new TealEngine({
  policy: {
    drift: {
      enabled: true,
      min_samples: 100,
      sensitivity: 'medium',
      actions: {
        monitor: 'log',        // Log drift events
        escalate: 'approval_required',
        deny: 'auto_deny'
      }
    }
  },
  modules: [
    new TealDrift({
      enabled: true,
      min_samples: 100,
      baselineWindow: '7d',
      sensitivity: 'medium',
      mcpMonitoring: { enabled: true, alertOnNewTools: true, alertOnParamChanges: true }
    })
  ]
});