@alumbwe/anvil 1.0.0

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

@@ -0,0 +1,126 @@
+import { describe, expect, test } from 'bun:test'
+
+import { formatValidationError } from '../validation-error-formatting'
+
+describe('formatValidationError', () => {
+  test('parses JSON array payloads and extracts field/message', () => {
+    const raw = `[
+  {
+    "code": "custom",
+    "path": [
+      "toolNames"
+    ],
+    "message": "Non-empty spawnableAgents array requires the 'spawn_agents' tool. Add 'spawn_agents' to toolNames or remove spawnableAgents."
+  }
+]`
+
+    const result = formatValidationError(raw)
+
+    expect(result.fieldName).toBe('toolNames')
+    expect(result.message).toBe(
+      "Non-empty spawnableAgents array requires the 'spawn_agents' tool. Add 'spawn_agents' to toolNames or remove spawnableAgents.",
+    )
+  })
+
+  test('strips agent name prefix', () => {
+    const result = formatValidationError(
+      'Agent "demo" (demo.ts): Invalid input: expected string, received number',
+    )
+
+    expect(result.fieldName).toBeUndefined()
+    expect(result.message).toBe(
+      'Invalid input: expected string, received number',
+    )
+  })
+
+  test('extracts field:message pattern', () => {
+    const result = formatValidationError(
+      'instructions: Required field is missing',
+    )
+
+    expect(result.fieldName).toBe('instructions')
+    expect(result.message).toBe('Required field is missing')
+  })
+
+  test('handles messages without field patterns', () => {
+    const result = formatValidationError(
+      'Schema validation failed: Generic error',
+    )
+
+    expect(result.fieldName).toBeUndefined()
+    expect(result.message).toBe('Generic error')
+  })
+
+  test('handles nested path from JSON error', () => {
+    const raw = `[
+  {
+    "path": ["outputSchema", "properties", "summary"],
+    "message": "Required"
+  }
+]`
+
+    const result = formatValidationError(raw)
+
+    expect(result.fieldName).toBe('outputSchema.properties.summary')
+    expect(result.message).toBe('Required')
+  })
+
+  test('handles empty string input', () => {
+    const result = formatValidationError('')
+
+    expect(result.fieldName).toBeUndefined()
+    expect(result.message).toBe('Unknown validation error')
+  })
+
+  test('handles JSON object (not array) with error', () => {
+    const raw = `{"path": ["field"], "message": "Invalid value"}`
+
+    const result = formatValidationError(raw)
+
+    expect(result.fieldName).toBe('field')
+    expect(result.message).toBe('Invalid value')
+  })
+
+  test('handles JSON with empty path array', () => {
+    const raw = `[{"path": [], "message": "Root level error"}]`
+
+    const result = formatValidationError(raw)
+
+    expect(result.fieldName).toBeUndefined()
+    expect(result.message).toBe('Root level error')
+  })
+
+  test('handles malformed JSON gracefully', () => {
+    const raw = '[{"path": ["field"], invalid json'
+
+    const result = formatValidationError(raw)
+
+    expect(result.fieldName).toBeUndefined()
+    expect(result.message).toBe('[{"path": ["field"], invalid json')
+  })
+
+  test('handles colon in message part correctly', () => {
+    const result = formatValidationError(
+      'fieldName: Error: something went wrong',
+    )
+
+    expect(result.fieldName).toBe('fieldName')
+    expect(result.message).toBe('Error: something went wrong')
+  })
+
+  test('handles field pattern with no message after colon', () => {
+    const result = formatValidationError('fieldName:')
+
+    expect(result.fieldName).toBeUndefined()
+    expect(result.message).toBe('fieldName:')
+  })
+
+  test('handles JSON with missing message property', () => {
+    const raw = `[{"path": ["field"], "code": "custom"}]`
+
+    const result = formatValidationError(raw)
+
+    expect(result.fieldName).toBe('field')
+    expect(result.message).toBe(raw)
+  })
+})

package/src/utils/__tests__/windows-terminal-health.test.ts

@@ -0,0 +1,101 @@
+import { AnalyticsEvent } from '@anvil/common/constants/analytics-events'
+import { afterEach, describe, expect, mock, test } from 'bun:test'
+
+import {
+  initAnalytics,
+  resetAnalyticsState,
+  trackEvent,
+  type AnalyticsDeps,
+} from '../analytics'
+import { deliverWindowsTerminalFailure } from '../windows-terminal-health'
+
+import type { LogRecordInput } from '@anvil/common/schemas/logs'
+
+const FAILED_ANALYTICS_DEPS: AnalyticsDeps = {
+  env: {},
+  isProd: true,
+  createClient: mock(() => {
+    throw new Error(
+      'PostHog client should not be created without configuration',
+    )
+  }),
+  generateAnonymousId: () => 'analytics-anonymous-id',
+}
+
+afterEach(() => {
+  resetAnalyticsState()
+})
+
+describe('Windows terminal-health delivery', () => {
+  test('queues and drains the bounded Axiom event when analytics initialization fails', async () => {
+    const analyticsRecords: LogRecordInput[] = []
+    resetAnalyticsState({
+      ...FAILED_ANALYTICS_DEPS,
+      enqueueClientLog: (record) => analyticsRecords.push(record),
+    })
+    expect(() => initAnalytics()).toThrow(
+      'NEXT_PUBLIC_POSTHOG_API_KEY or NEXT_PUBLIC_POSTHOG_HOST_URL is not set',
+    )
+    const fallbackRecords: LogRecordInput[] = []
+    const drainClientLogs = mock(async () => {})
+    const properties = {
+      version: '0.0.142',
+      platform: 'win32' as const,
+      stage: 'arming' as const,
+      failureCode: 'timeout' as const,
+    }
+
+    await deliverWindowsTerminalFailure(
+      AnalyticsEvent.TERMINAL_WATCHDOG_FAILED,
+      properties,
+      {
+        trackEvent,
+        getAnonymousId: () => 'anonymous-install-id',
+        enqueueClientLog: (record) => fallbackRecords.push(record),
+        drainClientLogs,
+      },
+    )
+
+    expect(analyticsRecords).toEqual([
+      {
+        level: 'info',
+        event: AnalyticsEvent.TERMINAL_WATCHDOG_FAILED,
+        message: AnalyticsEvent.TERMINAL_WATCHDOG_FAILED,
+        client_session_id: 'analytics-anonymous-id',
+        data: properties,
+      },
+    ])
+    expect(fallbackRecords).toEqual([])
+    expect(drainClientLogs).toHaveBeenCalledTimes(1)
+  })
+
+  test('preserves the analytics mirror without queuing a duplicate', async () => {
+    const tracked = mock(() => {})
+    const enqueueClientLog = mock((_record: LogRecordInput) => {})
+    const drainClientLogs = mock(async () => {})
+    const properties = {
+      version: '0.0.142',
+      platform: 'win32' as const,
+      stage: 'spawn' as const,
+      failureCode: 'enoent' as const,
+    }
+
+    await deliverWindowsTerminalFailure(
+      AnalyticsEvent.TERMINAL_BROKER_SPAWN_FAILED,
+      properties,
+      {
+        trackEvent: tracked,
+        getAnonymousId: () => 'unused',
+        enqueueClientLog,
+        drainClientLogs,
+      },
+    )
+
+    expect(tracked).toHaveBeenCalledWith(
+      AnalyticsEvent.TERMINAL_BROKER_SPAWN_FAILED,
+      properties,
+    )
+    expect(enqueueClientLog).not.toHaveBeenCalled()
+    expect(drainClientLogs).toHaveBeenCalledTimes(1)
+  })
+})

package/src/utils/__tests__/write-file-atomic.test.ts

@@ -0,0 +1,127 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test'
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+
+import { writeFileAtomic, writeFileAtomicAsync } from '../write-file-atomic'
+
+let tempDir = ''
+
+describe('writeFileAtomic', () => {
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'anvil-atomic-'))
+  })
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  test('writes a new file', () => {
+    const target = path.join(tempDir, 'out.json')
+
+    writeFileAtomic(target, '{"a":1}')
+
+    expect(fs.readFileSync(target, 'utf8')).toBe('{"a":1}')
+  })
+
+  test('replaces an existing file', () => {
+    const target = path.join(tempDir, 'out.json')
+    fs.writeFileSync(target, 'old content')
+
+    writeFileAtomic(target, 'new content')
+
+    expect(fs.readFileSync(target, 'utf8')).toBe('new content')
+  })
+
+  test('leaves no temp file behind on success', () => {
+    const target = path.join(tempDir, 'out.json')
+
+    writeFileAtomic(target, 'data')
+
+    expect(fs.readdirSync(tempDir)).toEqual(['out.json'])
+  })
+
+  test('cleans up the temp file and rethrows on failure', () => {
+    // Renaming a file over an existing directory fails on all platforms
+    const target = path.join(tempDir, 'target-dir')
+    fs.mkdirSync(target)
+
+    expect(() => writeFileAtomic(target, 'data')).toThrow()
+
+    expect(fs.readdirSync(tempDir)).toEqual(['target-dir'])
+  })
+
+  test('uses a unique temp name per write (no collision between calls)', () => {
+    // Two writes to different targets must not share a temp path, otherwise
+    // concurrent sync + async writes would tear each other. The temp name
+    // includes a random component, so back-to-back writes never collide.
+    const a = path.join(tempDir, 'a.json')
+    const b = path.join(tempDir, 'b.json')
+
+    writeFileAtomic(a, 'a')
+    writeFileAtomic(b, 'b')
+
+    expect(fs.readdirSync(tempDir).sort()).toEqual(['a.json', 'b.json'])
+  })
+})
+
+describe('writeFileAtomicAsync', () => {
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'anvil-atomic-async-'))
+  })
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  test('writes a new file', async () => {
+    const target = path.join(tempDir, 'out.json')
+
+    await writeFileAtomicAsync(target, '{"a":1}')
+
+    expect(fs.readFileSync(target, 'utf8')).toBe('{"a":1}')
+  })
+
+  test('replaces an existing file', async () => {
+    const target = path.join(tempDir, 'out.json')
+    fs.writeFileSync(target, 'old content')
+
+    await writeFileAtomicAsync(target, 'new content')
+
+    expect(fs.readFileSync(target, 'utf8')).toBe('new content')
+  })
+
+  test('leaves no temp file behind on success', async () => {
+    const target = path.join(tempDir, 'out.json')
+
+    await writeFileAtomicAsync(target, 'data')
+
+    expect(fs.readdirSync(tempDir)).toEqual(['out.json'])
+  })
+
+  test('cleans up the temp file and rejects on failure', async () => {
+    const target = path.join(tempDir, 'target-dir')
+    fs.mkdirSync(target)
+
+    await expect(writeFileAtomicAsync(target, 'data')).rejects.toThrow()
+
+    expect(fs.readdirSync(tempDir)).toEqual(['target-dir'])
+  })
+
+  test('concurrent writes to the same file do not tear (last write wins)', async () => {
+    const target = path.join(tempDir, 'out.json')
+
+    await Promise.all([
+      writeFileAtomicAsync(target, 'first'),
+      writeFileAtomicAsync(target, 'second'),
+      writeFileAtomicAsync(target, 'third'),
+    ])
+
+    // Whichever rename lands last wins, but the file is always one intact
+    // value — never a torn mix — and no temp files remain.
+    expect(['first', 'second', 'third']).toContain(
+      fs.readFileSync(target, 'utf8'),
+    )
+    expect(fs.readdirSync(tempDir)).toEqual(['out.json'])
+  })
+})

package/src/utils/active-run.ts

@@ -0,0 +1,131 @@
+/** Why the active agent run is being stopped. */
+export type ActiveRunStopReason =
+  | 'user-interrupt'
+  | 'logout'
+  | 'new-chat'
+  | 'history-resume'
+  | 'session-transition'
+  | 'process-exit'
+
+type ActiveRunQueuePolicy =
+  | 'pause-if-pending'
+  | 'clear-and-block'
+  | 'preserve-and-block'
+
+/**
+ * Every reason aborts through the same run owner, which marks the message
+ * interrupted and checkpoints it. Process-exit callers additionally flush
+ * that checkpoint synchronously. Queue behavior is the only policy that
+ * varies here: context changes discard old prompts, a manual interrupt pauses
+ * them, and exit preserves them while blocking any new dequeue.
+ */
+export const ACTIVE_RUN_QUEUE_POLICIES = {
+  'user-interrupt': 'pause-if-pending',
+  logout: 'clear-and-block',
+  'new-chat': 'clear-and-block',
+  'history-resume': 'clear-and-block',
+  'session-transition': 'clear-and-block',
+  'process-exit': 'preserve-and-block',
+} satisfies Record<ActiveRunStopReason, ActiveRunQueuePolicy>
+
+export type ActiveRunQueueControls = {
+  pauseQueueIfPending: () => void
+  discardQueue: () => void
+  setCanProcessQueue: (canProcess: boolean) => void
+}
+
+/** Apply the reason matrix to the persistent runtime's latest queue state. */
+export function applyActiveRunQueuePolicy(
+  reason: ActiveRunStopReason,
+  controls: ActiveRunQueueControls,
+): void {
+  const policy = ACTIVE_RUN_QUEUE_POLICIES[reason]
+  if (policy === 'pause-if-pending') {
+    controls.pauseQueueIfPending()
+    return
+  }
+  if (policy === 'clear-and-block') {
+    controls.discardQueue()
+    return
+  }
+  if (policy === 'preserve-and-block') {
+    // Freebuff exit can spend up to a second releasing the session seat. Keep
+    // queued prompts in memory, but do not let abort cleanup dequeue a new run
+    // during that window.
+    controls.setCanProcessQueue(false)
+  }
+}
+
+type ActiveRun = {
+  ownerId: string
+  stop: (reason: ActiveRunStopReason) => void
+}
+
+let activeRun: ActiveRun | null = null
+let runtimeStopHandler: ((reason: ActiveRunStopReason) => void) | null = null
+
+/**
+ * Install cleanup owned by the persistent ChatRuntime. It runs even while no
+ * SDK run exists, which is important for clearing a paused queue on /logout,
+ * /new, or a session reset.
+ */
+export function registerActiveRunStopHandler(
+  handler: (reason: ActiveRunStopReason) => void,
+): () => void {
+  runtimeStopHandler = handler
+  return () => {
+    if (runtimeStopHandler === handler) runtimeStopHandler = null
+  }
+}
+
+/** Register the sole run that may currently mutate the active chat. */
+export function registerActiveRun(
+  ownerId: string,
+  stop: (reason: ActiveRunStopReason) => void,
+): void {
+  const previousRun = activeRun
+  activeRun = { ownerId, stop }
+  if (previousRun && previousRun.ownerId !== ownerId) {
+    // This should only happen if an unexpected path bypassed the chain lock.
+    // Stop the displaced owner after installing the new one so its late
+    // owner-guarded cleanup cannot unregister the replacement.
+    try {
+      previousRun.stop('user-interrupt')
+    } catch {
+      // The new owner is already installed; never orphan it because cleanup
+      // for the displaced run failed.
+    }
+  }
+}
+
+/** Owner-guarded so a stale run settling cannot release a newer run. */
+export function clearActiveRun(ownerId: string): void {
+  if (activeRun?.ownerId === ownerId) {
+    activeRun = null
+  }
+}
+
+/**
+ * Stop the in-flight run, if any. Ownership is released before invoking the
+ * callback: repeated entry points are idempotent and the stopped run cannot
+ * consume a later reason intended for a newer run.
+ */
+export function stopActiveRun(reason: ActiveRunStopReason): boolean {
+  const run = activeRun
+  if (run) activeRun = null
+
+  try {
+    run?.stop(reason)
+  } catch {
+    // Cancellation is a best-effort boundary used during fatal process
+    // cleanup too; one broken run callback must not block queue/terminal
+    // cleanup.
+  }
+  try {
+    runtimeStopHandler?.(reason)
+  } catch {
+    // The run is already detached. Keep cancellation idempotent and allow the
+    // initiating transition or process cleanup to continue.
+  }
+  return run !== null
+}

package/src/utils/activity-tracker.ts

@@ -0,0 +1,66 @@
+/**
+ * Activity Tracker Module
+ * 
+ * A singleton module that tracks user activity in the terminal.
+ * Used by the ads feature and activity-aware query hooks.
+ */
+
+type ActivityListener = (timestamp: number) => void
+
+const listeners = new Set<ActivityListener>()
+let lastActivityTime = Date.now()
+
+/**
+ * Report that the user performed an activity.
+ * Call this when:
+ * - User types in the input field
+ * - User moves the mouse
+ * - User presses keyboard shortcuts
+ */
+export function reportActivity(): void {
+  lastActivityTime = Date.now()
+  for (const listener of listeners) {
+    listener(lastActivityTime)
+  }
+}
+
+/**
+ * Get the timestamp of the last user activity.
+ */
+export function getLastActivityTime(): number {
+  return lastActivityTime
+}
+
+/**
+ * Check if the user is currently active (within the idle threshold).
+ * @param idleThresholdMs - Time in ms to consider user idle (default: 30 seconds)
+ */
+export function isUserActive(idleThresholdMs: number = 30_000): boolean {
+  return Date.now() - lastActivityTime < idleThresholdMs
+}
+
+/**
+ * Get the time in ms since the last activity.
+ */
+export function getIdleTime(): number {
+  return Date.now() - lastActivityTime
+}
+
+/**
+ * Subscribe to activity events.
+ * @returns Unsubscribe function
+ */
+export function subscribeToActivity(callback: ActivityListener): () => void {
+  listeners.add(callback)
+  return () => {
+    listeners.delete(callback)
+  }
+}
+
+/**
+ * Reset the activity tracker (mainly for testing).
+ */
+export function resetActivityTracker(): void {
+  lastActivityTime = Date.now()
+  listeners.clear()
+}

package/src/utils/agent-display.ts

@@ -0,0 +1,87 @@
+import { getAgentBaseName } from './message-block-helpers'
+
+import type {
+  AgentContentBlock,
+  TextContentBlock,
+  ToolContentBlock,
+} from '../types/chat'
+
+const DEFAULT_BASHER_OUTPUT_PREVIEW_MAX_LENGTH = 120
+const PREVIEW_ELLIPSIS = '...'
+
+export function truncateToSingleLinePreview(
+  text: string,
+  maxLength = DEFAULT_BASHER_OUTPUT_PREVIEW_MAX_LENGTH,
+): string | undefined {
+  const singleLine = text.replace(/\s+/g, ' ').trim()
+  if (!singleLine) {
+    return undefined
+  }
+
+  if (singleLine.length <= maxLength) {
+    return singleLine
+  }
+
+  const previewLength = Math.max(0, maxLength - PREVIEW_ELLIPSIS.length)
+  return `${singleLine.slice(0, previewLength).trimEnd()}${PREVIEW_ELLIPSIS}`
+}
+
+export function getAgentDisplayPrompt(
+  agentBlock: AgentContentBlock,
+): string | undefined {
+  const initialPrompt = agentBlock.initialPrompt?.trim()
+  if (initialPrompt) {
+    return initialPrompt
+  }
+
+  if (getAgentBaseName(agentBlock.agentType) !== 'basher') {
+    return undefined
+  }
+
+  const whatToSummarize = agentBlock.params?.what_to_summarize
+  return typeof whatToSummarize === 'string' && whatToSummarize.trim()
+    ? whatToSummarize.trim()
+    : undefined
+}
+
+export function getBasherFinishedOutputPreview(
+  agentBlock: AgentContentBlock,
+  maxLength = DEFAULT_BASHER_OUTPUT_PREVIEW_MAX_LENGTH,
+): string | undefined {
+  if (
+    getAgentBaseName(agentBlock.agentType) !== 'basher' ||
+    agentBlock.status === 'running'
+  ) {
+    return undefined
+  }
+
+  const blocks = agentBlock.blocks ?? []
+  return (
+    truncateToSingleLinePreview(getTextOutput(blocks), maxLength) ??
+    truncateToSingleLinePreview(getCommandOutput(blocks), maxLength)
+  )
+}
+
+function getTextOutput(
+  blocks: NonNullable<AgentContentBlock['blocks']>,
+): string {
+  return blocks
+    .filter(
+      (block): block is TextContentBlock =>
+        block.type === 'text' && block.textType !== 'reasoning',
+    )
+    .map((block) => block.content)
+    .join('\n')
+}
+
+function getCommandOutput(
+  blocks: NonNullable<AgentContentBlock['blocks']>,
+): string {
+  return blocks
+    .filter(
+      (block): block is ToolContentBlock =>
+        block.type === 'tool' && block.toolName === 'run_terminal_command',
+    )
+    .map((block) => block.output ?? '')
+    .join('\n')
+}

package/src/utils/agent-helpers.ts

@@ -0,0 +1,27 @@
+import type { AgentContentBlock } from '../types/chat'
+
+export interface StatusInfo {
+  indicator: string
+  label: string
+  color: string
+  text: string
+}
+
+/** Get status indicator, label, color, and formatted text based on agent status */
+export function getAgentStatusInfo(
+  status: AgentContentBlock['status'],
+  theme: { primary: string; foreground: string; muted: string },
+): StatusInfo {
+  switch (status) {
+    case 'running':
+      return { indicator: '●', label: 'running', color: theme.primary, text: '● running' }
+    case 'failed':
+      return { indicator: '✗', label: 'failed', color: 'red', text: '✗ failed' }
+    case 'complete':
+      return { indicator: '✓', label: 'completed', color: theme.foreground, text: 'completed ✓' }
+    case 'cancelled':
+      return { indicator: '⊘', label: 'cancelled', color: 'red', text: '⊘ cancelled' }
+    default:
+      return { indicator: '○', label: 'waiting', color: theme.muted, text: '○ waiting' }
+  }
+}

package/src/utils/agent-id-utils.ts

@@ -0,0 +1,14 @@
+/**
+ * Utilities for parsing and normalizing agent identifiers
+ */
+
+/**
+ * Extracts the simple agent ID from a potentially qualified ID.
+ * Handles formats like:
+ * - "my-agent" -> "my-agent"
+ * - "publisher/my-agent" -> "my-agent"
+ * - "publisher/my-agent@1.0.0" -> "my-agent"
+ */
+export function getSimpleAgentId(qualifiedId: string): string {
+  return qualifiedId.split('/').pop()?.split('@')[0] ?? qualifiedId
+}

package/src/utils/ai-message-id.ts

@@ -0,0 +1,12 @@
+/**
+ * Identity of streamed AI-response messages, kept in a dependency-free leaf
+ * module so lightweight consumers (e.g. the ads hook) can discriminate real LLM
+ * answers from other 'ai'-variant messages without pulling in the full
+ * send-message helper graph.
+ */
+
+/** Id prefix identifying streamed AI response shells. */
+export const AI_MESSAGE_ID_PREFIX = 'ai-'
+
+export const generateAiMessageId = (): string =>
+  `${AI_MESSAGE_ID_PREFIX}${Date.now()}-${Math.random().toString(16).slice(2)}`