@xortex/xcode 3.0.0

package/utils/swarm/reconnection.ts

@@ -0,0 +1,119 @@
+/**
+ * Swarm Reconnection Module
+ *
+ * Handles initialization of swarm context for teammates.
+ * - Fresh spawns: Initialize from CLI args (set in main.tsx via dynamicTeamContext)
+ * - Resumed sessions: Initialize from teamName/agentName stored in the transcript
+ */
+
+import type { AppState } from '../../state/AppState.js'
+import { logForDebugging } from '../debug.js'
+import { logError } from '../log.js'
+import { getDynamicTeamContext } from '../teammate.js'
+import { getTeamFilePath, readTeamFile } from './teamHelpers.js'
+
+/**
+ * Computes the initial teamContext for AppState.
+ *
+ * This is called synchronously in main.tsx to compute the teamContext
+ * BEFORE the first render, eliminating the need for useEffect workarounds.
+ *
+ * @returns The teamContext object to include in initialState, or undefined if not a teammate
+ */
+export function computeInitialTeamContext():
+  | AppState['teamContext']
+  | undefined {
+  // dynamicTeamContext is set in main.tsx from CLI args
+  const context = getDynamicTeamContext()
+
+  if (!context?.teamName || !context?.agentName) {
+    logForDebugging(
+      '[Reconnection] computeInitialTeamContext: No teammate context set (not a teammate)',
+    )
+    return undefined
+  }
+
+  const { teamName, agentId, agentName } = context
+
+  // Read team file to get lead agent ID
+  const teamFile = readTeamFile(teamName)
+  if (!teamFile) {
+    logError(
+      new Error(
+        `[computeInitialTeamContext] Could not read team file for ${teamName}`,
+      ),
+    )
+    return undefined
+  }
+
+  const teamFilePath = getTeamFilePath(teamName)
+
+  const isLeader = !agentId
+
+  logForDebugging(
+    `[Reconnection] Computed initial team context for ${isLeader ? 'leader' : `teammate ${agentName}`} in team ${teamName}`,
+  )
+
+  return {
+    teamName,
+    teamFilePath,
+    leadAgentId: teamFile.leadAgentId,
+    selfAgentId: agentId,
+    selfAgentName: agentName,
+    isLeader,
+    teammates: {},
+  }
+}
+
+/**
+ * Initialize teammate context from a resumed session.
+ *
+ * This is called when resuming a session that has teamName/agentName stored
+ * in the transcript. It sets up teamContext in AppState so that heartbeat
+ * and other swarm features work correctly.
+ */
+export function initializeTeammateContextFromSession(
+  setAppState: (updater: (prev: AppState) => AppState) => void,
+  teamName: string,
+  agentName: string,
+): void {
+  // Read team file to get lead agent ID
+  const teamFile = readTeamFile(teamName)
+  if (!teamFile) {
+    logError(
+      new Error(
+        `[initializeTeammateContextFromSession] Could not read team file for ${teamName} (agent: ${agentName})`,
+      ),
+    )
+    return
+  }
+
+  // Find the member in the team file to get their agentId
+  const member = teamFile.members.find(m => m.name === agentName)
+  if (!member) {
+    logForDebugging(
+      `[Reconnection] Member ${agentName} not found in team ${teamName} - may have been removed`,
+    )
+  }
+  const agentId = member?.agentId
+
+  const teamFilePath = getTeamFilePath(teamName)
+
+  // Set teamContext in AppState
+  setAppState(prev => ({
+    ...prev,
+    teamContext: {
+      teamName,
+      teamFilePath,
+      leadAgentId: teamFile.leadAgentId,
+      selfAgentId: agentId,
+      selfAgentName: agentName,
+      isLeader: false,
+      teammates: {},
+    },
+  }))
+
+  logForDebugging(
+    `[Reconnection] Initialized agent context from session for ${agentName} in team ${teamName}`,
+  )
+}

package/utils/swarm/spawnInProcess.ts

@@ -0,0 +1,328 @@
+/**
+ * In-process teammate spawning
+ *
+ * Creates and registers an in-process teammate task. Unlike process-based
+ * teammates (tmux/iTerm2), in-process teammates run in the same Node.js
+ * process using AsyncLocalStorage for context isolation.
+ *
+ * The actual agent execution loop is handled by InProcessTeammateTask
+ * component (Task #14). This module handles:
+ * 1. Creating TeammateContext
+ * 2. Creating linked AbortController
+ * 3. Registering InProcessTeammateTaskState in AppState
+ * 4. Returning spawn result for backend
+ */
+
+import sample from 'lodash-es/sample.js'
+import { getSessionId } from '../../bootstrap/state.js'
+import { getSpinnerVerbs } from '../../constants/spinnerVerbs.js'
+import { TURN_COMPLETION_VERBS } from '../../constants/turnCompletionVerbs.js'
+import type { AppState } from '../../state/AppState.js'
+import { createTaskStateBase, generateTaskId } from '../../Task.js'
+import type {
+  InProcessTeammateTaskState,
+  TeammateIdentity,
+} from '../../tasks/InProcessTeammateTask/types.js'
+import { createAbortController } from '../abortController.js'
+import { formatAgentId } from '../agentId.js'
+import { registerCleanup } from '../cleanupRegistry.js'
+import { logForDebugging } from '../debug.js'
+import { emitTaskTerminatedSdk } from '../sdkEventQueue.js'
+import { evictTaskOutput } from '../task/diskOutput.js'
+import {
+  evictTerminalTask,
+  registerTask,
+  STOPPED_DISPLAY_MS,
+} from '../task/framework.js'
+import { createTeammateContext } from '../teammateContext.js'
+import {
+  isPerfettoTracingEnabled,
+  registerAgent as registerPerfettoAgent,
+  unregisterAgent as unregisterPerfettoAgent,
+} from '../telemetry/perfettoTracing.js'
+import { removeMemberByAgentId } from './teamHelpers.js'
+
+type SetAppStateFn = (updater: (prev: AppState) => AppState) => void
+
+/**
+ * Minimal context required for spawning an in-process teammate.
+ * This is a subset of ToolUseContext - only what spawnInProcessTeammate actually uses.
+ */
+export type SpawnContext = {
+  setAppState: SetAppStateFn
+  toolUseId?: string
+}
+
+/**
+ * Configuration for spawning an in-process teammate.
+ */
+export type InProcessSpawnConfig = {
+  /** Display name for the teammate, e.g., "researcher" */
+  name: string
+  /** Team this teammate belongs to */
+  teamName: string
+  /** Initial prompt/task for the teammate */
+  prompt: string
+  /** Optional UI color for the teammate */
+  color?: string
+  /** Whether teammate must enter plan mode before implementing */
+  planModeRequired: boolean
+  /** Optional model override for this teammate */
+  model?: string
+}
+
+/**
+ * Result from spawning an in-process teammate.
+ */
+export type InProcessSpawnOutput = {
+  /** Whether spawn was successful */
+  success: boolean
+  /** Full agent ID (format: "name@team") */
+  agentId: string
+  /** Task ID for tracking in AppState */
+  taskId?: string
+  /** AbortController for this teammate (linked to parent) */
+  abortController?: AbortController
+  /** Teammate context for AsyncLocalStorage */
+  teammateContext?: ReturnType<typeof createTeammateContext>
+  /** Error message if spawn failed */
+  error?: string
+}
+
+/**
+ * Spawns an in-process teammate.
+ *
+ * Creates the teammate's context, registers the task in AppState, and returns
+ * the spawn result. The actual agent execution is driven by the
+ * InProcessTeammateTask component which uses runWithTeammateContext() to
+ * execute the agent loop with proper identity isolation.
+ *
+ * @param config - Spawn configuration
+ * @param context - Context with setAppState for registering task
+ * @returns Spawn result with teammate info
+ */
+export async function spawnInProcessTeammate(
+  config: InProcessSpawnConfig,
+  context: SpawnContext,
+): Promise<InProcessSpawnOutput> {
+  const { name, teamName, prompt, color, planModeRequired, model } = config
+  const { setAppState } = context
+
+  // Generate deterministic agent ID
+  const agentId = formatAgentId(name, teamName)
+  const taskId = generateTaskId('in_process_teammate')
+
+  logForDebugging(
+    `[spawnInProcessTeammate] Spawning ${agentId} (taskId: ${taskId})`,
+  )
+
+  try {
+    // Create independent AbortController for this teammate
+    // Teammates should not be aborted when the leader's query is interrupted
+    const abortController = createAbortController()
+
+    // Get parent session ID for transcript correlation
+    const parentSessionId = getSessionId()
+
+    // Create teammate identity (stored as plain data in AppState)
+    const identity: TeammateIdentity = {
+      agentId,
+      agentName: name,
+      teamName,
+      color,
+      planModeRequired,
+      parentSessionId,
+    }
+
+    // Create teammate context for AsyncLocalStorage
+    // This will be used by runWithTeammateContext() during agent execution
+    const teammateContext = createTeammateContext({
+      agentId,
+      agentName: name,
+      teamName,
+      color,
+      planModeRequired,
+      parentSessionId,
+      abortController,
+    })
+
+    // Register agent in Perfetto trace for hierarchy visualization
+    if (isPerfettoTracingEnabled()) {
+      registerPerfettoAgent(agentId, name, parentSessionId)
+    }
+
+    // Create task state
+    const description = `${name}: ${prompt.substring(0, 50)}${prompt.length > 50 ? '...' : ''}`
+
+    const taskState: InProcessTeammateTaskState = {
+      ...createTaskStateBase(
+        taskId,
+        'in_process_teammate',
+        description,
+        context.toolUseId,
+      ),
+      type: 'in_process_teammate',
+      status: 'running',
+      identity,
+      prompt,
+      model,
+      abortController,
+      awaitingPlanApproval: false,
+      spinnerVerb: sample(getSpinnerVerbs()),
+      pastTenseVerb: sample(TURN_COMPLETION_VERBS),
+      permissionMode: planModeRequired ? 'plan' : 'default',
+      isIdle: false,
+      shutdownRequested: false,
+      lastReportedToolCount: 0,
+      lastReportedTokenCount: 0,
+      pendingUserMessages: [],
+      messages: [], // Initialize to empty array so getDisplayedMessages works immediately
+    }
+
+    // Register cleanup handler for graceful shutdown
+    const unregisterCleanup = registerCleanup(async () => {
+      logForDebugging(`[spawnInProcessTeammate] Cleanup called for ${agentId}`)
+      abortController.abort()
+      // Task state will be updated by the execution loop when it detects abort
+    })
+    taskState.unregisterCleanup = unregisterCleanup
+
+    // Register task in AppState
+    registerTask(taskState, setAppState)
+
+    logForDebugging(
+      `[spawnInProcessTeammate] Registered ${agentId} in AppState`,
+    )
+
+    return {
+      success: true,
+      agentId,
+      taskId,
+      abortController,
+      teammateContext,
+    }
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error ? error.message : 'Unknown error during spawn'
+    logForDebugging(
+      `[spawnInProcessTeammate] Failed to spawn ${agentId}: ${errorMessage}`,
+    )
+    return {
+      success: false,
+      agentId,
+      error: errorMessage,
+    }
+  }
+}
+
+/**
+ * Kills an in-process teammate by aborting its controller.
+ *
+ * Note: This is the implementation called by InProcessBackend.kill().
+ *
+ * @param taskId - Task ID of the teammate to kill
+ * @param setAppState - AppState setter
+ * @returns true if killed successfully
+ */
+export function killInProcessTeammate(
+  taskId: string,
+  setAppState: SetAppStateFn,
+): boolean {
+  let killed = false
+  let teamName: string | null = null
+  let agentId: string | null = null
+  let toolUseId: string | undefined
+  let description: string | undefined
+
+  setAppState((prev: AppState) => {
+    const task = prev.tasks[taskId]
+    if (!task || task.type !== 'in_process_teammate') {
+      return prev
+    }
+
+    const teammateTask = task as InProcessTeammateTaskState
+
+    if (teammateTask.status !== 'running') {
+      return prev
+    }
+
+    // Capture identity for cleanup after state update
+    teamName = teammateTask.identity.teamName
+    agentId = teammateTask.identity.agentId
+    toolUseId = teammateTask.toolUseId
+    description = teammateTask.description
+
+    // Abort the controller to stop execution
+    teammateTask.abortController?.abort()
+
+    // Call cleanup handler
+    teammateTask.unregisterCleanup?.()
+
+    // Update task state and remove from teamContext.teammates
+    killed = true
+
+    // Call pending idle callbacks to unblock any waiters (e.g., engine.waitForIdle)
+    teammateTask.onIdleCallbacks?.forEach(cb => cb())
+
+    // Remove from teamContext.teammates using the agentId
+    let updatedTeamContext = prev.teamContext
+    if (prev.teamContext && prev.teamContext.teammates && agentId) {
+      const { [agentId]: _, ...remainingTeammates } = prev.teamContext.teammates
+      updatedTeamContext = {
+        ...prev.teamContext,
+        teammates: remainingTeammates,
+      }
+    }
+
+    return {
+      ...prev,
+      teamContext: updatedTeamContext,
+      tasks: {
+        ...prev.tasks,
+        [taskId]: {
+          ...teammateTask,
+          status: 'killed' as const,
+          notified: true,
+          endTime: Date.now(),
+          onIdleCallbacks: [], // Clear callbacks to prevent stale references
+          messages: teammateTask.messages?.length
+            ? [teammateTask.messages[teammateTask.messages.length - 1]!]
+            : undefined,
+          pendingUserMessages: [],
+          inProgressToolUseIDs: undefined,
+          abortController: undefined,
+          unregisterCleanup: undefined,
+          currentWorkAbortController: undefined,
+        },
+      },
+    }
+  })
+
+  // Remove from team file (outside state updater to avoid file I/O in callback)
+  if (teamName && agentId) {
+    removeMemberByAgentId(teamName, agentId)
+  }
+
+  if (killed) {
+    void evictTaskOutput(taskId)
+    // notified:true was pre-set so no XML notification fires; close the SDK
+    // task_started bookend directly. The in-process runner's own
+    // completion/failure emit guards on status==='running' so it won't
+    // double-emit after seeing status:killed.
+    emitTaskTerminatedSdk(taskId, 'stopped', {
+      toolUseId,
+      summary: description,
+    })
+    setTimeout(
+      evictTerminalTask.bind(null, taskId, setAppState),
+      STOPPED_DISPLAY_MS,
+    )
+  }
+
+  // Release perfetto agent registry entry
+  if (agentId) {
+    unregisterPerfettoAgent(agentId)
+  }
+
+  return killed
+}

package/utils/swarm/spawnUtils.ts

@@ -0,0 +1,146 @@
+/**
+ * Shared utilities for spawning teammates across different backends.
+ */
+
+import {
+  getChromeFlagOverride,
+  getFlagSettingsPath,
+  getInlinePlugins,
+  getMainLoopModelOverride,
+  getSessionBypassPermissionsMode,
+} from '../../bootstrap/state.js'
+import { quote } from '../bash/shellQuote.js'
+import { isInBundledMode } from '../bundledMode.js'
+import type { PermissionMode } from '../permissions/PermissionMode.js'
+import { getTeammateModeFromSnapshot } from './backends/teammateModeSnapshot.js'
+import { TEAMMATE_COMMAND_ENV_VAR } from './constants.js'
+
+/**
+ * Gets the command to use for spawning teammate processes.
+ * Uses TEAMMATE_COMMAND_ENV_VAR if set, otherwise falls back to the
+ * current process executable path.
+ */
+export function getTeammateCommand(): string {
+  if (process.env[TEAMMATE_COMMAND_ENV_VAR]) {
+    return process.env[TEAMMATE_COMMAND_ENV_VAR]
+  }
+  return isInBundledMode() ? process.execPath : process.argv[1]!
+}
+
+/**
+ * Builds CLI flags to propagate from the current session to spawned teammates.
+ * This ensures teammates inherit important settings like permission mode,
+ * model selection, and plugin configuration from their parent.
+ *
+ * @param options.planModeRequired - If true, don't inherit bypass permissions (plan mode takes precedence)
+ * @param options.permissionMode - Permission mode to propagate
+ */
+export function buildInheritedCliFlags(options?: {
+  planModeRequired?: boolean
+  permissionMode?: PermissionMode
+}): string {
+  const flags: string[] = []
+  const { planModeRequired, permissionMode } = options || {}
+
+  // Propagate permission mode to teammates, but NOT if plan mode is required
+  // Plan mode takes precedence over bypass permissions for safety
+  if (planModeRequired) {
+    // Don't inherit bypass permissions when plan mode is required
+  } else if (
+    permissionMode === 'bypassPermissions' ||
+    getSessionBypassPermissionsMode()
+  ) {
+    flags.push('--dangerously-skip-permissions')
+  } else if (permissionMode === 'acceptEdits') {
+    flags.push('--permission-mode acceptEdits')
+  }
+
+  // Propagate --model if explicitly set via CLI
+  const modelOverride = getMainLoopModelOverride()
+  if (modelOverride) {
+    flags.push(`--model ${quote([modelOverride])}`)
+  }
+
+  // Propagate --settings if set via CLI
+  const settingsPath = getFlagSettingsPath()
+  if (settingsPath) {
+    flags.push(`--settings ${quote([settingsPath])}`)
+  }
+
+  // Propagate --plugin-dir for each inline plugin
+  const inlinePlugins = getInlinePlugins()
+  for (const pluginDir of inlinePlugins) {
+    flags.push(`--plugin-dir ${quote([pluginDir])}`)
+  }
+
+  // Propagate --teammate-mode so tmux teammates use the same mode as leader
+  const sessionMode = getTeammateModeFromSnapshot()
+  flags.push(`--teammate-mode ${sessionMode}`)
+
+  // Propagate --chrome / --no-chrome if explicitly set on the CLI
+  const chromeFlagOverride = getChromeFlagOverride()
+  if (chromeFlagOverride === true) {
+    flags.push('--chrome')
+  } else if (chromeFlagOverride === false) {
+    flags.push('--no-chrome')
+  }
+
+  return flags.join(' ')
+}
+
+/**
+ * Environment variables that must be explicitly forwarded to tmux-spawned
+ * teammates. Tmux may start a new login shell that doesn't inherit the
+ * parent's env, so we forward any that are set in the current process.
+ */
+const TEAMMATE_ENV_VARS = [
+  // API provider selection — without these, teammates default to firstParty
+  // and send requests to the wrong endpoint (GitHub issue #23561)
+  'CLAUDE_CODE_USE_BEDROCK',
+  'CLAUDE_CODE_USE_VERTEX',
+  'CLAUDE_CODE_USE_FOUNDRY',
+  // Custom API endpoint
+  'ANTHROPIC_BASE_URL',
+  // Config directory override
+  'CLAUDE_CONFIG_DIR',
+  // CCR marker — teammates need this for CCR-aware code paths. Auth finds
+  // its own way via /home/claude/.claude/remote/.oauth_token regardless;
+  // the FD env var wouldn't help (pipe FDs don't cross tmux).
+  'CLAUDE_CODE_REMOTE',
+  // Auto-memory gate (memdir/paths.ts) checks REMOTE && !MEMORY_DIR to
+  // disable memory on ephemeral CCR filesystems. Forwarding REMOTE alone
+  // would flip teammates to memory-off when the parent has it on.
+  'CLAUDE_CODE_REMOTE_MEMORY_DIR',
+  // Upstream proxy — the parent's MITM relay is reachable from teammates
+  // (same container network). Forward the proxy vars so teammates route
+  // customer-configured upstream traffic through the relay for credential
+  // injection. Without these, teammates bypass the proxy entirely.
+  'HTTPS_PROXY',
+  'https_proxy',
+  'HTTP_PROXY',
+  'http_proxy',
+  'NO_PROXY',
+  'no_proxy',
+  'SSL_CERT_FILE',
+  'NODE_EXTRA_CA_CERTS',
+  'REQUESTS_CA_BUNDLE',
+  'CURL_CA_BUNDLE',
+] as const
+
+/**
+ * Builds the `env KEY=VALUE ...` string for teammate spawn commands.
+ * Always includes CLAUDECODE=1 and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1,
+ * plus any provider/config env vars that are set in the current process.
+ */
+export function buildInheritedEnvVars(): string {
+  const envVars = ['CLAUDECODE=1', 'CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1']
+
+  for (const key of TEAMMATE_ENV_VARS) {
+    const value = process.env[key]
+    if (value !== undefined && value !== '') {
+      envVars.push(`${key}=${quote([value])}`)
+    }
+  }
+
+  return envVars.join(' ')
+}