ethagent 0.2.1 → 1.0.0

package/src/app/FirstRun.tsx

@@ -0,0 +1,412 @@
+import React, { useEffect, useState } from 'react'
+import { Box, Text } from 'ink'
+import { BrandSplash as Splash } from '../ui/BrandSplash.js'
+import { Select } from '../ui/Select.js'
+import { TextInput } from '../ui/TextInput.js'
+import { theme } from '../ui/theme.js'
+import { ModelPicker, type ModelPickerSelection } from '../models/ModelPicker.js'
+import { formatModelDisplayName } from '../models/modelDisplay.js'
+import { detectSpec, type SpecSnapshot } from '../models/runtimeDetection.js'
+import { FEATURED_HF_REPO_URL } from '../models/modelRecommendation.js'
+import {
+  saveConfig,
+  normalizeConfig,
+  defaultModelFor,
+  defaultBaseUrlFor,
+  type EthagentConfig,
+  type ProviderId,
+} from '../storage/config.js'
+import { setKey } from '../storage/secrets.js'
+import { IdentityHub, type IdentityHubResult } from '../identity/hub/IdentityHub.js'
+
+type Step =
+  | { kind: 'detecting' }
+  | { kind: 'detect-error'; message: string }
+  | { kind: 'identity-start'; spec: SpecSnapshot }
+  | { kind: 'identity-start-saving'; spec: SpecSnapshot; result: IdentityHubResult }
+  | { kind: 'choose-path'; spec: SpecSnapshot }
+  | { kind: 'hf-setup'; spec: SpecSnapshot }
+  | { kind: 'cloud-provider' }
+  | { kind: 'cloud-key'; provider: ProviderId; error?: string }
+  | { kind: 'cloud-key-saving'; provider: ProviderId }
+  | { kind: 'cloud-model'; provider: ProviderId }
+  | { kind: 'saving'; config: EthagentConfig }
+  | { kind: 'save-error'; config: EthagentConfig; message: string }
+  | { kind: 'done'; config: EthagentConfig }
+
+type FirstRunProps = {
+  onComplete: (config: EthagentConfig) => void
+  onCancel: () => void
+}
+
+const STATUS: Record<string, string> = {
+  'detecting':         'first-run setup · inspecting machine',
+  'detect-error':      'first-run setup · detection failed',
+  'choose-path':       'first-run setup · choose how to run',
+  'hf-setup':          'first-run setup · local model',
+  'cloud-provider':    'first-run setup · pick a cloud provider',
+  'cloud-key':         'first-run setup · paste API key',
+  'cloud-key-saving':  'first-run setup · storing key',
+  'cloud-model':       'first-run setup · pick a model',
+  'saving':            'first-run setup · saving config',
+  'save-error':        'first-run setup · save failed',
+  'done':              'ready',
+}
+
+const NAV_BACK = '↑↓ navigate · enter select · esc back'
+const NAV_CANCEL = '↑↓ navigate · enter select · esc cancel setup'
+
+export const FirstRun: React.FC<FirstRunProps> = ({ onComplete, onCancel }) => {
+  const [step, setStep] = useState<Step>({ kind: 'detecting' })
+  const [history, setHistory] = useState<Step[]>([])
+  const [firstRunIdentity, setFirstRunIdentity] = useState<EthagentConfig['identity']>(undefined)
+
+  const goTo = (next: Step): void => {
+    setHistory(h => [...h, step])
+    setStep(next)
+  }
+
+  const goBack = (): void => {
+    if (history.length === 0) {
+      onCancel()
+      return
+    }
+    const prev = history[history.length - 1]!
+    setStep(prev)
+    setHistory(h => h.slice(0, -1))
+  }
+
+  useEffect(() => {
+    let cancelled = false
+    detectSpec()
+      .then(spec => {
+        if (cancelled) return
+        setStep({ kind: 'identity-start', spec })
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return
+        setStep({ kind: 'detect-error', message: (err as Error).message })
+      })
+    return () => { cancelled = true }
+  }, [])
+
+  useEffect(() => {
+    if (step.kind !== 'saving') return
+    let cancelled = false
+    const config = normalizeConfig(step.config)
+    saveConfig(config)
+      .then(() => {
+        if (cancelled) return
+        setStep({ kind: 'done', config })
+        onComplete(config)
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return
+        setStep({ kind: 'save-error', config, message: (err as Error).message })
+      })
+    return () => { cancelled = true }
+  }, [step, onComplete])
+
+  useEffect(() => {
+    if (step.kind !== 'identity-start-saving') return
+    let cancelled = false
+    const persist = async (): Promise<void> => {
+      if (step.result.kind === 'token') {
+        setFirstRunIdentity(step.result.identity)
+      }
+    }
+    persist()
+      .then(() => {
+        if (cancelled) return
+        setStep({ kind: 'choose-path', spec: step.spec })
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return
+        setStep({
+          kind: 'detect-error',
+          message: `could not store identity: ${(err as Error).message}`,
+        })
+      })
+    return () => { cancelled = true }
+  }, [step])
+
+  const hint = (canBack: boolean): React.ReactElement => (
+    <Box marginTop={1}>
+      <Text color={theme.dim}>{canBack ? NAV_BACK : NAV_CANCEL}</Text>
+    </Box>
+  )
+
+  const withFirstRunIdentity = (config: EthagentConfig): EthagentConfig =>
+    firstRunIdentity ? { ...config, identity: firstRunIdentity } : config
+
+  if (step.kind === 'detecting') {
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Splash tipLine={STATUS['detecting']} />
+        <Text color={theme.dim}>inspecting machine…</Text>
+      </Box>
+    )
+  }
+
+  if (step.kind === 'detect-error') {
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Splash tipLine={STATUS['detect-error']} />
+        <Text color="#e87070">could not inspect machine: {step.message}</Text>
+        <Box marginTop={1}>
+          <Select<'quit'>
+            options={[{ value: 'quit', label: 'quit' }]}
+            onSubmit={onCancel}
+            onCancel={onCancel}
+          />
+        </Box>
+      </Box>
+    )
+  }
+
+  if (step.kind === 'identity-start') {
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Splash tipLine="first-run setup · agent identity" />
+        <IdentityHub
+          mode="first-run"
+          onComplete={result => {
+            if (result.kind === 'cancel') {
+              onCancel()
+              return
+            }
+            if (result.kind === 'skip') {
+              setStep({ kind: 'choose-path', spec: step.spec })
+              return
+            }
+            setStep({ kind: 'identity-start-saving', spec: step.spec, result })
+          }}
+        />
+      </Box>
+    )
+  }
+
+  if (step.kind === 'identity-start-saving') {
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Splash tipLine="first-run setup · storing identity" />
+        <Text color={theme.dim}>storing identity...</Text>
+      </Box>
+    )
+  }
+
+  if (step.kind === 'choose-path') {
+    const { spec } = step
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Splash tipLine={STATUS['choose-path']} />
+        <Box flexDirection="column" marginBottom={1}>
+          <Text color={theme.dim}>
+            detected {formatGB(spec.effectiveRamBytes)} RAM
+            {spec.gpuVramBytes ? `, ${formatGB(spec.gpuVramBytes)} VRAM` : ''}
+            {spec.isAppleSilicon ? ', Apple Silicon' : ''}
+          </Text>
+        </Box>
+        <Select<'cloud' | 'hf'>
+          label="how do you want to run?"
+          options={[
+            { value: 'cloud',  label: 'cloud API', hint: 'anthropic, openai, or gemini' },
+            { value: 'hf',     label: 'local model', hint: 'download and run locally' },
+          ]}
+          onSubmit={choice => {
+            if (choice === 'cloud') goTo({ kind: 'cloud-provider' })
+            else goTo({ kind: 'hf-setup', spec })
+          }}
+          onCancel={onCancel}
+        />
+        {hint(false)}
+      </Box>
+    )
+  }
+
+
+
+  if (step.kind === 'hf-setup') {
+    const modelPickerConfig: EthagentConfig = withFirstRunIdentity({
+      version: 1,
+      provider: 'llamacpp',
+      model: defaultModelFor('llamacpp'),
+      baseUrl: defaultBaseUrlFor('llamacpp'),
+      firstRunAt: new Date().toISOString(),
+    })
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Splash tipLine={STATUS['hf-setup']} />
+        <Box flexDirection="column" marginBottom={1}>
+          <Text color={theme.dim}>featured: {FEATURED_HF_REPO_URL}</Text>
+        </Box>
+        <ModelPicker
+          currentConfig={modelPickerConfig}
+          currentProvider="llamacpp"
+          currentModel={modelPickerConfig.model}
+          featuredHfRepo={FEATURED_HF_REPO_URL}
+          onPick={(selection: ModelPickerSelection) => {
+            goTo({ kind: 'saving', config: configFromModelPickerSelection(selection, modelPickerConfig) })
+          }}
+          onCancel={goBack}
+        />
+      </Box>
+    )
+  }
+
+  if (step.kind === 'cloud-provider') {
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Splash tipLine={STATUS['cloud-provider']} />
+        <Text color={theme.accentSecondary} bold>pick a cloud provider</Text>
+        <Box marginTop={1}>
+          <Select<ProviderId>
+            options={[
+              { value: 'openai',    label: 'openai' },
+              { value: 'anthropic', label: 'anthropic' },
+              { value: 'gemini',    label: 'gemini' },
+            ]}
+            onSubmit={provider => goTo({ kind: 'cloud-key', provider })}
+            onCancel={goBack}
+          />
+        </Box>
+        {hint(true)}
+      </Box>
+    )
+  }
+
+  if (step.kind === 'cloud-key' || step.kind === 'cloud-key-saving') {
+    const provider = step.provider
+    const saving = step.kind === 'cloud-key-saving'
+    const error = step.kind === 'cloud-key' ? step.error : undefined
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Splash tipLine={saving ? STATUS['cloud-key-saving'] : STATUS['cloud-key']} />
+        <Text color={theme.accentSecondary} bold>paste your {provider} API key</Text>
+        <Text color={theme.dim}>stored in your OS keyring when available; never written to config.json</Text>
+        {error ? <Text color="#e87070">{error}</Text> : null}
+        <Box marginTop={1}>
+          <TextInput
+            isSecret
+            placeholder={provider === 'openai' ? 'sk-...' : 'paste key and press enter'}
+            validate={v => v.trim().length >= 8 ? null : 'key looks too short'}
+            onSubmit={async value => {
+              const trimmed = value.trim()
+              setHistory(h => [...h, { kind: 'cloud-key', provider }])
+              setStep({ kind: 'cloud-key-saving', provider })
+              try {
+                await setKey(provider, trimmed)
+                setStep({ kind: 'cloud-model', provider })
+              } catch (err: unknown) {
+                setHistory(h => h.slice(0, -1))
+                setStep({
+                  kind: 'cloud-key',
+                  provider,
+                  error: `could not store key: ${(err as Error).message}`,
+                })
+              }
+            }}
+            onCancel={goBack}
+          />
+        </Box>
+        {saving ? <Text color={theme.dim}>storing key…</Text> : hint(true)}
+      </Box>
+    )
+  }
+
+  if (step.kind === 'cloud-model') {
+    const { provider } = step
+    const defaultModel = defaultModelFor(provider)
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Splash tipLine={STATUS['cloud-model']} />
+        <Text color={theme.accentSecondary} bold>which model?</Text>
+        <Text color={theme.dim}>press enter to accept default: {defaultModel}</Text>
+        <Box marginTop={1}>
+          <TextInput
+            initialValue={defaultModel}
+            placeholder={defaultModel}
+            onSubmit={model => goTo({
+              kind: 'saving',
+              config: withFirstRunIdentity({
+                version: 1,
+                provider,
+                model: model.trim() || defaultModel,
+                firstRunAt: new Date().toISOString(),
+              }),
+            })}
+            onCancel={goBack}
+          />
+        </Box>
+        {hint(true)}
+      </Box>
+    )
+  }
+
+  if (step.kind === 'saving') {
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Splash tipLine={STATUS['saving']} />
+        <Text color={theme.dim}>saving config…</Text>
+      </Box>
+    )
+  }
+
+  if (step.kind === 'save-error') {
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Splash tipLine={STATUS['save-error']} />
+        <Text color="#e87070">{step.message}</Text>
+        <Box marginTop={1}>
+          <Select<'retry' | 'back' | 'quit'>
+            options={[
+              { value: 'retry', label: 'retry save' },
+              { value: 'back',  label: 'go back and edit' },
+              { value: 'quit',  label: 'quit setup' },
+            ]}
+            onSubmit={choice => {
+              if (choice === 'retry') setStep({ kind: 'saving', config: step.config })
+              else if (choice === 'back') goBack()
+              else onCancel()
+            }}
+            onCancel={goBack}
+          />
+        </Box>
+        {hint(history.length > 0)}
+      </Box>
+    )
+  }
+
+  if (step.kind === 'done') {
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Splash tipLine={`ready · ${step.config.provider} · ${formatModelDisplayName(step.config.provider, step.config.model, { maxLength: 48 })}`} />
+        <Text color={theme.accentSecondary}>all set.</Text>
+      </Box>
+    )
+  }
+
+  return null
+}
+
+function configFromModelPickerSelection(selection: ModelPickerSelection, base: EthagentConfig): EthagentConfig {
+  if (selection.kind === 'llamacpp') {
+    return {
+      ...base,
+      provider: 'llamacpp',
+      model: selection.model,
+      baseUrl: defaultBaseUrlFor('llamacpp'),
+    }
+  }
+  return {
+    ...base,
+    provider: selection.provider,
+    model: selection.model,
+    baseUrl: undefined,
+  }
+}
+
+function formatGB(bytes: number): string {
+  const gb = bytes / (1024 * 1024 * 1024)
+  return gb < 10 ? `${gb.toFixed(1)}GB` : `${Math.round(gb)}GB`
+}

package/src/app/hooks/useCancelRequest.ts

@@ -0,0 +1,22 @@
+import { useCallback } from 'react'
+import { useKeybinding } from '../keybindings/KeybindingProvider.js'
+
+type Options = {
+  abortSignal?: AbortSignal
+  onCancel: () => void
+  isActive?: boolean
+}
+
+export function useCancelRequest({ abortSignal, onCancel, isActive = true }: Options): void {
+  const canCancel = abortSignal !== undefined && !abortSignal.aborted
+
+  const handleCancel = useCallback(() => {
+    if (!canCancel) return
+    onCancel()
+  }, [canCancel, onCancel])
+
+  useKeybinding('chat:cancel', handleCancel, {
+    context: 'Chat',
+    isActive: isActive && canCancel,
+  })
+}

package/src/app/hooks/useDoublePress.ts

@@ -0,0 +1,46 @@
+
+import { useCallback, useEffect, useRef } from 'react'
+
+export const DOUBLE_PRESS_TIMEOUT_MS = 1800
+
+export function useDoublePress(
+  setPending: (pending: boolean) => void,
+  onDoublePress: () => void,
+): () => void {
+  const lastPressRef = useRef<number>(0)
+  const timeoutRef = useRef<NodeJS.Timeout | undefined>(undefined)
+
+  const clearPendingTimeout = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+      timeoutRef.current = undefined
+    }
+  }, [])
+
+  useEffect(() => {
+    return () => {
+      clearPendingTimeout()
+    }
+  }, [clearPendingTimeout])
+
+  return useCallback(() => {
+    const now = Date.now()
+    const elapsed = now - lastPressRef.current
+    const isDouble = elapsed <= DOUBLE_PRESS_TIMEOUT_MS && timeoutRef.current !== undefined
+
+    if (isDouble) {
+      clearPendingTimeout()
+      setPending(false)
+      onDoublePress()
+    } else {
+      setPending(true)
+      clearPendingTimeout()
+      timeoutRef.current = setTimeout(() => {
+        setPending(false)
+        timeoutRef.current = undefined
+      }, DOUBLE_PRESS_TIMEOUT_MS)
+    }
+
+    lastPressRef.current = now
+  }, [setPending, onDoublePress, clearPendingTimeout])
+}

package/src/app/hooks/useExitOnCtrlC.ts

@@ -0,0 +1,36 @@
+import { useCallback, useMemo, useState } from 'react'
+import { useApp } from 'ink'
+import { useKeybinding } from '../keybindings/KeybindingProvider.js'
+import { useDoublePress } from './useDoublePress.js'
+
+export type ExitState = {
+  pending: boolean
+  keyName: 'ctrl+c' | null
+}
+
+type Options = {
+  isActive?: boolean
+  onInterrupt?: () => boolean
+  onExit?: () => void
+}
+
+export function useExitOnCtrlC({ isActive = true, onInterrupt, onExit }: Options = {}): ExitState {
+  const { exit } = useApp()
+  const [state, setState] = useState<ExitState>({ pending: false, keyName: null })
+
+  const exitFn = useMemo(() => onExit ?? exit, [onExit, exit])
+
+  const ctrlCDouble = useDoublePress(
+    pending => setState({ pending, keyName: 'ctrl+c' }),
+    exitFn,
+  )
+
+  const handleInterrupt = useCallback(() => {
+    if (onInterrupt?.()) return
+    ctrlCDouble()
+  }, [onInterrupt, ctrlCDouble])
+
+  useKeybinding('app:interrupt', handleInterrupt, { context: 'Global', isActive })
+
+  return state
+}

package/src/app/input/AppInputProvider.tsx

@@ -0,0 +1,116 @@
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef } from 'react'
+import { useStdin, useStdout } from 'ink'
+import type { AppInputEvent } from './appInputParser.js'
+import {
+  BRACKETED_PASTE_DISABLE,
+  BRACKETED_PASTE_ENABLE,
+  createAppInputParseState,
+  DISABLE_KITTY_KEYBOARD,
+  DISABLE_MODIFY_OTHER_KEYS,
+  ENABLE_KITTY_KEYBOARD,
+  ENABLE_MODIFY_OTHER_KEYS,
+  hasPendingAppInput,
+  parseAppInput,
+} from './appInputParser.js'
+
+type InputHandler = (input: string, key: AppInputEvent['key'], event: AppInputEvent) => void
+
+type HandlerEntry = {
+  handlerRef: React.MutableRefObject<InputHandler>
+  isActiveRef: React.MutableRefObject<boolean>
+}
+
+type AppInputContextValue = {
+  register(entry: HandlerEntry): () => void
+}
+
+const AppInputContext = createContext<AppInputContextValue | null>(null)
+const PENDING_ESCAPE_FLUSH_MS = 50
+
+export const AppInputProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const { stdin } = useStdin()
+  const { stdout } = useStdout()
+  const handlersRef = useRef<Set<HandlerEntry>>(new Set())
+  const parseStateRef = useRef(createAppInputParseState())
+  const flushTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const dispatch = useCallback((event: AppInputEvent) => {
+    for (const entry of handlersRef.current) {
+      if (!entry.isActiveRef.current) continue
+      entry.handlerRef.current(event.input, event.key, event)
+    }
+  }, [])
+
+  const flushPending = useCallback(() => {
+    flushTimerRef.current = null
+    const result = parseAppInput(parseStateRef.current, null)
+    parseStateRef.current = result.state
+    for (const event of result.events) dispatch(event)
+  }, [dispatch])
+
+  const scheduleFlush = useCallback(() => {
+    if (flushTimerRef.current) clearTimeout(flushTimerRef.current)
+    flushTimerRef.current = setTimeout(flushPending, PENDING_ESCAPE_FLUSH_MS)
+  }, [flushPending])
+
+  useEffect(() => {
+    if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') return
+
+    const handleData = (chunk: Buffer | string) => {
+      if (flushTimerRef.current) {
+        clearTimeout(flushTimerRef.current)
+        flushTimerRef.current = null
+      }
+      const result = parseAppInput(parseStateRef.current, chunk)
+      parseStateRef.current = result.state
+      for (const event of result.events) dispatch(event)
+      if (hasPendingAppInput(parseStateRef.current)) scheduleFlush()
+    }
+
+    stdin.setEncoding('utf8')
+    stdin.setRawMode(true)
+    stdin.ref()
+    stdin.on('data', handleData)
+    stdin.resume()
+    stdout.write(BRACKETED_PASTE_ENABLE)
+    stdout.write(ENABLE_KITTY_KEYBOARD)
+    stdout.write(ENABLE_MODIFY_OTHER_KEYS)
+
+    return () => {
+      if (flushTimerRef.current) clearTimeout(flushTimerRef.current)
+      stdout.write(DISABLE_MODIFY_OTHER_KEYS)
+      stdout.write(DISABLE_KITTY_KEYBOARD)
+      stdout.write(BRACKETED_PASTE_DISABLE)
+      stdin.off('data', handleData)
+      stdin.setRawMode(false)
+      stdin.pause()
+      stdin.unref()
+    }
+  }, [dispatch, scheduleFlush, stdin, stdout])
+
+  const value = useMemo<AppInputContextValue>(() => ({
+    register(entry) {
+      handlersRef.current.add(entry)
+      return () => {
+        handlersRef.current.delete(entry)
+      }
+    },
+  }), [])
+
+  return <AppInputContext.Provider value={value}>{children}</AppInputContext.Provider>
+}
+
+export function useAppInput(
+  handler: InputHandler,
+  options: { isActive?: boolean } = {},
+): void {
+  const ctx = useContext(AppInputContext)
+  if (!ctx) throw new Error('useAppInput must be used inside AppInputProvider')
+
+  const handlerRef = useRef(handler)
+  const isActiveRef = useRef(options.isActive !== false)
+
+  useEffect(() => { handlerRef.current = handler }, [handler])
+  useEffect(() => { isActiveRef.current = options.isActive !== false }, [options.isActive])
+  useEffect(() => ctx.register({ handlerRef, isActiveRef }), [ctx])
+}