@alumbwe/anvil 1.0.0

package/src/hooks/use-message-queue.ts

@@ -0,0 +1,387 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { logger } from '../utils/logger'
+
+import type { PendingAttachment } from '../types/store'
+
+export type StreamStatus = 'idle' | 'waiting' | 'streaming'
+
+export type QueuedMessage = {
+  /** Stable across edits and reorders so the queue editor can address a row
+   *  by identity rather than by a position that shifts underneath it. */
+  id: string
+  content: string
+  attachments: PendingAttachment[]
+}
+
+const newQueueId = () => crypto.randomUUID()
+
+// Watchdog timeout duration: 60 seconds
+const QUEUE_WATCHDOG_TIMEOUT_MS = 60 * 1000
+
+export const useMessageQueue = (
+  sendMessage: (message: QueuedMessage) => Promise<void>,
+  isChainInProgressRef: React.MutableRefObject<boolean>,
+  activeAgentStreamsRef: React.MutableRefObject<number>,
+  opts: {
+    /** External hold on dequeuing (e.g. the freebuff session ended and new
+     *  requests would be rejected). Queued messages are kept, not dropped;
+     *  processing resumes automatically when this flips back to false. */
+    sendBlocked?: boolean
+  } = {},
+) => {
+  const sendBlocked = opts.sendBlocked ?? false
+  const [queuedMessages, setQueuedMessages] = useState<QueuedMessage[]>([])
+  const [streamStatus, setStreamStatus] = useState<StreamStatus>('idle')
+  const [canProcessQueue, setCanProcessQueue] = useState<boolean>(true)
+  // Separate state for user-initiated pause to ensure re-renders when pause status changes
+  const [queuePausedState, setQueuePausedState] = useState<boolean>(false)
+
+  // Keep a ref so clearQueue can return the current queue synchronously.
+  const queuedMessagesRef = useRef<QueuedMessage[]>([])
+  const streamTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const streamIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null)
+  const streamMessageIdRef = useRef<string | null>(null)
+  const isProcessingQueueRef = useRef<boolean>(false)
+  const queueProcessingOwnerRef = useRef<symbol | null>(null)
+  // User-initiated pause state (separate from system-busy state)
+  const isQueuePausedRef = useRef<boolean>(false)
+  // Watchdog timer to recover from stuck queue processing lock
+  const watchdogTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  // queuePaused reflects whether the user has explicitly paused the queue
+  // (not whether the system is temporarily busy processing)
+  // Use state instead of ref to ensure components re-render when pause status changes
+  const queuePaused = queuePausedState
+
+  /** Every queue write goes through here: the ref is updated before React
+   *  state so anything reading between renders (cancellation, the next
+   *  dequeue) sees the same queue the user just acted on. */
+  const writeQueue = useCallback((next: QueuedMessage[]) => {
+    queuedMessagesRef.current = next
+    setQueuedMessages(next)
+  }, [])
+
+  const clearStreaming = useCallback(() => {
+    if (streamTimeoutRef.current) {
+      clearTimeout(streamTimeoutRef.current)
+      streamTimeoutRef.current = null
+    }
+    if (streamIntervalRef.current) {
+      clearInterval(streamIntervalRef.current)
+      streamIntervalRef.current = null
+    }
+    streamMessageIdRef.current = null
+    activeAgentStreamsRef.current = 0
+    setStreamStatus('idle')
+  }, [activeAgentStreamsRef])
+
+  useEffect(() => {
+    return () => {
+      clearStreaming()
+      // Clean up watchdog timer on unmount
+      if (watchdogTimeoutRef.current) {
+        clearTimeout(watchdogTimeoutRef.current)
+        watchdogTimeoutRef.current = null
+      }
+    }
+  }, [clearStreaming])
+
+  const processNextMessage = useCallback(() => {
+    const queuedList = queuedMessagesRef.current
+    const queueLength = queuedList.length
+
+    if (queueLength === 0) {
+      return
+    }
+
+    // Check if user has explicitly paused the queue
+    if (isQueuePausedRef.current) {
+      logger.debug(
+        { queueLength },
+        '[message-queue] Queue blocked: user paused',
+      )
+      return
+    }
+
+    // External hold: sending is currently pointless (e.g. freebuff session
+    // fully ended — requests without a live session are rejected). Leave the
+    // messages queued; the effect below re-runs when sendBlocked flips false.
+    // No log here: unlike the transient busy branches above, this state can
+    // persist for the whole hold, and this path re-runs on every render —
+    // the transition is logged once by the caller instead.
+    if (sendBlocked) {
+      return
+    }
+
+    if (!canProcessQueue) {
+      return
+    }
+    if (streamStatus !== 'idle') {
+      logger.debug(
+        { queueLength, streamStatus },
+        '[message-queue] Queue blocked: stream not idle',
+      )
+      return
+    }
+    if (streamMessageIdRef.current) {
+      logger.debug(
+        { queueLength, streamMessageId: streamMessageIdRef.current },
+        '[message-queue] Queue blocked: streamMessageId set',
+      )
+      return
+    }
+    if (isChainInProgressRef.current) {
+      logger.debug(
+        { queueLength, isChainInProgress: isChainInProgressRef.current },
+        '[message-queue] Queue blocked: chain in progress',
+      )
+      return
+    }
+    if (activeAgentStreamsRef.current > 0) {
+      logger.debug(
+        { queueLength, activeAgentStreams: activeAgentStreamsRef.current },
+        '[message-queue] Queue blocked: active agent streams',
+      )
+      return
+    }
+
+    if (isProcessingQueueRef.current) {
+      logger.debug(
+        { queueLength },
+        '[message-queue] Queue blocked: already processing',
+      )
+      return
+    }
+
+    logger.info(
+      { queueLength },
+      '[message-queue] Processing next message from queue',
+    )
+
+    const processingOwner = Symbol('queue-processing-owner')
+    queueProcessingOwnerRef.current = processingOwner
+    isProcessingQueueRef.current = true
+
+    // Start watchdog timer to recover from stuck processing lock
+    if (watchdogTimeoutRef.current) {
+      clearTimeout(watchdogTimeoutRef.current)
+    }
+    watchdogTimeoutRef.current = setTimeout(() => {
+      if (queueProcessingOwnerRef.current !== processingOwner) return
+      if (isProcessingQueueRef.current) {
+        logger.warn(
+          { stuckDurationMs: QUEUE_WATCHDOG_TIMEOUT_MS },
+          '[message-queue] Watchdog: isProcessingQueueRef stuck for too long, forcing reset',
+        )
+        // Also reset canProcessQueue to allow queue to resume (unless user-paused)
+        setCanProcessQueue(!isQueuePausedRef.current)
+      }
+      queueProcessingOwnerRef.current = null
+      isProcessingQueueRef.current = false
+      watchdogTimeoutRef.current = null
+    }, QUEUE_WATCHDOG_TIMEOUT_MS)
+
+    // Read the message to process from the synchronous queue source.
+    const messageToProcess = queuedMessagesRef.current[0]
+
+    if (!messageToProcess) {
+      queueProcessingOwnerRef.current = null
+      isProcessingQueueRef.current = false
+      // Clear watchdog timer on early return
+      if (watchdogTimeoutRef.current) {
+        clearTimeout(watchdogTimeoutRef.current)
+        watchdogTimeoutRef.current = null
+      }
+      return
+    }
+
+    // Remove it from both sources synchronously. Cancellation decisions read
+    // the ref between renders, so deferring this update inside a React state
+    // updater can make an in-flight message look queued.
+    writeQueue(queuedMessagesRef.current.slice(1))
+
+    sendMessage(messageToProcess)
+      .catch((err: unknown) => {
+        logger.warn(
+          { error: err },
+          '[message-queue] sendMessage promise rejected',
+        )
+      })
+      .finally(() => {
+        if (queueProcessingOwnerRef.current !== processingOwner) return
+        queueProcessingOwnerRef.current = null
+        isProcessingQueueRef.current = false
+        // Clear watchdog timer when processing completes normally
+        if (watchdogTimeoutRef.current) {
+          clearTimeout(watchdogTimeoutRef.current)
+          watchdogTimeoutRef.current = null
+        }
+        logger.debug('[message-queue] Processing lock released')
+      })
+  }, [
+    canProcessQueue,
+    streamStatus,
+    sendMessage,
+    sendBlocked,
+    isChainInProgressRef,
+    activeAgentStreamsRef,
+    writeQueue,
+  ])
+
+  useEffect(() => {
+    processNextMessage()
+  }, [
+    canProcessQueue,
+    streamStatus,
+    queuedMessages.length,
+    processNextMessage,
+    isChainInProgressRef,
+  ])
+
+  const addToQueue = useCallback(
+    (message: string, attachments: PendingAttachment[] = []) => {
+      const queuedMessage = {
+        id: newQueueId(),
+        content: message,
+        attachments,
+      }
+      writeQueue([...queuedMessagesRef.current, queuedMessage])
+    },
+    [writeQueue],
+  )
+
+  /** Put a message back at the HEAD of the queue. Used when a send was
+   *  aborted before it did anything (e.g. the freebuff session ended between
+   *  dequeue and run start) so the message keeps its place instead of being
+   *  consumed. */
+  const addToQueueFront = useCallback(
+    (message: Omit<QueuedMessage, 'id'>) => {
+      writeQueue([
+        { ...message, id: newQueueId() },
+        ...queuedMessagesRef.current,
+      ])
+    },
+    [writeQueue],
+  )
+
+  /** Replace a queued message's text, keeping its place and attachments.
+   *  Returns false when the message is no longer queued — it started running
+   *  between the editor's render and this call, and rewriting a prompt the
+   *  agent is already working on would be a lie either way. */
+  const editQueuedMessage = useCallback(
+    (id: string, content: string): boolean => {
+      const current = queuedMessagesRef.current
+      const index = current.findIndex((message) => message.id === id)
+      if (index === -1) return false
+
+      const next = [...current]
+      next[index] = { ...next[index]!, content }
+      writeQueue(next)
+      return true
+    },
+    [writeQueue],
+  )
+
+  /** Drop a single queued message. Returns false if it already left the
+   *  queue, which is the caller's cue that it is running, not cancelled. */
+  const removeQueuedMessage = useCallback(
+    (id: string): boolean => {
+      const current = queuedMessagesRef.current
+      const next = current.filter((message) => message.id !== id)
+      if (next.length === current.length) return false
+
+      writeQueue(next)
+      return true
+    },
+    [writeQueue],
+  )
+
+  /** Move a queued message to `toIndex`, clamped to the queue's bounds so
+   *  callers can pass index±1 at the edges without a guard. */
+  const moveQueuedMessage = useCallback(
+    (id: string, toIndex: number): boolean => {
+      const current = queuedMessagesRef.current
+      const from = current.findIndex((message) => message.id === id)
+      if (from === -1) return false
+
+      const to = Math.max(0, Math.min(current.length - 1, toIndex))
+      if (to === from) return false
+
+      const next = [...current]
+      const [moved] = next.splice(from, 1)
+      next.splice(to, 0, moved!)
+      writeQueue(next)
+      return true
+    },
+    [writeQueue],
+  )
+
+  const pauseQueue = useCallback(() => {
+    isQueuePausedRef.current = true
+    setQueuePausedState(true)
+    setCanProcessQueue(false)
+  }, [])
+
+  const pauseQueueIfPending = useCallback(() => {
+    if (queuedMessagesRef.current.length === 0) return
+    pauseQueue()
+  }, [pauseQueue])
+
+  const resumeQueue = useCallback(() => {
+    isQueuePausedRef.current = false
+    setQueuePausedState(false)
+    setCanProcessQueue(true)
+  }, [])
+
+  const clearQueue = useCallback(() => {
+    const current = queuedMessagesRef.current
+    writeQueue([])
+    return current
+  }, [writeQueue])
+
+  /** Drop queue state when leaving its chat. Unlike clearQueue (the user's
+   * Ctrl-C action), this also removes paused/processing bookkeeping so a
+   * same-provider /new cannot inherit a phantom paused queue. */
+  const discardQueue = useCallback(() => {
+    writeQueue([])
+    isQueuePausedRef.current = false
+    setQueuePausedState(false)
+    queueProcessingOwnerRef.current = null
+    isProcessingQueueRef.current = false
+    if (watchdogTimeoutRef.current) {
+      clearTimeout(watchdogTimeoutRef.current)
+      watchdogTimeoutRef.current = null
+    }
+    setCanProcessQueue(false)
+  }, [writeQueue])
+
+  const startStreaming = useCallback(() => {
+    setStreamStatus('streaming')
+    setCanProcessQueue(false)
+  }, [])
+
+  return {
+    queuedMessages,
+    streamStatus,
+    canProcessQueue,
+    queuePaused,
+    streamMessageIdRef,
+    addToQueue,
+    addToQueueFront,
+    editQueuedMessage,
+    removeQueuedMessage,
+    moveQueuedMessage,
+    startStreaming,
+    setStreamStatus,
+    clearStreaming,
+    setCanProcessQueue,
+    pauseQueue,
+    pauseQueueIfPending,
+    resumeQueue,
+    clearQueue,
+    discardQueue,
+    isQueuePausedRef,
+    isProcessingQueueRef,
+  }
+}

package/src/hooks/use-now.ts

@@ -0,0 +1,20 @@
+import { useEffect, useState } from 'react'
+
+/**
+ * Returns `Date.now()`, refreshed at the given interval. Pass `enabled: false`
+ * to freeze the timer (and cancel the interval). Multiple components can call
+ * this independently; setIntervals are cheap and React batches the resulting
+ * renders.
+ *
+ * Intended for short-lived UI countdowns like the freebuff session timer or
+ * elapsed-in-queue display.
+ */
+export function useNow(intervalMs: number, enabled = true): number {
+  const [now, setNow] = useState(() => Date.now())
+  useEffect(() => {
+    if (!enabled) return
+    const id = setInterval(() => setNow(Date.now()), intervalMs)
+    return () => clearInterval(id)
+  }, [intervalMs, enabled])
+  return now
+}

package/src/hooks/use-path-tab-completion.ts

@@ -0,0 +1,88 @@
+import { existsSync, statSync } from 'fs'
+import path from 'path'
+
+import { useCallback } from 'react'
+
+import { getPathCompletion } from '../utils/path-completion'
+
+export interface UsePathTabCompletionOptions {
+  /** Current search query */
+  searchQuery: string
+  /** Set the search query */
+  setSearchQuery: (query: string) => void
+  /** Current directory path */
+  currentPath: string
+  /** Set the current directory path */
+  setCurrentPath: (path: string) => void
+  /** Function to expand ~ to home directory */
+  expandPath: (inputPath: string) => string
+}
+
+export interface UsePathTabCompletionReturn {
+  /** Handle tab completion, returns true to indicate key was handled */
+  handleTabCompletion: () => boolean
+}
+
+/**
+ * Hook for path tab completion.
+ * Handles both absolute (/, ~) and relative path completion.
+ * Always navigates to completed directories when completion ends with /.
+ */
+export function usePathTabCompletion({
+  searchQuery,
+  setSearchQuery,
+  currentPath,
+  setCurrentPath,
+  expandPath,
+}: UsePathTabCompletionOptions): UsePathTabCompletionReturn {
+  const handleTabCompletion = useCallback((): boolean => {
+    if (searchQuery.startsWith('/') || searchQuery.startsWith('~')) {
+      // Absolute path completion
+      const completed = getPathCompletion(searchQuery)
+      if (completed) {
+        // If completion is a full directory (ends with /), navigate there and keep the path in input
+        if (completed.endsWith('/')) {
+          const dirPath = expandPath(completed.slice(0, -1))
+          try {
+            if (existsSync(dirPath) && statSync(dirPath).isDirectory()) {
+              setCurrentPath(dirPath)
+              setSearchQuery(completed)
+              return true
+            }
+          } catch {
+            // Fall through to just set the query
+          }
+        }
+        setSearchQuery(completed)
+      }
+    } else if (searchQuery.length > 0) {
+      // Relative path completion - try from current directory
+      const relativePath = path.join(currentPath, searchQuery)
+      const completed = getPathCompletion(relativePath)
+      if (completed) {
+        // If completion is a full directory (ends with /), navigate there and keep the path in input
+        if (completed.endsWith('/')) {
+          try {
+            const dirPath = completed.slice(0, -1)
+            if (existsSync(dirPath) && statSync(dirPath).isDirectory()) {
+              setCurrentPath(dirPath)
+              setSearchQuery(completed)
+              return true
+            }
+          } catch {
+            // Fall through to just set the query
+          }
+        }
+        // Convert back to relative path for display
+        if (completed.startsWith(currentPath + path.sep)) {
+          setSearchQuery(completed.slice(currentPath.length + 1))
+        } else {
+          setSearchQuery(completed)
+        }
+      }
+    }
+    return true
+  }, [searchQuery, setSearchQuery, currentPath, setCurrentPath, expandPath])
+
+  return { handleTabCompletion }
+}

package/src/hooks/use-publish-mutation.ts

@@ -0,0 +1,60 @@
+import { useMutation } from '@tanstack/react-query'
+import { useShallow } from 'zustand/react/shallow'
+
+import {
+  handlePublish as defaultHandlePublish,
+  type PublishResult,
+} from '../commands/publish'
+import { usePublishStore } from '../state/publish-store'
+
+// Query keys for type-safe cache management
+export const publishQueryKeys = {
+  all: ['publish'] as const,
+}
+
+export interface UsePublishMutationDeps {
+  handlePublish?: (agentIds: string[]) => Promise<PublishResult>
+}
+
+/**
+ * Hook for publishing agents to the agent store
+ * Uses TanStack Query mutation for proper state management
+ */
+export function usePublishMutation(deps: UsePublishMutationDeps = {}) {
+  const { handlePublish = defaultHandlePublish } = deps
+
+  const { setIsPublishing, setSuccessResult, setErrorResult } = usePublishStore(
+    useShallow((state) => ({
+      setIsPublishing: state.setIsPublishing,
+      setSuccessResult: state.setSuccessResult,
+      setErrorResult: state.setErrorResult,
+    })),
+  )
+
+  return useMutation({
+    mutationFn: async (agentIds: string[]) => {
+      setIsPublishing(true)
+      return handlePublish(agentIds)
+    },
+    onSuccess: (result) => {
+      if (result.success && result.publisherId && result.agents) {
+        setSuccessResult({
+          publisherId: result.publisherId,
+          agents: result.agents,
+        })
+      } else {
+        setErrorResult({
+          error: result.error || 'Unknown error',
+          details: result.details,
+          hint: result.hint,
+        })
+      }
+    },
+    onError: (error) => {
+      setErrorResult({
+        error: 'Publish failed',
+        details: error instanceof Error ? error.message : String(error),
+      })
+    },
+  })
+}

package/src/hooks/use-queue-controls.ts

@@ -0,0 +1,68 @@
+import { useCallback } from 'react'
+
+import type { QueuedMessage } from './use-message-queue'
+
+interface UseQueueControlsParams {
+  queuePaused: boolean
+  queuedCount: number
+  clearQueue: () => QueuedMessage[]
+  resumeQueue: () => void
+  inputHasText: boolean
+  baseHandleCtrlC: () => true
+}
+
+type QueueCtrlCHandlerOptions = UseQueueControlsParams
+
+export const createQueueCtrlCHandler = ({
+  queuePaused,
+  queuedCount,
+  clearQueue,
+  resumeQueue,
+  inputHasText,
+  baseHandleCtrlC,
+}: QueueCtrlCHandlerOptions) => () => {
+  if (queuePaused && queuedCount > 0 && !inputHasText) {
+    clearQueue()
+    resumeQueue()
+    return true
+  }
+  return baseHandleCtrlC()
+}
+
+export const useQueueControls = ({
+  queuePaused,
+  queuedCount,
+  clearQueue,
+  resumeQueue,
+  inputHasText,
+  baseHandleCtrlC,
+}: UseQueueControlsParams) => {
+  const handleCtrlC = useCallback(
+    createQueueCtrlCHandler({
+      queuePaused,
+      queuedCount,
+      clearQueue,
+      resumeQueue,
+      inputHasText,
+      baseHandleCtrlC,
+    }),
+    [
+      baseHandleCtrlC,
+      clearQueue,
+      inputHasText,
+      queuePaused,
+      queuedCount,
+      resumeQueue,
+    ],
+  )
+
+  const ensureQueueActiveBeforeSubmit = useCallback(() => {
+    if (queuePaused) {
+      resumeQueue()
+      return true
+    }
+    return false
+  }, [queuePaused, resumeQueue])
+
+  return { handleCtrlC, ensureQueueActiveBeforeSubmit }
+}

package/src/hooks/use-queue-ui.ts

@@ -0,0 +1,74 @@
+import { pluralize } from '@anvil/common/util/string'
+import { useMemo } from 'react'
+
+
+import { formatQueuedPreview } from '../utils/helpers'
+
+import type { QueuedMessage } from './use-message-queue'
+
+interface UseQueueUiParams {
+  queuePaused: boolean
+  queuedMessages: QueuedMessage[]
+  separatorWidth: number
+  terminalWidth: number
+}
+
+/** Below this the title has no room for a second segment, so the expand hint
+ *  is omitted rather than crowding out the preview itself. */
+const HINT_MIN_WIDTH = 80
+
+export const useQueueUi = ({
+  queuePaused,
+  queuedMessages,
+  separatorWidth,
+  terminalWidth,
+}: UseQueueUiParams) => {
+  const queuedCount = queuedMessages.length
+  const shouldShowQueuePreview = queuedCount > 0 && !queuePaused
+
+  /** The composer's border title: what is queued, and how to expand it.
+   *  Queuing is discoverable (you just type while it runs); editing what you
+   *  queued is not, so the hint rides along with the preview. */
+  const inputBoxTitle = useMemo(() => {
+    let preview: string | undefined
+    if (shouldShowQueuePreview) {
+      preview = formatQueuedPreview(
+        queuedMessages,
+        Math.max(30, separatorWidth - 20),
+      )
+    } else if (queuePaused && queuedCount > 0) {
+      preview = `⏸ ${pluralize(queuedCount, 'message')} queued — your next message sends first`
+    }
+
+    if (!preview) return undefined
+    if (terminalWidth < HINT_MIN_WIDTH) return ` ▸ ${preview} `
+    return ` ▸ ${preview}   click to expand `
+  }, [
+    shouldShowQueuePreview,
+    queuePaused,
+    queuedCount,
+    queuedMessages,
+    separatorWidth,
+    terminalWidth,
+  ])
+
+  const inputPlaceholder = useMemo(() => {
+    const base =
+      terminalWidth < 65
+        ? 'What are we building?'
+        : 'What are we building?  ( / for commands )'
+
+    if (queuePaused && queuedCount > 0) {
+      return 'Ctrl-C to cancel queued messages'
+    }
+
+    return base
+  }, [queuePaused, queuedCount, terminalWidth])
+
+  return {
+    queuedCount,
+    shouldShowQueuePreview,
+    inputBoxTitle,
+    inputPlaceholder,
+  }
+}