@xortex/xcode 3.0.0

package/utils/swarm/teammateInit.ts

@@ -0,0 +1,129 @@
+/**
+ * Teammate Initialization Module
+ *
+ * Handles initialization for Claude Code instances running as teammates in a swarm.
+ * Registers a Stop hook to notify the team leader when the teammate becomes idle.
+ */
+
+import type { AppState } from '../../state/AppState.js'
+import { logForDebugging } from '../debug.js'
+import { addFunctionHook } from '../hooks/sessionHooks.js'
+import { applyPermissionUpdate } from '../permissions/PermissionUpdate.js'
+import { jsonStringify } from '../slowOperations.js'
+import { getTeammateColor } from '../teammate.js'
+import {
+  createIdleNotification,
+  getLastPeerDmSummary,
+  writeToMailbox,
+} from '../teammateMailbox.js'
+import { readTeamFile, setMemberActive } from './teamHelpers.js'
+
+/**
+ * Initializes hooks for a teammate running in a swarm.
+ * Should be called early in session startup after AppState is available.
+ *
+ * Registers a Stop hook that sends an idle notification to the team leader
+ * when this teammate's session stops.
+ */
+export function initializeTeammateHooks(
+  setAppState: (updater: (prev: AppState) => AppState) => void,
+  sessionId: string,
+  teamInfo: { teamName: string; agentId: string; agentName: string },
+): void {
+  const { teamName, agentId, agentName } = teamInfo
+
+  // Read team file to get leader ID
+  const teamFile = readTeamFile(teamName)
+  if (!teamFile) {
+    logForDebugging(`[TeammateInit] Team file not found for team: ${teamName}`)
+    return
+  }
+
+  const leadAgentId = teamFile.leadAgentId
+
+  // Apply team-wide allowed paths if any exist
+  if (teamFile.teamAllowedPaths && teamFile.teamAllowedPaths.length > 0) {
+    logForDebugging(
+      `[TeammateInit] Found ${teamFile.teamAllowedPaths.length} team-wide allowed path(s)`,
+    )
+
+    for (const allowedPath of teamFile.teamAllowedPaths) {
+      // For absolute paths (starting with /), prepend one / to create //path/** pattern
+      // For relative paths, just use path/**
+      const ruleContent = allowedPath.path.startsWith('/')
+        ? `/${allowedPath.path}/**`
+        : `${allowedPath.path}/**`
+
+      logForDebugging(
+        `[TeammateInit] Applying team permission: ${allowedPath.toolName} allowed in ${allowedPath.path} (rule: ${ruleContent})`,
+      )
+
+      setAppState(prev => ({
+        ...prev,
+        toolPermissionContext: applyPermissionUpdate(
+          prev.toolPermissionContext,
+          {
+            type: 'addRules',
+            rules: [
+              {
+                toolName: allowedPath.toolName,
+                ruleContent,
+              },
+            ],
+            behavior: 'allow',
+            destination: 'session',
+          },
+        ),
+      }))
+    }
+  }
+
+  // Find the leader's name from the members array
+  const leadMember = teamFile.members.find(m => m.agentId === leadAgentId)
+  const leadAgentName = leadMember?.name || 'team-lead'
+
+  // Don't register hook if this agent is the leader
+  if (agentId === leadAgentId) {
+    logForDebugging(
+      '[TeammateInit] This agent is the team leader - skipping idle notification hook',
+    )
+    return
+  }
+
+  logForDebugging(
+    `[TeammateInit] Registering Stop hook for teammate ${agentName} to notify leader ${leadAgentName}`,
+  )
+
+  // Register Stop hook to notify leader when this teammate stops
+  addFunctionHook(
+    setAppState,
+    sessionId,
+    'Stop',
+    '', // No matcher - applies to all Stop events
+    async (messages, _signal) => {
+      // Mark this teammate as idle in the team config (fire and forget)
+      void setMemberActive(teamName, agentName, false)
+
+      // Send idle notification to the team leader using agent name (not UUID)
+      // Must await to ensure the write completes before process shutdown
+      const notification = createIdleNotification(agentName, {
+        idleReason: 'available',
+        summary: getLastPeerDmSummary(messages),
+      })
+      await writeToMailbox(leadAgentName, {
+        from: agentName,
+        text: jsonStringify(notification),
+        timestamp: new Date().toISOString(),
+        color: getTeammateColor(),
+      })
+      logForDebugging(
+        `[TeammateInit] Sent idle notification to leader ${leadAgentName}`,
+      )
+      return true // Don't block the Stop
+    },
+    'Failed to send idle notification to team leader',
+    {
+      timeout: 10000,
+    },
+  )
+}

package/utils/swarm/teammateLayoutManager.ts

@@ -0,0 +1,107 @@
+import type { AgentColorName } from '../../tools/AgentTool/agentColorManager.js'
+import { AGENT_COLORS } from '../../tools/AgentTool/agentColorManager.js'
+import { detectAndGetBackend } from './backends/registry.js'
+import type { PaneBackend } from './backends/types.js'
+
+// Track color assignments for teammates (persisted per session)
+const teammateColorAssignments = new Map<string, AgentColorName>()
+let colorIndex = 0
+
+/**
+ * Gets the appropriate backend for the current environment.
+ * detectAndGetBackend() caches internally — no need for a second cache here.
+ */
+async function getBackend(): Promise<PaneBackend> {
+  return (await detectAndGetBackend()).backend
+}
+
+/**
+ * Assigns a unique color to a teammate from the available palette.
+ * Colors are assigned in round-robin order.
+ */
+export function assignTeammateColor(teammateId: string): AgentColorName {
+  const existing = teammateColorAssignments.get(teammateId)
+  if (existing) {
+    return existing
+  }
+
+  const color = AGENT_COLORS[colorIndex % AGENT_COLORS.length]!
+  teammateColorAssignments.set(teammateId, color)
+  colorIndex++
+
+  return color
+}
+
+/**
+ * Gets the assigned color for a teammate, if any.
+ */
+export function getTeammateColor(
+  teammateId: string,
+): AgentColorName | undefined {
+  return teammateColorAssignments.get(teammateId)
+}
+
+/**
+ * Clears all teammate color assignments.
+ * Called during team cleanup to reset state for potential new teams.
+ */
+export function clearTeammateColors(): void {
+  teammateColorAssignments.clear()
+  colorIndex = 0
+}
+
+/**
+ * Checks if we're currently running inside a tmux session.
+ * Uses the detection module directly for this check.
+ */
+export async function isInsideTmux(): Promise<boolean> {
+  const { isInsideTmux: checkTmux } = await import('./backends/detection.js')
+  return checkTmux()
+}
+
+/**
+ * Creates a new teammate pane in the swarm view.
+ * Automatically selects the appropriate backend (tmux or iTerm2) based on environment.
+ *
+ * When running INSIDE tmux:
+ * - Uses TmuxBackend to split the current window
+ * - Leader stays on left (30%), teammates on right (70%)
+ *
+ * When running in iTerm2 (not in tmux) with it2 CLI:
+ * - Uses ITermBackend for native iTerm2 split panes
+ *
+ * When running OUTSIDE tmux/iTerm2:
+ * - Falls back to TmuxBackend with external claude-swarm session
+ */
+export async function createTeammatePaneInSwarmView(
+  teammateName: string,
+  teammateColor: AgentColorName,
+): Promise<{ paneId: string; isFirstTeammate: boolean }> {
+  const backend = await getBackend()
+  return backend.createTeammatePaneInSwarmView(teammateName, teammateColor)
+}
+
+/**
+ * Enables pane border status for a window (shows pane titles).
+ * Delegates to the detected backend.
+ */
+export async function enablePaneBorderStatus(
+  windowTarget?: string,
+  useSwarmSocket = false,
+): Promise<void> {
+  const backend = await getBackend()
+  return backend.enablePaneBorderStatus(windowTarget, useSwarmSocket)
+}
+
+/**
+ * Sends a command to a specific pane.
+ * Delegates to the detected backend.
+ */
+export async function sendCommandToPane(
+  paneId: string,
+  command: string,
+  useSwarmSocket = false,
+): Promise<void> {
+  const backend = await getBackend()
+  return backend.sendCommandToPane(paneId, command, useSwarmSocket)
+}

package/utils/swarm/teammateModel.ts

@@ -0,0 +1,10 @@
+import { CLAUDE_OPUS_4_6_CONFIG } from '../model/configs.js'
+import { getAPIProvider } from '../model/providers.js'
+
+// @[MODEL LAUNCH]: Update the fallback model below.
+// When the user has never set teammateDefaultModel in /config, new teammates
+// use Opus 4.6. Must be provider-aware so Bedrock/Vertex/Foundry customers get
+// the correct model ID.
+export function getHardcodedTeammateModelFallback(): string {
+  return CLAUDE_OPUS_4_6_CONFIG[getAPIProvider()]
+}

package/utils/swarm/teammatePromptAddendum.ts

@@ -0,0 +1,18 @@
+/**
+ * Teammate-specific system prompt addendum.
+ *
+ * This is appended to the full main agent system prompt for teammates.
+ * It explains visibility constraints and communication requirements.
+ */
+
+export const TEAMMATE_SYSTEM_PROMPT_ADDENDUM = `
+# Agent Teammate Communication
+
+IMPORTANT: You are running as an agent in a team. To communicate with anyone on your team:
+- Use the SendMessage tool with \`to: "<name>"\` to send messages to specific teammates
+- Use the SendMessage tool with \`to: "*"\` sparingly for team-wide broadcasts
+
+Just writing a response in text is not visible to others on your team - you MUST use the SendMessage tool.
+
+The user interacts primarily with the team lead. Your work is coordinated through the task system and teammate messaging.
+`

package/utils/systemDirectories.ts

@@ -0,0 +1,74 @@
+import { homedir } from 'os'
+import { join } from 'path'
+import { logForDebugging } from './debug.js'
+import { getPlatform, type Platform } from './platform.js'
+
+export type SystemDirectories = {
+  HOME: string
+  DESKTOP: string
+  DOCUMENTS: string
+  DOWNLOADS: string
+  [key: string]: string // Index signature for compatibility with Record<string, string>
+}
+
+type EnvLike = Record<string, string | undefined>
+
+type SystemDirectoriesOptions = {
+  env?: EnvLike
+  homedir?: string
+  platform?: Platform
+}
+
+/**
+ * Get cross-platform system directories
+ * Handles differences between Windows, macOS, Linux, and WSL
+ * @param options Optional overrides for testing (env, homedir, platform)
+ */
+export function getSystemDirectories(
+  options?: SystemDirectoriesOptions,
+): SystemDirectories {
+  const platform = options?.platform ?? getPlatform()
+  const homeDir = options?.homedir ?? homedir()
+  const env = options?.env ?? process.env
+
+  // Default paths used by most platforms
+  const defaults: SystemDirectories = {
+    HOME: homeDir,
+    DESKTOP: join(homeDir, 'Desktop'),
+    DOCUMENTS: join(homeDir, 'Documents'),
+    DOWNLOADS: join(homeDir, 'Downloads'),
+  }
+
+  switch (platform) {
+    case 'windows': {
+      // Windows: Use USERPROFILE if available (handles localized folder names)
+      const userProfile = env.USERPROFILE || homeDir
+      return {
+        HOME: homeDir,
+        DESKTOP: join(userProfile, 'Desktop'),
+        DOCUMENTS: join(userProfile, 'Documents'),
+        DOWNLOADS: join(userProfile, 'Downloads'),
+      }
+    }
+
+    case 'linux':
+    case 'wsl': {
+      // Linux/WSL: Check XDG Base Directory specification first
+      return {
+        HOME: homeDir,
+        DESKTOP: env.XDG_DESKTOP_DIR || defaults.DESKTOP,
+        DOCUMENTS: env.XDG_DOCUMENTS_DIR || defaults.DOCUMENTS,
+        DOWNLOADS: env.XDG_DOWNLOAD_DIR || defaults.DOWNLOADS,
+      }
+    }
+
+    case 'macos':
+    default: {
+      // macOS and unknown platforms use standard paths
+      if (platform === 'unknown') {
+        logForDebugging(`Unknown platform detected, using default paths`)
+      }
+      return defaults
+    }
+  }
+}

package/utils/systemPrompt.ts

@@ -0,0 +1,123 @@
+import { feature } from 'bun:bundle'
+import {
+  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  logEvent,
+} from '../services/analytics/index.js'
+import type { ToolUseContext } from '../Tool.js'
+import type { AgentDefinition } from '../tools/AgentTool/loadAgentsDir.js'
+import { isBuiltInAgent } from '../tools/AgentTool/loadAgentsDir.js'
+import { isEnvTruthy } from './envUtils.js'
+import { asSystemPrompt, type SystemPrompt } from './systemPromptType.js'
+
+export { asSystemPrompt, type SystemPrompt } from './systemPromptType.js'
+
+// Dead code elimination: conditional import for proactive mode.
+// Same pattern as prompts.ts — lazy require to avoid pulling the module
+// into non-proactive builds.
+/* eslint-disable @typescript-eslint/no-require-imports */
+const proactiveModule =
+  feature('PROACTIVE') || feature('KAIROS')
+    ? (require('../proactive/index.js') as typeof import('../proactive/index.js'))
+    : null
+/* eslint-enable @typescript-eslint/no-require-imports */
+
+function isProactiveActive_SAFE_TO_CALL_ANYWHERE(): boolean {
+  return proactiveModule?.isProactiveActive() ?? false
+}
+
+/**
+ * Builds the effective system prompt array based on priority:
+ * 0. Override system prompt (if set, e.g., via loop mode - REPLACES all other prompts)
+ * 1. Coordinator system prompt (if coordinator mode is active)
+ * 2. Agent system prompt (if mainThreadAgentDefinition is set)
+ *    - In proactive mode: agent prompt is APPENDED to default (agent adds domain
+ *      instructions on top of the autonomous agent prompt, like teammates do)
+ *    - Otherwise: agent prompt REPLACES default
+ * 3. Custom system prompt (if specified via --system-prompt)
+ * 4. Default system prompt (the standard Claude Code prompt)
+ *
+ * Plus appendSystemPrompt is always added at the end if specified (except when override is set).
+ */
+export function buildEffectiveSystemPrompt({
+  mainThreadAgentDefinition,
+  toolUseContext,
+  customSystemPrompt,
+  defaultSystemPrompt,
+  appendSystemPrompt,
+  overrideSystemPrompt,
+}: {
+  mainThreadAgentDefinition: AgentDefinition | undefined
+  toolUseContext: Pick<ToolUseContext, 'options'>
+  customSystemPrompt: string | undefined
+  defaultSystemPrompt: string[]
+  appendSystemPrompt: string | undefined
+  overrideSystemPrompt?: string | null
+}): SystemPrompt {
+  if (overrideSystemPrompt) {
+    return asSystemPrompt([overrideSystemPrompt])
+  }
+  // Coordinator mode: use coordinator prompt instead of default
+  // Use inline env check instead of coordinatorModule to avoid circular
+  // dependency issues during test module loading.
+  if (
+    feature('COORDINATOR_MODE') &&
+    isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE) &&
+    !mainThreadAgentDefinition
+  ) {
+    // Lazy require to avoid circular dependency at module load time
+    const { getCoordinatorSystemPrompt } =
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      require('../coordinator/coordinatorMode.js') as typeof import('../coordinator/coordinatorMode.js')
+    return asSystemPrompt([
+      getCoordinatorSystemPrompt(),
+      ...(appendSystemPrompt ? [appendSystemPrompt] : []),
+    ])
+  }
+
+  const agentSystemPrompt = mainThreadAgentDefinition
+    ? isBuiltInAgent(mainThreadAgentDefinition)
+      ? mainThreadAgentDefinition.getSystemPrompt({
+          toolUseContext: { options: toolUseContext.options },
+        })
+      : mainThreadAgentDefinition.getSystemPrompt()
+    : undefined
+
+  // Log agent memory loaded event for main loop agents
+  if (mainThreadAgentDefinition?.memory) {
+    logEvent('tengu_agent_memory_loaded', {
+      ...(process.env.USER_TYPE === 'ant' && {
+        agent_type:
+          mainThreadAgentDefinition.agentType as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      }),
+      scope:
+        mainThreadAgentDefinition.memory as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      source:
+        'main-thread' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+    })
+  }
+
+  // In proactive mode, agent instructions are appended to the default prompt
+  // rather than replacing it. The proactive default prompt is already lean
+  // (autonomous agent identity + memory + env + proactive section), and agents
+  // add domain-specific behavior on top — same pattern as teammates.
+  if (
+    agentSystemPrompt &&
+    (feature('PROACTIVE') || feature('KAIROS')) &&
+    isProactiveActive_SAFE_TO_CALL_ANYWHERE()
+  ) {
+    return asSystemPrompt([
+      ...defaultSystemPrompt,
+      `\n# Custom Agent Instructions\n${agentSystemPrompt}`,
+      ...(appendSystemPrompt ? [appendSystemPrompt] : []),
+    ])
+  }
+
+  return asSystemPrompt([
+    ...(agentSystemPrompt
+      ? [agentSystemPrompt]
+      : customSystemPrompt
+        ? [customSystemPrompt]
+        : defaultSystemPrompt),
+    ...(appendSystemPrompt ? [appendSystemPrompt] : []),
+  ])
+}

package/utils/systemPromptType.ts

@@ -0,0 +1,14 @@
+/**
+ * Branded type for system prompt arrays.
+ *
+ * This module is intentionally dependency-free so it can be imported
+ * from anywhere without risking circular initialization issues.
+ */
+
+export type SystemPrompt = readonly string[] & {
+  readonly __brand: 'SystemPrompt'
+}
+
+export function asSystemPrompt(value: readonly string[]): SystemPrompt {
+  return value as SystemPrompt
+}

package/utils/systemTheme.ts

@@ -0,0 +1,119 @@
+/**
+ * Terminal dark/light mode detection for the 'auto' theme setting.
+ *
+ * Detection is based on the terminal's actual background color (queried via
+ * OSC 11 by systemThemeWatcher.ts) rather than the OS appearance setting —
+ * a dark terminal on a light-mode OS should still resolve to 'dark'.
+ *
+ * The detected theme is cached module-level so callers can resolve 'auto'
+ * without awaiting the async OSC round-trip. The cache is seeded from
+ * $COLORFGBG (synchronous, set by some terminals at launch) and then
+ * updated by the watcher once the OSC 11 response arrives.
+ */
+
+import type { ThemeName, ThemeSetting } from './theme.js'
+
+export type SystemTheme = 'dark' | 'light'
+
+let cachedSystemTheme: SystemTheme | undefined
+
+/**
+ * Get the current terminal theme. Cached after first detection; the watcher
+ * updates the cache on live changes.
+ */
+export function getSystemThemeName(): SystemTheme {
+  if (cachedSystemTheme === undefined) {
+    cachedSystemTheme = detectFromColorFgBg() ?? 'dark'
+  }
+  return cachedSystemTheme
+}
+
+/**
+ * Update the cached terminal theme. Called by the watcher when the OSC 11
+ * query returns so non-React call sites stay in sync.
+ */
+export function setCachedSystemTheme(theme: SystemTheme): void {
+  cachedSystemTheme = theme
+}
+
+/**
+ * Resolve a ThemeSetting (which may be 'auto') to a concrete ThemeName.
+ */
+export function resolveThemeSetting(setting: ThemeSetting): ThemeName {
+  if (setting === 'auto') {
+    return getSystemThemeName()
+  }
+  return setting
+}
+
+/**
+ * Parse an OSC color response data string into a theme.
+ *
+ * Accepts XParseColor formats returned by OSC 10/11 queries:
+ * - `rgb:R/G/B` where each component is 1–4 hex digits (each scaled to
+ *   [0, 16^n - 1] for n digits). This is what xterm, iTerm2, Terminal.app,
+ *   Ghostty, kitty, Alacritty, etc. return.
+ * - `#RRGGBB` / `#RRRRGGGGBBBB` (rare, but cheap to accept).
+ *
+ * Returns undefined for unrecognized formats so callers can fall back.
+ */
+export function themeFromOscColor(data: string): SystemTheme | undefined {
+  const rgb = parseOscRgb(data)
+  if (!rgb) return undefined
+  // ITU-R BT.709 relative luminance. Midpoint split: > 0.5 is light.
+  const luminance = 0.2126 * rgb.r + 0.7152 * rgb.g + 0.0722 * rgb.b
+  return luminance > 0.5 ? 'light' : 'dark'
+}
+
+type Rgb = { r: number; g: number; b: number }
+
+function parseOscRgb(data: string): Rgb | undefined {
+  // rgb:RRRR/GGGG/BBBB — each component is 1–4 hex digits.
+  // Some terminals append an alpha component (rgba:…/…/…/…); ignore it.
+  const rgbMatch =
+    /^rgba?:([0-9a-f]{1,4})\/([0-9a-f]{1,4})\/([0-9a-f]{1,4})/i.exec(data)
+  if (rgbMatch) {
+    return {
+      r: hexComponent(rgbMatch[1]!),
+      g: hexComponent(rgbMatch[2]!),
+      b: hexComponent(rgbMatch[3]!),
+    }
+  }
+  // #RRGGBB or #RRRRGGGGBBBB — split into three equal hex runs.
+  const hashMatch = /^#([0-9a-f]+)$/i.exec(data)
+  if (hashMatch && hashMatch[1]!.length % 3 === 0) {
+    const hex = hashMatch[1]!
+    const n = hex.length / 3
+    return {
+      r: hexComponent(hex.slice(0, n)),
+      g: hexComponent(hex.slice(n, 2 * n)),
+      b: hexComponent(hex.slice(2 * n)),
+    }
+  }
+  return undefined
+}
+
+/** Normalize a 1–4 digit hex component to [0, 1]. */
+function hexComponent(hex: string): number {
+  const max = 16 ** hex.length - 1
+  return parseInt(hex, 16) / max
+}
+
+/**
+ * Read $COLORFGBG for a synchronous initial guess before the OSC 11
+ * round-trip completes. Format is `fg;bg` (or `fg;other;bg`) where values
+ * are ANSI color indices. rxvt convention: bg 0–6 or 8 are dark; bg 7
+ * and 9–15 are light. Only set by some terminals (rxvt-family, Konsole,
+ * iTerm2 with the option enabled), so this is a best-effort hint.
+ */
+function detectFromColorFgBg(): SystemTheme | undefined {
+  const colorfgbg = process.env['COLORFGBG']
+  if (!colorfgbg) return undefined
+  const parts = colorfgbg.split(';')
+  const bg = parts[parts.length - 1]
+  if (bg === undefined || bg === '') return undefined
+  const bgNum = Number(bg)
+  if (!Number.isInteger(bgNum) || bgNum < 0 || bgNum > 15) return undefined
+  // 0–6 and 8 are dark ANSI colors; 7 (white) and 9–15 (bright) are light.
+  return bgNum <= 6 || bgNum === 8 ? 'dark' : 'light'
+}

package/utils/taggedId.ts

@@ -0,0 +1,54 @@
+/**
+ * Tagged ID encoding compatible with the API's tagged_id.py format.
+ *
+ * Produces IDs like "user_01PaGUP2rbg1XDh7Z9W1CEpd" from a UUID string.
+ * The format is: {tag}_{version}{base58(uuid_as_128bit_int)}
+ *
+ * This must stay in sync with api/api/common/utils/tagged_id.py.
+ */
+
+const BASE_58_CHARS =
+  '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+const VERSION = '01'
+// ceil(128 / log2(58)) = 22
+const ENCODED_LENGTH = 22
+
+/**
+ * Encode a 128-bit unsigned integer as a fixed-length base58 string.
+ */
+function base58Encode(n: bigint): string {
+  const base = BigInt(BASE_58_CHARS.length)
+  const result = new Array<string>(ENCODED_LENGTH).fill(BASE_58_CHARS[0]!)
+  let i = ENCODED_LENGTH - 1
+  let value = n
+  while (value > 0n) {
+    const rem = Number(value % base)
+    result[i] = BASE_58_CHARS[rem]!
+    value = value / base
+    i--
+  }
+  return result.join('')
+}
+
+/**
+ * Parse a UUID string (with or without hyphens) into a 128-bit bigint.
+ */
+function uuidToBigInt(uuid: string): bigint {
+  const hex = uuid.replace(/-/g, '')
+  if (hex.length !== 32) {
+    throw new Error(`Invalid UUID hex length: ${hex.length}`)
+  }
+  return BigInt('0x' + hex)
+}
+
+/**
+ * Convert an account UUID to a tagged ID in the API's format.
+ *
+ * @param tag - The tag prefix (e.g. "user", "org")
+ * @param uuid - A UUID string (with or without hyphens)
+ * @returns Tagged ID string like "user_01PaGUP2rbg1XDh7Z9W1CEpd"
+ */
+export function toTaggedId(tag: string, uuid: string): string {
+  const n = uuidToBigInt(uuid)
+  return `${tag}_${VERSION}${base58Encode(n)}`
+}