plugin-undesirables 2.0.1 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/CHANGELOG.md +55 -0
  2. package/README.md +148 -70
  3. package/dist/index.d.ts +7 -6
  4. package/dist/index.js +435 -365
  5. package/dist/index.js.map +1 -1
  6. package/images/banner.jpg +0 -0
  7. package/images/logo.jpg +0 -0
  8. package/package.json +26 -5
  9. package/plugin.json +1 -1
  10. package/dist/index.d.ts.map +0 -1
  11. package/og_preview.png +0 -0
  12. package/src/index.ts +0 -554
  13. package/tsconfig.json +0 -20
package/CHANGELOG.md ADDED
@@ -0,0 +1,55 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ ## [2.0.3] - 2026-05-10
6
+
7
+ ### Changed
8
+ - Optimized npm description for search result truncation (130-char limit)
9
+ - Expanded Related Projects into full Ecosystem section (14 links across 4 categories)
10
+ - Fixed MCP server tool count reference (36 → 34)
11
+ - Fixed skill count consistency (23 → 24 to match actual source code)
12
+ - Added npm download, ElizaOS, MCP Server, and x402 badges to README
13
+ - Added `funding` field to package.json
14
+ - Added 8 new discovery keywords (x402, trading-cards, tcg, coinbase, base, usdc, content-creation, business-automation)
15
+ - Synced `plugin.json` version with `package.json` (was drifted at 2.0.0)
16
+
17
+ ### Fixed
18
+ - License updated from MIT to BUSL-1.1 across all files (v2.0.1)
19
+
20
+ ## [2.0.2] - 2026-04-24
21
+
22
+ ### Added
23
+ - Vitest test suite (`src/index.test.ts`)
24
+ - `plugin.json` registry metadata for ElizaOS submission
25
+ - `MemeTrendService` background service scaffold
26
+
27
+ ### Fixed
28
+ - 21 TypeScript compilation errors against real `@elizaos/core` v2 API
29
+ - `ActionExample` uses `name` field (was `user`) per v2 protobuf schema
30
+ - `Handler` returns `Promise<ActionResult>` (was `Promise<boolean>`)
31
+ - `Provider` has required `name` field and returns `ProviderResult`
32
+
33
+ ## [2.0.1] - 2026-04-24
34
+
35
+ ### Fixed
36
+ - **CRITICAL**: Action handlers were leaking raw prompt instructions to end users via `callback()`. Now routes through `runtime.generateText()`
37
+ - **CRITICAL**: Global state collision — second agent overwrote first agent's personality. Now uses `Map<string, SoulWorkspace>` keyed by `runtime.agentId`
38
+ - Replaced hand-written `elizaos-core.d.ts` type stubs with real `@elizaos/core@2.0.0-alpha.77`
39
+ - All `fs.readFileSync` calls replaced with `await fs.promises.readFile()`
40
+ - Replaced regex YAML parser with `js-yaml` using `JSON_SCHEMA` (no custom types)
41
+ - LICENSE file corrected from MIT to BUSL-1.1
42
+
43
+ ## [2.0.0] - 2026-04-24
44
+
45
+ ### Added
46
+ - Full ElizaOS v2 API compatibility
47
+ - 4 actions: `UNDESIRABLE_MARKET_ANALYSIS`, `UNDESIRABLE_BUSINESS_PILOT`, `UNDESIRABLE_MEME_MACHINE`, `UNDESIRABLE_LOAD_SKILL`
48
+ - `soulProvider` — injects personality context into every agent response
49
+ - 24-skill keyword matcher with trigger word routing
50
+ - Path traversal protection via `getSafePath()`
51
+ - Prototype pollution blocking in YAML parser
52
+ - ESM module format with `tsup` bundler
53
+
54
+ ### Changed
55
+ - Complete rewrite from v1.x Python G.A.M.E. SDK architecture to native TypeScript
package/README.md CHANGED
@@ -1,124 +1,202 @@
1
1
  # plugin-undesirables
2
2
 
3
- ![The Undesirables Banner](./og_preview.png)
3
+ ![The Undesirables Banner](./images/banner.jpg)
4
4
 
5
- [![npm version](https://img.shields.io/npm/v/plugin-undesirables.svg?style=flat-square)](https://www.npmjs.org/package/plugin-undesirables)
6
- [![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-blue.svg)](https://mariadb.com/bsl11/)
5
+ [![npm version](https://img.shields.io/npm/v/plugin-undesirables.svg)](https://www.npmjs.org/package/plugin-undesirables)
6
+ [![npm downloads](https://img.shields.io/npm/dw/plugin-undesirables.svg)](https://www.npmjs.org/package/plugin-undesirables)
7
+ [![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-blue.svg)](LICENSE)
8
+ [![ElizaOS](https://img.shields.io/badge/ElizaOS-v2_Compatible-purple.svg)](https://elizaos.ai)
9
+ [![MCP Server](https://img.shields.io/badge/MCP_Server-34_Tools-green.svg)](https://github.com/sailorpepe/undesirables-mcp-server)
10
+ [![x402](https://img.shields.io/badge/x402-Pay_Per_Request-orange.svg)](https://oracle.the-undesirables.com)
7
11
 
8
- > ElizaOS plugin for **The Undesirables** — 4,444 autonomous AI agents on Ethereum.
12
+ > Give any ElizaOS agent a persistent personality, market analysis skills, business automation, and content creation — all driven by a downloadable "soul workspace."
9
13
 
10
14
  ---
11
15
 
12
- ## 🛑 Prerequisites (Read Carefully)
13
- If you are new to running AI agents, you **must** have the following installed on your computer before continuing:
14
- 1. **[Node.js](https://nodejs.org)** (Version 23+ recommended).
15
- 2. **An existing ElizaOS bot**. This is a huge multi-agent framework. If you don't have one running yet, go read the official [ElizaOS documentation](https://elizaos.github.io/eliza/) first to set up your bot locally, then come back here to drop your Undesirable soul into it!
16
+ ## What This Does
16
17
 
17
- ---
18
-
19
- ## 📂 Step 1: Downloading Your Soul Workspace
18
+ Most AI agents are blank slates. They answer questions but have no personality, no memory, no conviction. This plugin changes that.
20
19
 
21
- Your AI agent isn't just code—it has an actual personality governed completely by the visual traits of your specific NFT.
20
+ When you install `plugin-undesirables`, your ElizaOS agent gets:
22
21
 
23
- 1. Go to [the-undesirables.com/soul](https://the-undesirables.com/soul) and connect the wallet holding your NFT.
24
- 2. Click **Download Workspace**.
25
- 3. Move the downloaded `.zip` file into a safe folder on your computer (like your Desktop) and **unzip it**.
26
- 4. This unzipped folder is your **Workspace**. *Do not arbitrarily delete files inside of it.*
22
+ - **A real personality** — not a system prompt hack, but a structured workspace with Big Five psychology scores, an archetype, a strategy style, adjectives, guardrails, and a backstory. The personality persists across sessions and colors every response.
23
+ - **Market analysis with conviction** — your agent doesn't just parrot data. It filters through its own risk tolerance and strategy to give you opinionated takes with conviction scores.
24
+ - **24 built-in skills** — portfolio checks, entry signals, exit strategies, whale tracking, meme creation, video production, music generation, and more. The agent auto-matches the right skill to your message.
25
+ - **Business Pilot** — AI-powered business automation modules: phone answering, SMS autoresponders, invoice chasers, appointment scheduling. Your agent becomes a business operations assistant.
26
+ - **Meme Machine** — content creation, brand voice setup, content calendars, and industry-specific meme packs. Your agent becomes a social media manager.
27
27
 
28
28
  ---
29
29
 
30
- ## 🔧 Step 2: Injecting the Plugin
30
+ ## Quick Start
31
31
 
32
- Open your computer's terminal, navigate to your existing ElizaOS bot folder, and install this specific adapter plugin:
32
+ ### 1. Install
33
33
 
34
34
  ```bash
35
- # Mac / Linux / Windows
36
35
  npm install plugin-undesirables
37
36
  ```
38
37
 
39
- Next, open your Eliza agent's main `character.json` file. You need to do two strict things:
40
- 1. Add the plugin to your `plugins` array.
41
- 2. Provide the **ABSOLUTE FULL PATH** on your hard drive to the Soul Workspace you unzipped in Step 1.
38
+ ### 2. Get a Soul Workspace
39
+
40
+ Go to [the-undesirables.com/soul](https://the-undesirables.com/soul), connect your wallet, and download your workspace. Unzip it somewhere on your machine.
41
+
42
+ Each workspace contains:
43
+ - `SOUL.md` — personality profile (Big Five scores, archetype, strategy, backstory)
44
+ - `SYSTEM_PROMPT.txt` — the full instruction set
45
+ - `MEMORY.md` — persistent memory file
46
+ - `PREDICTIONS_LEDGER.json` — track record of market calls
47
+ - `skills/` — 10-24 skill files depending on the agent's traits
42
48
 
43
- **🍎 Example `character.json` on Mac (Use forward slashes `/`):**
49
+ ### 3. Configure
50
+
51
+ Add to your ElizaOS `character.json`:
52
+
53
+ **macOS / Linux:**
44
54
  ```json
45
55
  {
56
+ "plugins": ["plugin-undesirables"],
46
57
  "settings": {
47
- "UNDESIRABLES_WORKSPACE": "/Users/YourName/Desktop/soul_folder/0420"
48
- },
49
- "plugins": ["plugin-undesirables"]
58
+ "UNDESIRABLES_WORKSPACE": "/Users/YourName/Desktop/soul_0420"
59
+ }
50
60
  }
51
61
  ```
52
62
 
53
- **🪟 Example `character.json` on Windows (Use double backslashes `\\`):**
63
+ **Windows:**
54
64
  ```json
55
65
  {
66
+ "plugins": ["plugin-undesirables"],
56
67
  "settings": {
57
- "UNDESIRABLES_WORKSPACE": "C:\\Users\\YourName\\Desktop\\soul_folder\\0420"
58
- },
59
- "plugins": ["plugin-undesirables"]
68
+ "UNDESIRABLES_WORKSPACE": "C:\\Users\\YourName\\Desktop\\soul_0420"
69
+ }
60
70
  }
61
71
  ```
62
72
 
63
- ---
64
-
65
- ## 🏃 Step 3: Run It!
73
+ ### 4. Run
66
74
 
67
- Simply start your ElizaOS framework like normal. It will automatically read your exact personality from the Workspace and format your Twitter/Discord interactions!
68
75
  ```bash
69
76
  elizaos start --character your-character.json
70
77
  ```
71
78
 
79
+ Your agent now has a persistent personality that influences every conversation.
80
+
81
+ ---
82
+
83
+ ## Actions
84
+
85
+ | Action | Trigger Examples | What Happens |
86
+ |--------|-----------------|--------------|
87
+ | `UNDESIRABLE_MARKET_ANALYSIS` | "What do you think about ETH?" | Personality-driven market analysis with risk guardrails and conviction scoring |
88
+ | `UNDESIRABLE_BUSINESS_PILOT` | "Set up phone answering for my barbershop" | Loads the Business Pilot skill, recommends top modules with setup steps |
89
+ | `UNDESIRABLE_MEME_MACHINE` | "Create memes for my coffee shop" | Generates meme concepts, captions, content calendars, brand voice |
90
+ | `UNDESIRABLE_LOAD_SKILL` | "Check my portfolio" / "Should I ape?" | Auto-matches your message to one of 24 skills and executes it |
91
+
92
+ ### All 24 Skills
93
+
94
+ | Skill | Trigger Words |
95
+ |-------|--------------|
96
+ | Portfolio Check | "portfolio", "balance", "holdings" |
97
+ | Content Creation | "tweet", "write", "promote", "thread" |
98
+ | Entry Signal | "should I buy", "buy signal", "good time to buy" |
99
+ | Exit Strategy | "sell", "take profit", "stop loss" |
100
+ | Risk Assessment | "risk", "downside", "worst case", "is this safe" |
101
+ | Whale Tracker | "whale", "smart money", "what are whales buying" |
102
+ | Conviction Score | "conviction", "confidence", "how sure" |
103
+ | Snipe Launch | "snipe", "new launch", "just launched" |
104
+ | Memecoin Scanner | "memecoin", "find me a gem", "degen scan" |
105
+ | Ape Checklist | "should I ape", "ape check" |
106
+ | Position Sizing | "position size", "how much should I buy" |
107
+ | Volatility Scan | "volatile", "what's moving" |
108
+ | Liquidation Watch | "liquidation levels", "longs", "shorts" |
109
+ | MEV Detection | "mev", "sandwich", "front-running" |
110
+ | Farm Yield | "yield farming", "liquidity", "best yield" |
111
+ | Compound Strategy | "compound", "auto-compound", "apy" |
112
+ | Copy Trade | "copy trade", "mirror this wallet" |
113
+ | Rebalance Check | "rebalance", "allocation", "portfolio drift" |
114
+ | Diversification | "diversify", "spread", "concentrate" |
115
+ | Sector Rotation | "sector", "rotation", "cycle" |
116
+ | Prediction Log | "predict", "forecast", "call" |
117
+ | Image Generation | "image", "picture", "generate art" |
118
+ | Music Generation | "music", "song", "beat" |
119
+ | Video Production | "video", "promo", "render video" |
120
+
121
+ ---
122
+
123
+ ## How Personality Works
124
+
125
+ Each soul workspace has a `SOUL.md` file with structured personality data:
126
+
127
+ ```yaml
128
+ name: "Doña Crypto"
129
+ archetype: "The Oracle"
130
+ strategy: "Long-term accumulation with high conviction"
131
+ adjectives: ["analytical", "patient", "contrarian"]
132
+ openness: 82
133
+ conscientiousness: 91
134
+ extraversion: 34
135
+ agreeableness: 45
136
+ neuroticism: 28
137
+ ```
138
+
139
+ The `soulProvider` injects this context into **every** agent response automatically. Your agent doesn't just have personality on request — it's always in character.
140
+
141
+ This means two different Undesirable agents will give you completely different takes on the same market question, filtered through their individual psychology.
142
+
72
143
  ---
73
144
 
74
- ## ⚠️ Common Idiot-Proof Diagnostics
145
+ ## Multi-Agent Safety
146
+
147
+ Workspaces are keyed by `runtime.agentId`. You can run multiple Undesirable agents in the same ElizaOS instance without personality collision. Agent #420 won't leak into Agent #69's responses.
75
148
 
76
- If your terminal crashes, stop and check here first:
149
+ ---
150
+
151
+ ## Troubleshooting
77
152
 
78
- - **AssertionError: Workspace /path/ does not exist**
79
- The plugin cannot find your downloaded soul. Make sure you extracted the `.zip` file, and that you pasted the *exact, full absolute path* into your `character.json`. If you are on Windows, make sure you double-escaped your slashes (e.g. `C:\\Users\\...`).
80
-
81
- - **Invalid JSON Error**
82
- Your `character.json` is missing a comma or has a syntax error. Use a real code editor like VS Code or Cursor to format your JSON properly instead of Notepad.
153
+ | Error | Fix |
154
+ |-------|-----|
155
+ | `Workspace /path/ does not exist` | Check the path in your `character.json`. It must be the **absolute** path to the unzipped workspace. Windows users: use double backslashes `\\`. |
156
+ | `Invalid JSON Error` | Your `character.json` has a syntax error. Open it in VS Code or Cursor and fix the formatting. |
157
+ | `No soul workspace loaded` | The `UNDESIRABLES_WORKSPACE` setting is missing or the path doesn't exist. |
83
158
 
84
159
  ---
85
-
86
- ## What It Does (Architecture)
87
160
 
88
- Adds soul personality, market analysis, Business Pilot (23 modules), Meme Machine, and 23 skills to any ElizaOS agent.
161
+ ## What's New in v2.0
89
162
 
90
- ### Actions
163
+ - Action handlers route through `runtime.generateText()` instead of leaking raw prompt instructions
164
+ - Multi-agent state isolation — workspaces keyed by `agentId`
165
+ - Real `@elizaos/core` v2 types (no more hand-written stubs)
166
+ - Async filesystem (`fs.promises`)
167
+ - Secure YAML parsing (`js-yaml` with `JSON_SCHEMA`)
168
+ - ESM module format
91
169
 
92
- | Action | Trigger | Description |
93
- |--------|---------|-------------|
94
- | `UNDESIRABLE_MARKET_ANALYSIS` | "What do you think about ETH?" | Personality-driven market analysis with risk guardrails |
95
- | `UNDESIRABLE_BUSINESS_PILOT` | "Set up phone answering for my business" | 23 AI-powered business automation modules |
96
- | `UNDESIRABLE_MEME_MACHINE` | "Create memes for my barbershop" | Content creation, meme templates, industry packs |
97
- | `UNDESIRABLE_LOAD_SKILL` | "Check my portfolio" | Auto-matches and loads any of 23 skills |
170
+ ---
98
171
 
99
- ### Provider
172
+ ## Ecosystem
100
173
 
101
- The `soulProvider` automatically injects the agent's personality context (archetype, strategy, adjectives, guardrails) into every single conversational response.
174
+ ### Plugins
175
+ - [plugin-undesirables](https://www.npmjs.com/package/plugin-undesirables) — Soul personality + business tools (this package)
176
+ - [@undesirables/plugin-tcg-oracle](https://github.com/sailorpepe/elizaos-tcg-oracle-plugin) — TCG market intelligence (search, grade, simulate)
102
177
 
103
- ## Converting Souls to character.json (Optional)
178
+ ### Servers & APIs
179
+ - [MCP Server](https://github.com/sailorpepe/undesirables-mcp-server) — 34-tool MCP server ([PyPI](https://pypi.org/project/undesirables-mcp-server/) · [Glama](https://glama.ai/mcp/servers/sailorpepe/undesirables-mcp-server) · [Official Registry](https://registry.modelcontextprotocol.io))
180
+ - [x402 Oracle API](https://oracle.the-undesirables.com) — Pay-per-request TCG + prediction market intelligence ([Swagger](https://oracle.the-undesirables.com/docs))
104
181
 
105
- If you don't want to use the Plugin abstraction layer above, you can force-convert a `.md` workspace directly into a massive monolithic `character.json` file using our companion converter script:
106
- ```bash
107
- # Setup the MCP server repo and run:
108
- node soul-to-eliza.js --token 420
109
- ```
110
- → [undesirables-mcp-server](https://gitlab.com/meme-merchants/undesirables-mcp-server)
182
+ ### Apps
183
+ - [TCG Oracle Desktop](https://github.com/sailorpepe/tcg-oracle-app) — macOS / Linux / Windows desktop app with AI card grading
184
+ - [Desktop Installer](https://github.com/sailorpepe/undesirables-desktop/releases/tag/v1.3.0) — DMG, DEB, RPM, AppImage, MSI binaries
185
+ - [TCG Oracle Tools](https://pypi.org/project/tcg-oracle-tools/) — Python SDK for the Oracle API
186
+
187
+ ### Data & Research
188
+ - [Kaggle Dataset](https://www.kaggle.com/datasets/sailorpepe/tcg-market-intelligence) — 370K+ TCG products across 25 games
189
+ - [HuggingFace Space](https://huggingface.co/spaces/sailorpepe/tcg-oracle) — Live demo
190
+ - [Dev.to Tutorial](https://dev.to/sailor_pepe_7920f552c5b9a/build-an-autonomous-pokemon-card-trading-agent-with-ai-grading-monte-carlo-pricing-2b86) — Build guide
111
191
 
112
- ## The Undesirables Ecosystem
192
+ ### Collection
193
+ - [The Undesirables](https://the-undesirables.com) — 4,444 NFTs on Ethereum
194
+ - [Soul Workspace](https://the-undesirables.com/soul) — Download your agent's personality
195
+ - [Etherscan](https://etherscan.io/address/0xa893648a701c03b14bf2fb767b72b2c55ed5c17a) — Contract
196
+ - [Scatter.art](https://scatter.art/the-undesirables) — Mint page
113
197
 
114
- 4,444 autonomous AI agents on Ethereum. Each one has a unique personality derived from its visual traits.
198
+ ---
115
199
 
116
- - **Website**: [the-undesirables.com](https://the-undesirables.com)
117
- - **Mint**: [scatter.art/the-undesirables](https://scatter.art/the-undesirables)
118
- - **MCP Server**: [gitlab.com/meme-merchants/undesirables-mcp-server](https://gitlab.com/meme-merchants/undesirables-mcp-server)
119
- - **TCG Oracle Tools**: [pypi.org/project/tcg-oracle-tools](https://pypi.org/project/tcg-oracle-tools/)
120
- - **MCP on PyPI**: [pypi.org/project/undesirables-mcp-server](https://pypi.org/project/undesirables-mcp-server/)
121
- - **Kaggle Dataset**: [370K+ TCG products](https://www.kaggle.com/datasets/sailorpepe/tcg-market-intelligence)
122
- - **Contract**: [0xa893...17a](https://etherscan.io/token/0xa893648a701c03b14bf2fb767b72b2c55ed5c17a)
200
+ ## License
123
201
 
124
- EST. 2026 🐸
202
+ [BUSL-1.1](LICENSE) — Business Source License 1.1. Copyright © 2026 The Undesirables LLC.
package/dist/index.d.ts CHANGED
@@ -1,3 +1,5 @@
1
+ import { Plugin } from '@elizaos/core';
2
+
1
3
  /**
2
4
  * The Undesirables — ElizaOS Plugin v2.0
3
5
  * ========================================
@@ -6,7 +8,7 @@
6
8
  *
7
9
  * Features:
8
10
  * - Load any of 4,444 unique soul personalities
9
- * - 23 unique skills across the collection (10 universal + 13 strategy-specific)
11
+ * - 34 unique tools across the collection
10
12
  * - Market analysis with personality-driven perspective
11
13
  * - Business Pilot — 23 AI-powered business modules
12
14
  * - Meme Machine — content creation & marketing
@@ -15,9 +17,9 @@
15
17
  * - Multi-agent safe (workspaces keyed by agentId)
16
18
  *
17
19
  * @see https://the-undesirables.com
18
- * @see https://gitlab.com/meme-merchants/undesirables-mcp-server
20
+ * @see https://github.com/sailorpepe/undesirables-mcp-server
19
21
  */
20
- import type { Plugin } from "@elizaos/core";
22
+
21
23
  interface SoulWorkspace {
22
24
  soulMd: string;
23
25
  systemPrompt: string;
@@ -28,6 +30,5 @@ interface SoulWorkspace {
28
30
  }
29
31
  declare function loadWorkspace(workspacePath: string): Promise<SoulWorkspace>;
30
32
  declare const undesirablePlugin: Plugin;
31
- export default undesirablePlugin;
32
- export { loadWorkspace, SoulWorkspace };
33
- //# sourceMappingURL=index.d.ts.map
33
+
34
+ export { type SoulWorkspace, undesirablePlugin as default, loadWorkspace };