ethagent 0.2.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bairon.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,55 +1,137 @@
-<img src="https://bairon.dev/preview/cli.png" alt="ethagent" width="600" />
+<img src="https://raw.githubusercontent.com/baairon/ethagent/master/preview/image.png" alt="ethagent" />
 
 
-A privacy-first AI agent with a permanent Ethereum identity. Your knowledge base lives on IPFS. Your agent's identity is registered onchain, tied to your wallet. Your inference never leaves your machine.
+A privacy-first AI agent with a portable Ethereum identity.
 
-```bash
-npm install -g ethagent
-```
+ethagent is a terminal agent for coding and project work. It gives the agent a wallet-owned ERC-8004 identity, keeps private continuity encrypted, and publishes public capability metadata as structured JSON so other applications and agents can understand what it can do.
 
-## What It Is
+The identity stays portable. The model can change. The private memory stays under wallet-gated encryption.
 
-ethagent bootstraps a local LLM on your machine and builds a personal knowledge base from sources you define. It works completely offline. No wifi, no API, just your hardware. The model is hotswappable, and if you need to, you can point it at a cloud model without losing any context. Offline-capable agents are going to be a core part of how software gets built, and ethagent is built for that from day one.
+## Install
 
-- Your Ethereum address owns and controls your agent
-- Your knowledge base is pinned to IPFS, content-addressed and portable
-- Your agent is registered onchain via [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004)
-- Everything you teach it compounds across sessions, not just within them
+ethagent requires Node.js 20 or newer. Install it from npm with `npm install -g ethagent`, then start it with `ethagent`.
 
-Wipe your laptop, restore from your address or ENS name, and you're back exactly where you left off.
+On first run, ethagent guides you through model setup and identity setup. You can use a local GGUF model through llama.cpp, or connect OpenAI, Anthropic, or Gemini.
 
-```bash
-npx ethagent init --from bairon.eth
-npx ethagent init --from 0xA1E977e700bF82019beb381F1582575303A389CE
-```
+## What It Does
 
-## Why It Exists
+* Runs an AI coding agent in your terminal.
+* Switches between cloud models and local GGUF models.
+* Creates or loads a wallet-owned ERC-8004 agent identity.
+* Encrypts private continuity before IPFS pinning.
+* Publishes public `skills.json` and Agent Card metadata for discovery.
+* Restores the same agent on another machine from the onchain record.
+* Supports workspace tools, managed edit rewind, session resume, context compaction, and MCP servers.
 
-AI platforms compete aggressively and users switch between them constantly. Every time you do, your conversation history, custom instructions, and everything your agent learned about you resets to zero. But every prompt you sent to the old platform is still there, training their next model.
+## First Run
 
-ethagent breaks that cycle. Your knowledge lives on IPFS, your identity lives on Ethereum. Switch models whenever you want. Your agent remembers everything regardless. Your data stays yours, not by policy, but by architecture.
+Start with `ethagent`. The setup flow asks for a model path first, then offers identity setup.
 
-## How It Works
+You can create a new ERC-8004 agent with a browser wallet, load an agent token you already own, or skip identity setup and add it later from the Identity Hub.
 
-ethagent accumulates a personal knowledge base from conversations, documents, and corrections you provide. That knowledge base is pinned to IPFS, so it's content-addressed, verifiable, and not locked to any single device. The underlying model is hotswappable, so you can run a local LLM or swap in a cloud model without losing any context.
+Use `Alt+P` to switch models and `Alt+I` to open the Identity Hub. Inside the agent, `/help` shows the live command list for the version you are running.
 
-Your agent's identity is registered onchain using ERC-8004, the token standard for autonomous agents on Ethereum. Identity is tied to an Ethereum address or ENS name, meaning your agent can be fully restored on any machine from just your address.
+## Identity Hub
 
-Think of it like a tamagotchi that lives in your wallet. You raise it, you feed it knowledge, and only your key can summon it. Every interaction compounds. It doesn't flatten your context into a generic system prompt. It accumulates. And because it lives on IPFS, it follows you to any machine you bring your wallet to.
+The Identity Hub is where the portable identity is managed.
 
-| Layer | Where | What it does |
-|-------|-------|--------------|
-| Inference | Your machine (or cloud) | Hotswappable model, local-first by default |
-| Knowledge | IPFS | Content-addressed, verifiable, portable across any machine |
-| Identity | Ethereum | Permanent agent registration via ERC-8004, restorable from address or ENS |
+| Area | What It Controls |
+| --- | --- |
+| Public Metadata | Profile name, description, image, `skills.json`, and Agent Card. |
+| Private Local Files | `SOUL.md`, `MEMORY.md`, and the local copy of `skills.json`. |
+| Recovery | Publishing the current encrypted snapshot or refetching the latest one from chain. |
+| Storage | The Pinata JWT used to pin continuity and metadata to IPFS. |
+| Agent Token | Registry, owner, token, URI, CID, and copyable identity values. |
 
-Your knowledge base is encrypted with your wallet's key. Only you can decrypt it. Even though the data lives on IPFS, it's unreadable to anyone without your key. Nobody can clone your agent, read its memories, or extract what it knows about you.
+The hub is a recovery panel, not a history archive. The current tokenURI is the source of truth for the latest published state.
+
+## Continuity
+
+Each identity gets a local continuity vault under `~/.ethagent/continuity`.
+
+| File | Visibility | Purpose |
+| --- | --- | --- |
+| `SOUL.md` | Private | Persona, boundaries, standing instructions, and identity framing. |
+| `MEMORY.md` | Private | Durable preferences, project context, decisions, and operating notes. |
+| `skills.json` | Public | Machine-readable capabilities, input modes, output modes, and discovery metadata. |
+
+`SOUL.md` and `MEMORY.md` are encrypted before they are pinned to IPFS. They are not published as plaintext in token metadata.
+
+`skills.json` is public by design. It uses schema `ethagent.public-skills.v1` and is meant to be easy for other agents, apps, and scanners to parse.
+
+## Recovery
+
+**Publish Snapshot Now** encrypts the current private continuity, pins the public discovery files, writes current registration metadata, and updates the ERC-8004 tokenURI.
+
+**Refetch Latest Snapshot** reads the current tokenURI from chain, downloads the encrypted continuity envelope, asks the owner wallet to sign the decrypt challenge, and restores local continuity files from the published state.
+
+Publishing replaces the current onchain pointer. Registration metadata contains the current CIDs only.
+
+## Public Discovery
+
+The public registration metadata is intentionally compact. It describes the current state of the agent, not its history.
+
+It can include:
+
+* Agent name, description, and image.
+* Current encrypted continuity CID.
+* Current public `skills.json` CID.
+* Current Agent Card CID.
+* Service entries with canonical `endpoint` values.
+* Registry linkage through `registrations[]`.
+
+This is enough for baseline agent-to-agent discovery and delegation without exposing private memory or installing executable code.
+
+## Models
+
+ethagent works with OpenAI, Anthropic, Gemini, and local GGUF models served through a llama.cpp-compatible endpoint.
+
+The model picker can discover provider models, manage cloud API keys, recommend GGUF files for the machine, and start or reconnect to a local runner when supported.
+
+The featured local model is [Qwen3.5-9B-Uncensored](https://huggingface.co/HauhauCS/Qwen3.5-9B-Uncensored-HauhauCS-Aggressive). You can also add other Hugging Face GGUF models by repo ID or URL.
+
+Cloud API keys are stored in the OS keyring when available. If a keyring is unavailable, ethagent uses an encrypted local file under `~/.ethagent`.
+
+## Tools And Workspace
+
+ethagent is built for real project work. It can read files, edit files, write new files, delete files, inspect directories, run shell commands, copy text to the clipboard, and connect MCP tools.
+
+Tool use is permissioned. Managed edits are tracked so recent workspace changes can be rewound from inside the agent.
+
+Sessions are local. You can resume prior sessions, export a transcript, compact older context, and review saved project permissions.
+
+## Privacy
+
+Public information includes token ownership, tokenURI metadata, public discovery files, and IPFS CIDs.
+
+Private information includes plaintext `SOUL.md`, plaintext `MEMORY.md`, sessions, prompt history, API keys, local permissions, and wallet signatures used for decrypting continuity.
+
+Continuity snapshots use an EIP-191 wallet signature as unlock material and encrypt with ML-KEM-1024, HKDF-SHA256, and AES-256-GCM. The unlock signature does not submit a transaction, spend funds, or grant token approval.
+
+If an ERC-8004 token is transferred, the new holder can see public metadata and encrypted backup CIDs. They cannot decrypt private continuity that was encrypted for the previous owner wallet.
+
+## Local Reset
+
+`ethagent reset` deletes local ethagent data from this machine while preserving installed local model assets. It does not burn or transfer ERC-8004 tokens, remove public IPFS content, or mutate onchain metadata.
+
+Before resetting, use **Publish Snapshot Now** if local continuity changes should become the current recoverable state.
+
+## Architecture
+
+| Layer | Role |
+| --- | --- |
+| Runtime | Terminal chat UI, sessions, context, permissions, and workspace tools. |
+| Model | Cloud provider or local GGUF runner. |
+| Identity | ERC-8004 token owned by the wallet. |
+| Continuity | Private files encrypted before IPFS pinning. |
+| Discovery | Public `skills.json`, Agent Card, services, and current metadata. |
+| Recovery | Refetch current tokenURI, decrypt the latest snapshot, and restore local files. |
+
+The ERC-8004 token is the durable handle. The machine, model, and local session can change around it.
 
 ## Links
 
-- [npm package](https://www.npmjs.com/package/ethagent)
-- [GitHub](https://github.com/baairon/ethagent)
-- [ERC-8004 specification](https://eips.ethereum.org/EIPS/eip-8004)
+[npm](https://www.npmjs.com/package/ethagent) · [GitHub](https://github.com/baairon/ethagent) · [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) · [soul.md](https://soul.md/)
 
 ## License
 

package/bin/ethagent.js

@@ -4,6 +4,15 @@ import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
-const cli = join(__dirname, '..', 'src', 'cli.tsx')
+const cli = join(__dirname, '..', 'src', 'cli', 'main.tsx')
 
-execFileSync('node', ['--import', 'tsx/esm', cli], { stdio: 'inherit' })
+try {
+  const tsxPath = import.meta.resolve('tsx/esm')
+  execFileSync('node', ['--import', tsxPath, cli, ...process.argv.slice(2)], { stdio: 'inherit' })
+} catch (err) {
+  if (err?.code === 'ENOENT') {
+    process.stderr.write('ethagent: node 20+ is required on PATH. install Node.js, then retry.\n')
+    process.exit(127)
+  }
+  process.exit(typeof err?.status === 'number' ? err.status : 1)
+}

package/package.json

@@ -1,36 +1,58 @@
 {
   "name": "ethagent",
-  "version": "0.2.0",
-  "description": "A privacy-first AI agent with an Ethereum identity",
+  "version": "1.0.0",
+  "description": "A privacy-first AI agent with a portable Ethereum identity",
   "type": "module",
+  "main": "bin/ethagent.js",
   "bin": {
-    "ethagent": "./bin/ethagent.js"
+    "ethagent": "bin/ethagent.js"
   },
   "files": [
     "bin",
-    "src"
+    "src",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
-    "start": "node bin/ethagent.js"
+    "start": "node bin/ethagent.js",
+    "typecheck": "tsc --noEmit",
+    "test": "node test/run-tests.mjs"
+  },
+  "engines": {
+    "node": ">=20.0.0"
   },
   "keywords": [
     "ethereum",
     "agent",
     "ai",
     "privacy-first",
-    "local-llm",
     "ipfs",
     "ERC-8004",
     "onchain",
     "offline",
     "ens"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baairon/ethagent.git"
+  },
   "author": "bairon.eth",
   "license": "MIT",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.8.0",
+    "@noble/post-quantum": "^0.6.1",
+    "ajv": "^8.18.0",
     "ink": "^6.8.0",
     "react": "^19.2.4",
-    "tsx": "^4.21.0"
+    "tsx": "^4.21.0",
+    "viem": "^2.48.4",
+    "zod": "^3.25.76"
   },
-  "devDependencies": {}
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@types/react": "^19.2.14",
+    "typescript": "^5.9.3"
+  }
 }