1  import { randomBytes, type UUID } from 'crypto'
 2  import type { AgentId } from 'src/types/ids.js'
 3  
 4  const uuidRegex =
 5    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 6  
 7  /**
 8   * Validate uuid
 9   * @param maybeUUID The value to be checked if it is a uuid
10   * @returns string as UUID or null if it is not valid
11   */
12  export function validateUuid(maybeUuid: unknown): UUID | null {
13    // UUID format: 8-4-4-4-12 hex digits
14    if (typeof maybeUuid !== 'string') return null
15  
16    return uuidRegex.test(maybeUuid) ? (maybeUuid as UUID) : null
17  }
18  
19  /**
20   * Generate a new agent ID with prefix for consistency with task IDs.
21   * Format: a{label-}{16 hex chars}
22   * Example: aa3f2c1b4d5e6f7a8, acompact-a3f2c1b4d5e6f7a8
23   */
24  export function createAgentId(label?: string): AgentId {
25    const suffix = randomBytes(8).toString('hex')
26    return (label ? `a${label}-${suffix}` : `a${suffix}`) as AgentId
27  }