1  /**
 2   * Branded types for session and agent IDs.
 3   * These prevent accidentally mixing up session IDs and agent IDs at compile time.
 4   */
 5  
 6  /**
 7   * A session ID uniquely identifies a Claude Code session.
 8   * Returned by getSessionId().
 9   */
10  export type SessionId = string & { readonly __brand: 'SessionId' }
11  
12  /**
13   * An agent ID uniquely identifies a subagent within a session.
14   * Returned by createAgentId().
15   * When present, indicates the context is a subagent (not the main session).
16   */
17  export type AgentId = string & { readonly __brand: 'AgentId' }
18  
19  /**
20   * Cast a raw string to SessionId.
21   * Use sparingly - prefer getSessionId() when possible.
22   */
23  export function asSessionId(id: string): SessionId {
24    return id as SessionId
25  }
26  
27  /**
28   * Cast a raw string to AgentId.
29   * Use sparingly - prefer createAgentId() when possible.
30   */
31  export function asAgentId(id: string): AgentId {
32    return id as AgentId
33  }
34  
35  const AGENT_ID_PATTERN = /^a(?:.+-)?[0-9a-f]{16}$/
36  
37  /**
38   * Validate and brand a string as AgentId.
39   * Matches the format produced by createAgentId(): `a` + optional `<label>-` + 16 hex chars.
40   * Returns null if the string doesn't match (e.g. teammate names, team-addressing).
41   */
42  export function toAgentId(s: string): AgentId | null {
43    return AGENT_ID_PATTERN.test(s) ? (s as AgentId) : null
44  }