@alumbwe/anvil 1.0.0

package/src/utils/think-tag-parser.ts

@@ -0,0 +1,95 @@
+/**
+ * Parses <think>...</think> tags from text and splits into segments.
+ * Handles streaming scenarios where tags may be incomplete.
+ */
+
+export const THINK_OPEN_TAG = '<think>'
+export const THINK_CLOSE_TAG = '</think>'
+
+export type ThinkSegment = {
+  type: 'text' | 'thinking'
+  content: string
+}
+
+/**
+ * Possible partial tag prefixes that we should buffer.
+ * These are prefixes that could become a complete tag with more input.
+ */
+const PARTIAL_OPEN_PREFIXES = ['<', '<t', '<th', '<thi', '<thin', '<think']
+const PARTIAL_CLOSE_PREFIXES = ['</', '</t', '</th', '</thi', '</thin', '</think']
+
+/**
+ * Check if text ends with a potential partial tag that we should buffer.
+ * Returns the length of the partial tag suffix, or 0 if none.
+ */
+export function getPartialTagLength(text: string): number {
+  // Check for partial closing tag first (longer prefixes)
+  for (const prefix of PARTIAL_CLOSE_PREFIXES) {
+    if (text.endsWith(prefix)) {
+      return prefix.length
+    }
+  }
+  // Check for partial opening tag
+  for (const prefix of PARTIAL_OPEN_PREFIXES) {
+    if (text.endsWith(prefix)) {
+      return prefix.length
+    }
+  }
+  return 0
+}
+
+/**
+ * Parse text for think tags and return segments.
+ * This handles complete tags only - partial tags at the end should be
+ * handled by the caller using getPartialTagLength.
+ */
+export function parseThinkTags(text: string): ThinkSegment[] {
+  if (!text) {
+    return []
+  }
+
+  const segments: ThinkSegment[] = []
+  let remaining = text
+  let insideThink = false
+
+  while (remaining.length > 0) {
+    if (insideThink) {
+      // Look for closing tag
+      const closeIdx = remaining.indexOf(THINK_CLOSE_TAG)
+      if (closeIdx === -1) {
+        // No closing tag found - all remaining is thinking content
+        if (remaining.length > 0) {
+          segments.push({ type: 'thinking', content: remaining })
+        }
+        break
+      }
+      // Content before closing tag is thinking
+      if (closeIdx > 0) {
+        segments.push({ type: 'thinking', content: remaining.slice(0, closeIdx) })
+      }
+      remaining = remaining.slice(closeIdx + THINK_CLOSE_TAG.length)
+      insideThink = false
+    } else {
+      // Look for opening tag
+      const openIdx = remaining.indexOf(THINK_OPEN_TAG)
+      if (openIdx === -1) {
+        // No opening tag found - all remaining is regular text
+        if (remaining.length > 0) {
+          segments.push({ type: 'text', content: remaining })
+        }
+        break
+      }
+      // Content before opening tag is regular text
+      if (openIdx > 0) {
+        segments.push({ type: 'text', content: remaining.slice(0, openIdx) })
+      }
+      remaining = remaining.slice(openIdx + THINK_OPEN_TAG.length)
+      insideThink = true
+    }
+  }
+
+  return segments
+}
+
+// Note: isThinkingOpen and mergeSegments were removed as they are not currently used.
+// They can be added back if needed for future functionality.

package/src/utils/time-format.ts

@@ -0,0 +1,21 @@
+import { formatTimeUntil } from '@anvil/common/util/dates'
+
+/**
+ * Format time until reset in human-readable form.
+ * @param resetDate - The date when the quota/resource resets
+ * @returns Human-readable string like "2h 30m" or "45m"
+ */
+export const formatResetTime = (resetDate: Date | null): string => {
+  if (!resetDate) return ''
+  return formatTimeUntil(resetDate, { fallback: 'now' })
+}
+
+/**
+ * Format time until reset in human-readable form, including days.
+ * @param resetDate - The date when the quota/resource resets
+ * @returns Human-readable string like "4d 7h" or "2h 30m"
+ */
+export const formatResetTimeLong = (resetDate: Date | string | null): string => {
+  if (!resetDate) return ''
+  return formatTimeUntil(resetDate, { fallback: 'now' })
+}

package/src/utils/trace-writer.ts

@@ -0,0 +1,162 @@
+import { appendFileSync, mkdirSync } from 'fs'
+import path, { dirname } from 'path'
+
+import { IS_DEV } from '@anvil/common/env'
+
+import { getCliEnv } from './env'
+import { getCurrentChatDir, getProjectRoot } from '../project-files'
+
+import type { TraceWriter } from '@anvil/common/types/contracts/trace'
+import type { Message } from '@anvil/common/types/messages/anvil-message'
+
+const TRACE_FILENAME = 'trace.jsonl'
+
+/**
+ * Stringify a trace record, breaking true cycles only (shared non-cyclic
+ * references are preserved). Traced messages carry tool content that can
+ * smuggle a cyclic reference in; a throw here would silently kill the trace
+ * line.
+ */
+function stringifyTraceRecord(record: Record<string, unknown>): string {
+  const stack: unknown[] = []
+  return JSON.stringify(record, function (this: unknown, _key, value) {
+    if (stack.length > 0) {
+      const thisPos = stack.indexOf(this)
+      if (thisPos !== -1) {
+        stack.splice(thisPos + 1)
+      } else {
+        stack.push(this)
+      }
+      if (typeof value === 'object' && value !== null && stack.includes(value)) {
+        return '[Circular]'
+      }
+    } else {
+      stack.push(value)
+    }
+    return value
+  })
+}
+
+type AgentTraceState = {
+  /** Roles of messages already written, in order. Used to detect history
+   * rewrites (compaction/expiry) without holding onto message objects. */
+  writtenRoles: string[]
+  system: string | undefined
+}
+
+/**
+ * Returns whether trace writing is enabled: always in dev, opt-in via
+ * ANVIL_TRACE=1 in production builds (so users don't pay disk for a second
+ * copy of their conversation by default).
+ */
+export function isTraceEnabled(): boolean {
+  if (IS_DEV) return true
+  // Same accepted values as ANVIL_FULL_TELEMETRY (see analytics-sampling)
+  const flag = getCliEnv().ANVIL_TRACE
+  return flag === '1' || flag === 'true' || flag === 'yes'
+}
+
+function getTraceFilePath(): string | null {
+  try {
+    return IS_DEV
+      ? path.join(getProjectRoot(), 'debug', TRACE_FILENAME)
+      : path.join(getCurrentChatDir(), TRACE_FILENAME)
+  } catch {
+    return null // No project root set yet
+  }
+}
+
+/**
+ * Create a TraceWriter that appends agent message histories to trace.jsonl —
+ * one message per line, each written exactly once.
+ *
+ * In dev the trace goes to <projectRoot>/debug/trace.jsonl (next to
+ * cli.jsonl); otherwise to the current chat directory. Returns undefined when
+ * tracing is disabled.
+ *
+ * History rewrites (compaction, message expiry) are detected by comparing the
+ * role sequence of the incoming history against what was already written; on
+ * mismatch a `history_rewritten` marker line is appended followed by the new
+ * history. Content-only edits that preserve the role sequence are not
+ * re-traced — acceptable for a debug trace.
+ */
+export function createTraceWriter(
+  resolveTraceFilePath: () => string | null = getTraceFilePath,
+): TraceWriter | undefined {
+  if (!isTraceEnabled()) {
+    return undefined
+  }
+
+  const agentStates = new Map<string, AgentTraceState>()
+  let ensuredDir: string | undefined
+
+  return {
+    recordStep: ({
+      agentId,
+      agentType,
+      runId,
+      userInputId,
+      step,
+      system,
+      messages,
+    }) => {
+      const state = agentStates.get(agentId) ?? {
+        writtenRoles: [],
+        system: undefined,
+      }
+      const base = { agentId, agentType, runId, userInputId, step }
+      const timestamp = new Date().toISOString()
+      const lines: string[] = []
+      const appendLine = (record: Record<string, unknown>): void => {
+        lines.push(stringifyTraceRecord({ timestamp, ...record }))
+      }
+
+      const rewritten =
+        messages.length < state.writtenRoles.length ||
+        state.writtenRoles.some((role, i) => messages[i]?.role !== role)
+      if (rewritten) {
+        appendLine({
+          ...base,
+          type: 'history_rewritten',
+          previousMessageCount: state.writtenRoles.length,
+          messageCount: messages.length,
+        })
+        state.writtenRoles = []
+      }
+
+      if (system !== undefined && system !== state.system) {
+        appendLine({ ...base, type: 'system', system })
+        state.system = system
+      }
+
+      for (let i = state.writtenRoles.length; i < messages.length; i++) {
+        const message = messages[i] as Message
+        appendLine({
+          ...base,
+          type: 'message',
+          index: i,
+          message,
+        })
+      }
+
+      state.writtenRoles = messages.map((m) => m.role)
+      agentStates.set(agentId, state)
+
+      if (lines.length === 0) return
+      // Resolve the path per step (not cached for the writer's lifetime: the
+      // current chat directory changes when the user starts a new chat).
+      const filePath = resolveTraceFilePath()
+      if (!filePath) return
+      try {
+        const dir = dirname(filePath)
+        if (ensuredDir !== dir) {
+          mkdirSync(dir, { recursive: true })
+          ensuredDir = dir
+        }
+        appendFileSync(filePath, lines.join('\n') + '\n')
+      } catch {
+        // Tracing must never break the run
+      }
+    },
+  }
+}

package/src/utils/ui-constants.ts

@@ -0,0 +1,69 @@
+import type { BorderCharacters } from '@opentui/core'
+
+/**
+ * Dark text color for focused/inverted controls (dark label on the green
+ * `theme.primary` fill). The themes set `background: 'transparent'`, so it
+ * can't be used as an inverted-text color — a transparent foreground on the
+ * green fill renders the label invisible. This near-black reads cleanly on the
+ * bright green fill in both the dark and light themes.
+ */
+export const INVERTED_CTA_FG = '#10131a'
+
+export const BORDER_CHARS: BorderCharacters = {
+  topLeft: '╭',
+  topRight: '╮',
+  bottomLeft: '╰',
+  bottomRight: '╯',
+  horizontal: '─',
+  vertical: '│',
+  topT: '┬',
+  bottomT: '┴',
+  leftT: '├',
+  rightT: '┤',
+  cross: '┼',
+}
+
+/** Dashed border characters with rounded corners for ghost/ephemeral UI */
+export const DASHED_BORDER_CHARS: BorderCharacters = {
+  topLeft: '╭',
+  topRight: '╮',
+  bottomLeft: '╰',
+  bottomRight: '╯',
+  horizontal: '┄',
+  vertical: '┆',
+  topT: '┬',
+  bottomT: '┴',
+  leftT: '├',
+  rightT: '┤',
+  cross: '┼',
+}
+
+/** Square corner border for image cards (separate from the rounded default) */
+export const IMAGE_CARD_BORDER_CHARS: BorderCharacters = {
+  horizontal: '─',
+  vertical: '│',
+  topLeft: '┌',
+  topRight: '┐',
+  bottomLeft: '└',
+  bottomRight: '┘',
+  topT: '┬',
+  bottomT: '┴',
+  leftT: '├',
+  rightT: '┤',
+  cross: '┼',
+}
+
+/** Dashed border with rounded corners for proposal cards */
+export const PROPOSAL_BORDER_CHARS: BorderCharacters = {
+  topLeft: '╭',
+  topRight: '╮',
+  bottomLeft: '╰',
+  bottomRight: '╯',
+  horizontal: '┈',
+  vertical: '┊',
+  topT: '┬',
+  bottomT: '┴',
+  leftT: '├',
+  rightT: '┤',
+  cross: '┼',
+}

package/src/utils/update-checker.ts

@@ -0,0 +1,110 @@
+/**
+ * Check for CLI updates on npm registry
+ * Runs silently in background, shows notification if update available
+ */
+
+import { execSync } from 'child_process'
+
+const NPM_REGISTRY = 'https://registry.npmjs.org'
+const PACKAGE_NAME = 'anvil'
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000 // 24 hours
+
+interface UpdateInfo {
+  currentVersion: string
+  latestVersion: string
+  updateAvailable: boolean
+}
+
+/**
+ * Get the latest version from npm registry
+ */
+async function getLatestVersion(): Promise<string | null> {
+  try {
+    const response = await fetch(`${NPM_REGISTRY}/${PACKAGE_NAME}/latest`)
+    if (!response.ok) return null
+    const data = await response.json()
+    return data.version || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Compare semver versions
+ * Returns: 1 if a > b, -1 if a < b, 0 if equal
+ */
+function compareVersions(a: string, b: string): number {
+  const partsA = a.split('.').map(Number)
+  const partsB = b.split('.').map(Number)
+  
+  for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
+    const numA = partsA[i] || 0
+    const numB = partsB[i] || 0
+    if (numA > numB) return 1
+    if (numA < numB) return -1
+  }
+  return 0
+}
+
+/**
+ * Check for updates and return info
+ */
+export async function checkForUpdates(currentVersion: string): Promise<UpdateInfo> {
+  const latestVersion = await getLatestVersion()
+  
+  if (!latestVersion) {
+    return {
+      currentVersion,
+      latestVersion: currentVersion,
+      updateAvailable: false
+    }
+  }
+  
+  const updateAvailable = compareVersions(latestVersion, currentVersion) > 0
+  
+  return {
+    currentVersion,
+    latestVersion,
+    updateAvailable
+  }
+}
+
+/**
+ * Show update notification in terminal
+ */
+export function showUpdateNotification(info: UpdateInfo): void {
+  if (!info.updateAvailable) return
+  
+  console.log('')
+  console.log('\x1b[33m┌─────────────────────────────────────────────────────┐\x1b[0m')
+  console.log('\x1b[33m│\x1b[0m  \x1b[1mUpdate available!\x1b[0m                               \x1b[33m│\x1b[0m')
+  console.log('\x1b[33m│\x1b[0m                                                     \x1b[33m│\x1b[0m')
+  console.log(`\x1b[33m│\x1b[0m  Current: \x1b[31m${info.currentVersion}\x1b[0m                        \x1b[33m│\x1b[0m`)
+  console.log(`\x1b[33m│\x1b[0m  Latest:  \x1b[32m${info.latestVersion}\x1b[0m                        \x1b[33m│\x1b[0m`)
+  console.log('\x1b[33m│\x1b[0m                                                     \x1b[33m│\x1b[0m')
+  console.log('\x1b[33m│\x1b[0m  Run \x1b[1mnpm i -g anvil@latest\x1b[0m to update              \x1b[33m│\x1b[0m')
+  console.log('\x1b[33m└─────────────────────────────────────────────────────┘\x1b[0m')
+  console.log('')
+}
+
+/**
+ * Check for updates in background (non-blocking)
+ * Call this at CLI startup
+ */
+export function checkForUpdatesInBackground(currentVersion: string): void {
+  // Skip check for dev versions
+  if (!currentVersion || currentVersion === 'dev' || currentVersion.includes('-dev')) {
+    return
+  }
+  
+  // Run check in background, don't block CLI startup
+  checkForUpdates(currentVersion)
+    .then(info => {
+      if (info.updateAvailable) {
+        showUpdateNotification(info)
+      }
+    })
+    .catch(() => {
+      // Silently ignore errors - update check is best effort
+    })
+}

package/src/utils/usage-banner-state.ts

@@ -0,0 +1,146 @@
+export const HIGH_CREDITS_THRESHOLD = 1000
+export const MEDIUM_CREDITS_THRESHOLD = 500
+export const LOW_CREDITS_THRESHOLD = 100
+
+export type BannerColorLevel = 'success' | 'warning' | 'error'
+
+export type CreditTier = 'high' | 'medium' | 'low' | 'out'
+
+export type ThresholdInfo = {
+  tier: CreditTier
+  colorLevel: BannerColorLevel
+  threshold: number
+}
+
+/**
+ * Gets comprehensive threshold information for a given credit balance.
+ * This is the single source of truth for credit tier classification.
+ */
+export function getThresholdInfo(balance: number | null): ThresholdInfo {
+  if (balance === null) {
+    return {
+      tier: 'medium',
+      colorLevel: 'warning',
+      threshold: MEDIUM_CREDITS_THRESHOLD,
+    }
+  }
+  if (balance >= HIGH_CREDITS_THRESHOLD) {
+    return {
+      tier: 'high',
+      colorLevel: 'success',
+      threshold: HIGH_CREDITS_THRESHOLD,
+    }
+  }
+  if (balance >= MEDIUM_CREDITS_THRESHOLD) {
+    return {
+      tier: 'medium',
+      colorLevel: 'warning',
+      threshold: MEDIUM_CREDITS_THRESHOLD,
+    }
+  }
+  if (balance >= LOW_CREDITS_THRESHOLD) {
+    return {
+      tier: 'low',
+      colorLevel: 'warning',
+      threshold: LOW_CREDITS_THRESHOLD,
+    }
+  }
+  return { tier: 'out', colorLevel: 'error', threshold: 0 }
+}
+
+/**
+ * Determines the appropriate color level for the usage banner based on credit balance.
+ *
+ * Color mapping:
+ * - success (green): >= 1000 credits
+ * - warning (yellow): 100-999 credits OR balance is null/unknown
+ * - error (red): < 100 credits
+ *
+ * @deprecated Use getThresholdInfo(balance).colorLevel instead
+ */
+export function getBannerColorLevel(balance: number | null): BannerColorLevel {
+  return getThresholdInfo(balance).colorLevel
+}
+
+/**
+ * Generates loading text for the usage banner while data is being fetched.
+ */
+export function generateLoadingBannerText(sessionCreditsUsed: number): string {
+  return `Session usage: ${sessionCreditsUsed.toLocaleString()}. Loading credit balance...`
+}
+
+/**
+ * Gets the threshold tier for a given balance.
+ * Returns null if balance is above all thresholds.
+ */
+function getThresholdTier(balance: number): number | null {
+  if (balance < LOW_CREDITS_THRESHOLD) return LOW_CREDITS_THRESHOLD
+  if (balance < MEDIUM_CREDITS_THRESHOLD) return MEDIUM_CREDITS_THRESHOLD
+  if (balance < HIGH_CREDITS_THRESHOLD) return HIGH_CREDITS_THRESHOLD
+  return null
+}
+
+export interface AutoShowDecision {
+  shouldShow: boolean
+  newWarningThreshold: number | null
+}
+
+/**
+ * Determines whether the usage banner should auto-show based on credit threshold crossings.
+ *
+ * The banner auto-shows when:
+ * - User is not in a chain (isChainInProgress = false)
+ * - User is authenticated (hasAuthToken = true)
+ * - User has credit data available (remainingBalance !== null)
+ * - User crosses a new threshold (1000, 500, or 100) that hasn't been warned about yet
+ * - User does NOT have auto top-up enabled (unless truly out of credits <= 0)
+ */
+export function shouldAutoShowBanner(
+  isChainInProgress: boolean,
+  hasAuthToken: boolean,
+  remainingBalance: number | null,
+  lastWarnedThreshold: number | null,
+  autoTopupEnabled: boolean = false,
+): AutoShowDecision {
+  // Don't show during active chains
+  if (isChainInProgress) {
+    return { shouldShow: false, newWarningThreshold: lastWarnedThreshold }
+  }
+
+  // Don't show for unauthenticated users
+  if (!hasAuthToken) {
+    return { shouldShow: false, newWarningThreshold: lastWarnedThreshold }
+  }
+
+  // Don't show if we don't have balance data
+  if (remainingBalance === null) {
+    return { shouldShow: false, newWarningThreshold: lastWarnedThreshold }
+  }
+
+  // For users with auto top-up enabled, only show if truly out of credits (<= 0)
+  // Auto top-up users want to "set and forget" - don't bother them with threshold warnings
+  if (autoTopupEnabled && remainingBalance > 0) {
+    return { shouldShow: false, newWarningThreshold: null }
+  }
+
+  const currentThreshold = getThresholdTier(remainingBalance)
+
+  // Clear warning state if user is back above all thresholds
+  if (currentThreshold === null) {
+    return { shouldShow: false, newWarningThreshold: null }
+  }
+
+  // Show banner if we've crossed a new threshold we haven't warned about
+  // A "new" threshold means either:
+  // 1. We haven't warned about any threshold yet (lastWarnedThreshold === null)
+  // 2. The current threshold is lower than what we last warned about
+  const isNewThreshold =
+    lastWarnedThreshold === null || currentThreshold < lastWarnedThreshold
+
+  if (isNewThreshold) {
+    return { shouldShow: true, newWarningThreshold: currentThreshold }
+  }
+
+  // Already warned about this threshold
+  return { shouldShow: false, newWarningThreshold: lastWarnedThreshold }
+}

package/src/utils/validation-error-formatting.ts

@@ -0,0 +1,86 @@
+export type FormattedValidationError = {
+  fieldName?: string
+  message: string
+}
+
+type ValidationErrorObject = {
+  path?: string[]
+  message?: string
+  code?: string
+}
+
+const stripCommonPrefixes = (text: string): string => {
+  return text
+    .replace(/Agent "[^"]+"\s*(?:\([^)]+\))?\s*:\s*/g, '')
+    .replace(/Schema validation failed:\s*/gi, '')
+    .trim()
+}
+
+const tryParseJsonErrors = (text: string): FormattedValidationError | null => {
+  if (!text.startsWith('[') && !text.startsWith('{')) {
+    return null
+  }
+
+  try {
+    const parsed = JSON.parse(text)
+    const errors = Array.isArray(parsed) ? parsed : [parsed]
+
+    if (errors.length === 0) {
+      return null
+    }
+
+    const first = errors[0] as ValidationErrorObject
+    const fieldName = Array.isArray(first.path) && first.path.length > 0
+      ? first.path.join('.')
+      : undefined
+
+    const message = typeof first.message === 'string' && first.message.length > 0
+      ? first.message
+      : text
+
+    return { fieldName, message }
+  } catch {
+    return null
+  }
+}
+
+const tryExtractFieldPattern = (text: string): FormattedValidationError | null => {
+  const colonIndex = text.indexOf(':')
+  if (colonIndex === -1) {
+    return null
+  }
+
+  const potentialField = text.slice(0, colonIndex).trim()
+  const remainingMessage = text.slice(colonIndex + 1).trim()
+
+  // Validate that the field looks like a valid identifier or path
+  // Allow word characters, dots, hyphens, brackets, and underscores
+  if (!/^[\w.\-\[\]]+$/.test(potentialField) || remainingMessage.length === 0) {
+    return null
+  }
+
+  return { fieldName: potentialField, message: remainingMessage }
+}
+
+export const formatValidationError = (rawMessage: string): FormattedValidationError => {
+  if (typeof rawMessage !== 'string' || rawMessage.length === 0) {
+    return { fieldName: undefined, message: 'Unknown validation error' }
+  }
+
+  const cleaned = stripCommonPrefixes(rawMessage)
+
+  // Try parsing as JSON first
+  const jsonResult = tryParseJsonErrors(cleaned)
+  if (jsonResult) {
+    return jsonResult
+  }
+
+  // Try extracting field:message pattern
+  const fieldResult = tryExtractFieldPattern(cleaned)
+  if (fieldResult) {
+    return fieldResult
+  }
+
+  // Fall back to the cleaned message without a field
+  return { fieldName: undefined, message: cleaned }
+}