compliance-auditor

/**
 * Compliance Auditor - Production Reference Agent
 *
 * Canon alignment: KB 22 (HumanOS) - Provenance, Policy
 * Demonstrates: ctx.provenance.query(), ctx.provenance.trace()
 *
 * Real use case: Check actions against compliance rules via provenance.
 */

import { handler, withProvenanceContext } from '@human/agent-sdk';
import type { ExecutionContext } from '@human/agent-sdk';

export const AGENT_ID = 'compliance-auditor';
export const VERSION = '1.0.0';
export const CAPABILITIES = ['compliance/audit'];

export interface ComplianceAuditorInput {
  execution_id?: string;
  action_prefix?: string;
  time_range_hours?: number;
}

export interface ComplianceAuditorOutput {
  success: boolean;
  events_reviewed: number;
  violations: Array<{ action: string; severity: string }>;
  provenance_id: string;
}

const execute = async (
  ctx: ExecutionContext,
  input: ComplianceAuditorInput
): Promise<ComplianceAuditorOutput> => {
  ctx.log.info('Running compliance audit');

  const executionId = input.execution_id ?? ctx.executionId;
  const hours = input.time_range_hours ?? 24;
  const end = Date.now();
  const start = end - hours * 60 * 60 * 1000;

  // Query provenance (ctx.provenance.query)
  const events = await ctx.provenance.query({
    executionId,
    actionPrefix: input.action_prefix,
    timeRange: { start, end },
    limit: 500,
  });

  // Trace full execution (ctx.provenance.trace)
  const trace = await ctx.provenance.trace(executionId);

  // Check compliance rules against provenance trace
  const violations: ComplianceAuditorOutput['violations'] = [];

  // Rule 1: Sensitive actions must have provenance (P7 Verifiability)
  const sensitiveActions = ['secrets.get', 'db.delete', 'files.delete'];
  for (const e of trace) {
    const eventType = e.type ?? (e as any).action;
    const isSensitive = sensitiveActions.some((a) => eventType?.includes(a));
    if (isSensitive && !e.id) {
      violations.push({
        action: eventType ?? 'unknown',
        severity: 'high',
      });
    }
  }

  // Rule 2: High-cost operations must be within budget
  for (const e of trace) {
    const costUsd = e.cost?.currency === 'USD' ? e.cost.amount : 0;
    if (e.cost && costUsd > 10.0) {
      violations.push({
        action: e.type ?? (e as any).action ?? 'unknown',
        severity: 'medium',
      });
    }
  }

  // Rule 3: Errors without escalation (Fourth Law - AI must escalate on failure)
  const errorEvents = trace.filter((e) => (e.metadata?.error ?? (e as any).error));
  const escalationEvents = trace.filter((e) => {
    const t = e.type ?? (e as any).action ?? '';
    return t.includes('escalat') || t.includes('human');
  });
  if (errorEvents.length > 0 && escalationEvents.length === 0) {
    violations.push({
      action: 'missing_escalation',
      severity: 'high',
    });
  }

  const provenanceId = await ctx.provenance.log(
    withProvenanceContext(ctx, {
      type: 'compliance:audit_complete',
      timestamp: Date.now(),
      status: 'success',
      metadata: {
        input: { execution_id: executionId },
        output: { events_reviewed: events.length, violations: violations.length },
      },
    })
  );

  return {
    success: violations.length === 0,
    events_reviewed: events.length,
    violations,
    provenance_id: provenanceId,
  };
};

export default handler({
  name: AGENT_ID,
  id: AGENT_ID,
  version: VERSION,
  capabilities: CAPABILITIES,
  manifest: {
    operations: [
      {
        name: 'audit',
        description: 'Check actions against compliance rules via provenance query and trace',
        paramsSchema: {
          execution_id: { type: 'string', description: 'Execution to audit (default: current)' },
          action_prefix: { type: 'string', description: 'Filter events by action prefix' },
          time_range_hours: { type: 'number', description: 'Time range in hours (default: 24)' },
        },
        resultKind: 'agent.compliance-auditor.result',
      },
    ],
  },
  execute,
});