ethagent 4.2.0 → 4.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ethagent",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "Portable Ethereum identity for your AI agent. Its soul, memory, and skills live onchain via ERC-8004 + IPFS and snap back into any session.",
   "author": { "name": "bairon.dev" },
   "homepage": "https://github.com/baairon/ethagent",

package/README.md

@@ -63,7 +63,7 @@ Using another harness? You can still sync, but only Claude Code does it automati
 npx ethagent --sync
 ```
 
-One command syncs it into every harness on this machine — soul, memory, and skills (public and private) — but only when you run it. To back it up so you can restore it anywhere, open `ethagent` and choose **Save Snapshot**.
+One command syncs it into every harness on this machine — soul, memory, and skills (public and private) — but only when you run it. To back it up so you can restore it anywhere, run `ethagent save` (or open `ethagent` and choose **Save Snapshot**); either way you approve the signature in your wallet.
 
 ## 🔒 What stays private
 
@@ -117,7 +117,8 @@ Run with `npx ethagent`:
 
 | Command | What it does |
 | --- | --- |
-| `ethagent` | Open the interactive identity manager: create, ENS, custody, snapshots, transfer. |
+| `ethagent` | Open the interactive identity manager: create, ENS, custody, transfer. |
+| `save` | Save an encrypted snapshot: pin to IPFS and rotate the onchain pointer. Opens your browser wallet to approve; add `--no-open` to only print the URL, `--json` for machine output. |
 | `--sync` | Sync soul, memory, and skills (public and private) into every harness it detects. |
 | `--sync-list` | List sync adapters and which ones detect in the current environment. |
 | `--status` | Print a one-line identity summary. |

package/commands/ethagent.md

@@ -3,9 +3,10 @@ name: ethagent
 description: Point the user at ethagent. ethagent stores an agent's identity onchain via ERC-8004 and syncs its soul, memory, and public skills into the active harness (Claude Code or Codex) on every SessionStart. To manage identity (create, ENS, custody, snapshots, transfer), the user runs `npx ethagent` in a separate terminal.
 ---
 
-Tell the user to run these in a separate terminal window, not inside this session:
+Most of these run in a separate terminal because they need a wallet or a TTY, but a few are safe to run from inside this session; each bullet says which:
 
-- `npx ethagent` opens the interactive identity manager for anything that needs a wallet signature (create agent, set ENS, switch custody, save snapshot, prepare transfer).
+- `npx ethagent` opens the interactive identity manager for anything that needs a wallet signature (create agent, set ENS, switch custody, prepare transfer).
+- `ethagent save` runs Save Snapshot (encrypt, pin to IPFS, rotate the onchain pointer). **You can run this yourself** as a normal tool call (e.g. `npx ethagent save`): no separate terminal and no TTY, and it will not hang. It prints a localhost wallet URL and opens the browser tab so the user approves the signature and transaction there. You trigger and run it; the user only approves in the wallet. Pass `--no-open` to just print the URL. Only run it when the user specifically asks to save or back up the agent; never run it on your own initiative or as a side effect of other work. It is a no-op (no wallet, no gas) when there are no local changes since the last snapshot.
 - `npx ethagent --sync` syncs the agent's soul, memory, and skills with every detected harness; soul and memory sync both ways, newest edit wins.
 - `npx ethagent --sync-list` shows which harnesses ethagent detects on this machine.
 - `npx ethagent --demo` walks the identity manager with synthetic data, no wallet or network required.
@@ -14,7 +15,7 @@ Tell the user to run these in a separate terminal window, not inside this sessio
 
 To rebuild the agent on a new machine, the user runs `npx ethagent`; it restores the identity from an ENS name or ERC-8004 token id, then asks the wallet to sign.
 
-You may run the non-interactive flags yourself when it helps (`--sync`, `--status`, `--sync-list`). Never launch the bare interactive `npx ethagent` or `--demo` from inside a session: they open a full-screen terminal app that needs a TTY and will hang the tool call. Anything that needs a wallet signature, the user always runs themselves.
+You may run the read-only non-interactive commands yourself whenever they help (`--sync`, `--status`, `--sync-list`). `ethagent save` is different: run it only when the user specifically asks you to save or back up the agent, never on your own initiative or as a side effect of other work. When they do ask, you can run it directly: there is no CLI step for the user and no separate terminal needed. It is headless, will not hang, prints a wallet URL, and opens the browser tab where the user approves the signature. You trigger and run the command; you never sign. (It is also a no-op when there are no local changes since the last snapshot.) Never launch the bare interactive `npx ethagent` or `--demo` from inside a session: they open a full-screen terminal app that needs a TTY and will hang the tool call. Anything else that needs a wallet signature (create, ENS, custody, transfer), the user always runs themselves.
 
 Where the synced files land:
 
@@ -35,6 +36,6 @@ The agent's portable identity lives in the ethagent vault and syncs into every h
   - Voice, standards, operating principles, and boundaries go in the vault `SOUL.md` in the same folder.
 - The vault files are the source of truth. After editing them, run `npx ethagent --sync` so the change propagates into `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, and any other detected harness.
 - Do NOT store durable identity in Claude Code's per-project memory (`~/.claude/projects/<slug>/memory/`): the sync treats those files as write-only mirror targets and overwrites them, and they never reach Codex or the encrypted backup. Keep only session- or repo-specific scratch notes there.
-- Syncing is not backup. To persist durable changes into the encrypted IPFS snapshot and onchain pointer, the user runs `npx ethagent` and chooses Save Snapshot (needs a wallet signature).
+- Syncing is not backup. To persist durable changes into the encrypted IPFS snapshot and onchain pointer, run `ethagent save` yourself: it pins the encrypted snapshot and rotates the onchain pointer, and the user only approves the signature in the browser wallet.
 
 If they ask "what's my agent" or "list my skills" without an identity yet, point them at `npx ethagent` to set one up first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ethagent",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "Portable Ethereum identity for your AI agent. Its soul, memory, and skills live onchain via ERC-8004 + IPFS and snap back into any session.",
   "type": "module",
   "bin": {

package/src/cli/main.tsx

@@ -18,6 +18,7 @@ import { runPreToolGuard } from './pretoolGuard.js'
 import { runSessionStart } from './sessionStart.js'
 import { runStatus } from './status.js'
 import { runResetCommand } from './reset.js'
+import { runSave } from './save.js'
 import { enableDemoMode, synthDemoConfig } from './demo.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -38,6 +39,7 @@ function printHelp(): void {
     '',
     'usage:',
     '  ethagent                    manage identity',
+    '  ethagent save               save an encrypted snapshot: pin to IPFS, rotate the onchain pointer (you approve in your wallet)',
     '  ethagent reset              delete local identity, continuity, and secrets',
     '  ethagent --sync             sync soul, memory, and skills to every harness',
     '  ethagent --sync-list        list sync adapters and which ones detect here',
@@ -163,6 +165,8 @@ async function main(): Promise<number> {
     enableDemoMode()
     return renderHub(synthDemoConfig())
   }
+  if (argv[0] === 'save') return runSave(argv.slice(1))
+  if (flags.has('--save')) return runSave(argv.filter(a => a !== '--save'))
   if (argv[0] === 'reset') return runResetCommand(argv.slice(1))
 
   const unknown = argv.find(a => a.startsWith('-'))

package/src/cli/save.ts

@@ -0,0 +1,162 @@
+import { stdout, stderr } from 'node:process'
+import { loadConfig, saveConfig, type EthagentConfig } from '../storage/config.js'
+import { resolveRegistryForIdentity } from '../identity/registry/registryConfig.js'
+import { continuityVaultStatus, continuityWorkingTreeStatus } from '../identity/continuity/storage/status.js'
+import { listPublishedContinuitySnapshots } from '../identity/continuity/snapshots.js'
+import { resolveValidatedPinataJwt } from '../identity/storage/pinataJwt.js'
+import { runRebackupSigning } from '../identity/manager/continuity/effects.js'
+import type { EffectCallbacks } from '../identity/manager/shared/effects/types.js'
+import { isWalletCancelled } from '../identity/manager/shared/utils.js'
+import type { Step } from '../identity/manager/reducer.js'
+import { openExternalUrl } from '../utils/openExternal.js'
+
+// Headless Save Snapshot: encrypt soul/memory/skills, pin to IPFS, and rotate the
+// ERC-8004 onchain pointer. The agent can trigger this; the human still approves the
+// signature and transaction in the browser wallet tab. The whole pipeline is reused
+// from the ink TUI (`runRebackupSigning`) with a print-only callbacks shim.
+//
+// Exit codes: 0 success · 1 no identity / not restored / generic runtime error ·
+// 2 usage (unknown option) · 3 credential or wallet problem the human must resolve
+// (no JWT, invalid JWT, or wallet cancelled/timed out).
+
+export type RunSaveDeps = {
+  loadConfig: typeof loadConfig
+  saveConfig: typeof saveConfig
+  resolveValidatedPinataJwt: typeof resolveValidatedPinataJwt
+  continuityVaultStatus: typeof continuityVaultStatus
+  continuityWorkingTreeStatus: typeof continuityWorkingTreeStatus
+  listPublishedContinuitySnapshots: typeof listPublishedContinuitySnapshots
+  runRebackupSigning: typeof runRebackupSigning
+  openExternalUrl: typeof openExternalUrl
+}
+
+const defaultDeps: RunSaveDeps = {
+  loadConfig,
+  saveConfig,
+  resolveValidatedPinataJwt,
+  continuityVaultStatus,
+  continuityWorkingTreeStatus,
+  listPublishedContinuitySnapshots,
+  runRebackupSigning,
+  openExternalUrl,
+}
+
+export async function runSave(args: string[] = [], deps: RunSaveDeps = defaultDeps): Promise<number> {
+  const json = args.includes('--json')
+  const noOpen = args.includes('--no-open')
+  const unknown = args.filter(a => a !== '--json' && a !== '--no-open')
+  if (unknown.length > 0) {
+    stderr.write(`unknown save option: ${unknown[0]}\nusage: ethagent save [--json] [--no-open]\n`)
+    return 2
+  }
+
+  const fail = (code: number, message: string): number => {
+    if (json) stdout.write(JSON.stringify({ ok: false, code, error: message }) + '\n')
+    else stderr.write(message + '\n')
+    return code
+  }
+
+  const config = await deps.loadConfig().catch(() => null)
+  if (!config?.identity) {
+    return fail(1, 'No agent identity yet. Run `npx ethagent` to create or link one.')
+  }
+  const activeConfig: EthagentConfig = config
+  const identity = config.identity
+
+  if (!identity.agentId) {
+    return fail(1, 'This identity has no agent token ID yet. Create or restore it with `npx ethagent` first.')
+  }
+
+  const registry = resolveRegistryForIdentity(identity, activeConfig)
+  if (!registry) {
+    return fail(1, 'No agent registry configured for this identity. Run `npx ethagent` to set it up.')
+  }
+
+  const vault = await deps.continuityVaultStatus(identity).catch(() => ({ ready: false }))
+  if (!vault.ready) {
+    return fail(1, 'Local continuity files are not restored. Run `npx ethagent` and restore this identity before saving a snapshot.')
+  }
+
+  // Only proceed when the working tree actually differs from the last published
+  // snapshot. If it is already up to date, do nothing: no wallet, no transaction, no
+  // gas. We only block on the confirmed-equal state ('published'); first saves
+  // ('not-published') and undeterminable cases still go through.
+  let publishState: string | undefined
+  try {
+    const [latest] = await deps.listPublishedContinuitySnapshots(identity, 1)
+    const tree = await deps.continuityWorkingTreeStatus(identity, latest)
+    publishState = tree.publishState
+  } catch {
+    publishState = undefined
+  }
+  if (publishState === 'published') {
+    if (json) stdout.write(JSON.stringify({ ok: true, skipped: true, reason: 'no-local-changes' }) + '\n')
+    else stdout.write('No local changes since the last snapshot; nothing to save.\n')
+    return 0
+  }
+
+  // JWT is resolved and validated BEFORE opening the wallet, so we never ask for a
+  // signature on a snapshot that then cannot be pinned.
+  let jwt: string | undefined
+  try {
+    jwt = await deps.resolveValidatedPinataJwt()
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err)
+    return fail(3, `The configured Pinata JWT is invalid or unreachable (${detail}). The wallet was not opened. Update it via \`npx ethagent\` -> IPFS Storage, then retry \`ethagent save\`.`)
+  }
+  if (!jwt) {
+    return fail(3, 'No IPFS storage credential configured, so the snapshot cannot be pinned and the wallet was not opened. Run `npx ethagent` once and set up IPFS Storage (or export PINATA_JWT in this shell), then retry `ethagent save`.')
+  }
+
+  let completed = false
+  const callbacks: EffectCallbacks = {
+    onStep: () => {},
+    onWalletReady: ready => {
+      if (!ready) return
+      const sink = json ? stderr : stdout
+      sink.write(`Approve this snapshot in your browser wallet tab: ${ready.url}\n`)
+      sink.write('Connect your wallet, sign one message, and approve one transaction (up to ~5 minutes)...\n')
+      if (!noOpen) deps.openExternalUrl(ready.url)
+    },
+    onIdentityComplete: async nextIdentity => {
+      await deps.saveConfig({ ...activeConfig, identity: nextIdentity })
+      completed = true
+      if (json) {
+        stdout.write(JSON.stringify({
+          ok: true,
+          cid: nextIdentity.backup?.cid ?? null,
+          txHash: nextIdentity.backup?.txHash ?? null,
+          agentUri: nextIdentity.agentUri ?? null,
+        }) + '\n')
+      } else {
+        stdout.write('Snapshot saved.\n')
+        if (nextIdentity.backup?.cid) stdout.write(`  CID:      ${nextIdentity.backup.cid}\n`)
+        if (nextIdentity.backup?.txHash) stdout.write(`  tx:       ${nextIdentity.backup.txHash}\n`)
+        if (nextIdentity.agentUri) stdout.write(`  agentURI: ${nextIdentity.agentUri}\n`)
+      }
+    },
+  }
+
+  const step: Extract<Step, { kind: 'rebackup-signing' }> = {
+    kind: 'rebackup-signing',
+    identity,
+    registry,
+    pinataJwt: jwt,
+    returnTo: { kind: 'menu' },
+  }
+
+  try {
+    await deps.runRebackupSigning(step, callbacks)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    if (isWalletCancelled(err) || /timed out/i.test(message)) {
+      return fail(3, 'Wallet approval was cancelled or timed out. No snapshot was saved. Retry `ethagent save` when ready.')
+    }
+    return fail(1, `Save failed: ${message}`)
+  }
+
+  if (!completed) {
+    return fail(1, 'Save did not complete and no snapshot was recorded. Retry `ethagent save`.')
+  }
+  return 0
+}

package/src/identity/manager/useController.ts

@@ -2,7 +2,7 @@ import { useEffect, useReducer, useState } from 'react'
 import type { EthagentConfig, EthagentIdentity } from '../../storage/config.js'
 import { setTokenIdentity } from '../../storage/identity.js'
 import type { BrowserWalletReady } from '../wallet/browserWallet.js'
-import { registryConfigFromConfig } from '../registry/registryConfig.js'
+import { resolveRegistryForIdentity as resolveRegistryForIdentityFromConfig } from '../registry/registryConfig.js'
 import type { Erc8004RegistryConfig } from '../registry/erc8004.js'
 import {
   hasPinataJwt,
@@ -94,18 +94,8 @@ export function useIdentityManagerController({
     }
   }
 
-  const resolveRegistryForIdentity = (target: EthagentIdentity): Erc8004RegistryConfig | null => {
-    const resolution = registryConfigFromConfig(config)
-    if (target.chainId && target.identityRegistryAddress) {
-      return {
-        chainId: target.chainId,
-        rpcUrl: target.rpcUrl ?? resolution.defaultRpcUrl,
-        identityRegistryAddress: target.identityRegistryAddress as `0x${string}`,
-      }
-    }
-    if (resolution.config) return resolution.config
-    return null
-  }
+  const resolveRegistryForIdentity = (target: EthagentIdentity): Erc8004RegistryConfig | null =>
+    resolveRegistryForIdentityFromConfig(target, config)
 
   const completeTokenIdentity = async (nextIdentity: EthagentIdentity, message: string, source?: IdentityCompletionSource): Promise<void> => {
     if (mode === 'first-run' || !config) {

package/src/identity/registry/registryConfig.ts

@@ -1,4 +1,4 @@
-import type { EthagentConfig, SelectableNetwork } from '../../storage/config.js'
+import type { EthagentConfig, EthagentIdentity, SelectableNetwork } from '../../storage/config.js'
 import {
   chainIdForNetwork,
   DEFAULT_ERC8004_CHAIN_ID,
@@ -67,3 +67,22 @@ export function registryConfigFromConfig(config?: EthagentConfig): RegistryResol
     throw err
   }
 }
+
+// Resolve the registry an existing identity should operate against: prefer the
+// identity's own chain + registry address (filling in a default RPC when it has
+// none), otherwise fall back to the config-derived registry. Pure function of
+// (identity, config) so both the TUI controller and headless commands share it.
+export function resolveRegistryForIdentity(
+  identity: Pick<EthagentIdentity, 'chainId' | 'identityRegistryAddress' | 'rpcUrl'>,
+  config?: EthagentConfig,
+): Erc8004RegistryConfig | null {
+  const resolution = registryConfigFromConfig(config)
+  if (identity.chainId && identity.identityRegistryAddress) {
+    return {
+      chainId: identity.chainId,
+      rpcUrl: identity.rpcUrl ?? resolution.defaultRpcUrl,
+      identityRegistryAddress: identity.identityRegistryAddress as `0x${string}`,
+    }
+  }
+  return resolution.config
+}