ethagent 1.1.2 → 2.0.1

package/src/identity/hub/flows/custody/custodyFlowActions.ts

@@ -0,0 +1,236 @@
+import type { Address } from 'viem'
+import { createErc8004PublicClient } from '../../../registry/erc8004.js'
+import { discoverPriorVaultFromTokenOwner, isAgentInVault } from '../../../registry/operatorVault.js'
+import type { ProfileUpdates, Step } from '../../identityHubReducer.js'
+import { isCustodyEditStep } from './CustodyEditFlow.js'
+import { resolveOperatorVaultAddress } from './custodyEffects.js'
+import type { CustodyFlowDeps } from './custodyFlowTypes.js'
+import { humanOwnerAddress } from './custodyFlowHelpers.js'
+
+export function createCustodyFlowActions({
+  config,
+  setStep,
+  handleStepError,
+  guardOwnership,
+  triggerRebackup,
+}: CustodyFlowDeps): {
+  beginVaultDeposit: (currentStep: Step, returnTo: Step, profileUpdates: ProfileUpdates) => void
+  beginVaultUnwrap: (currentStep: Step, returnTo: Step, profileUpdates: ProfileUpdates) => void
+  beginWithdrawToken: (currentStep: Step, returnTo: Step) => void
+  beginReturnToVault: (currentStep: Step, returnTo: Step, vaultAddress: Address) => void
+} {
+  const beginVaultDeposit = (currentStep: Step, returnTo: Step, profileUpdates: ProfileUpdates): void => {
+    if (!isCustodyEditStep(currentStep) || currentStep.kind !== 'custody-advanced-confirm') return
+    const vaultAddress = resolveOperatorVaultAddress(currentStep.identity, config?.erc8004?.operatorVaults)
+    const expectedOwnerForDiscovery = humanOwnerAddress(currentStep.identity)
+    if (!vaultAddress) {
+      const registry = currentStep.registry
+      ;(async () => {
+        try {
+          const client = createErc8004PublicClient(registry)
+          const probe = await discoverPriorVaultFromTokenOwner({
+            client,
+            registry: registry.identityRegistryAddress,
+            agentId: BigInt(currentStep.identity.agentId ?? '0'),
+            expectedOwner: expectedOwnerForDiscovery,
+          })
+          if (probe.found) {
+            const recoveredVault = probe.vaultAddress
+            const recoveredProfileUpdates = withVaultProfileUpdates(profileUpdates, recoveredVault)
+            const status = await isAgentInVault({
+              client,
+              vaultAddress: recoveredVault,
+              registry: registry.identityRegistryAddress,
+              agentId: BigInt(currentStep.identity.agentId ?? '0'),
+            })
+            if (status.inVault && status.ownerAddress?.toLowerCase() === expectedOwnerForDiscovery.toLowerCase()) {
+              triggerRebackup(returnTo, recoveredProfileUpdates, { vaultAddress: recoveredVault })
+              return
+            }
+            if (status.inVault) {
+              handleStepError(
+                new Error(`Recovered operator delegation vault ${recoveredVault} holds the token, but the vault-level depositor is ${status.ownerAddress ?? 'unknown'}, not your wallet ${expectedOwnerForDiscovery}. Mid-flow recovery requires the original depositor's wallet to call vault.unwrap.`),
+                { kind: 'custody-model', identity: currentStep.identity, registry, returnTo },
+              )
+              return
+            }
+            setStep({
+              kind: 'custody-vault-deposit-tx',
+              identity: currentStep.identity,
+              registry,
+              vaultAddress: recoveredVault,
+              profileUpdates: recoveredProfileUpdates,
+              returnTo,
+            })
+            return
+          }
+        } catch {
+          void 0
+        }
+        setStep({
+          kind: 'custody-vault-deploy-tx',
+          identity: currentStep.identity,
+          registry,
+          profileUpdates,
+          returnTo,
+        })
+      })()
+      return
+    }
+    const expectedOwner = humanOwnerAddress(currentStep.identity)
+    const registry = currentStep.registry
+    ;(async () => {
+      try {
+        const client = createErc8004PublicClient(registry)
+        const vaultProfileUpdates = withVaultProfileUpdates(profileUpdates, vaultAddress)
+        const status = await isAgentInVault({
+          client,
+          vaultAddress,
+          registry: registry.identityRegistryAddress,
+          agentId: BigInt(currentStep.identity.agentId ?? '0'),
+        })
+        if (status.inVault && status.ownerAddress?.toLowerCase() === expectedOwner.toLowerCase()) {
+          triggerRebackup(returnTo, vaultProfileUpdates, { vaultAddress })
+          return
+        }
+        if (status.inVault) {
+          handleStepError(
+            new Error(`Token is held by the operator delegation vault, but the vault-level owner is ${status.ownerAddress ?? 'unknown'}, not your wallet ${expectedOwner}. Recovery requires that wallet to call vault.unwrap.`),
+            { kind: 'custody-model', identity: currentStep.identity, registry, returnTo },
+          )
+          return
+        }
+        setStep({
+          kind: 'custody-vault-deposit-tx',
+          identity: currentStep.identity,
+          registry,
+          vaultAddress,
+          profileUpdates: vaultProfileUpdates,
+          returnTo,
+        })
+      } catch (err: unknown) {
+        setStep({
+          kind: 'custody-vault-deposit-tx',
+          identity: currentStep.identity,
+          registry,
+          vaultAddress,
+          profileUpdates: withVaultProfileUpdates(profileUpdates, vaultAddress),
+          returnTo,
+        })
+        void err
+      }
+    })()
+  }
+
+  const beginWithdrawToken = (currentStep: Step, returnTo: Step): void => {
+    if (!isCustodyEditStep(currentStep)) return
+    const vaultAddress = resolveOperatorVaultAddress(currentStep.identity, config?.erc8004?.operatorVaults)
+    if (!vaultAddress) {
+      handleStepError(
+        new Error('No agent vault is recorded for this identity. There is nothing to withdraw.'),
+        { kind: 'custody-model', identity: currentStep.identity, registry: currentStep.registry, returnTo },
+      )
+      return
+    }
+    const depositor = humanOwnerAddress(currentStep.identity)
+    const activeAgentId = currentStep.identity.agentId
+    if (!activeAgentId) {
+      handleStepError(
+        new Error('This identity does not have an ERC-8004 token ID. There is nothing to withdraw.'),
+        { kind: 'custody-model', identity: currentStep.identity, registry: currentStep.registry, returnTo },
+      )
+      return
+    }
+    setStep({
+      kind: 'custody-vault-withdraw-discovering',
+      identity: currentStep.identity,
+      registry: currentStep.registry,
+      vaultAddress,
+      returnTo,
+    })
+    ;(async () => {
+      const client = createErc8004PublicClient(currentStep.registry)
+      try {
+        const status = await isAgentInVault({
+          client,
+          vaultAddress,
+          registry: currentStep.registry.identityRegistryAddress,
+          agentId: BigInt(activeAgentId),
+        })
+        if (status.inVault) {
+          if (status.ownerAddress && status.ownerAddress.toLowerCase() !== depositor.toLowerCase()) {
+            handleStepError(
+              new Error(`Agent vault holds token #${activeAgentId} but recorded the depositor as ${status.ownerAddress}, not your wallet ${depositor}. Only the original depositor can withdraw.`),
+              { kind: 'custody-model', identity: currentStep.identity, registry: currentStep.registry, returnTo },
+            )
+            return
+          }
+          setStep({
+            kind: 'custody-vault-withdraw-tx',
+            identity: currentStep.identity,
+            registry: currentStep.registry,
+            vaultAddress,
+            agentId: activeAgentId,
+            returnTo,
+          })
+          return
+        }
+        handleStepError(
+          new Error(`Token #${activeAgentId} is not currently in the agent vault. There is nothing to withdraw; the token is already with the owner wallet.`),
+          { kind: 'custody-model', identity: currentStep.identity, registry: currentStep.registry, returnTo },
+        )
+      } catch (err: unknown) {
+        handleStepError(err, { kind: 'custody-model', identity: currentStep.identity, registry: currentStep.registry, returnTo })
+      }
+    })()
+  }
+
+  const beginVaultUnwrap = (currentStep: Step, returnTo: Step, profileUpdates: ProfileUpdates): void => {
+    if (!isCustodyEditStep(currentStep) || currentStep.kind !== 'custody-simple-confirm') return
+    const vaultAddress = resolveOperatorVaultAddress(currentStep.identity, config?.erc8004?.operatorVaults)
+    if (!vaultAddress) {
+      triggerRebackup(returnTo, profileUpdates, { useVault: false })
+      return
+    }
+    ;(async () => {
+      const allowed = await guardOwnership(currentStep.identity, currentStep.registry, 'vault-level-owner', returnTo)
+      if (!allowed) return
+      const agentIds = currentStep.identity.agentId ? [currentStep.identity.agentId] : []
+      setStep({
+        kind: 'custody-vault-unwrap-tx',
+        identity: currentStep.identity,
+        registry: currentStep.registry,
+        vaultAddress,
+        profileUpdates,
+        returnTo,
+        agentIds,
+      })
+    })()
+  }
+
+  const beginReturnToVault = (currentStep: Step, returnTo: Step, vaultAddress: Address): void => {
+    if (!isCustodyEditStep(currentStep)) return
+    setStep({
+      kind: 'custody-vault-deposit-tx',
+      identity: currentStep.identity,
+      registry: currentStep.registry,
+      vaultAddress,
+      profileUpdates: withVaultProfileUpdates({}, vaultAddress),
+      returnTo,
+    })
+  }
+
+  return {
+    beginVaultDeposit,
+    beginVaultUnwrap,
+    beginWithdrawToken,
+    beginReturnToVault,
+  }
+}
+
+function withVaultProfileUpdates(profileUpdates: ProfileUpdates, vaultAddress: Address): ProfileUpdates {
+  return {
+    ...profileUpdates,
+    operatorVaultAddress: vaultAddress,
+  }
+}

package/src/identity/hub/flows/custody/custodyFlowEffects.ts

@@ -0,0 +1,163 @@
+import { useEffect } from 'react'
+import { createErc8004PublicClient } from '../../../registry/erc8004.js'
+import { confirmAgentInVault } from '../../../registry/operatorVault.js'
+import { invalidateOwnershipCache } from '../../reconciliation/index.js'
+import type { ProfileUpdates } from '../../identityHubReducer.js'
+import type { CustodyFlowDeps } from './custodyFlowTypes.js'
+import { humanOwnerAddress } from './custodyFlowHelpers.js'
+import {
+  runVaultDeployTransaction,
+  runVaultDepositTransaction,
+  runVaultUnwrapTransaction,
+  runVaultWithdrawTransaction,
+} from './custodyEffects.js'
+
+export function useCustodyTransactionEffects({
+  step,
+  setStep,
+  callbacks,
+  handleStepError,
+  triggerRebackup,
+  refreshReconciliation,
+}: CustodyFlowDeps): void {
+  useEffect(() => {
+    if (step.kind !== 'custody-vault-deploy-tx') return
+    let cancelled = false
+    if (!step.identity.agentId) {
+      handleStepError(
+        new Error('Cannot deploy agent vault: agent token ID is missing'),
+        { kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo },
+      )
+      return () => { cancelled = true }
+    }
+    runVaultDeployTransaction({
+      registry: step.registry,
+      walletAddress: humanOwnerAddress(step.identity),
+      agentId: BigInt(step.identity.agentId),
+      callbacks,
+      flowId: 'advanced-custody',
+    })
+      .then(async ({ vaultAddress }) => {
+        if (cancelled) return
+        setStep({
+          kind: 'custody-vault-deposit-tx',
+          identity: step.identity,
+          registry: step.registry,
+          vaultAddress,
+          profileUpdates: withVaultProfileUpdates(step.profileUpdates, vaultAddress),
+          returnTo: step.returnTo,
+        })
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return
+        handleStepError(err, { kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })
+      })
+    return () => { cancelled = true }
+  }, [step])
+
+  useEffect(() => {
+    if (step.kind !== 'custody-vault-deposit-tx') return
+    let cancelled = false
+    runVaultDepositTransaction({
+      identity: step.identity,
+      registry: step.registry,
+      vaultAddress: step.vaultAddress,
+      callbacks,
+      flowId: 'advanced-custody',
+    })
+      .then(async () => {
+        if (cancelled) return
+        invalidateOwnershipCache()
+        refreshReconciliation()
+        const probeClient = createErc8004PublicClient(step.registry)
+        const expectedOwner = humanOwnerAddress(step.identity)
+        const status = await confirmAgentInVault({
+          client: probeClient,
+          vaultAddress: step.vaultAddress,
+          registry: step.registry.identityRegistryAddress,
+          agentId: BigInt(step.identity.agentId ?? '0'),
+        })
+        if (cancelled) return
+        if (status.ownerAddress.toLowerCase() !== expectedOwner.toLowerCase()) {
+          throw new Error(
+            `Vault holds the token but recorded the depositor as ${status.ownerAddress} instead of ${expectedOwner}. Use Withdraw Token to recover.`,
+          )
+        }
+        triggerRebackup(step.returnTo ?? { kind: 'menu' }, step.profileUpdates, { vaultAddress: step.vaultAddress })
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return
+        handleStepError(err, { kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })
+      })
+    return () => { cancelled = true }
+  }, [step])
+
+  useEffect(() => {
+    if (step.kind !== 'custody-vault-withdraw-tx') return
+    let cancelled = false
+    runVaultWithdrawTransaction({
+      identity: step.identity,
+      registry: step.registry,
+      vaultAddress: step.vaultAddress,
+      callbacks,
+      ...(step.agentId ? { agentId: BigInt(step.agentId) } : {}),
+    })
+      .then(({ recipient }) => {
+        if (cancelled) return
+        invalidateOwnershipCache()
+        refreshReconciliation()
+        setStep({
+          kind: 'custody-vault-withdraw-done',
+          identity: step.identity,
+          registry: step.registry,
+          vaultAddress: step.vaultAddress,
+          recipient,
+          returnTo: step.returnTo,
+          ...(step.returnContext ? { returnContext: step.returnContext } : {}),
+        })
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return
+        handleStepError(err, { kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })
+      })
+    return () => { cancelled = true }
+  }, [step])
+
+  useEffect(() => {
+    if (step.kind !== 'custody-vault-unwrap-tx') return
+    let cancelled = false
+    const agentIds = step.agentIds && step.agentIds.length > 0
+      ? step.agentIds
+      : (step.identity.agentId ? [step.identity.agentId] : [])
+    ;(async () => {
+      try {
+        for (const agentIdStr of agentIds) {
+          if (cancelled) return
+          await runVaultUnwrapTransaction({
+            identity: step.identity,
+            registry: step.registry,
+            vaultAddress: step.vaultAddress,
+            callbacks,
+            flowId: 'simple-custody',
+            agentId: BigInt(agentIdStr),
+          })
+        }
+        if (cancelled) return
+        invalidateOwnershipCache()
+        refreshReconciliation()
+        triggerRebackup(step.returnTo ?? { kind: 'menu' }, step.profileUpdates, { useVault: false })
+      } catch (err: unknown) {
+        if (cancelled) return
+        handleStepError(err, { kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })
+      }
+    })()
+    return () => { cancelled = true }
+  }, [step])
+}
+
+function withVaultProfileUpdates(profileUpdates: ProfileUpdates, vaultAddress: `0x${string}`): ProfileUpdates {
+  return {
+    ...profileUpdates,
+    operatorVaultAddress: vaultAddress,
+  }
+}

package/src/identity/hub/flows/custody/custodyFlowHelpers.ts

@@ -0,0 +1,25 @@
+import type { EthagentConfig, EthagentIdentity } from '../../../../storage/config.js'
+import { buildSeedConfigForIdentity } from '../../../../storage/config.js'
+import { readOwnerAddressField } from '../../../identityCompat.js'
+import { supportedErc8004ChainForId, type Erc8004RegistryConfig } from '../../../registry/erc8004.js'
+
+export function chainLabel(chainId: number): string {
+  return supportedErc8004ChainForId(chainId)?.name ?? `chain ${chainId}`
+}
+
+export function humanOwnerAddress(identity: EthagentIdentity): `0x${string}` {
+  const stateOwnerAddress = readOwnerAddressField(identity.state as Record<string, unknown> | undefined)
+  if (stateOwnerAddress && /^0x[a-fA-F0-9]{40}$/.test(stateOwnerAddress)) {
+    return stateOwnerAddress as `0x${string}`
+  }
+  return (identity.ownerAddress ?? identity.address) as `0x${string}`
+}
+
+export function buildSeedConfigFromStep(identity: EthagentIdentity, registry: Erc8004RegistryConfig): EthagentConfig {
+  return buildSeedConfigForIdentity({
+    identity,
+    chainId: registry.chainId,
+    rpcUrl: registry.rpcUrl,
+    identityRegistryAddress: registry.identityRegistryAddress,
+  })
+}

package/src/identity/hub/flows/custody/custodyFlowRoutes.tsx

@@ -0,0 +1,239 @@
+import React from 'react'
+import { Box, Text } from 'ink'
+import { Surface } from '../../../../ui/Surface.js'
+import { Select } from '../../../../ui/Select.js'
+import { theme } from '../../../../ui/theme.js'
+import { WalletApprovalScreen } from '../../components/WalletApprovalScreen.js'
+import { shortAddress } from '../../model/format.js'
+import type { Step } from '../../identityHubReducer.js'
+import type { CustodyFlowDeps } from './custodyFlowTypes.js'
+import { chainLabel, humanOwnerAddress } from './custodyFlowHelpers.js'
+
+const Row: React.FC<{ label: string; value: string }> = ({ label, value }) => (
+  <Text>
+    <Text color={theme.dim}>{label.padEnd(18)}</Text>
+    <Text color={theme.text}>{value}</Text>
+  </Text>
+)
+
+export function renderCustodyStep({
+  step,
+  setStep,
+  walletSession,
+}: CustodyFlowDeps): React.ReactElement | null {
+  if (step.kind === 'custody-vault-deploy-tx') {
+    return (
+      <WalletApprovalScreen
+        title="Deploy Operator Delegation Vault"
+        subtitle={`Deploying a dedicated OperatorVault for this ERC-8004 token on ${chainLabel(step.registry.chainId)}.`}
+        walletSession={walletSession}
+        label="waiting for owner wallet transaction..."
+        onCancel={() => setStep({ kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })}
+      />
+    )
+  }
+  if (step.kind === 'custody-vault-deposit-tx') {
+    return (
+      <WalletApprovalScreen
+        title="Deposit Token Into Operator Delegation Vault"
+        subtitle={`Sign one ${chainLabel(step.registry.chainId)} transaction. Sends ERC-8004 token #${step.identity.agentId ?? ''} to its agent vault.`}
+        walletSession={walletSession}
+        label="waiting for token-owner wallet transaction..."
+        onCancel={() => setStep({ kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })}
+      />
+    )
+  }
+  if (step.kind === 'custody-vault-withdraw-discovering') {
+    const targetAgentId = step.identity.agentId ?? ''
+    return (
+      <Surface
+        title="Checking Vault"
+        subtitle={targetAgentId
+          ? `Confirming the agent vault holds ERC-8004 token #${targetAgentId} on ${chainLabel(step.registry.chainId)}.`
+          : `Checking this identity's recorded agent vault on ${chainLabel(step.registry.chainId)}.`}
+        footer={<Text color={theme.dim}>esc cancel</Text>}
+      >
+        <Box marginTop={1}>
+          <Text color={theme.textSubtle}>Reading vault state from chain...</Text>
+        </Box>
+      </Surface>
+    )
+  }
+  if (step.kind === 'custody-vault-withdraw-tx') {
+    const targetAgentId = step.agentId ?? step.identity.agentId ?? ''
+    return (
+      <WalletApprovalScreen
+        title="Withdraw Token"
+        subtitle={`Unwraps ERC-8004 token #${targetAgentId} from its agent vault to your owner wallet on ${chainLabel(step.registry.chainId)}.`}
+        walletSession={walletSession}
+        label="waiting for owner wallet transaction..."
+        onCancel={() => setStep({ kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })}
+      />
+    )
+  }
+  if (step.kind === 'custody-vault-withdraw-pick-token') {
+    const activeId = step.identity.agentId
+    const options = step.tokens.map(t => ({
+      value: t.agentId,
+      label: `Token #${t.agentId}${activeId && t.agentId === activeId ? ' (active)' : ''}`,
+      hint: 'Withdraw this token to your owner wallet',
+    }))
+    return (
+      <Surface
+        title="Pick a Vaulted Token"
+        subtitle={`Your wallet has ${step.tokens.length} vaulted tokens on ${chainLabel(step.registry.chainId)}. Pick one to withdraw.`}
+        footer={<Text color={theme.dim}>enter select · esc back</Text>}
+      >
+        <Box marginTop={1}>
+          <Select<string>
+            options={[
+              { value: 'header', role: 'section', label: 'Vaulted Tokens' },
+              ...options,
+              { value: 'cancel', role: 'section', label: 'Navigation' },
+              { value: 'cancel', label: 'Back', hint: 'Return to Custody Mode', role: 'utility' },
+            ]}
+            hintLayout="inline"
+            onSubmit={choice => {
+              if (choice === 'cancel') {
+                setStep({ kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })
+                return
+              }
+              setStep({
+                kind: 'custody-vault-withdraw-tx',
+                identity: step.identity,
+                registry: step.registry,
+                vaultAddress: step.vaultAddress,
+                agentId: choice,
+                returnTo: step.returnTo,
+                ...(step.returnContext ? { returnContext: step.returnContext } : {}),
+              })
+            }}
+            onCancel={() => setStep({ kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })}
+          />
+        </Box>
+      </Surface>
+    )
+  }
+  if (step.kind === 'custody-vault-withdraw-done') {
+    const onReturnToVault = () => {
+      setStep({
+        kind: 'custody-vault-deposit-tx',
+        identity: step.identity,
+        registry: step.registry,
+        vaultAddress: step.vaultAddress,
+        profileUpdates: { operatorVaultAddress: step.vaultAddress },
+        returnTo: step.returnTo,
+      })
+    }
+    const onKeepOut = () => {
+      if (step.returnContext === 'ens' && step.returnTo) {
+        setStep(step.returnTo)
+      } else {
+        setStep({ kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })
+      }
+    }
+    return (
+      <Surface
+        title="Token Returned to Owner Wallet"
+        subtitle={`Token returned to ${shortAddress(step.recipient)} on ${chainLabel(step.registry.chainId)}. The agent vault can be reused for this token.`}
+        footer={<Text color={theme.dim}>enter select · esc back</Text>}
+      >
+        <Box flexDirection="column">
+          <Text color={theme.textSubtle}>
+            {step.returnContext === 'ens'
+              ? 'Use the token with your owner wallet to set ENS records, then return it to the vault to resume Advanced custody.'
+              : 'Use the token with your owner wallet for whatever you need, then return it to the vault when finished.'}
+          </Text>
+        </Box>
+        <Box marginTop={1}>
+          <Select<'return-to-vault' | 'keep-out'>
+            options={[
+              { value: 'return-to-vault', role: 'section', label: 'Resume Advanced Custody' },
+              { value: 'return-to-vault', label: 'Return Token to Vault', hint: 'Redeposit to this agent vault. No redeploy, no operator re-add' },
+              { value: 'keep-out', role: 'section', label: 'Later' },
+              { value: 'keep-out', label: 'Keep Out For Now', hint: 'Token stays with the owner wallet; redeposit any time from Custody Mode', role: 'utility' },
+            ]}
+            hintLayout="inline"
+            onSubmit={choice => {
+              if (choice === 'return-to-vault') onReturnToVault()
+              else onKeepOut()
+            }}
+            onCancel={onKeepOut}
+          />
+        </Box>
+      </Surface>
+    )
+  }
+  if (step.kind === 'custody-vault-unwrap-tx') {
+    return (
+      <WalletApprovalScreen
+        title="Unwrap Token From Agent Vault"
+        subtitle={`Sign one ${chainLabel(step.registry.chainId)} transaction. Calls the agent vault's unwrap function to return ERC-8004 token #${step.identity.agentId ?? ''} to the owner wallet.`}
+        walletSession={walletSession}
+        label="waiting for owner wallet transaction..."
+        onCancel={() => setStep({ kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })}
+      />
+    )
+  }
+  if (step.kind === 'custody-advanced-done') {
+    const state = (step.identity.state ?? {}) as Record<string, unknown>
+    const ownerWallet = humanOwnerAddress(step.identity) as string
+    const operatorCount = Array.isArray(state.approvedOperatorWallets) ? state.approvedOperatorWallets.length : 0
+    return (
+      <Surface
+        title="Advanced Custody Active"
+        subtitle="Your token is held in its own OperatorVault. Authorized operator wallets can rotate the agent URI onchain without owner signatures."
+        footer={<Text color={theme.dim}>enter continues</Text>}
+      >
+        <Box flexDirection="column">
+          {step.vaultAddress ? <Row label="Agent Vault" value={shortAddress(step.vaultAddress)} /> : null}
+          <Row label="Owner Wallet" value={shortAddress(ownerWallet)} />
+          <Row label="Operator Wallets" value={operatorCount === 1 ? '1 approved' : `${operatorCount} approved`} />
+          <Box marginTop={1}>
+            <Text color={theme.textSubtle}>Use Manage Operators to add or revoke operator wallets. Use Withdraw Token to pull this token out of its vault temporarily without dismantling advanced custody.</Text>
+          </Box>
+        </Box>
+        <Box marginTop={1}>
+          <Select<'continue'>
+            options={[{ value: 'continue', label: 'Return to Custody Mode' }]}
+            onSubmit={() => setStep({ kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })}
+            onCancel={() => setStep({ kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })}
+          />
+        </Box>
+      </Surface>
+    )
+  }
+  if (step.kind === 'custody-simple-done') {
+    const ownerWallet = humanOwnerAddress(step.identity) as string
+    return (
+      <Surface
+        title="Simple Custody Active"
+        subtitle={`The token is back with the owner wallet. Operator slots are cleared.`}
+        footer={<Text color={theme.dim}>enter continues</Text>}
+      >
+        <Box flexDirection="column">
+          <Row label="Owner Wallet" value={shortAddress(ownerWallet)} />
+          <Box marginTop={1}>
+            <Text color={theme.textSubtle}>Future URI rotations require an owner wallet signature per edit. Switch back to Advanced from Custody Mode at any time.</Text>
+          </Box>
+        </Box>
+        <Box marginTop={1}>
+          <Select<'continue'>
+            options={[{ value: 'continue', label: 'Return to Custody Mode' }]}
+            onSubmit={() => setStep({ kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })}
+            onCancel={() => setStep({ kind: 'custody-model', identity: step.identity, registry: step.registry, returnTo: step.returnTo })}
+          />
+        </Box>
+      </Surface>
+    )
+  }
+  return null
+}
+
+export function renderRebackupSubtitle(
+  defaultSubtitle: React.ReactNode,
+  vaultRouted: boolean,
+): React.ReactNode {
+  if (!vaultRouted) return defaultSubtitle
+  return <Text color={theme.textSubtle}>{defaultSubtitle} Routed through this token's agent vault.</Text>
+}