@alumbwe/anvil 1.0.0

package/src/state/freebuff-model-store.ts

@@ -0,0 +1,42 @@
+import {
+  DEFAULT_FREEBUFF_MODEL_ID,
+  resolveAvailableFreebuffModel,
+  resolveSupportedFreebuffModel,
+} from '@anvil/common/constants/freebuff-models'
+import { create } from 'zustand'
+
+import { loadFreebuffModelPreference } from '../utils/settings'
+
+/**
+ * Holds the user's currently-selected freebuff model. Initialized from the
+ * persisted settings file so freebuff defaults to whatever model the user
+ * last picked.
+ *
+ * `setSelectedModel` is in-memory only — it does NOT persist. Persistence
+ * happens exclusively in `startFreebuffSession` (the explicit-pick path), so
+ * server-driven auto-flips (`model_locked`, `model_unavailable`, takeover)
+ * can update the in-memory selection without overwriting the user's saved
+ * preference. The latter previously caused users to get permanently flipped
+ * to the fallback model after a single auto-fallback.
+ *
+ * Components on the landing screen read this to highlight the current row in
+ * the model picker; the session hook reads it to decide which model to start.
+ */
+interface FreebuffModelStore {
+  selectedModel: string
+  setSelectedModel: (model: string) => void
+}
+
+export const useFreebuffModelStore = create<FreebuffModelStore>((set) => ({
+  selectedModel: resolveAvailableFreebuffModel(
+    loadFreebuffModelPreference() ?? DEFAULT_FREEBUFF_MODEL_ID,
+  ),
+  setSelectedModel: (model) =>
+    set({ selectedModel: resolveSupportedFreebuffModel(model) }),
+}))
+
+/** Imperative read for non-React callers (the session hook's tick loop and
+ *  the chat-completions metadata builder). */
+export function getSelectedFreebuffModel(): string {
+  return useFreebuffModelStore.getState().selectedModel
+}

package/src/state/freebuff-session-store.ts

@@ -0,0 +1,53 @@
+import { create } from 'zustand'
+
+import type { FreebuffSessionResponse } from '../types/freebuff-session'
+
+export interface FreebuffSessionRetry {
+  /** One-based number of the request that will be made next. */
+  attempt: number
+  /** Absolute client timestamp when the poll loop will retry. */
+  retryAtMs: number
+}
+
+interface FreebuffSessionFailureBase {
+  message: string
+  retry: FreebuffSessionRetry | null
+  /** The server may have committed a mutating request before its result was lost. */
+  outcomeUnknown: boolean
+}
+
+export type FreebuffSessionFailure =
+  | (FreebuffSessionFailureBase & {
+      type: 'http'
+      statusCode: number
+    })
+  | (FreebuffSessionFailureBase & {
+      type: 'timeout' | 'other'
+    })
+
+/**
+ * Shared state for the freebuff free session.
+ *
+ * The hook in `use-freebuff-session.ts` owns the poll loop and writes into
+ * this store; React components subscribe via selectors, and non-React code
+ * reads via `useFreebuffSessionStore.getState()`.
+ *
+ * Imperative session controls (force re-POST, mark superseded/ended) live on
+ * the module exports of `use-freebuff-session.ts` rather than on this store —
+ * that way callers don't need to null-check a "driver" slot whose lifetime
+ * is tied to the React tree.
+ */
+interface FreebuffSessionStore {
+  session: FreebuffSessionResponse | null
+  failure: FreebuffSessionFailure | null
+
+  setSession: (session: FreebuffSessionResponse | null) => void
+  setFailure: (failure: FreebuffSessionFailure | null) => void
+}
+
+export const useFreebuffSessionStore = create<FreebuffSessionStore>((set) => ({
+  session: null,
+  failure: null,
+  setSession: (session) => set({ session }),
+  setFailure: (failure) => set({ failure }),
+}))

package/src/state/login-store.ts

@@ -0,0 +1,150 @@
+import { create } from 'zustand'
+import { immer } from 'zustand/middleware/immer'
+
+export type LoginStoreState = {
+  loginUrl: string | null
+  loading: boolean
+  error: string | null
+  fingerprintId: string | null
+  fingerprintHash: string | null
+  expiresAt: string | null
+  isWaitingForEnter: boolean
+  hasOpenedBrowser: boolean
+  sheenPosition: number
+  copyMessage: string | null
+  justCopied: boolean
+  hasClickedLink: boolean
+}
+
+type LoginStoreActions = {
+  setLoginUrl: (
+    value: string | null | ((prev: string | null) => string | null),
+  ) => void
+  setLoading: (loading: boolean) => void
+  setError: (
+    value: string | null | ((prev: string | null) => string | null),
+  ) => void
+  setFingerprintId: (
+    value: string | null | ((prev: string | null) => string | null),
+  ) => void
+  setFingerprintHash: (
+    value: string | null | ((prev: string | null) => string | null),
+  ) => void
+  setExpiresAt: (
+    value: string | null | ((prev: string | null) => string | null),
+  ) => void
+  setIsWaitingForEnter: (waiting: boolean) => void
+  setHasOpenedBrowser: (opened: boolean) => void
+  setSheenPosition: (value: number | ((prev: number) => number)) => void
+  setCopyMessage: (
+    value: string | null | ((prev: string | null) => string | null),
+  ) => void
+  setJustCopied: (copied: boolean) => void
+  setHasClickedLink: (clicked: boolean) => void
+  resetLoginState: () => void
+}
+
+type LoginStore = LoginStoreState & LoginStoreActions
+
+const initialState: LoginStoreState = {
+  loginUrl: null,
+  loading: false,
+  error: null,
+  fingerprintId: null,
+  fingerprintHash: null,
+  expiresAt: null,
+  isWaitingForEnter: false,
+  hasOpenedBrowser: false,
+  sheenPosition: 0,
+  copyMessage: null,
+  justCopied: false,
+  hasClickedLink: false,
+}
+
+export const useLoginStore = create<LoginStore>()(
+  immer((set) => ({
+    ...initialState,
+
+    setLoginUrl: (value) =>
+      set((state) => {
+        state.loginUrl =
+          typeof value === 'function' ? value(state.loginUrl) : value
+      }),
+
+    setLoading: (loading) =>
+      set((state) => {
+        state.loading = loading
+      }),
+
+    setError: (value) =>
+      set((state) => {
+        state.error = typeof value === 'function' ? value(state.error) : value
+      }),
+
+    setFingerprintId: (value) =>
+      set((state) => {
+        state.fingerprintId =
+          typeof value === 'function' ? value(state.fingerprintId) : value
+      }),
+
+    setFingerprintHash: (value) =>
+      set((state) => {
+        state.fingerprintHash =
+          typeof value === 'function' ? value(state.fingerprintHash) : value
+      }),
+
+    setExpiresAt: (value) =>
+      set((state) => {
+        state.expiresAt =
+          typeof value === 'function' ? value(state.expiresAt) : value
+      }),
+
+    setIsWaitingForEnter: (waiting) =>
+      set((state) => {
+        state.isWaitingForEnter = waiting
+      }),
+
+    setHasOpenedBrowser: (opened) =>
+      set((state) => {
+        state.hasOpenedBrowser = opened
+      }),
+
+    setSheenPosition: (value) =>
+      set((state) => {
+        state.sheenPosition =
+          typeof value === 'function' ? value(state.sheenPosition) : value
+      }),
+
+    setCopyMessage: (value) =>
+      set((state) => {
+        state.copyMessage =
+          typeof value === 'function' ? value(state.copyMessage) : value
+      }),
+
+    setJustCopied: (copied) =>
+      set((state) => {
+        state.justCopied = copied
+      }),
+
+    setHasClickedLink: (clicked) =>
+      set((state) => {
+        state.hasClickedLink = clicked
+      }),
+
+    resetLoginState: () =>
+      set((state) => {
+        state.loginUrl = initialState.loginUrl
+        state.loading = initialState.loading
+        state.error = initialState.error
+        state.fingerprintId = initialState.fingerprintId
+        state.fingerprintHash = initialState.fingerprintHash
+        state.expiresAt = initialState.expiresAt
+        state.isWaitingForEnter = initialState.isWaitingForEnter
+        state.hasOpenedBrowser = initialState.hasOpenedBrowser
+        state.sheenPosition = initialState.sheenPosition
+        state.copyMessage = initialState.copyMessage
+        state.justCopied = initialState.justCopied
+        state.hasClickedLink = initialState.hasClickedLink
+      }),
+  })),
+)

package/src/state/message-block-store.ts

@@ -0,0 +1,149 @@
+import { enableMapSet } from 'immer'
+import { create } from 'zustand'
+import { immer } from 'zustand/middleware/immer'
+
+import type { FeedbackCategory } from '@anvil/common/constants/feedback'
+
+import type { AdResponse } from '../hooks/use-gravity-ad'
+import type { ChatMessage } from '../types/chat'
+import type { ChatTheme } from '../types/theme-system'
+import type { MarkdownPalette } from '../utils/markdown-renderer'
+
+// Every store that drafts a Map or Set through immer enables the plugin itself.
+// immer's Map/Set support is opt-in and lives on a PROCESS-GLOBAL registry, so
+// enabling it from one place far away (this used to happen in init-app) made a
+// store correct only once the app had booted: importing it directly threw
+// "[Immer] minified error nr: 0", and its tests passed only when some other file
+// happened to run first and enable the plugin. Doing it per store makes each one
+// correct on its own import, and makes a store that forgets fail the same way
+// everywhere instead of only outside the app. enableMapSet() is idempotent.
+enableMapSet()
+
+/**
+ * Context values that are updated by the Chat component and consumed by
+ * message rendering components (MessageWithAgents, AgentMessage, etc).
+ */
+export interface MessageBlockContext {
+  /** Active chat theme (colors, etc). */
+  theme: ChatTheme | null
+  /** Palette for markdown rendering. Null until Chat component initializes it. */
+  markdownPalette: MarkdownPalette | null
+  /** Message tree mapping parent message ID -> child agent messages. */
+  messageTree: Map<string, ChatMessage[]> | null
+  /** Whether the main agent is currently waiting for a response. */
+  isWaitingForResponse: boolean
+  /** Timer start time for the main agent stream, used for UI timers. */
+  timerStartTime: number | null
+  /** Available width for rendering message content. */
+  availableWidth: number
+  /**
+   * Ads to intersperse inside assistant responses, keyed by message id.
+   * Populated by the Chat component from the ads hook; empty when ads are
+   * disabled or hidden.
+   */
+  responseAds: Record<string, AdResponse[]>
+}
+
+/**
+ * Stable callback functions for message block interactions.
+ * These are set by the Chat component and consumed by message blocks.
+ */
+export interface MessageBlockCallbacks {
+  onToggleCollapsed: (id: string) => void
+  onBuildFast: () => void
+  onBuildMax: () => void
+  onBuildLite: () => void
+  onFeedback: (
+    messageId: string,
+    options?: {
+      category?: FeedbackCategory
+      footerMessage?: string
+      errors?: Array<{ id: string; message: string }>
+    },
+  ) => void
+  onCloseFeedback: () => void
+  /** Record a click on an interspersed response ad. */
+  onAdClick: (ad: AdResponse) => void
+  /** Record an impression for an interspersed response ad. */
+  onAdImpression: (ad: AdResponse) => void
+  /** Ensure the response has fetched ads for every currently eligible slot. */
+  onResponseAdsNeeded: (messageId: string, count: number) => void
+}
+
+interface MessageBlockStoreState {
+  context: MessageBlockContext
+  callbacks: MessageBlockCallbacks
+}
+
+interface MessageBlockStoreActions {
+  /**
+   * Batch update context values. Pass only the values you want to update.
+   *
+   * This is called from the Chat component whenever any of the dependent
+   * values (theme, markdownPalette, messageTree, etc) change.
+   */
+  setContext: (context: Partial<MessageBlockContext>) => void
+  /**
+   * Replace all callbacks at once. These are typically stable functions set
+   * up once when the Chat component mounts.
+   */
+  setCallbacks: (callbacks: MessageBlockCallbacks) => void
+  /**
+   * Reset the store to its initial state. Primarily used by tests.
+   */
+  reset: () => void
+}
+
+type MessageBlockStore = MessageBlockStoreState & MessageBlockStoreActions
+
+const noop = () => {}
+const noopFeedback: MessageBlockCallbacks['onFeedback'] = () => {}
+
+const initialContext: MessageBlockContext = {
+  theme: null,
+  markdownPalette: null,
+  messageTree: null,
+  isWaitingForResponse: false,
+  timerStartTime: null,
+  availableWidth: 80,
+  responseAds: {},
+}
+
+const initialCallbacks: MessageBlockCallbacks = {
+  onToggleCollapsed: noop,
+  onBuildFast: noop,
+  onBuildMax: noop,
+  onBuildLite: noop,
+  onFeedback: noopFeedback,
+  onCloseFeedback: noop,
+  onAdClick: noop,
+  onAdImpression: noop,
+  onResponseAdsNeeded: noop,
+}
+
+const initialState: MessageBlockStoreState = {
+  context: initialContext,
+  callbacks: initialCallbacks,
+}
+
+export const useMessageBlockStore = create<MessageBlockStore>()(
+  immer((set) => ({
+    ...initialState,
+
+    setContext: (updates) =>
+      set((state) => {
+        state.context = { ...state.context, ...updates }
+      }),
+
+    setCallbacks: (callbacks) =>
+      set((state) => {
+        state.callbacks = callbacks
+      }),
+
+    reset: () =>
+      set((state) => {
+        state.context = { ...initialContext }
+        state.callbacks = { ...initialCallbacks }
+      }),
+  })),
+)

package/src/state/publish-store.ts

@@ -0,0 +1,146 @@
+import { enableMapSet } from 'immer'
+import { create } from 'zustand'
+import { immer } from 'zustand/middleware/immer'
+
+// Drafts a Set (selectedAgentIds) through immer; see message-block-store for
+// why the store enables the plugin itself.
+enableMapSet()
+
+export type PublishStep = 'selection' | 'confirmation' | 'success' | 'error'
+
+export interface PublishSuccessResult {
+  publisherId: string
+  agents: Array<{
+    id: string
+    version: string
+    displayName: string
+  }>
+}
+
+export interface PublishErrorResult {
+  error: string
+  details?: string
+  hint?: string
+}
+
+interface PublishState {
+  publishMode: boolean
+  selectedAgentIds: Set<string>
+  searchQuery: string
+  currentStep: PublishStep
+  focusedIndex: number
+  isPublishing: boolean
+  successResult: PublishSuccessResult | null
+  errorResult: PublishErrorResult | null
+  /** Whether to include agents that spawn the selected agents (reverse dependencies) */
+  includeDependents: boolean
+}
+
+interface PublishActions {
+  openPublishMode: () => void
+  closePublish: () => void
+  toggleAgentSelection: (agentId: string) => void
+  setSearchQuery: (query: string) => void
+  goToConfirmation: () => void
+  goBackToSelection: () => void
+  setFocusedIndex: (index: number) => void
+  preSelectAgents: (agentIds: string[]) => void
+  setIsPublishing: (publishing: boolean) => void
+  setSuccessResult: (result: PublishSuccessResult) => void
+  setErrorResult: (result: PublishErrorResult) => void
+  setIncludeDependents: (include: boolean) => void
+  reset: () => void
+}
+
+type PublishStore = PublishState & PublishActions
+
+const createInitialState = (publishMode = false): PublishState => ({
+  publishMode,
+  selectedAgentIds: new Set(),
+  searchQuery: '',
+  currentStep: 'selection',
+  focusedIndex: 0,
+  isPublishing: false,
+  successResult: null,
+  errorResult: null,
+  includeDependents: false,
+})
+
+const initialState: PublishState = createInitialState()
+
+export const usePublishStore = create<PublishStore>()(
+  immer((set) => ({
+    ...initialState,
+
+    openPublishMode: () => set(() => createInitialState(true)),
+
+    closePublish: () => set(() => createInitialState(false)),
+
+    toggleAgentSelection: (agentId) =>
+      set((state) => {
+        if (state.selectedAgentIds.has(agentId)) {
+          state.selectedAgentIds.delete(agentId)
+        } else {
+          state.selectedAgentIds.add(agentId)
+        }
+      }),
+
+    setSearchQuery: (query) =>
+      set((state) => {
+        state.searchQuery = query
+        state.focusedIndex = 0 // Reset focus when search changes
+      }),
+
+    goToConfirmation: () =>
+      set((state) => {
+        state.currentStep = 'confirmation'
+        state.focusedIndex = 0
+      }),
+
+    goBackToSelection: () =>
+      set((state) => {
+        state.currentStep = 'selection'
+        state.focusedIndex = 0
+      }),
+
+    setFocusedIndex: (index) =>
+      set((state) => {
+        state.focusedIndex = index
+      }),
+
+    preSelectAgents: (agentIds) =>
+      set(() => {
+        const nextState = createInitialState(true)
+        nextState.selectedAgentIds = new Set(agentIds)
+        // Stay on selection step so user can review/modify before confirming
+        nextState.currentStep = 'selection'
+        return nextState
+      }),
+
+    setIsPublishing: (publishing) =>
+      set((state) => {
+        state.isPublishing = publishing
+      }),
+
+    setSuccessResult: (result) =>
+      set((state) => {
+        state.successResult = result
+        state.currentStep = 'success'
+        state.isPublishing = false
+      }),
+
+    setErrorResult: (result) =>
+      set((state) => {
+        state.errorResult = result
+        state.currentStep = 'error'
+        state.isPublishing = false
+      }),
+
+    setIncludeDependents: (include) =>
+      set((state) => {
+        state.includeDependents = include
+      }),
+
+    reset: () => set(() => createInitialState(false)),
+  })),
+)

package/src/state/queue-panel-store.ts

@@ -0,0 +1,26 @@
+import { create } from 'zustand'
+import { immer } from 'zustand/middleware/immer'
+
+interface QueuePanelState {
+  /** The queue editor takes the composer's place while open, the way the
+   *  review screen does — the queue is what the user is typing about. */
+  queuePanelOpen: boolean
+  openQueuePanel: () => void
+  closeQueuePanel: () => void
+}
+
+export const useQueuePanelStore = create<QueuePanelState>()(
+  immer((set) => ({
+    queuePanelOpen: false,
+    openQueuePanel: () => {
+      set((state) => {
+        state.queuePanelOpen = true
+      })
+    },
+    closeQueuePanel: () => {
+      set((state) => {
+        state.queuePanelOpen = false
+      })
+    },
+  })),
+)

package/src/state/review-store.ts

@@ -0,0 +1,24 @@
+import { create } from 'zustand'
+import { immer } from 'zustand/middleware/immer'
+
+interface ReviewState {
+  reviewMode: boolean
+  openReviewScreen: () => void
+  closeReviewScreen: () => void
+}
+
+export const useReviewStore = create<ReviewState>()(
+  immer((set) => ({
+    reviewMode: false,
+    openReviewScreen: () => {
+      set((state) => {
+        state.reviewMode = true
+      })
+    },
+    closeReviewScreen: () => {
+      set((state) => {
+        state.reviewMode = false
+      })
+    },
+  })),
+)

package/src/testing/env.ts

@@ -0,0 +1,46 @@
+import { createTestBaseEnv } from '@anvil/common/testing-env-process'
+
+import type { CliEnv } from '../types/env'
+
+/**
+ * Test-only CLI env builder.
+ */
+export const createTestCliEnv = (overrides: Partial<CliEnv> = {}): CliEnv => ({
+  ...createTestBaseEnv(),
+
+  // CLI-specific defaults
+  SSH_CLIENT: undefined,
+  SSH_TTY: undefined,
+  SSH_CONNECTION: undefined,
+  KITTY_WINDOW_ID: undefined,
+  SIXEL_SUPPORT: undefined,
+  ZED_NODE_ENV: undefined,
+  ZED_TERM: undefined,
+  ZED_SHELL: undefined,
+  COLORTERM: undefined,
+  VSCODE_THEME_KIND: undefined,
+  VSCODE_COLOR_THEME_KIND: undefined,
+  VSCODE_GIT_IPC_HANDLE: undefined,
+  VSCODE_PID: undefined,
+  VSCODE_CWD: undefined,
+  VSCODE_NLS_CONFIG: undefined,
+  CURSOR_PORT: undefined,
+  CURSOR: undefined,
+  JETBRAINS_REMOTE_RUN: undefined,
+  IDEA_INITIAL_DIRECTORY: undefined,
+  IDE_CONFIG_DIR: undefined,
+  JB_IDE_CONFIG_DIR: undefined,
+  VISUAL: undefined,
+  EDITOR: undefined,
+  ANVIL_CLI_EDITOR: undefined,
+  ANVIL_EDITOR: undefined,
+  OPEN_TUI_THEME: undefined,
+  OPENTUI_THEME: undefined,
+  ANVIL_IS_BINARY: undefined,
+  ANVIL_CLI_VERSION: undefined,
+  ANVIL_CLI_TARGET: undefined,
+  ANVIL_RG_PATH: undefined,
+  ANVIL_SCROLL_MULTIPLIER: undefined,
+  FREEBUFF_MODE: undefined,
+  ...overrides,
+})

package/src/types/chat-state.ts

@@ -0,0 +1,15 @@
+/**
+ * Type definitions for chat state management.
+ * Re-exports types from the extracted hooks for convenience.
+ */
+
+// Re-export types from the extracted hooks
+export type { UseChatStateReturn } from '../hooks/use-chat-state'
+
+export type {
+  UseChatMessagesOptions,
+  UseChatMessagesReturn,
+} from '../hooks/use-chat-messages'
+
+// Re-export StreamStatus from use-message-queue for convenience
+export type { StreamStatus } from '../hooks/use-message-queue'