@alumbwe/anvil 1.0.0

package/src/utils/send-message-helpers.ts

@@ -0,0 +1,210 @@
+/**
+ * Message-level helpers for send-message logic.
+ * These functions operate on ChatMessage objects, not raw blocks.
+ * For block-level operations, import from message-block-helpers.ts or block-operations.ts.
+ */
+
+import { has } from 'lodash'
+
+import { AI_MESSAGE_ID_PREFIX, generateAiMessageId } from './ai-message-id'
+import { markRunningAgentsAsCancelled } from './block-operations'
+import { shouldHideAgent } from './constants'
+import { formatTimestamp } from './helpers'
+import {
+  appendInterruptionNotice,
+  autoCollapseBlocks,
+  createAgentBlock,
+  stripHiddenAgentBlocks,
+} from './message-block-helpers'
+
+import type { AgentMode } from './constants'
+import type { ChatMessage, ContentBlock } from '../types/chat'
+
+// -----------------------------------------------------------------------------
+// Message Creation Helpers
+// -----------------------------------------------------------------------------
+
+export const createModeDividerMessage = (
+  agentMode: AgentMode,
+): ChatMessage => ({
+  id: `divider-${Date.now()}`,
+  variant: 'ai',
+  content: '',
+  blocks: [
+    {
+      type: 'mode-divider',
+      mode: agentMode,
+    },
+  ],
+  timestamp: formatTimestamp(),
+})
+
+export const createAiMessageShell = (messageId: string): ChatMessage => ({
+  id: messageId,
+  variant: 'ai',
+  content: '',
+  blocks: [],
+  timestamp: formatTimestamp(),
+  metadata: { allowInlineAds: true },
+})
+
+export const createErrorMessage = (content: string): ChatMessage => ({
+  id: `error-${Date.now()}`,
+  variant: 'error',
+  content,
+  timestamp: formatTimestamp(),
+})
+
+// Re-exported (imported above) from a dependency-free leaf module so lightweight
+// consumers can import the id prefix without dragging in this helper graph.
+// Shared with sanitizeRestoredMessages so the two can't silently drift apart.
+export { AI_MESSAGE_ID_PREFIX, generateAiMessageId }
+
+/**
+ * A restored chat may contain an AI response that was still streaming when the
+ * process died (checkpoint saves persist in-flight turns). Mark it complete
+ * with an interruption notice so it doesn't render as still in progress.
+ * Only touches streamed response shells (ids from generateAiMessageId) —
+ * other 'ai'-variant messages (mode dividers, system notices, bash results)
+ * are never marked complete by design.
+ *
+ * Also drops hidden agent blocks (e.g. context-pruner) that were persisted
+ * before live streams filtered them.
+ */
+export const sanitizeRestoredMessages = (
+  messages: ChatMessage[],
+): ChatMessage[] =>
+  messages.map((message) => {
+    let restoredMessage = message
+    if (message.metadata?.allowInlineAds) {
+      const { allowInlineAds: _, ...metadata } = message.metadata
+      restoredMessage = { ...message, metadata }
+    }
+
+    if (restoredMessage.blocks) {
+      const blocks = stripHiddenAgentBlocks(restoredMessage.blocks)
+      if (blocks !== restoredMessage.blocks) {
+        restoredMessage = { ...restoredMessage, blocks }
+      }
+    }
+
+    if (
+      restoredMessage.variant !== 'ai' ||
+      !restoredMessage.id.startsWith(AI_MESSAGE_ID_PREFIX) ||
+      restoredMessage.isComplete
+    ) {
+      return restoredMessage
+    }
+    try {
+      return {
+        ...restoredMessage,
+        isComplete: true,
+        blocks: appendInterruptionNotice(
+          markRunningAgentsAsCancelled(restoredMessage.blocks ?? []),
+        ),
+      }
+    } catch {
+      // Corrupted persisted blocks (e.g. null entries) must not prevent the
+      // chat from restoring; keep the message as-is.
+      return { ...restoredMessage, isComplete: true }
+    }
+  })
+
+// -----------------------------------------------------------------------------
+// Auto-Collapse Logic
+// -----------------------------------------------------------------------------
+
+export const autoCollapsePreviousMessages = (
+  messages: ChatMessage[],
+  currentAiMessageId: string,
+): ChatMessage[] =>
+  messages.map((message) => {
+    if (message.id === currentAiMessageId) {
+      return message
+    }
+
+    if (message.variant === 'agent') {
+      const userOpened = message.metadata?.userOpened ?? false
+      return userOpened
+        ? message
+        : {
+            ...message,
+            metadata: {
+              ...message.metadata,
+              isCollapsed: true,
+            },
+          }
+    }
+
+    if (!message.blocks) {
+      return message
+    }
+
+    return {
+      ...message,
+      blocks: autoCollapseBlocks(message.blocks),
+    }
+  })
+
+// -----------------------------------------------------------------------------
+// Spawn Agents Helpers
+// -----------------------------------------------------------------------------
+
+export const createSpawnAgentBlocks = (
+  toolCallId: string,
+  agents: Array<{ agent_type?: string; prompt?: string }>,
+): ContentBlock[] =>
+  agents
+    .map((agent, index) => ({ agent, index }))
+    .filter(({ agent }) => !shouldHideAgent(agent.agent_type || ''))
+    .map(({ agent, index }) =>
+      createAgentBlock({
+        agentId: `${toolCallId}-${index}`,
+        agentType: agent.agent_type || '',
+        prompt: agent.prompt,
+      }),
+    )
+
+export const isSpawnAgentsResult = (outputValue: unknown): boolean =>
+  Array.isArray(outputValue) &&
+  outputValue.some((v: unknown) => {
+    if (typeof v !== 'object' || v === null) return false
+    return has(v, 'agentName') || has(v, 'agentType')
+  })
+
+// -----------------------------------------------------------------------------
+// Message Completion Helpers
+// -----------------------------------------------------------------------------
+
+export const markMessageComplete = (
+  message: ChatMessage,
+  options?: {
+    completionTime?: string
+    credits?: number
+    runState?: unknown
+  },
+): ChatMessage => {
+  const metadata = {
+    ...(message.metadata ?? {}),
+    ...(options?.runState ? { runState: options.runState } : {}),
+  }
+  return {
+    ...message,
+    isComplete: true,
+    ...(options?.completionTime
+      ? { completionTime: options.completionTime }
+      : {}),
+    ...(options?.credits !== undefined ? { credits: options.credits } : {}),
+    metadata,
+  }
+}
+
+export const setMessageError = (
+  message: ChatMessage,
+  errorContent: string,
+): ChatMessage => ({
+  ...message,
+  content: errorContent,
+  blocks: undefined,
+  isComplete: true,
+})

package/src/utils/send-message-timer.ts

@@ -0,0 +1,110 @@
+// Lightweight timer wrapper so UI can react to start/stop events.
+import type { ElapsedTimeTracker } from '../hooks/use-elapsed-time'
+
+export type SendMessageTimerEvent =
+  | {
+      type: 'start'
+      startedAt: number
+      messageId: string
+      agentId?: string
+    }
+  | {
+      type: 'stop'
+      startedAt: number
+      finishedAt: number
+      elapsedMs: number
+      messageId: string
+      agentId?: string
+      outcome: 'success' | 'error' | 'aborted'
+    }
+
+export type SendMessageTimerOutcome = 'success' | 'error' | 'aborted'
+
+export interface SendMessageTimerController {
+  start: (messageId: string) => void
+  stop: (outcome: SendMessageTimerOutcome) => {
+    finishedAt: number
+    elapsedMs: number
+  } | null
+  pause: () => void
+  resume: () => void
+  isActive: () => boolean
+}
+
+export interface SendMessageTimerControllerOptions {
+  mainAgentTimer: ElapsedTimeTracker
+  onTimerEvent: (event: SendMessageTimerEvent) => void
+  agentId?: string
+  now?: () => number
+}
+
+export const createSendMessageTimerController = (
+  options: SendMessageTimerControllerOptions,
+): SendMessageTimerController => {
+  const {
+    mainAgentTimer,
+    onTimerEvent,
+    agentId,
+    now = () => Date.now(),
+  } = options
+
+  let timerStartedAt: number | null = null
+  let timerMessageId: string | null = null
+  let timerActive = false
+
+  const start = (messageId: string) => {
+    if (timerActive) {
+      return
+    }
+    timerActive = true
+    timerMessageId = messageId
+    timerStartedAt = now()
+    mainAgentTimer.start()
+    const startEvent: SendMessageTimerEvent = {
+      type: 'start',
+      startedAt: timerStartedAt,
+      messageId,
+    }
+    if (agentId) {
+      startEvent.agentId = agentId
+    }
+    onTimerEvent(startEvent)
+  }
+
+  const stop = (outcome: SendMessageTimerOutcome) => {
+    if (!timerActive || timerStartedAt == null || !timerMessageId) {
+      return null
+    }
+    timerActive = false
+    mainAgentTimer.stop()
+    const finishedAt = now()
+    const elapsedMs = Math.max(0, finishedAt - timerStartedAt)
+    const stopEvent: SendMessageTimerEvent = {
+      type: 'stop',
+      startedAt: timerStartedAt,
+      finishedAt,
+      elapsedMs,
+      messageId: timerMessageId,
+      outcome,
+    }
+    if (agentId) {
+      stopEvent.agentId = agentId
+    }
+    onTimerEvent(stopEvent)
+    timerStartedAt = null
+    timerMessageId = null
+    return { finishedAt, elapsedMs }
+  }
+
+  const pause = () => {
+    mainAgentTimer.pause()
+  }
+
+  const resume = () => {
+    mainAgentTimer.resume()
+  }
+
+  const isActive = () => timerActive
+
+  return { start, stop, pause, resume, isActive }
+}

package/src/utils/settings.ts

@@ -0,0 +1,226 @@
+import fs from 'fs'
+import path from 'path'
+
+import {
+  FREEBUFF_MODELS,
+  isFreebuffModelId,
+  migrateSupersededFreebuffModelPreference,
+} from '@anvil/common/constants/freebuff-models'
+
+import { getConfigDir } from './auth'
+import { AGENT_MODES } from './constants'
+import { logger } from './logger'
+
+import type { AgentMode } from './constants'
+
+const DEFAULT_SETTINGS: Settings = {
+  mode: 'DEFAULT' as const,
+  adsEnabled: true,
+}
+
+// Note: The old FREE mode has been renamed back to LITE; migrate on load.
+
+/**
+ * Settings schema - add new settings here as the product evolves
+ */
+export interface Settings {
+  mode?: AgentMode
+  adsEnabled?: boolean
+  /** Last model the user picked in the freebuff model selector. Restored on
+   *  next freebuff launch so users land in the queue for their preferred
+   *  model without re-picking. Persisted as the canonical model id. */
+  freebuffModel?: string
+  /** @deprecated Use server-side fallbackToALaCarte setting instead */
+  alwaysUseALaCarte?: boolean
+  /** @deprecated Use server-side fallbackToALaCarte setting instead */
+  fallbackToALaCarte?: boolean
+  /** Set once the user has submitted their first prompt. Used to gate the
+   *  first-time onboarding suggested prompts so they only show to brand-new
+   *  users and quietly retire afterwards. */
+  hasSubmittedFirstPrompt?: boolean
+}
+
+/**
+ * Get the settings file path
+ */
+export const getSettingsPath = (): string => {
+  return path.join(getConfigDir(), 'settings.json')
+}
+
+/**
+ * Ensure the config directory exists, creating it if necessary
+ */
+const ensureConfigDirExists = (): void => {
+  const configDir = getConfigDir()
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true })
+  }
+}
+
+/**
+ * Load all settings from file system
+ * @returns The saved settings object, with defaults for missing values
+ */
+export const loadSettings = (): Settings => {
+  const settingsPath = getSettingsPath()
+
+  if (!fs.existsSync(settingsPath)) {
+    ensureConfigDirExists()
+    // Create default settings file
+    fs.writeFileSync(settingsPath, JSON.stringify(DEFAULT_SETTINGS, null, 2))
+    return DEFAULT_SETTINGS
+  }
+
+  try {
+    const settingsFile = fs.readFileSync(settingsPath, 'utf8')
+    const parsed = JSON.parse(settingsFile)
+    return validateSettings(parsed)
+  } catch (error) {
+    logger.debug(
+      {
+        error: error instanceof Error ? error.message : String(error),
+      },
+      'Error reading settings',
+    )
+    return {}
+  }
+}
+
+/**
+ * Validate and sanitize settings from file
+ */
+const validateSettings = (parsed: unknown): Settings => {
+  if (typeof parsed !== 'object' || parsed === null) {
+    return {}
+  }
+
+  const settings: Settings = {}
+  const obj = parsed as Record<string, unknown>
+
+  // Validate mode; migrate the previously-saved 'FREE' value to 'LITE'.
+  if (typeof obj.mode === 'string') {
+    const normalized = obj.mode === 'FREE' ? 'LITE' : obj.mode
+    if (AGENT_MODES.includes(normalized as AgentMode)) {
+      settings.mode = normalized as AgentMode
+    }
+  }
+
+  // Validate adsEnabled
+  if (typeof obj.adsEnabled === 'boolean') {
+    settings.adsEnabled = obj.adsEnabled
+  }
+
+  // Validate freebuffModel against the current picker catalog. Server support
+  // may intentionally outlive client visibility during a staged model
+  // retirement, but an updated client must not restore a retired selection.
+  if (
+    typeof obj.freebuffModel === 'string' &&
+    isFreebuffModelId(obj.freebuffModel)
+  ) {
+    settings.freebuffModel = obj.freebuffModel
+  }
+
+  // Steer off a model that has since been superseded (MiniMax M3, MiMo 2.5 →
+  // V4 Flash) on EVERY load, so each new freebuff session starts
+  // on the better model instead of a pick made before it existed. Picking a
+  // superseded model still works for the session you are in; it just stops
+  // being what the next launch opens on.
+  const replacement = migrateSupersededFreebuffModelPreference(
+    settings.freebuffModel,
+    FREEBUFF_MODELS.map((model) => model.id),
+  )
+  if (replacement) settings.freebuffModel = replacement
+
+  // Validate alwaysUseALaCarte (legacy)
+  if (typeof obj.alwaysUseALaCarte === 'boolean') {
+    settings.alwaysUseALaCarte = obj.alwaysUseALaCarte
+  }
+
+  // Validate fallbackToALaCarte (legacy)
+  if (typeof obj.fallbackToALaCarte === 'boolean') {
+    settings.fallbackToALaCarte = obj.fallbackToALaCarte
+  }
+
+  // Validate hasSubmittedFirstPrompt
+  if (typeof obj.hasSubmittedFirstPrompt === 'boolean') {
+    settings.hasSubmittedFirstPrompt = obj.hasSubmittedFirstPrompt
+  }
+
+  return settings
+}
+
+/**
+ * Save settings to file system (merges with existing settings)
+ */
+export const saveSettings = (newSettings: Partial<Settings>): void => {
+  const settingsPath = getSettingsPath()
+
+  try {
+    ensureConfigDirExists()
+
+    // Load existing settings and merge
+    const existingSettings = loadSettings()
+    const mergedSettings = { ...existingSettings, ...newSettings }
+
+    fs.writeFileSync(settingsPath, JSON.stringify(mergedSettings, null, 2))
+  } catch (error) {
+    logger.debug(
+      {
+        error: error instanceof Error ? error.message : String(error),
+      },
+      'Error saving settings',
+    )
+  }
+}
+
+/**
+ * Load the saved agent mode preference
+ * @returns The saved mode, or 'DEFAULT' if not found or invalid
+ */
+export const loadModePreference = (): AgentMode => {
+  const settings = loadSettings()
+  return settings.mode ?? 'DEFAULT'
+}
+
+/**
+ * Save the agent mode preference
+ */
+export const saveModePreference = (mode: AgentMode): void => {
+  saveSettings({ mode })
+}
+
+/**
+ * Load the saved freebuff model preference. Returns undefined if none is
+ * saved yet — callers should fall back to DEFAULT_FREEBUFF_MODEL_ID.
+ */
+export const loadFreebuffModelPreference = (): string | undefined => {
+  return loadSettings().freebuffModel
+}
+
+/**
+ * Save an ordinary freebuff picker preference so the next launch defaults to
+ * it. Referral-only and retired session models are deliberately not
+ * rememberable: they may be valid for the current session without being
+ * selectable on the next landing screen.
+ */
+export const saveFreebuffModelPreference = (model: string): void => {
+  if (!isFreebuffModelId(model)) return
+  saveSettings({ freebuffModel: model })
+}
+
+/**
+ * Whether the user has ever submitted a prompt. False only for brand-new
+ * users, who get the onboarding suggested prompts on an empty chat.
+ */
+export const hasSubmittedFirstPrompt = (): boolean => {
+  return loadSettings().hasSubmittedFirstPrompt === true
+}
+
+/**
+ * Mark that the user has submitted their first prompt, retiring the onboarding
+ * suggested prompts on future launches. Idempotent.
+ */
+export const markFirstPromptSubmitted = (): void => {
+  if (loadSettings().hasSubmittedFirstPrompt === true) return
+  saveSettings({ hasSubmittedFirstPrompt: true })
+}

package/src/utils/skill-registry.ts

@@ -0,0 +1,94 @@
+import { loadSkills as sdkLoadSkills } from '@anvil/sdk'
+
+import { getProjectRoot } from '../project-files'
+import { logger } from './logger'
+
+import type { SkillDefinition, SkillsMap } from '@anvil/common/types/skill'
+
+// ============================================================================
+// Skills cache (loaded via SDK at startup)
+// ============================================================================
+
+let skillsCache: SkillsMap = {}
+
+/**
+ * Initialize the skill registry by loading skills via the SDK.
+ * This must be called at CLI startup.
+ * 
+ * Skills are loaded from:
+ * - ~/.agents/skills/ (global)
+ * - {projectRoot}/.agents/skills/ (project, overrides global)
+ */
+export async function initializeSkillRegistry(): Promise<void> {
+  const cwd = getProjectRoot() || process.cwd()
+
+  try {
+    // Load skills from both global (~/.agents/skills) and project directories
+    // The SDK handles merging, with project skills overriding global ones
+    skillsCache = await sdkLoadSkills({
+      cwd,
+      verbose: false,
+    })
+  } catch (error) {
+    logger.warn({ error }, 'Failed to load skills')
+    skillsCache = {}
+  }
+}
+
+// ============================================================================
+// Skills access
+// ============================================================================
+
+/**
+ * Get all loaded skills.
+ */
+export function getLoadedSkills(): SkillsMap {
+  return skillsCache
+}
+
+/**
+ * Get a skill by name.
+ */
+export function getSkillByName(name: string): SkillDefinition | undefined {
+  return skillsCache[name]
+}
+
+/**
+ * Get the number of loaded skills.
+ */
+export function getSkillCount(): number {
+  return Object.keys(skillsCache).length
+}
+
+// ============================================================================
+// UI/Display utilities
+// ============================================================================
+
+/**
+ * Get a message describing loaded skills for display.
+ */
+export function getLoadedSkillsMessage(): string | null {
+  const skills = Object.values(skillsCache)
+
+  if (skills.length === 0) {
+    return null
+  }
+
+  const header = `Loaded ${skills.length} skill${skills.length === 1 ? '' : 's'}`
+  const skillList = skills
+    .map((skill) => `  - ${skill.name}: ${skill.description.slice(0, 60)}${skill.description.length > 60 ? '...' : ''}`)
+    .join('\n')
+
+  return `${header}\n${skillList}`
+}
+
+// ============================================================================
+// Testing utilities
+// ============================================================================
+
+/**
+ * Clear cached skills. Intended for test scenarios.
+ */
+export function __resetSkillRegistryForTests(): void {
+  skillsCache = {}
+}

package/src/utils/spawn-agent-matcher.ts

@@ -0,0 +1,55 @@
+import { getAgentBaseName, moveSpawnAgentBlock } from './message-block-helpers'
+
+import type { SpawnAgentInfo } from '../hooks/stream-state'
+import type { ContentBlock } from '../types/chat'
+
+export interface SpawnAgentMatch {
+  tempId: string
+  info: SpawnAgentInfo
+}
+
+export const findMatchingSpawnAgent = (
+  spawnAgentsMap: Map<string, SpawnAgentInfo>,
+  eventAgentType: string,
+): SpawnAgentMatch | null => {
+  const eventBaseName = getAgentBaseName(eventAgentType || '')
+
+  for (const [tempId, info] of spawnAgentsMap.entries()) {
+    const storedBaseName = getAgentBaseName(info.agentType || '')
+    if (eventBaseName === storedBaseName) {
+      return { tempId, info }
+    }
+  }
+
+  return null
+}
+
+export const resolveSpawnAgentToReal = (options: {
+  blocks: ContentBlock[]
+  match: SpawnAgentMatch
+  realAgentId: string
+  realAgentType?: string
+  parentAgentId?: string
+  params?: Record<string, unknown>
+  prompt?: string
+}): ContentBlock[] => {
+  const {
+    blocks,
+    match,
+    realAgentId,
+    realAgentType,
+    parentAgentId,
+    params: agentParams,
+    prompt,
+  } = options
+
+  return moveSpawnAgentBlock(
+    blocks,
+    match.tempId,
+    realAgentId,
+    parentAgentId,
+    agentParams,
+    prompt,
+    realAgentType,
+  )
+}