identity

Documentation

Index

• func AgentIDToName(agentID string) string
• func ExtractDisplayName(agentID string) string
• func GenerateAgentID(repoID, role, module, name string) string
• func GenerateDaemonID() string
• func GenerateEventID() string
• func GenerateGroupID() string
• func GenerateMessageID() string
• func GenerateRepoID(originURL string) (string, error)
• func GenerateSessionID() string
• func GenerateSessionToken() string
• func GenerateThreadID() string
• func GenerateUserID(username string) string
• func IsLegacyDaemonID(id, hostname string) bool
• func ParseAgentID(agentID string) (role, hash string)
• func ParseULID(s string) (time.Time, error)
• func SanitizeAgentName(s string) string
• func ULIDTimestamp(s string) (time.Time, error)
• func ValidateAgentName(name string) error
• type Identity
  • func Bootstrap(thrumDir, repoPath string) (Identity, error)

Functions

func AgentIDToName

func AgentIDToName(agentID string) string

AgentIDToName converts an agent ID to a filename-safe name. Handles backward compatibility by converting legacy format to current unnamed format:

• Legacy "agent:coordinator:1B9K33T6RK" -> "coordinator_1B9K33T6RK"
• Unnamed "coordinator_1B9K33T6RK" -> "coordinator_1B9K33T6RK"
• Named "furiosa" -> "furiosa"

func ExtractDisplayName

func ExtractDisplayName(agentID string) string

ExtractDisplayName extracts a display name from an agent ID for UI presentation. Returns the name prefixed with @ for mention-style display:

• Legacy "agent:coordinator:1B9K33T6RK" -> "@coordinator"
• Unnamed "implementer_35HV62T9B9" -> "@implementer"
• Named "furiosa" -> "@furiosa"

func GenerateAgentID

func GenerateAgentID(repoID, role, module, name string) string

GenerateAgentID generates an agent ID. If name is provided, uses it directly (e.g., "furiosa"). Otherwise, generates a deterministic ID: role + "_" + base32(sha256(repo_id + "|" + role + "|" + module))[:10].

func GenerateDaemonID

func GenerateDaemonID() string

GenerateDaemonID generates a new random ULID-based daemon id. Format: "d_" + ulid(). Daemon ids are per-repo, generated once at thrum init and persisted in config.json. Old hostname-derived ids are migrated on daemon startup by checking IsLegacyDaemonID.

func GenerateEventID

func GenerateEventID() string

GenerateEventID generates a unique event ID using ULID. Format: "evt_" + ulid() Used for event deduplication in JSONL merge operations.

func GenerateGroupID

func GenerateGroupID() string

GenerateGroupID generates a unique group ID using ULID. Format: "grp_" + ulid().

func GenerateMessageID

func GenerateMessageID() string

GenerateMessageID generates a unique message ID using ULID. Format: "msg_" + ulid().

func GenerateRepoID

func GenerateRepoID(originURL string) (string, error)

GenerateRepoID generates a deterministic repository ID from a Git origin URL. Format: "r_" + base32(sha256(normalized_origin_url))[:12].

func GenerateSessionID

func GenerateSessionID() string

GenerateSessionID generates a unique session ID using ULID. Format: "ses_" + ulid().

func GenerateSessionToken

func GenerateSessionToken() string

GenerateSessionToken generates a unique session token using ULID. Format: "tok_" + ulid() Used for WebSocket reconnection.

func GenerateThreadID

func GenerateThreadID() string

GenerateThreadID generates a unique thread ID using ULID. Format: "thr_" + ulid().

func GenerateUserID

func GenerateUserID(username string) string

GenerateUserID generates a user ID from a username. Format: "user:" + username No hashing - usernames are human-readable identifiers.

func IsLegacyDaemonID

func IsLegacyDaemonID(id, hostname string) bool

IsLegacyDaemonID reports whether id was generated by the pre-2026-04-17 hostname-derivation scheme for the given hostname. Returns false for empty ids (those are "missing", not "legacy") and for any value that doesn't match the hostname-derived form.

func ParseAgentID

func ParseAgentID(agentID string) (role, hash string)

ParseAgentID parses an agent ID and extracts the role and hash components. Handles three formats for backward compatibility:

• Legacy: "agent:role:hash" -> returns (role, hash)
• Unnamed: "role_hash" -> returns (role, hash)
• Named: "name" -> returns ("", "")

To distinguish unnamed "role_hash" from named "name_with_underscores": - Hashes are base32 encoded (Crockford alphabet: uppercase letters + digits only) - Named agents can have lowercase letters.

func ParseULID

func ParseULID(s string) (time.Time, error)

ParseULID parses a ULID string and returns the timestamp.

func SanitizeAgentName

func SanitizeAgentName(s string) string

SanitizeAgentName converts a raw string (e.g., branch name) into a valid agent name component. It lowercases, replaces invalid characters with underscores, collapses consecutive underscores, and strips leading/trailing underscores and hyphens. Returns "main" for empty results.

func ULIDTimestamp

func ULIDTimestamp(s string) (time.Time, error)

ULIDTimestamp extracts the timestamp from a ULID string.

func ValidateAgentName

func ValidateAgentName(name string) error

ValidateAgentName validates an agent name according to the naming rules. Names must be safe for: file paths, @mention targets, JSONL field values, git tracking.

Rules:

• Allowed characters: lowercase letters (a-z), digits (0-9), underscores (_), hyphens (-)
• Rejected: dots, spaces, path separators, uppercase, special characters
• Reserved names: daemon, system, thrum, all, broadcast
• Cannot be empty

Returns nil if valid, error with explanation if invalid.

Types

type Identity

type Identity struct {
	DaemonID     string `json:"daemon_id"`
	RepoName     string `json:"repo_name"`
	Hostname     string `json:"hostname"`
	RepoPath     string `json:"repo_path"`
	GitOriginURL string `json:"git_origin_url"`
	InitAt       string `json:"init_at"`
}

Identity is the runtime view of the daemon's identity block.

func Bootstrap

func Bootstrap(thrumDir, repoPath string) (Identity, error)

Bootstrap loads or creates the daemon identity stored in <thrumDir>/config.json under the "identity" key. Callers:

• thrum init (explicit creation)
• daemon startup (lazy backfill for pre-identity installs)

Behavior:

• Empty daemon_id → generate ULID, set init_at, populate metadata.
• Legacy hostname-derived daemon_id → rotate to ULID, log WARN.
• Existing ULID → refresh metadata (hostname, repo_path, repo_name) in-place, do not rotate.

Config.json is always written back atomically.