ethagent 1.1.2 → 2.0.0

package/src/identity/hub/flows/ens/IdentityHubEnsFlow.tsx

@@ -0,0 +1,299 @@
+import React from 'react'
+import { openImageFilePicker } from '../../../profile/imagePicker.js'
+import { readOwnerAddressField } from '../../../identityCompat.js'
+import type { BrowserWalletReady } from '../../../wallet/browserWallet.js'
+import type { ProfileUpdates, Step } from '../../identityHubReducer.js'
+import { readCustodyMode } from '../../model/custody.js'
+import { OperatorWalletsScreen } from './OperatorWalletsScreen.js'
+import { EDIT_PROFILE_STEPS, EditProfileFlow } from '../profile/EditProfileFlow.js'
+import { FlowTimeline } from '../../components/FlowTimeline.js'
+import { WalletApprovalScreen } from '../../components/WalletApprovalScreen.js'
+
+type StepOf<K extends Step['kind']> = Extract<Step, { kind: K }>
+
+type IdentityHubEnsStep = StepOf<
+  | 'manage-ens-operators'
+  | 'edit-profile-name'
+  | 'edit-profile-description'
+  | 'edit-profile-image'
+  | 'edit-profile-review'
+  | 'edit-profile-ens'
+  | 'ens-records-tx'
+  | 'ens-setup-registry-tx'
+  | 'ens-setup-records-tx'
+  | 'public-profile-signing'
+>
+
+type IdentityHubEnsFlowProps = {
+  step: IdentityHubEnsStep
+  walletSession: BrowserWalletReady | null
+  onSetStep: (step: Step) => void
+  onBack: () => void
+  onWalletReady: (session: BrowserWalletReady | null) => void
+  onTriggerRebackup: (backStep: Step, profileUpdates?: ProfileUpdates) => void
+  onTriggerPublicProfileSave: (backStep: Step, profileUpdates: ProfileUpdates) => void
+}
+
+export function isIdentityHubEnsStep(step: Step): step is IdentityHubEnsStep {
+  return step.kind === 'manage-ens-operators'
+    || step.kind === 'edit-profile-name'
+    || step.kind === 'edit-profile-description'
+    || step.kind === 'edit-profile-image'
+    || step.kind === 'edit-profile-review'
+    || step.kind === 'edit-profile-ens'
+    || step.kind === 'ens-records-tx'
+    || step.kind === 'ens-setup-registry-tx'
+    || step.kind === 'ens-setup-records-tx'
+    || step.kind === 'public-profile-signing'
+}
+
+export const IdentityHubEnsFlow: React.FC<IdentityHubEnsFlowProps> = ({
+  step,
+  walletSession,
+  onSetStep,
+  onBack,
+  onWalletReady,
+  onTriggerRebackup,
+  onTriggerPublicProfileSave,
+}) => {
+  if (step.kind === 'manage-ens-operators') {
+    return (
+      <OperatorWalletsScreen
+        identity={step.identity}
+        registry={step.registry}
+        walletSession={walletSession}
+        notice={step.notice}
+        error={step.error}
+        onSave={updates => onTriggerRebackup(step.returnTo ?? { kind: 'menu' }, updates)}
+        onWalletReady={onWalletReady}
+        onBack={onBack}
+      />
+    )
+  }
+
+  if (isEditProfileStep(step)) {
+    return (
+      <EditProfileFlow
+        step={step}
+        onNameSubmit={name => {
+          if (step.kind !== 'edit-profile-name') return
+          onSetStep({
+            kind: 'edit-profile-description',
+            identity: step.identity,
+            registry: step.registry,
+            name,
+            description: step.description,
+            imagePath: step.imagePath,
+            returnTo: step.returnTo,
+          })
+        }}
+        onDescriptionSubmit={description => {
+          if (step.kind !== 'edit-profile-description') return
+          onSetStep({ kind: 'edit-profile-image', identity: step.identity, registry: step.registry, name: step.name, description, imagePath: step.imagePath, returnTo: step.returnTo })
+        }}
+        onIconSubmit={iconPath => {
+          if (step.kind !== 'edit-profile-image') return
+          onSetStep({ kind: 'edit-profile-review', identity: step.identity, registry: step.registry, name: step.name, description: step.description, ...(iconPath !== undefined ? { imagePath: iconPath } : {}), returnTo: step.returnTo })
+        }}
+        onIconPick={() => {
+          if (step.kind !== 'edit-profile-image') return
+          const iconStep = step
+          void openImageFilePicker()
+            .then(result => {
+              if (!result.ok) {
+                onSetStep({ ...iconStep, error: result.cancelled ? 'icon selection cancelled.' : `${result.error}` })
+                return
+              }
+              onSetStep({
+                kind: 'edit-profile-review',
+                identity: iconStep.identity,
+                registry: iconStep.registry,
+                name: iconStep.name,
+                description: iconStep.description,
+                imagePath: result.file,
+                returnTo: iconStep.returnTo,
+              })
+            })
+            .catch((err: unknown) => {
+              onSetStep({ ...iconStep, error: `${(err as Error).message}` })
+            })
+        }}
+        onReviewSave={() => {
+          if (step.kind !== 'edit-profile-review') return
+          const updates: ProfileUpdates = {
+            name: step.name,
+            description: step.description,
+            ...(step.imagePath !== undefined ? { imagePath: step.imagePath } : {}),
+          }
+          onTriggerPublicProfileSave(step.returnTo ?? { kind: 'continuity-public' }, updates)
+        }}
+        onEnsLink={(fullName, options) => {
+          if (step.kind !== 'edit-profile-ens') return
+          const state = (step.identity.state ?? {}) as Record<string, unknown>
+          const savedOwnerAddress = readOwnerAddressField(state) ?? ''
+          const updates: ProfileUpdates = {
+            ensName: fullName,
+            ...(options.mode === 'advanced' && options.ownerAddress && !savedOwnerAddress ? { ownerAddress: options.ownerAddress } : {}),
+            ...(options.mode === 'advanced' && options.operatorWallet ? {
+              approvedOperatorWallets: [options.operatorWallet],
+              activeOperatorAddress: options.operatorWallet,
+            } : {}),
+          }
+          onTriggerRebackup(step.returnTo ?? { kind: 'menu' }, updates)
+        }}
+        onEnsUnlink={() => {
+          if (step.kind !== 'edit-profile-ens') return
+          onTriggerRebackup(step.returnTo ?? { kind: 'menu' }, { ensName: '' })
+        }}
+        onEnsRecordsUpdate={(fullName, records, options, clearRecords, currentRecords) => {
+          if (step.kind !== 'edit-profile-ens') return
+          onSetStep({
+            kind: 'ens-records-tx',
+            identity: step.identity,
+            registry: step.registry,
+            fullName,
+            records,
+            ...(currentRecords ? { currentRecords } : {}),
+            ...(clearRecords ? { clearRecords: true } : {}),
+            ...(options.mode === 'advanced' && options.ownerAddress ? { ownerAddress: options.ownerAddress } : {}),
+            returnTo: step.returnTo ?? { kind: 'menu' },
+          })
+        }}
+        onEnsSetup={setup => {
+          if (step.kind !== 'edit-profile-ens') return
+          if (setup.registryAction === 'none') {
+            onSetStep({
+              kind: 'ens-setup-records-tx',
+              identity: step.identity,
+              registry: step.registry,
+              setup,
+              returnTo: step.returnTo ?? { kind: 'menu' },
+            })
+            return
+          }
+          onSetStep({
+            kind: 'ens-setup-registry-tx',
+            identity: step.identity,
+            registry: step.registry,
+            setup,
+            returnTo: step.returnTo ?? { kind: 'menu' },
+          })
+        }}
+        onManageOperatorWalletAccess={() => {
+          if (step.kind !== 'edit-profile-ens') return
+          onSetStep({
+            kind: 'manage-ens-operators',
+            identity: step.identity,
+            registry: step.registry,
+            returnTo: { kind: 'edit-profile-ens', identity: step.identity, registry: step.registry, returnTo: step.returnTo, initialView: 'advanced' },
+          })
+        }}
+        onBack={onBack}
+        onMenu={() => onSetStep(step.returnTo ?? { kind: 'continuity-public' })}
+      />
+    )
+  }
+
+  if (step.kind === 'ens-records-tx') {
+    return (
+      <WalletApprovalScreen
+        title={step.clearRecords ? 'Unlink ENS' : 'Update ENS Records'}
+        subtitle={step.clearRecords
+          ? `Ethereum Mainnet: sign one transaction to clear ethagent record values on ${step.fullName}. Requires gas.`
+          : `Ethereum Mainnet: sign one transaction to set ENS records on ${step.fullName}. Requires gas.`}
+        walletSession={walletSession}
+        label="waiting for wallet transaction..."
+        onCancel={() => onSetStep({ kind: 'edit-profile-ens', identity: step.identity, registry: step.registry, returnTo: step.returnTo })}
+      />
+    )
+  }
+
+  if (step.kind === 'ens-setup-registry-tx') {
+    const signer = step.setup.mode === 'simple' ? 'Connected wallet' : 'Owner wallet'
+    return (
+      <WalletApprovalScreen
+        title={step.setup.mode === 'simple' ? 'Use Connected Wallet' : 'Use Owner Wallet'}
+        subtitle={`${signer} signs one Ethereum Mainnet ENS registry transaction for ${step.setup.fullName}.`}
+        walletSession={walletSession}
+        label={step.setup.mode === 'simple' ? 'waiting for connected wallet transaction...' : 'waiting for owner wallet transaction...'}
+        onCancel={() => onSetStep({
+          kind: 'edit-profile-ens',
+          identity: step.identity,
+          registry: step.registry,
+          returnTo: step.returnTo,
+          ...(step.setup.mode === 'advanced' ? { initialView: 'advanced' as const } : {}),
+        })}
+      />
+    )
+  }
+
+  if (step.kind === 'ens-setup-records-tx') {
+    const signer = step.setup.mode === 'simple' ? 'Connected wallet' : 'Owner wallet'
+    return (
+      <WalletApprovalScreen
+        title={step.setup.mode === 'simple' ? 'Use Connected Wallet' : 'Use Owner Wallet'}
+        subtitle={`${signer} signs one Ethereum Mainnet resolver transaction for ${step.setup.fullName}.`}
+        walletSession={walletSession}
+        label={step.setup.mode === 'simple' ? 'waiting for connected wallet transaction...' : 'waiting for owner wallet transaction...'}
+        onCancel={() => onSetStep({
+          kind: 'edit-profile-ens',
+          identity: step.identity,
+          registry: step.registry,
+          returnTo: step.returnTo,
+          ...(step.setup.mode === 'advanced' ? { initialView: 'advanced' as const } : {}),
+        })}
+      />
+    )
+  }
+
+  const approval = publicProfileWalletApprovalView(step)
+  return (
+    <WalletApprovalScreen
+      title={approval.title}
+      subtitle={approval.subtitle}
+      walletSession={walletSession}
+      label={approval.label}
+      onCancel={() => onSetStep(step.returnTo ?? { kind: 'continuity-public' })}
+    />
+  )
+}
+
+function publicProfileWalletApprovalView(step: StepOf<'public-profile-signing'>): {
+  title: string
+  subtitle: React.ReactNode
+  label: string
+} {
+  if (usesAdvancedSetup(step)) {
+    return {
+      title: 'Use Wallet',
+      subtitle: 'Sign the public profile and ERC-8004 token URI update.',
+      label: 'waiting for wallet signature...',
+    }
+  }
+  return {
+    title: 'Use Wallet',
+    subtitle: <FlowTimeline steps={EDIT_PROFILE_STEPS} current={5} />,
+    label: 'waiting for wallet signature...',
+  }
+}
+
+function usesAdvancedSetup(step: StepOf<'public-profile-signing'>): boolean {
+  const state = (step.identity.state ?? {}) as Record<string, unknown>
+  const custodyMode = step.profileUpdates?.custodyMode ?? readCustodyMode(state)
+  const ownerAddress = step.profileUpdates?.ownerAddress ?? readOwnerAddressField(state)
+  return custodyMode === 'advanced' && typeof ownerAddress === 'string' && ownerAddress.trim().length > 0
+}
+
+function isEditProfileStep(step: IdentityHubEnsStep): step is StepOf<
+  | 'edit-profile-name'
+  | 'edit-profile-description'
+  | 'edit-profile-image'
+  | 'edit-profile-review'
+  | 'edit-profile-ens'
+> {
+  return step.kind === 'edit-profile-name'
+    || step.kind === 'edit-profile-description'
+    || step.kind === 'edit-profile-image'
+    || step.kind === 'edit-profile-review'
+    || step.kind === 'edit-profile-ens'
+}

package/src/identity/hub/flows/ens/OperatorWalletsScreen.tsx

@@ -0,0 +1,398 @@
+import React from 'react'
+import { Box, Text } from 'ink'
+import { getAddress, isAddress, type Address } from 'viem'
+import { Surface } from '../../../../ui/Surface.js'
+import { Select, type SelectOption } from '../../../../ui/Select.js'
+import { Spinner } from '../../../../ui/Spinner.js'
+import { theme } from '../../../../ui/theme.js'
+import { useAppInput } from '../../../../app/input/AppInputProvider.js'
+import { openExternalUrl } from '../../../../utils/openExternal.js'
+import type { EthagentIdentity } from '../../../../storage/config.js'
+import { readOwnerAddressField } from '../../../identityCompat.js'
+import type { Erc8004RegistryConfig } from '../../../registry/erc8004.js'
+import {
+  createWalletRestoreAccessChallenge,
+  createWalletRestoreAccessKey,
+} from '../../../continuity/envelope.js'
+import { requestBrowserWalletSignature, type BrowserWalletReady } from '../../../wallet/browserWallet.js'
+import { FlowTimeline } from '../../components/FlowTimeline.js'
+import { OPEN_BROWSER_HINT } from '../../components/WalletApprovalScreen.js'
+import { readCustodyMode } from '../../model/custody.js'
+import { shortAddress } from '../../model/format.js'
+import type { ProfileUpdates } from '../../identityHubReducer.js'
+import {
+  normalizeApprovedOperatorWallets,
+  removeApprovedOperatorWallet,
+  upsertApprovedOperatorWallet,
+  type ApprovedOperatorWalletRecord,
+} from '../../operatorWallets.js'
+import {
+  reconcileWalletSetup,
+  type RecordsFixPlan,
+} from '../../reconciliation/index.js'
+
+type OperatorPhase =
+  | { kind: 'main'; notice?: string; error?: string }
+  | { kind: 'signing' }
+
+type OperatorAction =
+  | 'add-browser'
+  | 'back'
+  | 'remove-all'
+  | `remove:${string}`
+  | `activate:${string}`
+
+type OperatorWalletsScreenProps = {
+  identity: EthagentIdentity
+  registry: Erc8004RegistryConfig
+  walletSession: BrowserWalletReady | null
+  notice?: string
+  error?: string
+  onSave: (updates: ProfileUpdates) => void
+  onWalletReady: (session: BrowserWalletReady | null) => void
+  onBack: () => void
+}
+
+export const OperatorWalletsScreen: React.FC<OperatorWalletsScreenProps> = ({
+  identity,
+  registry,
+  walletSession,
+  notice,
+  error,
+  onSave,
+  onWalletReady,
+  onBack,
+}) => {
+  const state = (identity.state ?? {}) as Record<string, unknown>
+  const custodyMode = readCustodyMode(state)
+  const ownerAddressRaw = readOwnerAddressField(state)
+  const ownerAddress = ownerAddressRaw && isAddress(ownerAddressRaw, { strict: false }) ? getAddress(ownerAddressRaw) : undefined
+  const activeOperatorAddress = readStateAddress(state, 'activeOperatorAddress')
+  const restoreAccessEpoch = readStateNumber(state, 'restoreAccessEpoch') ?? 0
+  const records = normalizeApprovedOperatorWallets(state.approvedOperatorWallets)
+  const [phase, setPhase] = React.useState<OperatorPhase>({ kind: 'main', notice, error })
+  const [fixPlan, setFixPlan] = React.useState<RecordsFixPlan | null>(null)
+
+  React.useEffect(() => {
+    setPhase(current => current.kind === 'main' ? { kind: 'main', notice, error } : current)
+  }, [notice, error])
+
+  React.useEffect(() => {
+    if (custodyMode !== 'advanced' || records.length === 0) {
+      setFixPlan(null)
+      return
+    }
+    let cancelled = false
+    reconcileWalletSetup({ identity, registry })
+      .then(plan => { if (!cancelled) setFixPlan(plan) })
+      .catch(() => { if (!cancelled) setFixPlan(null) })
+    return () => { cancelled = true }
+  }, [identity, registry, custodyMode, records.length])
+
+  const driftItems = fixPlan?.items.filter(item =>
+    item.kind === 'missing-approval' || item.kind === 'stale-approval',
+  ) ?? []
+
+  const saveOperators = React.useCallback((
+    approvedOperatorWallets: ApprovedOperatorWalletRecord[],
+    activeOperator: Address | '' | undefined,
+  ) => {
+    const updates: ProfileUpdates = {
+      custodyMode: 'advanced',
+      ...(ownerAddress ? { ownerAddress } : {}),
+      approvedOperatorWallets,
+      restoreAccessEpoch: restoreAccessEpoch + 1,
+    }
+    if (activeOperator !== undefined) updates.activeOperatorAddress = activeOperator
+    onSave(updates)
+  }, [ownerAddress, onSave, restoreAccessEpoch])
+
+  const addRecord = React.useCallback((record: ApprovedOperatorWalletRecord) => {
+    if (!ownerAddress) {
+      setPhase({ kind: 'main', error: 'advanced custody needs an owner wallet before managing operator wallets' })
+      return
+    }
+    if (record.address.toLowerCase() === ownerAddress.toLowerCase()) {
+      setPhase({ kind: 'main', error: 'operator wallet must differ from the owner wallet' })
+      return
+    }
+    const next = upsertApprovedOperatorWallet(records, record)
+    const active = activeOperatorAddress ?? record.address
+    saveOperators(next, active)
+  }, [activeOperatorAddress, ownerAddress, records, saveOperators])
+
+  const startBrowserSignature = React.useCallback(() => {
+    if (!ownerAddress) {
+      setPhase({ kind: 'main', error: 'advanced custody needs an owner wallet before managing operator wallets' })
+      return
+    }
+    if (!identity.agentId) {
+      setPhase({ kind: 'main', error: 'agent token ID is required before authorizing a wallet' })
+      return
+    }
+    const token = restoreAccessToken(registry, identity.agentId)
+    const nextEpoch = restoreAccessEpoch + 1
+    setPhase({ kind: 'signing' })
+    requestBrowserWalletSignature({
+      chainId: registry.chainId,
+      purpose: 'operator-proof',
+      messageForAccount: account => createWalletRestoreAccessChallenge({
+        token,
+        ownerAddress: ownerAddress,
+        walletAddress: account,
+        accessEpoch: nextEpoch,
+        purpose: 'restore-operator',
+      }),
+      onReady: onWalletReady,
+    }).then(wallet => {
+      onWalletReady(null)
+      const restoreAccessKey = createWalletRestoreAccessKey({
+        token,
+        ownerAddress: ownerAddress,
+        walletAddress: wallet.account,
+        walletSignature: wallet.signature,
+        accessEpoch: nextEpoch,
+        createdAt: new Date().toISOString(),
+        purpose: 'restore-operator',
+      })
+      addRecord({
+        address: wallet.account,
+        challenge: wallet.message,
+        verifiedAt: restoreAccessKey.createdAt,
+        restoreAccessKey,
+      })
+    }).catch((err: unknown) => {
+      onWalletReady(null)
+      setPhase({ kind: 'main', error: err instanceof Error ? err.message : String(err) })
+    })
+  }, [addRecord, ownerAddress, identity.agentId, onWalletReady, registry, restoreAccessEpoch])
+
+  if (custodyMode !== 'advanced' || !ownerAddress) {
+    return (
+      <Surface
+        title="Operator Wallets"
+        subtitle="Advanced custody must be set up before operator wallets can be managed."
+        footer={footerHint('enter select · esc back')}
+      >
+        <Box flexDirection="column">
+          <Text color={theme.dim}>Switch to Advanced custody from the Custody Mode menu to capture an owner wallet.</Text>
+          <Text color={theme.dim}>Operator wallets can be changed later and never receive token control.</Text>
+          {phase.kind === 'main' && phase.error ? <Text color={theme.accentError}>{phase.error}</Text> : null}
+        </Box>
+        <Box marginTop={1}>
+          <Select<'back'>
+            options={[
+              { value: 'back', role: 'section', label: 'Navigation' },
+              { value: 'back', label: 'Back', hint: 'Return to the previous screen', role: 'utility' },
+            ]}
+            hintLayout="inline"
+            onSubmit={() => onBack()}
+            onCancel={onBack}
+          />
+        </Box>
+      </Surface>
+    )
+  }
+
+  if (phase.kind === 'signing') {
+    return (
+      <WalletWaitSurface
+        title="Authorize Wallet"
+        subtitle={
+          <Box flexDirection="column">
+            <FlowTimeline steps={['Verify Operator', 'Sign Backup', 'Publish Snapshot', 'Approve ENS', 'Approve Vault']} current={1} />
+            <Text color={theme.dim}>Operator wallet signs restore access. Owner wallet then re-attests the backup, publishes the new snapshot, and authorizes the operator onchain (ENS + vault).</Text>
+          </Box>
+        }
+        walletSession={walletSession}
+        onCancel={() => {
+          onWalletReady(null)
+          setPhase({ kind: 'main' })
+        }}
+      />
+    )
+  }
+
+  const options = operatorOptions({
+    records,
+    activeOperatorAddress,
+  })
+  const phaseNotice = phase.kind === 'main' ? phase.notice : undefined
+  const phaseError = phase.kind === 'main' ? phase.error : undefined
+
+  return (
+    <Surface
+      title="Operator Wallets"
+      subtitle="Owner wallet controls this list. The active operator wallet signs frequent updates; others stay authorized."
+      footer={footerHint('enter select · esc back')}
+    >
+      <Box flexDirection="column">
+        <Text>
+          <Text color={theme.dim}>{'Owner Wallet'.padEnd(18)}</Text>
+          <Text color={theme.text}>{shortAddress(ownerAddress)}</Text>
+        </Text>
+        <Box marginTop={1} flexDirection="column">
+          <Text color={theme.dim}>Operator Wallets</Text>
+          {records.length > 0
+            ? records.map(record => {
+                const isActive = record.address.toLowerCase() === activeOperatorAddress?.toLowerCase()
+                const approved = record.verifiedAt ? `approved ${record.verifiedAt.slice(0, 10)}` : null
+                const meta = [isActive ? 'active' : null, approved].filter(Boolean).join(' · ')
+                return (
+                  <Text key={record.address}>
+                    <Text color={isActive ? theme.accentPeriwinkle : theme.text}>
+                      {shortAddress(record.address)}
+                    </Text>
+                    {meta ? <Text color={theme.dim}>{`  ${meta}`}</Text> : null}
+                  </Text>
+                )
+              })
+            : <Text color={theme.dim}>No operator wallets saved.</Text>}
+        </Box>
+        <Box marginTop={1} flexDirection="column">
+          <Text color={theme.dim}>Add as many operator wallets as needed; unlink any saved wallet here.</Text>
+          <Text color={theme.dim}>No approve(), setApprovalForAll(), transferFrom(), or token approval is requested.</Text>
+        </Box>
+        {driftItems.length > 0
+          ? (
+              <Box marginTop={1} flexDirection="column">
+                <Text color="#e8a070">
+                  {`! ENS resolver drift: ${driftItems.length} operator wallet${driftItems.length === 1 ? '' : 's'} missing onchain approval.`}
+                </Text>
+                <Text color={theme.dim}>Run "Fix Records" from Custody Mode to re-sync; onchain ENS writes will fail until then.</Text>
+              </Box>
+            )
+          : null}
+        {phaseNotice ? <Text color={theme.accentPeriwinkle}>{phaseNotice}</Text> : null}
+        {phaseError ? <Text color={theme.accentError}>{phaseError}</Text> : null}
+      </Box>
+      <Box marginTop={1}>
+        <Select<OperatorAction>
+          options={options}
+          hintLayout="inline"
+          maxVisible={10}
+          onSubmit={choice => {
+            if (choice === 'add-browser') return startBrowserSignature()
+            if (choice === 'back') return onBack()
+            if (choice === 'remove-all') {
+              try {
+                saveOperators([], '')
+              } catch (err: unknown) {
+                setPhase({ kind: 'main', error: err instanceof Error ? err.message : String(err) })
+              }
+              return
+            }
+            if (choice.startsWith('remove:')) {
+              try {
+                const address = getAddress(choice.slice('remove:'.length))
+                const next = removeApprovedOperatorWallet(records, address)
+                const removedActive = activeOperatorAddress?.toLowerCase() === address.toLowerCase()
+                const nextActive = removedActive ? '' : activeOperatorAddress ?? ''
+                saveOperators(next, nextActive)
+              } catch (err: unknown) {
+                setPhase({ kind: 'main', error: err instanceof Error ? err.message : String(err) })
+              }
+            }
+            if (choice.startsWith('activate:')) {
+              try {
+                const address = getAddress(choice.slice('activate:'.length))
+                saveOperators(records, address)
+              } catch (err: unknown) {
+                setPhase({ kind: 'main', error: err instanceof Error ? err.message : String(err) })
+              }
+            }
+          }}
+          onCancel={onBack}
+        />
+      </Box>
+    </Surface>
+  )
+}
+
+function operatorOptions(args: {
+  records: ApprovedOperatorWalletRecord[]
+  activeOperatorAddress: Address | undefined
+}): Array<SelectOption<OperatorAction>> {
+  const options: Array<SelectOption<OperatorAction>> = [
+    { value: 'add-browser', role: 'section', label: 'Operator Wallets' },
+    { value: 'add-browser', label: 'Add Wallet', hint: 'Connect wallet to sign restore access' },
+  ]
+  if (args.records[0]) options.push({ value: `remove:${args.records[0].address}`, role: 'section', label: 'Operator Wallets' })
+  for (const record of args.records) {
+    const active = args.activeOperatorAddress?.toLowerCase() === record.address.toLowerCase()
+    if (!active) {
+      options.push({
+        value: `activate:${record.address}`,
+        label: `Set Active: ${shortAddress(record.address)}`,
+        hint: 'Make this the active operator wallet (owner wallet signs)',
+      })
+    }
+    options.push({
+      value: `remove:${record.address}`,
+      label: `Unlink ${shortAddress(record.address)}${active ? ' (active)' : ''}`,
+      hint: active
+        ? 'Active operator wallet. Unlinking clears the active slot; pick a new active from the list.'
+        : 'Remove this wallet from the approved list (owner wallet signs)',
+    })
+  }
+  if (args.records.length > 1) {
+    options.push({
+      value: 'remove-all',
+      label: 'Unlink All Operator Wallets',
+      hint: 'Remove every approved operator wallet (owner wallet signs)',
+    })
+  }
+  options.push(
+    { value: 'back', role: 'section', label: 'Navigation' },
+    { value: 'back', label: 'Back', hint: 'Return to the previous screen', role: 'utility' },
+  )
+  return options
+}
+
+const WalletWaitSurface: React.FC<{
+  title: string
+  subtitle: React.ReactNode
+  walletSession: BrowserWalletReady | null
+  onCancel: () => void
+}> = ({ title, subtitle, walletSession, onCancel }) => {
+  useAppInput((_input, key) => {
+    if (key.escape) onCancel()
+    if (key.return && walletSession?.url) {
+      openExternalUrl(walletSession.url)
+    }
+  })
+  return (
+    <Surface title={title} subtitle={subtitle} footer={footerHint('esc cancels')}>
+      <Box marginTop={1}>
+        <Spinner label={walletSession ? 'waiting for wallet signature...' : 'opening wallet request...'} />
+      </Box>
+      {walletSession ? (
+        <Box flexDirection="column">
+          <Text color={theme.accentPeriwinkle} underline>{walletSession.url}</Text>
+          <Text color={theme.dim}>{OPEN_BROWSER_HINT}</Text>
+        </Box>
+      ) : null}
+    </Surface>
+  )
+}
+
+const footerHint = (hint: string) => <Text color={theme.dim}>{hint}</Text>
+
+function readStateNumber(state: Record<string, unknown>, key: string): number | undefined {
+  const value = state[key]
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined
+}
+
+function restoreAccessToken(registry: Erc8004RegistryConfig, agentId: string) {
+  return {
+    chainId: registry.chainId,
+    identityRegistryAddress: registry.identityRegistryAddress,
+    agentId,
+  }
+}
+
+function readStateAddress(state: Record<string, unknown>, key: string): Address | undefined {
+  const value = state[key]
+  if (typeof value !== 'string' || !isAddress(value, { strict: false })) return undefined
+  return getAddress(value)
+}