@aiaiaichain/agent 0.1.2 → 0.1.4

package/docs/COMMANDS.md

@@ -0,0 +1,93 @@
+# Commands Reference
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `aiaiaichain` | Start interactive TUI |
+| `aiaiaichain setup` | First-time setup wizard |
+| `aiaiaichain config` | Show/edit configuration |
+| `aiaiaichain price` | Show $AIAIAI price |
+| `aiaiaichain status` | Full status + wallets |
+| `aiaiaichain wallet` | Agent wallet balances |
+| `aiaiaichain deposit` | Deposit instructions |
+| `aiaiaichain burn` | Burn instructions |
+| `aiaiaichain actions` | Recent buy/burn actions |
+| `aiaiaichain fees` | Fee tracker |
+| `aiaiaichain keys` | Provider key management |
+| `aiaiaichain gmgn help` | GMGN sub-commands |
+| `aiaiaichain gmgn setup` | Configure GMGN key |
+| `aiaiaichain gmgn status` | GMGN status |
+| `aiaiaichain gmgn <cmd>` | Forward to gmgn-cli |
+| `aiaiaichain update` | Check/install updates |
+| `aiaiaichain --headless "q"` | Single-turn mode |
+| `aiaiaichain --help` | Help |
+| `aiaiaichain --version` | Version |
+| `aiai-mcp` | MCP server |
+
+## TUI Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show all commands |
+| `/price` | $AIAIAI price |
+| `/news` | Latest crypto news |
+| `/models [q]` | List/search models |
+| `/model [q]` | Switch AI model |
+| `/cost` | Token usage cost |
+| `/wallet` | Agent wallets |
+| `/deposit` | Deposit instructions |
+| `/burn` | Burn instructions |
+| `/actions` | Recent actions |
+| `/fees` | Fee tracker |
+| `/keys` | Provider management |
+| `/goals [add|done|list]` | Goal management |
+| `/schedule` | Task scheduler |
+| `/memory <q>` | Search memory |
+| `/sessions` | List saved sessions |
+| `/resume <n>` | Resume a session |
+| `/clear` | Clear chat |
+| `/exit` | Exit |
+
+### GMGN Commands
+
+| Command | Description |
+|---------|-------------|
+| `/token info --chain <c> --address <a>` | Token info |
+| `/token security --chain <c> --address <a>` | Security audit |
+| `/token holders --chain <c> --address <a>` | Holder list |
+| `/token traders --chain <c> --address <a>` | Trader list |
+| `/track kol --chain <c>` | Top KOL buys |
+| `/track smartmoney --chain <c>` | Smart money buys |
+| `/track follow-wallet --chain <c>` | Followed wallet buys |
+| `/market kline --chain <c> --address <a> --resolution <1h|4h|1d>` | Candlestick chart |
+| `/market trending --chain <c> --interval <1h|6h|24h>` | Trending tokens |
+| `/market trenches --chain <c> --type <new|near|completed>` | Launchpad trenches |
+| `/market signal --chain <sol|bsc>` | Buy/sell signals |
+| `/gmgn` / `/gmgnhelp` | GMGN help |
+| `/gmgn status` | GMGN status |
+
+### Cross-Tool Commands
+
+| Command | Description |
+|---------|-------------|
+| `/watch <address>` | Add token to watch list |
+| `/unwatch <address>` | Remove from watch list |
+| `/watchlist` | Show watched tokens |
+| `/alert above <price>` | Set price alert (above) |
+| `/alert below <price>` | Set price alert (below) |
+| `/alerts` | List active alerts |
+| `/compare <addr1> <addr2>` | Side-by-side token comparison |
+| `/portfolio [address]` | Wallet portfolio analysis |
+
+## TUI Keyboard
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+C` | Exit |
+| `Escape` | Abort streaming response |
+| `↑` / `↓` | Command history navigation |
+| `Tab` | Auto-complete commands |
+| `Enter` | Submit message / command |
+| `Shift+Enter` | New line (multi-line input) |
+| `/` | Command prefix |

package/docs/CORE.md

@@ -0,0 +1,67 @@
+# Core Modules
+
+## AgentDir (`src/core/AgentDir.ts`)
+Manages `~/.aiaiai/` home directory. Creates subdirectories on first run.
+
+## ChainConfig (`src/core/ChainConfig.ts`)
+Single source of truth for chain configuration. Solana is primary. EVM chains available but disabled by default.
+
+## EnvLoader (`src/core/EnvLoader.ts`)
+Loads/writes environment variables from `~/.aiaiai/.env`. Supports `set()` for persistent key storage.
+
+## ModelRegistry (`src/models/ModelRegistry.ts`)
+Discovers models from any configured provider. Tiered pools: orchestrator → analyst → worker → free.
+
+## CostTracker (`src/models/CostTracker.ts`)
+Tracks token usage and cost across sessions. Persists to `~/.aiaiai/lifetime-cost.json`.
+
+## AgentRunner (`src/runner/AgentRunner.ts`)
+Main agent loop. Handles tool calling, streaming, message processing. Supports approval gates.
+
+## ModelClient (`src/runner/ModelClient.ts`)
+LLM API client for OpenRouter. Handles streaming SSE responses.
+
+## ToolDispatcher (`src/runner/ToolDispatcher.ts`)
+Routes tool calls to registered handlers. Returns errors for unknown tools.
+
+## SwarmRouter (`src/runner/SwarmRouter.ts`)
+Parallel sub-agent orchestration. Routes tasks to appropriate model tiers.
+
+## SessionManager (`src/session/SessionManager.ts`)
+Manages conversation state. Context pressure tracking (green/yellow/red/critical).
+
+## MemoryStore (`src/session/MemoryStore.ts`)
+Long-term conversation memory. JSONL per session. Searchable.
+
+## GoalManager (`src/session/GoalManager.ts`)
+Persistent cross-session goals. Add, complete, note.
+
+## ContextStore (`src/session/ContextStore.ts`)
+Task context folders for multi-step operations.
+
+## AgentScheduler (`src/scheduler/AgentScheduler.ts`)
+Cron and price-triggered scheduled tasks. Persisted to `~/.aiaiai/memory/schedule.json`.
+
+## PriceFeed (`src/tools/PriceFeed.ts`)
+DexScreener price data for any Solana token. 30s cache.
+
+## NewsSentiment (`src/tools/NewsSentiment.ts`)
+Crypto news with lexicon-based sentiment scoring. CryptoPanic API with fallback.
+
+## TechnicalAnalysis (`src/tools/TechnicalAnalysis.ts`)
+RSI, MACD, Bollinger Bands, EMA, SMA, ATR. Works with OHLCV candle data.
+
+## MarketSentiment (`src/tools/MarketSentiment.ts`)
+Fear & Greed, Binance funding rates, BTC mempool, DeFi TVL, Solana stats.
+
+## GmgnIntegration (`src/tools/GmgnIntegration.ts`)
+GMGN token research + smart money tracking + market data. Auto-manages `GMGN_API_KEY`.
+
+## AgentWallet (`src/wallet/AgentWallet.ts`)
+Reads cold + action + deposit wallet balances via public Solana RPC.
+
+## ActionFeed (`src/wallet/ActionFeed.ts`)
+Reads agent action wallet transactions. Classifies as buy/burn. Tracks fees.
+
+## ProviderRegistry (`src/providers/ProviderRegistry.ts`)
+All 29 AI model providers with env vars, endpoints, docs URLs.

package/docs/GMGN.md

@@ -0,0 +1,116 @@
+# GMGN Integration
+
+## Setup
+
+```bash
+# CLI
+aiaiai gmgn setup
+
+# TUI
+/gmgn setup
+```
+
+This saves `GMGN_API_KEY` to `~/.config/gmgn/.env`.
+
+## Token Research
+
+### Price + Market Cap
+```bash
+aiaiai gmgn token info --chain sol --address <address>
+```
+
+### Security Check
+```bash
+aiaiai gmgn token security --chain sol --address <address>
+# Shows: honeypot, taxes, rug ratio, holder concentration
+```
+
+### Holders
+```bash
+aiaiai gmgn token holders --chain sol --address <address> --limit 20
+```
+
+### Traders
+```bash
+aiaiai gmgn token traders --chain sol --address <address> --limit 20
+# --tag smart_degen  → filter by smart money
+# --tag renowned     → filter by KOLs
+```
+
+## Market Data
+
+### Kline / Candlestick
+```bash
+aiaiai gmgn market kline --chain sol --address <address> --resolution 1h
+# --from <unix_ts> --to <unix_ts>
+```
+
+### Trending Tokens
+```bash
+aiaiai gmgn market trending --chain sol --interval 1h
+# --order-by volume --limit 20
+# --platform Pump.fun --platform letsbonk
+# --filter renounced --filter frozen
+```
+
+### Trenches (New Tokens)
+```bash
+aiaiai gmgn market trenches --chain sol --type new_creation
+aiaiai gmgn market trenches --chain sol --type near_completion
+aiaiai gmgn market trenches --chain sol --type completed
+# --filter-preset safe
+# --filter-preset smart-money
+# --min-smart-degen-count 1
+```
+
+### Signals
+```bash
+aiaiai gmgn market signal --chain sol
+# --signal-type 12  → smart money buys
+# --signal-type 6   → price spikes
+# --mc-min 50000
+```
+
+## Smart Money Tracking
+
+### KOL Activity
+```bash
+aiaiai gmgn track kol --chain sol --limit 20
+# --side buy
+```
+
+### Smart Money Activity
+```bash
+aiaiai gmgn track smartmoney --chain sol --limit 20
+# --side sell
+```
+
+### Followed Wallet Trades
+```bash
+aiaiai gmgn track follow-wallet --chain sol
+# --wallet <address>
+# --side buy --min-amount-usd 100
+```
+
+### Followed Tokens
+```bash
+aiaiai gmgn track follow-tokens --chain sol --wallet <address>
+```
+
+## Agent Tool
+
+The agent can use GMGN via the `gmgn` tool. Examples:
+
+```
+"Research this token" → gmgn tool with subcommand: "token info"
+"Show me trending"   → gmgn tool with subcommand: "market trending"
+"What are KOLs buying?" → gmgn tool with subcommand: "track kol"
+```
+
+## Rate Limits
+
+GMGN uses a leaky-bucket limiter (20 requests burst). The agent handles 429s gracefully.
+
+## IPv6 Issue
+
+GMGN only works over IPv4. If you get 401/403, disable IPv6 on your network interface.

package/docs/PROVIDERS.md

@@ -0,0 +1,71 @@
+# Provider Registry
+
+## 29 AI Model Providers
+
+| # | Provider | Env Var | Has Model API |
+|---|----------|---------|---------------|
+| 1 | OpenRouter | `OPENROUTER_API_KEY` | ✅ |
+| 2 | Anthropic | `ANTHROPIC_API_KEY` | ✅ |
+| 3 | OpenAI | `OPENAI_API_KEY` | ✅ |
+| 4 | Google Gemini | `GOOGLE_API_KEY` | ✅ |
+| 5 | DeepSeek | `DEEPSEEK_API_KEY` | ✅ |
+| 6 | Groq | `GROQ_API_KEY` | ✅ |
+| 7 | Mistral | `MISTRAL_API_KEY` | ✅ |
+| 8 | Together AI | `TOGETHER_API_KEY` | ✅ |
+| 9 | Fireworks | `FIREWORKS_API_KEY` | ✅ |
+| 10 | Cerebras | `CEREBRAS_API_KEY` | ✅ |
+| 11 | Amazon Bedrock | `AWS_ACCESS_KEY_ID` | ❌ |
+| 12 | Google Vertex AI | `GOOGLE_APPLICATION_CREDENTIALS` | ❌ |
+| 13 | Azure OpenAI | `AZURE_OPENAI_API_KEY` | ❌ |
+| 14 | Hugging Face | `HUGGINGFACE_API_KEY` | ✅ |
+| 15 | NVIDIA NIM | `NVIDIA_NIM_API_KEY` | ✅ |
+| 16 | xAI | `XAI_API_KEY` | ✅ |
+| 17 | Moonshot AI | `MOONSHOT_API_KEY` | ✅ |
+| 18 | Moonshot AI China | `MOONSHOT_CHINA_API_KEY` | ✅ |
+| 19 | MiniMax | `MINIMAX_API_KEY` | ✅ |
+| 20 | MiniMax China | `MINIMAX_CHINA_API_KEY` | ✅ |
+| 21 | Kimi For Coding | `KIMI_API_KEY` | ✅ |
+| 22 | Ant Ling | `ANTLING_API_KEY` | ❌ |
+| 23 | Cloudflare AI Gateway | `CF_API_KEY` | ❌ |
+| 24 | Cloudflare Workers AI | `CF_API_KEY` | ❌ |
+| 25 | Vercel AI Gateway | `VERCEL_API_KEY` | ❌ |
+| 26 | OpenCode Go | `OPENCODE_API_KEY` | ❌ |
+| 27 | OpenCode Zen | `OPENCODE_ZEN_API_KEY` | ❌ |
+| 28 | Xiaomi MiMo | `XIAOMI_API_KEY` | ❌ |
+| 29 | Xiaomi MiMo Token Plan | `XIAOMI_TOKEN_API_KEY` | ❌ |
+
+## Adding Keys
+
+### CLI
+```bash
+aiaiai keys
+# Select a number, paste your key
+```
+
+### TUI
+```
+/keys
+# Select a number, paste your key
+```
+
+### Direct
+```bash
+# Edit ~/.aiaiai/.env
+OPENROUTER_API_KEY=sk-or-...
+ANTHROPIC_API_KEY=sk-...
+```
+
+## Model Tiers
+
+Models are auto-classified into 4 tiers:
+
+| Tier | Description | Example |
+|------|-------------|---------|
+| ⭐ Orchestrator | Best reasoning, highest cost | GPT-4o, Claude 3.5 Sonnet |
+| 🔬 Analyst | Mid-range capable | GPT-4o-mini, Gemini 2.0 Flash |
+| ⚡ Worker | Fast, cheap | Llama 3.1 8B, Mistral 7B |
+| 🆓 Free | Free tier models | Various |
+
+## Auto-Fetch Models
+
+When you add a provider key, the agent automatically fetches available models from that provider's API. Models appear in `/models` and the model selector (`/model`).

package/docs/README.md

@@ -0,0 +1,106 @@
+# AIAIAI Chain Agent
+
+## What is AIAIAI?
+
+AIAIAI Chain Agent is a Solana-native AI agent that runs entirely in your terminal. It buys and burns `$AIAIAI` tokens, tracks on-chain activity, researches tokens via GMGN, and manages 29 AI model providers — all through a beautiful Ink TUI.
+
+**Ticker:** `$AIAIAI`  
+**Contract:** `AVPJS61gZmWKtaEpb7qYPKo8Fk2xQUsayYQxPiPMpump`  
+**Chain:** Solana (primary)  
+**License:** MIT
+
+**Links:** [X / Twitter](https://x.com/aiaiaisol) · [aiaiaichain.xyz](https://aiaiaichain.xyz)
+
+## Installation
+
+```bash
+npm install -g @aiaiaichain/agent
+```
+
+## Quick Start
+
+```bash
+# 1. Configure (requires OpenRouter API key)
+aiaiaichain setup
+
+# 2. Start the agent
+aiaiaichain
+
+# 3. Or check $AIAIAI price directly
+aiaiaichain price
+```
+
+## Architecture
+
+```
+Your machine
+├── aiaiaichain (CLI)
+│   ├── Ink TUI             ← streaming terminal UI with sidebar
+│   ├── AgentRunner         ← model loop + tool dispatcher
+│   ├── SwarmRouter         ← parallel sub-agent orchestration
+│   ├── PriceFeed           ← DexScreener price data
+│   ├── NewsFeed            ← crypto news + sentiment
+│   ├── TechnicalAnalysis   ← RSI, MACD, Bollinger, ATR
+│   ├── MarketSentiment     ← Fear & Greed, funding, TVL
+│   ├── AgentWallet         ← cold + action + deposit wallets
+│   ├── ActionFeed          ← buy/burn tracking
+│   ├── GoalManager         ← persistent goals
+│   ├── AgentScheduler      ← cron/price-triggered tasks
+│   ├── ModelRegistry       ← 29 AI providers, tiered pools
+│   ├── GMGN Integration    ← token research + smart money tracking
+│   └── MCPServer           ← Model Context Protocol
+│
+├── ~/.aiaiai/
+│   ├── .env                ← API keys
+│   ├── config/             ← settings
+│   ├── memory/             ← long-term memory
+│   ├── checkpoints/        ← agent state
+│   └── sessions/           ← task contexts
+│
+├── ~/.config/gmgn/
+│   └── .env                ← GMGN_API_KEY
+│
+└── Outbound only (no inbound):
+    ├── openrouter.ai           ← AI models
+    ├── api.dexscreener.com     ← prices
+    ├── api.binance.com         ← OHLCV
+    ├── api.alternative.me      ← Fear & Greed
+    ├── api.llama.fi            ← DeFi TVL
+    ├── mempool.space           ← BTC mempool
+    ├── cryptopanic.com         ← news
+    └── gmgn.ai                 ← token research
+```
+
+## Wallets
+
+| Role | Address | Purpose |
+|------|---------|---------|
+| Cold | `A11iZoqEt6hU7HyggqC67ee4AtYmaJjwKCvJLerJRV2J` | Treasury |
+| Action | `BygDYM1ZXLQNC1HXLhnd1rHZ7E5XjioqT3vPjJFfjnU2` | Buys + Burns |
+| Deposit | `FBMDYpG9WXKy4SgxuATQdB2sCyzHsJWPrEr45z3TgL2e` | User deposits (SOL/USDC) |
+| Signer | `GmFrDZT2cdrqykgTikVdXbe8EtCgzUDM9VsDhQnwsUsG` | Burn authority |
+
+## Outbound Connections
+
+| Service | Purpose | Required Key |
+|---------|---------|-------------|
+| OpenRouter | AI model access | `OPENROUTER_API_KEY` |
+| DexScreener | Token prices | None (public) |
+| Binance API | OHLCV candles | None (public) |
+| Alternative.me | Fear & Greed | None (public) |
+| DeFiLlama | TVL data | None (public) |
+| Mempool.space | BTC mempool | None (public) |
+| CryptoPanic | Crypto news | None (public) |
+| GMGN | Token research + tracking | `GMGN_API_KEY` |
+
+## Inbound Connections
+
+**None.** The agent is 100% outbound. No ports are opened, no servers listen, no inbound connections are accepted. All data is pulled via HTTP GET/POST requests.
+
+## Security
+
+- All API keys stored in `~/.aiaiai/.env` (chmod 600)
+- GMGN key stored in `~/.config/gmgn/.env` (chmod 600)
+- No keys leave your machine
+- No inbound ports
+- All outbound connections use HTTPS

package/docs/TOOLS.md

@@ -0,0 +1,81 @@
+# Tools Reference
+
+## Price & Market
+| Tool | Description |
+|------|-------------|
+| `get_aiaiai_price` | $AIAIAI price, liquidity, MCap, volume (DexScreener) |
+| `get_token_price` | Any Solana token price data (DexScreener) |
+| `get_news` | Crypto news with sentiment scoring |
+| `get_candles` | OHLCV candles from Binance + full TA analysis |
+| `analyze_ta` | RSI, MACD, Bollinger, ATR on price array |
+
+## Market Sentiment
+| Tool | Description |
+|------|-------------|
+| `get_fear_greed` | Crypto Fear & Greed Index (7-day) |
+| `get_funding_rates` | Binance perpetual funding rates |
+| `get_btc_mempool` | BTC mempool stats + fees |
+| `get_defi_tvl` | DeFiLlama TVL by chain |
+| `get_solana_stats` | Solana epoch, slot, SOL price |
+
+## Wallet & Actions
+| Tool | Description |
+|------|-------------|
+| `get_agent_balance` | Cold + action wallet balances |
+| `get_deposit_balance` | Deposit wallet + instructions |
+| `get_actions` | Recent buy/burn actions |
+| `get_fees` | Accumulated fees (0.5% per action) |
+
+## AI Models
+| Tool | Description |
+|------|-------------|
+| `list_models` | Search/filter models by provider/tier |
+| `pick_model` | Find cheapest model in a tier |
+| `model_summary` | Provider and tier breakdown |
+| `cost_report` | Session/lifetime token usage |
+
+## Context & Goals
+| Tool | Description |
+|------|-------------|
+| `set_goal` | Set persistent goal |
+| `complete_goal` | Mark goal done |
+| `list_goals` | List all goals |
+| `add_goal_note` | Progress note |
+| `set_goal` | Set goal |
+
+## Tasks & Schedule
+| Tool | Description |
+|------|-------------|
+| `schedule_task` | Schedule recurring task |
+| `list_schedule` | List scheduled tasks |
+| `remove_schedule` | Remove task |
+| `read_task_context` | Read saved task context |
+| `list_tasks` | List task contexts |
+
+## GMGN Token Research
+| Tool | Description |
+|------|-------------|
+| `gmgn` | Full GMGN access (token info, security, holders, traders, KOL, smart money, kline, trending, trenches, signals) |
+
+## Built-in Commands
+| Command | Description |
+|---------|-------------|
+| `/help` | Show all commands |
+| `/price` | $AIAIAI price |
+| `/news` | Latest news |
+| `/models` | List models |
+| `/model` | Switch model |
+| `/cost` | Token usage |
+| `/wallet` | Agent wallets |
+| `/deposit` | Deposit instructions |
+| `/burn` | Burn instructions |
+| `/actions` | Recent actions |
+| `/fees` | Fee tracker |
+| `/keys` | Provider key management |
+| `/gmgn` | GMGN token research |
+| `/update` | Check for updates |
+| `/goals` | Goal management |
+| `/schedule` | Task scheduler |
+| `/memory` | Search memory |
+| `/clear` | Clear chat |
+| `/exit` | Exit |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiaichain/agent",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "AIAIAI Chain Agent — Solana-native AI agent for decentralized AI governance. Ticker: $AIAIAI",
   "author": "AIAIAI Foundation",
   "license": "MIT",
@@ -28,7 +28,8 @@
     "start": "node dist/cli.js",
     "type-check": "tsc --noEmit --project tsconfig.json",
     "test": "echo \"no tests yet\" && exit 0",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/postinstall.js"
   },
   "dependencies": {
     "@sinclair/typebox": "^0.32.0",
@@ -41,7 +42,7 @@
   "devDependencies": {
     "@types/node": "^20.19.41",
     "@types/react": "^18.3.29",
-    "typescript": "^5.9.3"
+    "typescript": "^5.10.0"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -58,7 +59,9 @@
   "files": [
     "dist",
     "bin",
+    "scripts",
     "README.md",
+    "docs",
     "!dist/**/*.map"
   ]
 }

package/scripts/postinstall.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * postinstall.js — creates bin symlinks if npm didn't do it.
+ * This handles the case where `npm install -g` doesn't create
+ * symlinks for scoped packages.
+ */
+
+import { existsSync, symlinkSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(__dirname, '..');
+const BIN_DIR = join(PKG_ROOT, 'bin');
+
+// Only run if we're in a node_modules install (not dev)
+if (!PKG_ROOT.includes('node_modules')) process.exit(0);
+
+const NM_BIN = join(PKG_ROOT, 'node_modules', '.bin');
+
+try {
+  mkdirSync(NM_BIN, { recursive: true });
+
+  const bins = readdirSync(BIN_DIR).filter(f => !f.endsWith('.map'));
+  for (const bin of bins) {
+    const src = join(BIN_DIR, bin);
+    const dst = join(NM_BIN, bin);
+    try { symlinkSync(src, dst); } catch { /* already exists */ }
+  }
+} catch {
+  // Non-fatal — npm might have already created the links
+}