ethagent 2.4.0 → 3.0.1

package/README.md

@@ -2,7 +2,7 @@
 
 A privacy-first AI agent with a portable Ethereum identity.
 
-ethagent binds an AI agent to a wallet-owned ERC-8004 token. Soul and memory stay encrypted under your wallet signature and pinned to IPFS. Public skills publish as plain JSON so other agents can discover what the agent does. Swap models, switch machines, or restore the same agent from a single onchain pointer.
+Switch providers or machines and the AI agent you customized stays behind. `ethagent` ties the agent to a wallet you own, so its soul, memory, and skills follow you across providers, machines, and models.
 
 - **Portable.** The ERC-8004 token is the agent's durable identity. Use the ENS name as a readable handle, or the token ID plus chain as the permanent reference, to restore the same agent anywhere.
 - **Private.** Soul and memory are encrypted before they are pinned to IPFS. The wallet signature used to unlock them stays local and never submits a transaction, spends funds, or grants token approval.
@@ -61,13 +61,16 @@ Every agent has a continuity directory at `~/.ethagent/continuity`.
 
 ## Continuity
 
-Each agent's continuity directory holds three files. Two are private and encrypted before they ever reach IPFS; one is public so other agents can discover what the agent does.
+Each agent's continuity directory holds a small set of files. Private files are encrypted before they ever reach IPFS; public files are plain JSON so other agents can discover what the agent does.
 
 | File | Visibility | Purpose |
 | --- | --- | --- |
 | `SOUL.md` | Private | Soul, boundaries, standing instructions, and identity framing. |
 | `MEMORY.md` | Private | Durable preferences, project context, decisions, and operating notes. |
-| `skills.json` | Public | Machine-readable capabilities. |
+| `skills/` | Mixed | Skill folders. Each skill is private, discoverable, or public; new skills default to discoverable. |
+| `skills.json` | Public | Machine-readable capabilities derived from public skills. |
+
+`SOUL.md`, `MEMORY.md`, and each `SKILL.md` are plain Markdown you edit through the Identity Hub under Continuity. Skills carry extra metadata: the frontmatter at the top of each `SKILL.md` (name, description, when_to_use, visibility, tags) tells the agent when to load it. Visibility is `private` (local-only, never shared), `discoverable` (indexed in `skills.json` so other agents can find it), or `public` (indexed and surfaced on the Agent Card).
 
 - **Save Snapshot Now** encrypts the private files, pins them to IPFS, and rotates the onchain pointer to the new CID.
 - **Refetch Latest** reads the pointer back, signs the decrypt challenge with your wallet, and overwrites local files from the snapshot.
@@ -97,7 +100,7 @@ Save the token ID + network somewhere safe. ENS records can be cleared and rebui
 
 **Prepare Token Transfer** runs before any ERC-8004 token transfer, and only when the token sits directly in your wallet. An agent in Advanced custody has to switch to Simple first from Custody Mode, which unwraps the token from its Vault back to the owner wallet.
 
-- sender signs snapshot access, receiver signs restore access.
+- Sender signs snapshot access, receiver signs restore access.
 - Sender publishes the snapshot pointer to the agent URI.
 - The actual transfer happens externally afterwards, in whichever wallet UI you prefer.
 - Once the token has moved, the receiver opens **Load Agent** with the receiving wallet and restores the same agent from the published snapshot.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ethagent",
-  "version": "2.4.0",
+  "version": "3.0.1",
   "description": "A privacy-first AI agent with a portable Ethereum identity",
   "type": "module",
   "main": "bin/ethagent.js",
@@ -56,6 +56,7 @@
     "react": "^19.2.4",
     "tsx": "^4.21.0",
     "viem": "^2.48.4",
+    "wrap-ansi": "^9.0.2",
     "zod": "^3.25.76"
   },
   "devDependencies": {

package/src/app/FirstRun.tsx

@@ -1,7 +1,8 @@
-import React, { useEffect, useState } from 'react'
+import React, { useEffect, useRef, useState } from 'react'
 import { Box, Text } from 'ink'
 import { BrandSplash as Splash } from '../ui/BrandSplash.js'
 import { Select } from '../ui/Select.js'
+import { Spinner } from '../ui/Spinner.js'
 import { Surface } from '../ui/Surface.js'
 import { TextInput } from '../ui/TextInput.js'
 import { theme } from '../ui/theme.js'
@@ -10,6 +11,9 @@ import { formatModelDisplayName } from '../models/modelDisplay.js'
 import { providerDisplayName } from '../models/providerDisplay.js'
 import { detectSpec, type SpecSnapshot } from '../models/runtimeDetection.js'
 import { FEATURED_HF_REPO_URL } from '../models/modelRecommendation.js'
+import { OPENAI_OAUTH_DEFAULT_MODEL } from '../models/catalog.js'
+import { OpenAIOAuthService } from '../auth/openaiOAuth/index.js'
+import { openExternalUrl } from '../utils/openExternal.js'
 import {
   loadConfig,
   saveConfigWithMerge,
@@ -31,6 +35,8 @@ type Step =
   | { kind: 'choose-path'; spec: SpecSnapshot }
   | { kind: 'hf-setup'; spec: SpecSnapshot }
   | { kind: 'cloud-provider' }
+  | { kind: 'cloud-openai-auth' }
+  | { kind: 'cloud-openai-oauth'; phase: 'waiting' | 'exchanging' | 'error'; url?: string; message?: string }
   | { kind: 'cloud-key'; provider: ProviderId; error?: string }
   | { kind: 'cloud-key-saving'; provider: ProviderId }
   | { kind: 'cloud-model'; provider: ProviderId }
@@ -44,17 +50,19 @@ type FirstRunProps = {
 }
 
 const TITLE: Record<string, string> = {
-  'detecting':         'Inspecting Machine',
-  'detect-error':      'Detection Failed',
-  'choose-path':       'Choose How To Run',
-  'hf-setup':          'Local Model',
-  'cloud-provider':    'Pick A Cloud Provider',
-  'cloud-key':         'Paste API Key',
-  'cloud-key-saving':  'Storing Key',
-  'cloud-model':       'Pick A Model',
-  'saving':            'Saving Config',
-  'save-error':        'Save Failed',
-  'done':              'Ready',
+  'detecting':              'Inspecting Machine',
+  'detect-error':           'Detection Failed',
+  'choose-path':            'Choose How To Run',
+  'hf-setup':               'Local Model',
+  'cloud-provider':         'Pick A Cloud Provider',
+  'cloud-openai-auth':      'Sign in with ChatGPT or API Key',
+  'cloud-openai-oauth':     'Sign in with ChatGPT',
+  'cloud-key':              'Paste API Key',
+  'cloud-key-saving':       'Storing Key',
+  'cloud-model':            'Pick A Model',
+  'saving':                 'Saving Config',
+  'save-error':             'Save Failed',
+  'done':                   'Ready',
 }
 
 const NAV_BACK = '↑↓ navigate · enter select · esc back'
@@ -65,6 +73,7 @@ export const FirstRun: React.FC<FirstRunProps> = ({ onComplete, onCancel }) => {
   const [history, setHistory] = useState<Step[]>([])
   const [firstRunIdentity, setFirstRunIdentity] = useState<EthagentConfig['identity']>(undefined)
   const [firstRunConfig, setFirstRunConfig] = useState<EthagentConfig | undefined>(undefined)
+  const oauthServiceRef = useRef<OpenAIOAuthService | null>(null)
 
   useEffect(() => {
     let cancelled = false
@@ -171,6 +180,51 @@ export const FirstRun: React.FC<FirstRunProps> = ({ onComplete, onCancel }) => {
 
   const navHint = (canBack: boolean): string => canBack ? NAV_BACK : NAV_CANCEL
 
+  const startFirstRunOpenAIOAuth = async (): Promise<void> => {
+    oauthServiceRef.current?.cleanup()
+    const service = new OpenAIOAuthService()
+    oauthServiceRef.current = service
+    goTo({ kind: 'cloud-openai-oauth', phase: 'waiting' })
+    try {
+      const result = await service.start(authUrl => {
+        openExternalUrl(authUrl)
+        setStep({ kind: 'cloud-openai-oauth', phase: 'waiting', url: authUrl })
+      })
+      if (oauthServiceRef.current !== service) return
+      setStep({ kind: 'cloud-openai-oauth', phase: 'exchanging' })
+      if (result.kind === 'apikey') {
+        if (typeof result.apiKey !== 'string' || result.apiKey.length === 0) {
+          throw new Error('OAuth result was apikey kind but no key was returned')
+        }
+        await setKey('openai', result.apiKey)
+      }
+      if (oauthServiceRef.current !== service) return
+      oauthServiceRef.current = null
+      if (result.kind === 'oauth-only') {
+        setStep({
+          kind: 'saving',
+          config: withFirstRunIdentity({
+            version: 1,
+            provider: 'openai',
+            model: OPENAI_OAUTH_DEFAULT_MODEL,
+            firstRunAt: new Date().toISOString(),
+          }),
+        })
+        return
+      }
+      setStep({ kind: 'cloud-model', provider: 'openai' })
+    } catch (err: unknown) {
+      if (oauthServiceRef.current !== service) return
+      oauthServiceRef.current = null
+      const message = err instanceof Error ? err.message : String(err)
+      if (message === 'OpenAI sign-in was cancelled.') {
+        setStep({ kind: 'cloud-openai-auth' })
+        return
+      }
+      setStep({ kind: 'cloud-openai-oauth', phase: 'error', message })
+    }
+  }
+
   const withFirstRunIdentity = (config: EthagentConfig): EthagentConfig => {
     const merged: EthagentConfig = firstRunConfig
       ? {
@@ -271,11 +325,12 @@ export const FirstRun: React.FC<FirstRunProps> = ({ onComplete, onCancel }) => {
             {spec.isAppleSilicon ? ', Apple Silicon' : ''}
           </Text>
         </Box>
-        <Select<'cloud' | 'hf'>
+        <Select<'hf' | 'cloud'>
           options={[
-            { value: 'cloud', label: 'Cloud API', hint: 'OpenAI, Anthropic, or Gemini' },
             { value: 'hf', label: 'Local Model', hint: 'Download and run locally' },
+            { value: 'cloud', label: 'Cloud API', hint: 'OpenAI, Anthropic, or Gemini' },
           ]}
+          hintLayout="inline"
           onSubmit={choice => {
             if (choice === 'cloud') goTo({ kind: 'cloud-provider' })
             else goTo({ kind: 'hf-setup', spec })
@@ -300,6 +355,7 @@ export const FirstRun: React.FC<FirstRunProps> = ({ onComplete, onCancel }) => {
         currentProvider="llamacpp"
         currentModel={modelPickerConfig.model}
         featuredHfRepo={FEATURED_HF_REPO_URL}
+        localOnly
         onPick={(selection: ModelPickerSelection) => {
           goTo({ kind: 'saving', config: configFromModelPickerSelection(selection, modelPickerConfig) })
         }}
@@ -316,12 +372,96 @@ export const FirstRun: React.FC<FirstRunProps> = ({ onComplete, onCancel }) => {
           { value: 'anthropic', label: 'Anthropic' },
           { value: 'gemini', label: 'Gemini' },
         ]}
-        onSubmit={provider => goTo({ kind: 'cloud-key', provider })}
+        onSubmit={provider => {
+          if (provider === 'openai') goTo({ kind: 'cloud-openai-auth' })
+          else goTo({ kind: 'cloud-key', provider })
+        }}
         onCancel={goBack}
       />
     ), navHint(true))
   }
 
+  if (step.kind === 'cloud-openai-auth') {
+    return renderShell(step.kind, TITLE['cloud-openai-auth']!, (
+      <Select<'oauth' | 'apikey'>
+        options={[
+          { value: 'oauth', role: 'section', label: 'Recommended' },
+          { value: 'oauth', label: 'Sign in with ChatGPT', hint: 'Use your ChatGPT subscription', bold: true },
+          { value: 'apikey', role: 'section', label: 'Alternative' },
+          { value: 'apikey', label: 'Paste API Key', hint: 'Use an OpenAI platform key', role: 'utility' },
+        ]}
+        hintLayout="inline"
+        onSubmit={choice => {
+          if (choice === 'oauth') void startFirstRunOpenAIOAuth()
+          else goTo({ kind: 'cloud-key', provider: 'openai' })
+        }}
+        onCancel={goBack}
+      />
+    ), navHint(true))
+  }
+
+  if (step.kind === 'cloud-openai-oauth') {
+    if (step.phase === 'error') {
+      return renderShell(step.kind, TITLE['cloud-openai-oauth']!, (
+        <>
+          <Text color={theme.accentError}>{step.message ?? 'Sign-in did not complete.'}</Text>
+          <Box marginTop={1}>
+            <Select<'retry' | 'apikey' | 'back'>
+              options={[
+                { value: 'retry', role: 'section', label: 'Recovery' },
+                { value: 'retry', label: 'Try Again', hint: 'Reopen the browser sign-in flow' },
+                { value: 'apikey', label: 'Use API Key Instead', hint: 'Paste an OpenAI platform key' },
+                { value: 'back', role: 'section', label: 'Navigation' },
+                { value: 'back', label: 'Back', hint: 'Return to sign-in choice', role: 'utility' },
+              ]}
+              hintLayout="inline"
+              onSubmit={choice => {
+                if (choice === 'retry') void startFirstRunOpenAIOAuth()
+                else if (choice === 'apikey') goTo({ kind: 'cloud-key', provider: 'openai' })
+                else goTo({ kind: 'cloud-openai-auth' })
+              }}
+              onCancel={() => goTo({ kind: 'cloud-openai-auth' })}
+            />
+          </Box>
+        </>
+      ), navHint(true))
+    }
+    if (step.phase === 'exchanging') {
+      return renderShell(step.kind, TITLE['cloud-openai-oauth']!, (
+        <Box marginTop={1}>
+          <Spinner label="completing sign-in..." />
+        </Box>
+      ))
+    }
+    return renderShell(step.kind, TITLE['cloud-openai-oauth']!, (
+      <>
+        <Spinner label="waiting for browser sign-in..." />
+        {step.url ? (
+          <Box flexDirection="column" marginTop={1}>
+            <Text color={theme.dim}>If the browser did not open, visit:</Text>
+            <Text color={theme.dim}>{step.url}</Text>
+          </Box>
+        ) : null}
+        <Box marginTop={1}>
+          <Select<'cancel'>
+            options={[{ value: 'cancel', label: 'Cancel Sign-in', role: 'utility' }]}
+            hintLayout="inline"
+            onSubmit={() => {
+              oauthServiceRef.current?.cleanup()
+              oauthServiceRef.current = null
+              goTo({ kind: 'cloud-openai-auth' })
+            }}
+            onCancel={() => {
+              oauthServiceRef.current?.cleanup()
+              oauthServiceRef.current = null
+              goTo({ kind: 'cloud-openai-auth' })
+            }}
+          />
+        </Box>
+      </>
+    ))
+  }
+
   if (step.kind === 'cloud-key' || step.kind === 'cloud-key-saving') {
     const provider = step.provider
     const saving = step.kind === 'cloud-key-saving'

package/src/app/FirstRunTimeline.tsx

@@ -11,6 +11,8 @@ export type FirstRunStepKind =
   | 'choose-path'
   | 'hf-setup'
   | 'cloud-provider'
+  | 'cloud-openai-auth'
+  | 'cloud-openai-oauth'
   | 'cloud-key'
   | 'cloud-key-saving'
   | 'cloud-model'
@@ -29,6 +31,8 @@ export function firstRunStageNumber(stepKind: FirstRunStepKind): number {
     case 'choose-path':
     case 'hf-setup':
     case 'cloud-provider':
+    case 'cloud-openai-auth':
+    case 'cloud-openai-oauth':
     case 'cloud-key':
     case 'cloud-key-saving':
     case 'cloud-model':

package/src/app/input/AppInputProvider.tsx

@@ -1,3 +1,6 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef } from 'react'
 import { useStdin, useStdout } from 'ink'
 import type { AppInputEvent } from './appInputParser.js'
@@ -13,6 +16,21 @@ import {
   parseAppInput,
 } from './appInputParser.js'
 
+const DEBUG_INPUT = Boolean(process.env.ETHAGENT_DEBUG_INPUT)
+const DEBUG_LOG_PATH = path.join(os.homedir(), '.ethagent', 'input-debug.log')
+
+function logRawChunk(chunk: Buffer | string): void {
+  if (!DEBUG_INPUT) return
+  try {
+    const text = typeof chunk === 'string' ? chunk : chunk.toString('utf8')
+    const codepoints = [...text].map(c => c.codePointAt(0)?.toString(16).padStart(4, '0') ?? '????').join(' ')
+    const hex = Buffer.isBuffer(chunk) ? chunk.toString('hex') : Buffer.from(chunk, 'utf8').toString('hex')
+    const line = `[${new Date().toISOString()}] codepoints=${codepoints} hex=${hex} text=${JSON.stringify(text)}\n`
+    fs.appendFileSync(DEBUG_LOG_PATH, line)
+  } catch {
+  }
+}
+
 type InputHandler = (input: string, key: AppInputEvent['key'], event: AppInputEvent) => void
 
 type HandlerEntry = {
@@ -57,6 +75,7 @@ export const AppInputProvider: React.FC<{ children: React.ReactNode }> = ({ chil
     if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') return
 
     const handleData = (chunk: Buffer | string) => {
+      logRawChunk(chunk)
       if (flushTimerRef.current) {
         clearTimeout(flushTimerRef.current)
         flushTimerRef.current = null

package/src/app/input/appInputParser.ts

@@ -175,9 +175,11 @@ function parseNormalInput(source: string, flushing: boolean): NormalParseResult
 
   if (source.length >= 2) {
     const next = source.slice(1, 2)
+    const code = next.charCodeAt(0)
+    const altInput = code >= 0x20 && code <= 0x7e ? next : ''
     return {
       kind: 'event',
-      event: createInputEvent(next, { meta: true }, source.slice(0, 2)),
+      event: createInputEvent(altInput, { meta: true }, source.slice(0, 2)),
       length: 2,
     }
   }
@@ -189,6 +191,18 @@ function parseNormalInput(source: string, flushing: boolean): NormalParseResult
   }
 }
 
+const PRINTABLE_CHAR_RE = /[\p{L}\p{N}\p{M}\p{P}\p{S}\p{Z}]/u
+
+function stripNoise(text: string): string {
+  let out = ''
+  for (const ch of text) {
+    if (ch === '\uFFFD') continue
+    if (!PRINTABLE_CHAR_RE.test(ch)) continue
+    out += ch
+  }
+  return out
+}
+
 function createTextEvent(text: string): AppInputEvent {
   if (text === '\r' || text === '\n') return createInputEvent('', { return: true }, text)
   if (text === '\t') return createInputEvent('', { tab: true }, text)
@@ -204,7 +218,8 @@ function createTextEvent(text: string): AppInputEvent {
     }
     if (/[A-Z]/.test(text)) return createInputEvent(text, { shift: true }, text)
   }
-  return createInputEvent(text, {}, text)
+  const cleaned = stripNoise(text)
+  return createInputEvent(cleaned, {}, text)
 }
 
 function keycodeEvent(raw: string, codepoint: number, modifier: number): AppInputEvent {
@@ -212,8 +227,8 @@ function keycodeEvent(raw: string, codepoint: number, modifier: number): AppInpu
   if (codepoint === 9)  return createInputEvent('', { ...key, tab: true }, raw)
   if (codepoint === 13) return createInputEvent('', { ...key, return: true }, raw)
   if (codepoint === 27) return createInputEvent('', { ...key, escape: true, meta: true }, raw)
-  const char = String.fromCodePoint(codepoint)
-  return createInputEvent(char, key, raw)
+  const printable = codepoint >= 0x20 && codepoint <= 0x7e
+  return createInputEvent(printable ? String.fromCodePoint(codepoint) : '', key, raw)
 }
 
 function decodeModifier(modifier: number): Partial<Key> {

package/src/chat/ChatBottomPane.tsx

@@ -55,6 +55,7 @@ type ChatBottomPaneProps = {
   history: string[]
   busy: boolean
   streaming: boolean
+  streamingStartedAt: number | null
   activity: BottomPaneActivity
   placeholderHints: string[]
   queuedInputs: string[]
@@ -101,6 +102,7 @@ export function ChatBottomPane({
   history,
   busy,
   streaming,
+  streamingStartedAt,
   activity,
   placeholderHints,
   queuedInputs,
@@ -257,7 +259,7 @@ export function ChatBottomPane({
         </Box>
       ) : streaming ? (
         <Box marginLeft={2} marginBottom={1}>
-          <Spinner active hint="esc to cancel" />
+          <Spinner active hint="esc to cancel" startedAt={streamingStartedAt ?? undefined} />
         </Box>
       ) : null}
       <ChatInput

package/src/chat/ChatScreen.tsx

@@ -134,6 +134,7 @@ export const ChatScreen: React.FC<ChatScreenProps> = ({ config: initialConfig, o
   const [rows, setRows] = useState<MessageRow[]>([])
   const [history, setHistory] = useState<string[]>([])
   const [streaming, setStreaming] = useState(false)
+  const [streamingStartedAt, setStreamingStartedAt] = useState<number | null>(null)
   const [queuedInputs, setQueuedInputs] = useState<string[]>([])
   const [turns, setTurns] = useState(0)
   const [approxTokens, setApproxTokens] = useState(0)
@@ -840,6 +841,10 @@ export const ChatScreen: React.FC<ChatScreenProps> = ({ config: initialConfig, o
       const controller = new AbortController()
       streamAbortRef.current = controller
       let planCandidate: PendingPlan | null = null
+      const setStreamingWithStart = (value: boolean) => {
+        setStreaming(value)
+        setStreamingStartedAt(value ? Date.now() : null)
+      }
       const result = await runStreamingTurn({
         provider: turnProvider,
         mode: activeMode,
@@ -854,7 +859,7 @@ export const ChatScreen: React.FC<ChatScreenProps> = ({ config: initialConfig, o
         getDisplayCwd: () => compressHome(cwdRef.current),
         getSessionMessages: () => sessionMessagesRef.current,
         setActiveCheckpoint: checkpoint => { activeCheckpointRef.current = checkpoint },
-        setStreaming,
+        setStreaming: setStreamingWithStart,
         updateRows,
         pushNote,
         persistTurnMessage: message => persistSessionMessage(attachActiveTurn(message)),
@@ -1569,6 +1574,7 @@ export const ChatScreen: React.FC<ChatScreenProps> = ({ config: initialConfig, o
           history={history}
           busy={busy}
           streaming={streaming}
+          streamingStartedAt={streamingStartedAt}
           activity={null}
           placeholderHints={placeholderHints}
           queuedInputs={queuedInputs}

package/src/chat/ConversationStack.tsx

@@ -1,5 +1,5 @@
 import React from 'react'
-import { Box } from 'ink'
+import { Box, Static } from 'ink'
 import { TranscriptView } from './transcript/TranscriptView.js'
 import type { MessageRow } from './MessageList.js'
 
@@ -27,24 +27,30 @@ export const ConversationStack: React.FC<ConversationStackProps> = ({
   onTranscriptScrollabilityChange,
 }) => {
   return (
-    <Box flexDirection="column" padding={1}>
-      {header}
-      <TranscriptView
-        key={`transcript-${sessionKey}`}
-        rows={rows}
-        active={transcriptActive}
-        bottomVariant={bottomVariant}
-        onVisibleReasoningIdsChange={onVisibleReasoningIdsChange}
-        onScrollabilityChange={onTranscriptScrollabilityChange}
-      />
-      <Box marginTop={1} width="100%">
-        {bottom}
-      </Box>
-      {status ? (
-        <Box marginTop={1}>
-          {status}
-        </Box>
+    <>
+      {header ? (
+        <Static items={[{ id: `header-${sessionKey}`, node: header }]}>
+          {item => <Box key={item.id} paddingX={1} paddingTop={1}>{item.node}</Box>}
+        </Static>
       ) : null}
-    </Box>
+      <Box flexDirection="column" padding={1}>
+        <TranscriptView
+          key={`transcript-${sessionKey}`}
+          rows={rows}
+          active={transcriptActive}
+          bottomVariant={bottomVariant}
+          onVisibleReasoningIdsChange={onVisibleReasoningIdsChange}
+          onScrollabilityChange={onTranscriptScrollabilityChange}
+        />
+        <Box marginTop={1} width="100%">
+          {bottom}
+        </Box>
+        {status ? (
+          <Box marginTop={1}>
+            {status}
+          </Box>
+        ) : null}
+      </Box>
+    </>
   )
 }