@xortex/xcode 3.0.0 → 3.0.2

package/hooks/useSkillsChange.ts

@@ -0,0 +1,62 @@
+import { useCallback, useEffect } from 'react'
+import type { Command } from '../commands.js'
+import {
+  clearCommandMemoizationCaches,
+  clearCommandsCache,
+  getCommands,
+} from '../commands.js'
+import { onGrowthBookRefresh } from '../services/analytics/growthbook.js'
+import { logError } from '../utils/log.js'
+import { skillChangeDetector } from '../utils/skills/skillChangeDetector.js'
+
+/**
+ * Keep the commands list fresh across two triggers:
+ *
+ * 1. Skill file changes (watcher) — full cache clear + disk re-scan, since
+ *    skill content changed on disk.
+ * 2. GrowthBook init/refresh — memo-only clear, since only `isEnabled()`
+ *    predicates may have changed. Handles commands like /btw whose gate
+ *    reads a flag that isn't in the disk cache yet on first session after
+ *    a flag rename: getCommands() runs before GB init (main.tsx:2855 vs
+ *    showSetupScreens at :3106), so the memoized list is baked with the
+ *    default. Once init populates remoteEvalFeatureValues, re-filter.
+ */
+export function useSkillsChange(
+  cwd: string | undefined,
+  onCommandsChange: (commands: Command[]) => void,
+): void {
+  const handleChange = useCallback(async () => {
+    if (!cwd) return
+    try {
+      // Clear all command caches to ensure fresh load
+      clearCommandsCache()
+      const commands = await getCommands(cwd)
+      onCommandsChange(commands)
+    } catch (error) {
+      // Errors during reload are non-fatal - log and continue
+      if (error instanceof Error) {
+        logError(error)
+      }
+    }
+  }, [cwd, onCommandsChange])
+
+  useEffect(() => skillChangeDetector.subscribe(handleChange), [handleChange])
+
+  const handleGrowthBookRefresh = useCallback(async () => {
+    if (!cwd) return
+    try {
+      clearCommandMemoizationCaches()
+      const commands = await getCommands(cwd)
+      onCommandsChange(commands)
+    } catch (error) {
+      if (error instanceof Error) {
+        logError(error)
+      }
+    }
+  }, [cwd, onCommandsChange])
+
+  useEffect(
+    () => onGrowthBookRefresh(handleGrowthBookRefresh),
+    [handleGrowthBookRefresh],
+  )
+}

package/hooks/useSwarmInitialization.ts

@@ -0,0 +1,81 @@
+/**
+ * Swarm Initialization Hook
+ *
+ * Initializes swarm features: teammate hooks and context.
+ * Handles both fresh spawns and resumed teammate sessions.
+ *
+ * This hook is conditionally loaded to allow dead code elimination when swarms are disabled.
+ */
+
+import { useEffect } from 'react'
+import { getSessionId } from '../bootstrap/state.js'
+import type { AppState } from '../state/AppState.js'
+import type { Message } from '../types/message.js'
+import { isAgentSwarmsEnabled } from '../utils/agentSwarmsEnabled.js'
+import { initializeTeammateContextFromSession } from '../utils/swarm/reconnection.js'
+import { readTeamFile } from '../utils/swarm/teamHelpers.js'
+import { initializeTeammateHooks } from '../utils/swarm/teammateInit.js'
+import { getDynamicTeamContext } from '../utils/teammate.js'
+
+type SetAppState = (f: (prevState: AppState) => AppState) => void
+
+/**
+ * Hook that initializes swarm features when ENABLE_AGENT_SWARMS is true.
+ *
+ * Handles both:
+ * - Resumed teammate sessions (from --resume or /resume) where teamName/agentName
+ *   are stored in transcript messages
+ * - Fresh spawns where context is read from environment variables
+ */
+export function useSwarmInitialization(
+  setAppState: SetAppState,
+  initialMessages: Message[] | undefined,
+  { enabled = true }: { enabled?: boolean } = {},
+): void {
+  useEffect(() => {
+    if (!enabled) return
+    if (isAgentSwarmsEnabled()) {
+      // Check if this is a resumed agent session (from --resume or /resume)
+      // Resumed sessions have teamName/agentName stored in transcript messages
+      const firstMessage = initialMessages?.[0]
+      const teamName =
+        firstMessage && 'teamName' in firstMessage
+          ? (firstMessage.teamName as string | undefined)
+          : undefined
+      const agentName =
+        firstMessage && 'agentName' in firstMessage
+          ? (firstMessage.agentName as string | undefined)
+          : undefined
+
+      if (teamName && agentName) {
+        // Resumed agent session - set up team context from stored info
+        initializeTeammateContextFromSession(setAppState, teamName, agentName)
+
+        // Get agentId from team file for hook initialization
+        const teamFile = readTeamFile(teamName)
+        const member = teamFile?.members.find(
+          (m: { name: string }) => m.name === agentName,
+        )
+        if (member) {
+          initializeTeammateHooks(setAppState, getSessionId(), {
+            teamName,
+            agentId: member.agentId,
+            agentName,
+          })
+        }
+      } else {
+        // Fresh spawn or standalone session
+        // teamContext is already computed in main.tsx via computeInitialTeamContext()
+        // and included in initialState, so we only need to initialize hooks here
+        const context = getDynamicTeamContext?.()
+        if (context?.teamName && context?.agentId && context?.agentName) {
+          initializeTeammateHooks(setAppState, getSessionId(), {
+            teamName: context.teamName,
+            agentId: context.agentId,
+            agentName: context.agentName,
+          })
+        }
+      }
+    }
+  }, [setAppState, initialMessages, enabled])
+}

package/hooks/useSwarmPermissionPoller.ts

@@ -0,0 +1,330 @@
+/**
+ * Swarm Permission Poller Hook
+ *
+ * This hook polls for permission responses from the team leader when running
+ * as a worker agent in a swarm. When a response is received, it calls the
+ * appropriate callback (onAllow/onReject) to continue execution.
+ *
+ * This hook should be used in conjunction with the worker-side integration
+ * in useCanUseTool.ts, which creates pending requests that this hook monitors.
+ */
+
+import { useCallback, useEffect, useRef } from 'react'
+import { useInterval } from 'usehooks-ts'
+import { logForDebugging } from '../utils/debug.js'
+import { errorMessage } from '../utils/errors.js'
+import {
+  type PermissionUpdate,
+  permissionUpdateSchema,
+} from '../utils/permissions/PermissionUpdateSchema.js'
+import {
+  isSwarmWorker,
+  type PermissionResponse,
+  pollForResponse,
+  removeWorkerResponse,
+} from '../utils/swarm/permissionSync.js'
+import { getAgentName, getTeamName } from '../utils/teammate.js'
+
+const POLL_INTERVAL_MS = 500
+
+/**
+ * Validate permissionUpdates from external sources (mailbox IPC, disk polling).
+ * Malformed entries from buggy/old teammate processes are filtered out rather
+ * than propagated unchecked into callback.onAllow().
+ */
+function parsePermissionUpdates(raw: unknown): PermissionUpdate[] {
+  if (!Array.isArray(raw)) {
+    return []
+  }
+  const schema = permissionUpdateSchema()
+  const valid: PermissionUpdate[] = []
+  for (const entry of raw) {
+    const result = schema.safeParse(entry)
+    if (result.success) {
+      valid.push(result.data)
+    } else {
+      logForDebugging(
+        `[SwarmPermissionPoller] Dropping malformed permissionUpdate entry: ${result.error.message}`,
+        { level: 'warn' },
+      )
+    }
+  }
+  return valid
+}
+
+/**
+ * Callback signature for handling permission responses
+ */
+export type PermissionResponseCallback = {
+  requestId: string
+  toolUseId: string
+  onAllow: (
+    updatedInput: Record<string, unknown> | undefined,
+    permissionUpdates: PermissionUpdate[],
+    feedback?: string,
+  ) => void
+  onReject: (feedback?: string) => void
+}
+
+/**
+ * Registry for pending permission request callbacks
+ * This allows the poller to find and invoke the right callbacks when responses arrive
+ */
+type PendingCallbackRegistry = Map<string, PermissionResponseCallback>
+
+// Module-level registry that persists across renders
+const pendingCallbacks: PendingCallbackRegistry = new Map()
+
+/**
+ * Register a callback for a pending permission request
+ * Called by useCanUseTool when a worker submits a permission request
+ */
+export function registerPermissionCallback(
+  callback: PermissionResponseCallback,
+): void {
+  pendingCallbacks.set(callback.requestId, callback)
+  logForDebugging(
+    `[SwarmPermissionPoller] Registered callback for request ${callback.requestId}`,
+  )
+}
+
+/**
+ * Unregister a callback (e.g., when the request is resolved locally or times out)
+ */
+export function unregisterPermissionCallback(requestId: string): void {
+  pendingCallbacks.delete(requestId)
+  logForDebugging(
+    `[SwarmPermissionPoller] Unregistered callback for request ${requestId}`,
+  )
+}
+
+/**
+ * Check if a request has a registered callback
+ */
+export function hasPermissionCallback(requestId: string): boolean {
+  return pendingCallbacks.has(requestId)
+}
+
+/**
+ * Clear all pending callbacks (both permission and sandbox).
+ * Called from clearSessionCaches() on /clear to reset stale state,
+ * and also used in tests for isolation.
+ */
+export function clearAllPendingCallbacks(): void {
+  pendingCallbacks.clear()
+  pendingSandboxCallbacks.clear()
+}
+
+/**
+ * Process a permission response from a mailbox message.
+ * This is called by the inbox poller when it detects a permission_response message.
+ *
+ * @returns true if the response was processed, false if no callback was registered
+ */
+export function processMailboxPermissionResponse(params: {
+  requestId: string
+  decision: 'approved' | 'rejected'
+  feedback?: string
+  updatedInput?: Record<string, unknown>
+  permissionUpdates?: unknown
+}): boolean {
+  const callback = pendingCallbacks.get(params.requestId)
+
+  if (!callback) {
+    logForDebugging(
+      `[SwarmPermissionPoller] No callback registered for mailbox response ${params.requestId}`,
+    )
+    return false
+  }
+
+  logForDebugging(
+    `[SwarmPermissionPoller] Processing mailbox response for request ${params.requestId}: ${params.decision}`,
+  )
+
+  // Remove from registry before invoking callback
+  pendingCallbacks.delete(params.requestId)
+
+  if (params.decision === 'approved') {
+    const permissionUpdates = parsePermissionUpdates(params.permissionUpdates)
+    const updatedInput = params.updatedInput
+    callback.onAllow(updatedInput, permissionUpdates)
+  } else {
+    callback.onReject(params.feedback)
+  }
+
+  return true
+}
+
+// ============================================================================
+// Sandbox Permission Callback Registry
+// ============================================================================
+
+/**
+ * Callback signature for handling sandbox permission responses
+ */
+export type SandboxPermissionResponseCallback = {
+  requestId: string
+  host: string
+  resolve: (allow: boolean) => void
+}
+
+// Module-level registry for sandbox permission callbacks
+const pendingSandboxCallbacks: Map<string, SandboxPermissionResponseCallback> =
+  new Map()
+
+/**
+ * Register a callback for a pending sandbox permission request
+ * Called when a worker sends a sandbox permission request to the leader
+ */
+export function registerSandboxPermissionCallback(
+  callback: SandboxPermissionResponseCallback,
+): void {
+  pendingSandboxCallbacks.set(callback.requestId, callback)
+  logForDebugging(
+    `[SwarmPermissionPoller] Registered sandbox callback for request ${callback.requestId}`,
+  )
+}
+
+/**
+ * Check if a sandbox request has a registered callback
+ */
+export function hasSandboxPermissionCallback(requestId: string): boolean {
+  return pendingSandboxCallbacks.has(requestId)
+}
+
+/**
+ * Process a sandbox permission response from a mailbox message.
+ * Called by the inbox poller when it detects a sandbox_permission_response message.
+ *
+ * @returns true if the response was processed, false if no callback was registered
+ */
+export function processSandboxPermissionResponse(params: {
+  requestId: string
+  host: string
+  allow: boolean
+}): boolean {
+  const callback = pendingSandboxCallbacks.get(params.requestId)
+
+  if (!callback) {
+    logForDebugging(
+      `[SwarmPermissionPoller] No sandbox callback registered for request ${params.requestId}`,
+    )
+    return false
+  }
+
+  logForDebugging(
+    `[SwarmPermissionPoller] Processing sandbox response for request ${params.requestId}: allow=${params.allow}`,
+  )
+
+  // Remove from registry before invoking callback
+  pendingSandboxCallbacks.delete(params.requestId)
+
+  // Resolve the promise with the allow decision
+  callback.resolve(params.allow)
+
+  return true
+}
+
+/**
+ * Process a permission response by invoking the registered callback
+ */
+function processResponse(response: PermissionResponse): boolean {
+  const callback = pendingCallbacks.get(response.requestId)
+
+  if (!callback) {
+    logForDebugging(
+      `[SwarmPermissionPoller] No callback registered for request ${response.requestId}`,
+    )
+    return false
+  }
+
+  logForDebugging(
+    `[SwarmPermissionPoller] Processing response for request ${response.requestId}: ${response.decision}`,
+  )
+
+  // Remove from registry before invoking callback
+  pendingCallbacks.delete(response.requestId)
+
+  if (response.decision === 'approved') {
+    const permissionUpdates = parsePermissionUpdates(response.permissionUpdates)
+    const updatedInput = response.updatedInput
+    callback.onAllow(updatedInput, permissionUpdates)
+  } else {
+    callback.onReject(response.feedback)
+  }
+
+  return true
+}
+
+/**
+ * Hook that polls for permission responses when running as a swarm worker.
+ *
+ * This hook:
+ * 1. Only activates when isSwarmWorker() returns true
+ * 2. Polls every 500ms for responses
+ * 3. When a response is found, invokes the registered callback
+ * 4. Cleans up the response file after processing
+ */
+export function useSwarmPermissionPoller(): void {
+  const isProcessingRef = useRef(false)
+
+  const poll = useCallback(async () => {
+    // Don't poll if not a swarm worker
+    if (!isSwarmWorker()) {
+      return
+    }
+
+    // Prevent concurrent polling
+    if (isProcessingRef.current) {
+      return
+    }
+
+    // Don't poll if no callbacks are registered
+    if (pendingCallbacks.size === 0) {
+      return
+    }
+
+    isProcessingRef.current = true
+
+    try {
+      const agentName = getAgentName()
+      const teamName = getTeamName()
+
+      if (!agentName || !teamName) {
+        return
+      }
+
+      // Check each pending request for a response
+      for (const [requestId, _callback] of pendingCallbacks) {
+        const response = await pollForResponse(requestId, agentName, teamName)
+
+        if (response) {
+          // Process the response
+          const processed = processResponse(response)
+
+          if (processed) {
+            // Clean up the response from the worker's inbox
+            await removeWorkerResponse(requestId, agentName, teamName)
+          }
+        }
+      }
+    } catch (error) {
+      logForDebugging(
+        `[SwarmPermissionPoller] Error during poll: ${errorMessage(error)}`,
+      )
+    } finally {
+      isProcessingRef.current = false
+    }
+  }, [])
+
+  // Only poll if we're a swarm worker
+  const shouldPoll = isSwarmWorker()
+  useInterval(() => void poll(), shouldPoll ? POLL_INTERVAL_MS : null)
+
+  // Initial poll on mount
+  useEffect(() => {
+    if (isSwarmWorker()) {
+      void poll()
+    }
+  }, [poll])
+}

package/hooks/useTaskListWatcher.ts

@@ -0,0 +1,221 @@
+import { type FSWatcher, watch } from 'fs'
+import { useEffect, useRef } from 'react'
+import { logForDebugging } from '../utils/debug.js'
+import {
+  claimTask,
+  DEFAULT_TASKS_MODE_TASK_LIST_ID,
+  ensureTasksDir,
+  getTasksDir,
+  listTasks,
+  type Task,
+  updateTask,
+} from '../utils/tasks.js'
+
+const DEBOUNCE_MS = 1000
+
+type Props = {
+  /** When undefined, the hook does nothing. The task list id is also used as the agent ID. */
+  taskListId?: string
+  isLoading: boolean
+  /**
+   * Called when a task is ready to be worked on.
+   * Returns true if submission succeeded, false if rejected.
+   */
+  onSubmitTask: (prompt: string) => boolean
+}
+
+/**
+ * Hook that watches a task list directory and automatically picks up
+ * open, unowned tasks to work on.
+ *
+ * This enables "tasks mode" where Claude watches for externally-created
+ * tasks and processes them one at a time.
+ */
+export function useTaskListWatcher({
+  taskListId,
+  isLoading,
+  onSubmitTask,
+}: Props): void {
+  const currentTaskRef = useRef<string | null>(null)
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  // Stabilize unstable props via refs so the watcher effect doesn't depend on
+  // them. isLoading flips every turn, and onSubmitTask's identity changes
+  // whenever onQuery's deps change. Without this, the watcher effect re-runs
+  // on every turn, calling watcher.close() + watch() each time — which is a
+  // trigger for Bun's PathWatcherManager deadlock (oven-sh/bun#27469).
+  const isLoadingRef = useRef(isLoading)
+  isLoadingRef.current = isLoading
+  const onSubmitTaskRef = useRef(onSubmitTask)
+  onSubmitTaskRef.current = onSubmitTask
+
+  const enabled = taskListId !== undefined
+  const agentId = taskListId ?? DEFAULT_TASKS_MODE_TASK_LIST_ID
+
+  // checkForTasks reads isLoading and onSubmitTask from refs — always
+  // up-to-date, no stale closure, and doesn't force a new function identity
+  // per render. Stored in a ref so the watcher effect can call it without
+  // depending on it.
+  const checkForTasksRef = useRef<() => Promise<void>>(async () => {})
+  checkForTasksRef.current = async () => {
+    if (!enabled) {
+      return
+    }
+
+    // Don't need to submit new tasks if we are already working
+    if (isLoadingRef.current) {
+      return
+    }
+
+    const tasks = await listTasks(taskListId)
+
+    // If we have a current task, check if it's been resolved
+    if (currentTaskRef.current !== null) {
+      const currentTask = tasks.find(t => t.id === currentTaskRef.current)
+      if (!currentTask || currentTask.status === 'completed') {
+        logForDebugging(
+          `[TaskListWatcher] Task #${currentTaskRef.current} is marked complete, ready for next task`,
+        )
+        currentTaskRef.current = null
+      } else {
+        // Still working on current task
+        return
+      }
+    }
+
+    // Find an open task with no owner that isn't blocked
+    const availableTask = findAvailableTask(tasks)
+
+    if (!availableTask) {
+      return
+    }
+
+    logForDebugging(
+      `[TaskListWatcher] Found available task #${availableTask.id}: ${availableTask.subject}`,
+    )
+
+    // Claim the task using the task list's agent ID
+    const result = await claimTask(taskListId, availableTask.id, agentId)
+
+    if (!result.success) {
+      logForDebugging(
+        `[TaskListWatcher] Failed to claim task #${availableTask.id}: ${result.reason}`,
+      )
+      return
+    }
+
+    currentTaskRef.current = availableTask.id
+
+    // Format the task as a prompt
+    const prompt = formatTaskAsPrompt(availableTask)
+
+    logForDebugging(
+      `[TaskListWatcher] Submitting task #${availableTask.id} as prompt`,
+    )
+
+    const submitted = onSubmitTaskRef.current(prompt)
+    if (!submitted) {
+      logForDebugging(
+        `[TaskListWatcher] Failed to submit task #${availableTask.id}, releasing claim`,
+      )
+      // Release the claim
+      await updateTask(taskListId, availableTask.id, { owner: undefined })
+      currentTaskRef.current = null
+    }
+  }
+
+  // -- Watcher setup
+
+  // Schedules a check after DEBOUNCE_MS, collapsing rapid fs events.
+  // Shared between the watcher callback and the idle-trigger effect below.
+  const scheduleCheckRef = useRef<() => void>(() => {})
+
+  useEffect(() => {
+    if (!enabled) return
+
+    void ensureTasksDir(taskListId)
+    const tasksDir = getTasksDir(taskListId)
+
+    let watcher: FSWatcher | null = null
+
+    const debouncedCheck = (): void => {
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current)
+      }
+      debounceTimerRef.current = setTimeout(
+        ref => void ref.current(),
+        DEBOUNCE_MS,
+        checkForTasksRef,
+      )
+    }
+    scheduleCheckRef.current = debouncedCheck
+
+    try {
+      watcher = watch(tasksDir, debouncedCheck)
+      watcher.unref()
+      logForDebugging(`[TaskListWatcher] Watching for tasks in ${tasksDir}`)
+    } catch (error) {
+      // fs.watch throws synchronously on ENOENT — ensureTasksDir should have
+      // created the dir, but handle the race gracefully
+      logForDebugging(`[TaskListWatcher] Failed to watch ${tasksDir}: ${error}`)
+    }
+
+    // Initial check
+    debouncedCheck()
+
+    return () => {
+      // This cleanup only fires when taskListId changes or on unmount —
+      // never per-turn. That keeps watcher.close() out of the Bun
+      // PathWatcherManager deadlock window.
+      scheduleCheckRef.current = () => {}
+      if (watcher) {
+        watcher.close()
+      }
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current)
+      }
+    }
+  }, [enabled, taskListId])
+
+  // Previously, the watcher effect depended on checkForTasks (and transitively
+  // isLoading), so going idle triggered a re-setup whose initial debouncedCheck
+  // would pick up the next task. Preserve that behavior explicitly: when
+  // isLoading drops, schedule a check.
+  useEffect(() => {
+    if (!enabled) return
+    if (isLoading) return
+    scheduleCheckRef.current()
+  }, [enabled, isLoading])
+}
+
+/**
+ * Find an available task that can be worked on:
+ * - Status is 'pending'
+ * - No owner assigned
+ * - Not blocked by any unresolved tasks
+ */
+function findAvailableTask(tasks: Task[]): Task | undefined {
+  const unresolvedTaskIds = new Set(
+    tasks.filter(t => t.status !== 'completed').map(t => t.id),
+  )
+
+  return tasks.find(task => {
+    if (task.status !== 'pending') return false
+    if (task.owner) return false
+    // Check all blockers are completed
+    return task.blockedBy.every(id => !unresolvedTaskIds.has(id))
+  })
+}
+
+/**
+ * Format a task as a prompt for Claude to work on.
+ */
+function formatTaskAsPrompt(task: Task): string {
+  let prompt = `Complete all open tasks. Start with task #${task.id}: \n\n ${task.subject}`
+
+  if (task.description) {
+    prompt += `\n\n${task.description}`
+  }
+
+  return prompt
+}