Headless identity: restore, profile, custody changes, create, storage, transfer

[baairon]

Summary

Every action in the interactive manager now has a headless command. An agent can be restored, edited, re-custodied, created and handed over without a TTY.

Each command follows the same conventions as custody and ens:

• It previews by default and acts only with --yes.
• It runs all of its wallet prompts in one browser tab.
• It returns the stable {"schema":1} JSON envelope and the existing exit codes.

The commands reuse the manager's existing runners, so the headless and interactive paths share their logic. One commit per step:

1. Shared groundwork
   • Gas fix: browser wallet sessions now pass the prepared gas and fees to the wallet page. One-shot requests already did; sessions dropped them, which also affected ens.
   • Session option: the Vault runners and the operator sync take an optional wallet session.
   • Restore and refetch signer: they take an optional signer, either a wallet session or the operator key, which decrypts locally through its slot in the snapshot.
   • Revoke before withdrawing: switching to Simple now revokes the Vault's operator approvals before the withdrawal, in the manager too. Some Vault builds keep approvals across a withdrawal.
2. restore
   • restore <token-id>|<name> rebuilds an agent on this machine.
   • restore --owner <address> lists the agents a wallet holds.
   • restore with no target pulls the newest onchain snapshot into the vault.
   • --operator decrypts with the operator key and opens no browser. The vault is checkpointed first, and config is saved only after the files land.
3. profile
   • Changes the name, description and image (--image none removes it) in one save.
   • --operator works in Advanced custody with a linked ENS name; otherwise it says what is missing.
4. Custody changes
   • custody --advanced deploys or reuses a Vault, deposits the token and saves.
   • custody --simple revokes the Vault's operators, withdraws the token and saves.
   • --add-operator, --remove-operator and --activate-operator manage operators.
   • Each change is planned from chain state, so a run that stops part way resumes when run again.
   • --add-operator --operator has the injected key sign its own proof.
   • The operator proof logic moved out of the manager screen into a shared helper, which the screen now uses.
5. create
   • Mints a new agent. --advanced continues into the Vault in the same tab, --import folds in notes from local tools, and --replace is required when an agent already exists.
6. storage
   • Shows whether IPFS storage is ready.
   • --set reads a Pinata JWT from stdin only; --forget removes it after a preview.
7. transfer <address|name>
   • Both wallets sign in one tab and the owner publishes the re-encrypted snapshot.
   • Refuses a token that is still in the Vault, and states that ethagent never moves the token itself.
8. Docs
   • README: common tasks, command rows, a "Setting up and moving an agent" section, exit code 4 for partly-done runs, and a mention of create in the quick start.
   • --help lists the new commands.
   • Agent guidance: previews and read-only forms are the agent's to run, --yes is the user's, and restore --operator --yes may run when the user asks.

Testing

• npm run typecheck is clean.
• npm test passes all 763 tests in a clean CI-like environment.
• New test files:
  • restoreCommand, including an end-to-end decrypt with a local key against a real envelope that writes the vault;
  • profileCommand;
  • custodyWrite, covering step order, the single wallet tab, resuming, partial cancellation, revoking, and the operator-key proof;
  • setupCommands (create, storage, transfer);
  • a session gas passthrough test.

Live checks after merge (non-destructive first)

1. keychain exec ethagent -- ethagent restore 45744 --network base --operator (preview), then with --yes into a temporary HOME.
2. ethagent profile and a profile --name <text> preview.
3. ethagent custody --add-operator --operator preview, then custody --simple preview, to check the revoke step lists the current operators.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HG2miyE22qTuug1Quxj7iw

---

Generated by Claude Code